Performance

Scene optimization (SDK 0.5.1)

library.assembleScene(scene, { optimize: true }) (Three.js) or <OptimizedScene> (React Three Fiber) draws every mesh that at least two instances share with GPU instancing. Only the draw calls change; triangles are counted per instance either way.

Agent-written towns (10)

169–264 → 63–93 — draw calls, −55.6 % to −69.6 %

Explorable town (161 instances)

621 → 148 — draw calls, −76.2 %

Largest pixel difference

0.070 % — of the pixels; pass condition <= 0.1 % pixels > 16/255

The draw counts are identical in every run (Host GPU and Software rendering (SwiftShader)).

Draw calls: per frame, plain → optimized. Pixels: share of the frame that differs by more than 16/255 between the plain and the optimized render. Frame ms: median render and GPU sync, plain / optimized — reported, not judged.

What was judged

• draw calls: agent-written towns: optimized <= 50 % of plain; every other scene: fewer draw calls (the reduction is recorded)
• pixels: <= 0.1 % pixels > 16/255
• picking: identical first visible hit
• semantics: customize after optimize, clip; variants scenes: parts picked, both variants batched
• frame time: reported, not judged.

Fewer draw calls cut CPU and driver work per frame. Whether that makes frames faster on slower or mobile GPUs was not measured, so it is not claimed.

When not to batch an instance

The optimization keeps the SDK’s behaviour by itself: playClip and town.customize hand an instance back and batch it again, and an instance you move, hide or give another material is drawn by its own objects from that frame on. Leave an instance out of the batches when your code changes it often or decorates it per object:

const town = await library.assembleScene(sceneJson, { optimize: { exclude: ['windmill-1', 'house-3'] } });
// or { optimize: 'strict' }: only unmodified, clip-free instances are batched; customized ones keep their own meshes

<OptimizedScene exclude={['windmill-1']}>
  {instances.map((i) => <Asset key={i.instance_id} instanceId={i.instance_id} assetId={i.asset} customize={Object.keys(i.values).length ? i.values : undefined} position={i.position_m} quaternion={i.quaternion_xyzw} />)}
</OptimizedScene>
// or <OptimizedScene preset="strict">

• Exclude by instance id. An exclusion names the scene instance, so it still applies after town.customize(id, …) replaces the instance. SDK 0.5.1 also accepts the instance’s LoadedAsset (with SDK 0.5.0 only an id survives town.customize).
• strict keeps every customized or clip-bearing instance on its own meshes and still batches the repeated tiles and props; it saves fewer draw calls than the default large-scene.
• Picking needs no exclusion. Raw raycasts return exactly the hits they return without optimization, and town.optimization.pick(raycaster) resolves the first drawn hit to its instance and mounted part.

GLB optimization: nothing shipped

Quantized and meshopt-compressed variants of the kit's 30 reference GLBs were built and measured. Decision: no variant is shipped — not every condition holds for any variant (see conditions); the reference GLB stays the only published file. Loading a variant (loadAsset(ref, { variant: 'optimized' })) is refused with VARIANT_NOT_AVAILABLE.

Host GPU

ANGLE (Apple, ANGLE Metal Renderer: Apple M2 Pro, Unspecified Version). References: decode 24.6 ms for all 30, town frame 2.2 ms; variants: decode 25.9 / 26.6 / 26.8 / 26.8 ms, frame 2.2 / 2.2 / 2.2 / 2.3 ms (in the table's order). Measured 2026-10-26.

Conditions each variant does not meet

• quantize: KHR_mesh_quantization: positions 14 bit (per mesh volume), normals 10 bit; no decoder
  • bytes-smaller: raw 2853108 vs 3939716 B (-27.6 %), gzip 852295 vs 761807 (11.9 %), brotli 561970 vs 525815 (6.9 %)
  • image-equivalent: 0.1860 % of pixels differ by more than 16/255 from the reference render (max delta 157)
  • geometry-within-slot-tolerance:
    largest vertex displacement 0.62 mm (normals 0.087 deg); the published slot-consistency gate allows 0.1 mm between a host's baked part and the part… Show all

    largest vertex displacement 0.62 mm (normals 0.087 deg); the published slot-consistency gate allows 0.1 mm between a host's baked part and the part asset, i.e. 0.05 mm per side
• meshopt-lossless: EXT_meshopt_compression codec only (no quantization, no reorder): bit-exact data; MeshoptDecoder required
  • bytes-smaller: raw 2584328 vs 3939716 B (-34.4 %), gzip 1064515 vs 761807 (39.7 %), brotli 910468 vs 525815 (73.2 %)
  • no-decoder-needed:
    needs MeshoptDecoder (three/examples/jsm/libs/meshopt_decoder.module.js, 29 KB, self-hostable); the SDK loads baseline GLBs only (DECODER_REQUIRED /… Show all

    needs MeshoptDecoder (three/examples/jsm/libs/meshopt_decoder.module.js, 29 KB, self-hostable); the SDK loads baseline GLBs only (DECODER_REQUIRED / VARIANT_NOT_AVAILABLE) and would need a decoder path plus tests
• meshopt: gltf-transform meshopt level 'medium': reorder + quantize (14/10 bit) + codec; MeshoptDecoder required
  • bytes-smaller: raw 1328268 vs 3939716 B (-66.3 %), gzip 598141 vs 761807 (-21.5 %), brotli 526596 vs 525815 (0.1 %)
  • image-equivalent: 0.1860 % of pixels differ by more than 16/255 from the reference render (max delta 157)
  • geometry-within-slot-tolerance:
    largest vertex displacement 0.62 mm (normals 0.087 deg); the published slot-consistency gate allows 0.1 mm between a host's baked part and the part… Show all

    largest vertex displacement 0.62 mm (normals 0.087 deg); the published slot-consistency gate allows 0.1 mm between a host's baked part and the part asset, i.e. 0.05 mm per side
  • no-decoder-needed:
    needs MeshoptDecoder (three/examples/jsm/libs/meshopt_decoder.module.js, 29 KB, self-hostable); the SDK loads baseline GLBs only (DECODER_REQUIRED /… Show all

    needs MeshoptDecoder (three/examples/jsm/libs/meshopt_decoder.module.js, 29 KB, self-hostable); the SDK loads baseline GLBs only (DECODER_REQUIRED / VARIANT_NOT_AVAILABLE) and would need a decoder path plus tests
• meshopt-high: gltf-transform meshopt level 'high': as medium + 8-bit octahedral normals, filtered animation data; MeshoptDecoder required
  • image-equivalent: 0.1860 % of pixels differ by more than 16/255 from the reference render (max delta 157)
  • animations:
    clips unchanged by name and target; largest keyframe rotation change 0.0036 deg (limit 0.01), largest translation/scale/weight change 0.000453 (limit… Show all

    clips unchanged by name and target; largest keyframe rotation change 0.0036 deg (limit 0.01), largest translation/scale/weight change 0.000453 (limit 1e-6)
  • geometry-within-slot-tolerance:
    largest vertex displacement 0.62 mm (normals 1.025 deg); the published slot-consistency gate allows 0.1 mm between a host's baked part and the part… Show all

    largest vertex displacement 0.62 mm (normals 1.025 deg); the published slot-consistency gate allows 0.1 mm between a host's baked part and the part asset, i.e. 0.05 mm per side
  • no-decoder-needed:
    needs MeshoptDecoder (three/examples/jsm/libs/meshopt_decoder.module.js, 29 KB, self-hostable); the SDK loads baseline GLBs only (DECODER_REQUIRED /… Show all

    needs MeshoptDecoder (three/examples/jsm/libs/meshopt_decoder.module.js, 29 KB, self-hostable); the SDK loads baseline GLBs only (DECODER_REQUIRED / VARIANT_NOT_AVAILABLE) and would need a decoder path plus tests

Publishing conditions

• Passed reference-unchanged: all 30 reference GLBs re-hashed after the run: equal to their manifest pins (they were only read)
• Failed own-sha256-and-manifest-entry: Publishing a variant adds an entry to the asset manifest, which changes the bytes a published version pins. A variant therefore ships as a new asset version, never as an edit of an existing one.
• Failed variant-passes-its-own-qa: The quality gates validate the reference GLB only. No gate validates an optimized variant yet (decoder setup, slot consistency on quantized geometry, customization on the variant).

Demo budgets of the explorable town

Measured on the vanilla demo and the R3F example (161 instances) with the explicit recipe below. The budgets describe the shipped scene, not yours: your customizations change the totals. No mobile performance is claimed: real devices were not measured.

The explicit recipe

{ optimize: true } is this recipe in one option, plus automatic hand-back and re-batching. The explicit form still works and keeps its behaviour: batched meshes snapshot transforms, so call unbatch(id) before you change an instance yourself. An instance is batched by at most one helper at a time.

import { instanceStatic } from '@agent-ready-assets/runtime-three';

const town = await library.assembleScene(sceneJson);
const batches = instanceStatic(town, { includeCustomized: true, includeAnimatable: true });
scene.add(town.group);
renderer.shadowMap.autoUpdate = false; // set renderer.shadowMap.needsUpdate = true when something changes
batches.stats(); // { drawsBefore, drawsAfter, triangles, ... }
// before moving or hiding one instance yourself: batches.unbatch(id); on teardown: batches.dispose(); town.release();

Instancing reduces draw calls only; triangles are counted per instance either way. Measure your own scene with renderer.info.render and stats().

What a choice costs