@vgai/engine 0.2.0 → 0.3.0

package/dist/scene/scene-loader.js

@@ -0,0 +1,1213 @@
+import * as THREE from 'three';
+import { RGBELoader } from 'three/addons/loaders/RGBELoader.js';
+import { initNavigation, NavMeshManager } from '../ai/navigation';
+import { buildClipMap } from '../animation/clip-map';
+import { log } from '../dev/logger';
+import { loadingManager, resolveUrl } from '../loader';
+import { resolveRenderSettings } from '../render/render-settings';
+import { assetCacheSizes, clearAssetCaches as clearSharedAssetCaches, loadGLTF, resolveGltfNode, } from './asset-loaders';
+import { getAssetMeta, loadRegistry } from './asset-registry';
+import { computeColliderWorldDimensions, computeColliderWorldOffset } from './collider-dimensions';
+import { applyComponents } from './component-registry';
+import { DEFAULTS } from './defaults';
+import './geometries';
+import './instancers';
+import { buildInstancedMesh, buildInstancedMeshFromTuples } from './instance-registry';
+import { createCamera, createLight } from './light-camera-factory';
+import { createGeometry, createMaterial } from './material-factory';
+import './materials';
+import { parseInstancesFile, parseMaterialFile, parsePrefabFile, parseSceneFile } from './parse';
+import { createParticleSystemFromData } from './particles-factory';
+import { mergePrefabInstance, } from './scene-types';
+import { isEntityRefSchema } from './schema/entity-ref';
+import { getUserData, setUserData } from './user-data';
+// GLTF / texture load+cache logic lives in the shared ./asset-loaders module
+// (A2) so the editor and runtime share one cache + one clone-safety contract.
+// Only the IBL/skybox env-map cache stays here — it needs a WebGLRenderer
+// (PMREM), which the shared module deliberately doesn't depend on.
+const envTextureCache = new Map();
+let pmremGenerator = null;
+/**
+ * Clear module-level asset caches (textures, GLTF scenes, IBL env maps). Call
+ * on full runtime teardown to release cached GPU resources and avoid leaking
+ * across editor Play sessions. Delegates the GLTF/texture caches to
+ * {@link clearSharedAssetCaches} and additionally frees the local
+ * IBL env-map cache + PMREM generator.
+ *
+ * Lifetime / P1.8: these caches are intentionally module-level and persist
+ * ACROSS hot-reloads / scene switches (they are NOT cleared on every
+ * loadSceneFromData). This is deliberate: (1) it makes repeated Play→Stop→Play
+ * cheap, and (2) it underpins the `__sharedGeometry` contract from P0.2 —
+ * GLTF clones share the cached source geometry, so clearing mid-session would
+ * orphan live clones. The caches are keyed by URL, so loading the SAME scene N
+ * times is bounded (one entry per distinct asset URL, not per load). They are
+ * only released here, on full runtime teardown (`fullCleanup`).
+ */
+export function clearAssetCaches() {
+    clearSharedAssetCaches();
+    envTextureCache.clear();
+    if (pmremGenerator) {
+        pmremGenerator.dispose();
+        pmremGenerator = null;
+    }
+}
+/**
+ * F7 — per-frame LOD tick. THREE.LOD only swaps its active level when
+ * `.update(camera)` runs, so every `THREE.LOD` in the scene graph (built by
+ * the `mesh.lod` spawn branch above) needs this called once a frame. Mirrors
+ * `tickCustomMaterials`'s traverse-and-tick shape; wired into the runtime's
+ * `preRender` system in `vgai-scene-game-adapter.ts`.
+ */
+export function updateSceneLODs(scene, camera) {
+    scene.traverse((o) => {
+        if (o.isLOD)
+            o.update(camera);
+    });
+}
+/**
+ * Test-only: current sizes of the module-level asset caches. Used by the P1.8
+ * headless test to assert caches stay bounded (one entry per distinct asset URL)
+ * across repeated loads of the same scene, rather than growing per load.
+ */
+export function __assetCacheSizesForTest() {
+    const sizes = assetCacheSizes();
+    return {
+        textures: sizes.textures,
+        gltf: sizes.gltf,
+        env: envTextureCache.size,
+    };
+}
+/**
+ * Load an equirectangular HDR/EXR/image as a PMREM-processed IBL environment
+ * map and assign it to `scene.background` + `scene.environment`. Mirrors the
+ * editor's scene-sync `applyEnvironment`/`loadEnvTexture` so the runtime renders
+ * the same skybox the editor previews. Requires a WebGLRenderer for PMREM; in
+ * headless (no renderer) this is skipped and no placeholder is set.
+ */
+function applySkybox(skybox, env, ctx) {
+    const renderer = ctx.renderer;
+    if (!renderer)
+        return;
+    const cached = envTextureCache.get(skybox);
+    if (cached) {
+        ctx.scene.background = cached;
+        ctx.scene.environment = cached;
+        ctx.scene.environmentIntensity = env.envMapIntensity ?? DEFAULTS.environment.envMapIntensity;
+        return;
+    }
+    loadEnvTexture(skybox, renderer)
+        .then((texture) => {
+        if (!texture)
+            return;
+        envTextureCache.set(skybox, texture);
+        ctx.scene.background = texture;
+        ctx.scene.environment = texture;
+        ctx.scene.environmentIntensity = env.envMapIntensity ?? DEFAULTS.environment.envMapIntensity;
+    })
+        .catch(() => {
+        // HDRI load failed — leave background unset rather than show a wrong sky.
+    });
+}
+async function loadEnvTexture(path, renderer) {
+    try {
+        if (!pmremGenerator) {
+            pmremGenerator = new THREE.PMREMGenerator(renderer);
+            pmremGenerator.compileEquirectangularShader();
+        }
+        const ext = path.split('.').pop()?.toLowerCase();
+        const rawTexture = ext === 'hdr'
+            ? await new RGBELoader(loadingManager).loadAsync(resolveUrl(path))
+            : await new THREE.TextureLoader(loadingManager).loadAsync(resolveUrl(path));
+        rawTexture.mapping = THREE.EquirectangularReflectionMapping;
+        const envMap = pmremGenerator.fromEquirectangular(rawTexture).texture;
+        rawTexture.dispose();
+        return envMap;
+    }
+    catch {
+        return null;
+    }
+}
+/** Build a Three.js CatmullRomCurve3 from a spline descriptor (≥2 points). */
+function createCurveFromSpline(spline) {
+    if (spline.points.length < 2)
+        return null;
+    const points = spline.points.map((p) => new THREE.Vector3(p[0], p[1], p[2]));
+    return new THREE.CatmullRomCurve3(points, spline.closed ?? false, spline.curveType, spline.tension ?? 0.5);
+}
+/**
+ * Loads a .vscn.json file and instantiates all entities.
+ *
+ * Creates Three.js objects and Rapier bodies. The Object3D IS the entity —
+ * there is no separate ECS id. Uses raw Three.js/Rapier calls — no abstraction.
+ *
+ * Returns a SceneInstance that must be ticked each frame (for GLTF animations).
+ */
+export async function loadScene(url, ctx) {
+    const res = await fetch(resolveUrl(url));
+    // Checklist item 9 (audit residual — the editor-side equivalent was fixed
+    // under T1.12): a 404/500 response body is typically HTML, not JSON — feed
+    // it straight to `res.json()` and the failure surfaces as an opaque
+    // "Unexpected token '<'" JSON parse error instead of naming the URL/status
+    // that actually failed. Throw loudly here instead.
+    if (!res.ok) {
+        throw new Error(`Failed to load scene: ${url} (${res.status} ${res.statusText})`);
+    }
+    const data = parseSceneFile(await res.json(), url);
+    return instantiateScene(data, ctx, url);
+}
+/**
+ * Instantiate a scene from an already-parsed SceneFile.
+ *
+ * Same as loadScene but skips the fetch — useful when the scene data is
+ * already in memory (e.g. serialized from the editor for play-mode preview).
+ */
+export async function loadSceneFromData(data, ctx) {
+    return instantiateScene(data, ctx);
+}
+const ROOT_ANCESTOR_CONTEXT = { worldMatrix: new THREE.Matrix4() };
+/** Human-readable entity identifier for error messages (loud-failure naming). */
+function entityLabel(def) {
+    return def.id ? `${def.name} (id: "${def.id}")` : def.name;
+}
+// ---------------------------------------------------------------------------
+// T3.9 — bounded-concurrency asset prefetch.
+//
+// Child/asset fetches (prefab files, materials, GLTF models) used to only
+// ever happen inline, one at a time, inside the fully-sequential
+// `spawnEntity` recursion — fine at ~20 assets, product-breaking at hundreds
+// (every fetch's network round-trip is paid serially). Rather than restructure
+// the deterministic sequential spawn walk itself (which authored array order,
+// tickFns/mixers order, and GameComponent registration order all depend on),
+// this prefetch pass walks the WHOLE entity tree up front and warms the
+// existing URL-keyed caches (asset-loaders.ts's module-level GLTF cache, and
+// this module's ctx-level prefab/material file caches) with a
+// small concurrency limiter. The sequential spawn pass below is completely
+// unchanged — its `await`s just resolve instantly against a warm cache, so
+// wall-clock time is bounded by ceil(assetCount / limit) round-trips instead
+// of assetCount. Prefetching is a pure optimization: any error here is
+// swallowed and re-surfaced normally (with a real error) by the sequential
+// pass that actually consumes the data.
+// ---------------------------------------------------------------------------
+const PREFETCH_CONCURRENCY = 8;
+/**
+ * Tiny concurrency-limited task runner — no new dependency. Runs `tasks` with
+ * at most `limit` in flight at once. Tasks may push MORE tasks onto the same
+ * array while running (each worker re-checks `tasks.length` every loop), which
+ * is how nested prefab expansion gets picked up without a second pass.
+ */
+async function runLimited(tasks, limit) {
+    let next = 0;
+    async function worker() {
+        for (;;) {
+            const i = next++;
+            if (i >= tasks.length)
+                return;
+            try {
+                await tasks[i]();
+            }
+            catch {
+                // Swallow — prefetching is an optimization; the real (sequential)
+                // spawn pass re-fetches and surfaces genuine load errors normally.
+            }
+        }
+    }
+    const workerCount = Math.min(limit, tasks.length);
+    await Promise.all(Array.from({ length: workerCount }, () => worker()));
+}
+/**
+ * Recursively collect asset-prefetch tasks for an entity subtree (T3.9).
+ * Best-effort: walks JSON-prefab expansion (fetch the `.prefab.json`, merge,
+ * recurse into the merged root) so a prefab's OWN nested asset refs get
+ * warmed too. Any inaccuracy here (e.g. a merge that would actually throw)
+ * only costs a bit of parallelism, never correctness — errors are swallowed
+ * by `runLimited` and the real spawn pass is unaffected.
+ */
+function collectPrefetchTasks(def, ctx, tasks, seenPrefabUrls) {
+    if (def.mesh?.type === 'gltf' && def.mesh.src) {
+        const src = def.mesh.src;
+        tasks.push(() => loadGLTF(src));
+    }
+    if (def.materialRef) {
+        const ref = def.materialRef;
+        tasks.push(() => loadMaterialFile(ref, ctx));
+    }
+    if (def.prefab && !ctx.prefabs?.has(def.prefab) && !seenPrefabUrls.has(def.prefab)) {
+        const prefabUrl = def.prefab;
+        seenPrefabUrls.add(prefabUrl);
+        tasks.push(async () => {
+            const prefabDef = await loadPrefabFile(prefabUrl, ctx);
+            const merged = mergePrefabInstance(prefabDef.root, def);
+            collectPrefetchTasks(merged, ctx, tasks, seenPrefabUrls);
+        });
+    }
+    if (def.children) {
+        for (const child of def.children)
+            collectPrefetchTasks(child, ctx, tasks, seenPrefabUrls);
+    }
+}
+async function instantiateScene(data, ctx, url) {
+    const tickFns = [];
+    const mixers = [];
+    // Ensure asset registry is loaded before spawning entities
+    await loadRegistry();
+    // T3.9 — warm asset caches for the whole tree with bounded concurrency
+    // before the deterministic sequential spawn pass below.
+    const prefetchTasks = [];
+    const seenPrefabUrls = new Set();
+    for (const entityDef of data.entities) {
+        collectPrefetchTasks(entityDef, ctx, prefetchTasks, seenPrefabUrls);
+    }
+    await runLimited(prefetchTasks, PREFETCH_CONCURRENCY);
+    // F7 — populate the scene-level render-feature scope once, before any entity
+    // spawns, so the mesh.lod master-gate check (resolveRenderSettings) below has
+    // it available regardless of whether `data.environment` is set.
+    if (data.environment?.rendering) {
+        ctx.sceneRendering = data.environment.rendering;
+    }
+    // Environment
+    if (data.environment) {
+        const env = data.environment;
+        if (env.ambient) {
+            const light = new THREE.AmbientLight(env.ambient.color, env.ambient.intensity);
+            ctx.scene.add(light);
+        }
+        if (env.fog) {
+            if (env.fog.type === 'exponential') {
+                ctx.scene.fog = new THREE.FogExp2(env.fog.color, env.fog.density ?? DEFAULTS.fog.exponential.density);
+            }
+            else {
+                ctx.scene.fog = new THREE.Fog(env.fog.color, env.fog.near ?? DEFAULTS.fog.linear.near, env.fog.far ?? DEFAULTS.fog.linear.far);
+            }
+        }
+        if (env.background) {
+            ctx.scene.background = new THREE.Color(env.background);
+        }
+        if (env.skybox) {
+            // Load the real HDRI as a PMREM IBL env map (background + environment),
+            // mirroring the editor. Async + fire-and-forget; no placeholder color.
+            applySkybox(env.skybox, env, ctx);
+        }
+    }
+    // Entities — pass 1: spawn all, build entity ID → Object3D mapping.
+    // spawnEntity recurses into children itself and registers every id
+    // (including nested children) in idMap via the idMap parameter.
+    const idMap = new Map();
+    for (const entityDef of data.entities) {
+        const obj = await spawnEntity(entityDef, ctx, tickFns, mixers, idMap);
+        ctx.scene.add(obj);
+    }
+    // Pass 1.5: animated attachments must resolve only after every entity and
+    // GLTF skeleton has spawned. Reparenting preserves the authored transform
+    // as the local socket offset; gameplay components remain on the same
+    // Object3D and therefore require no mirror or adapter entity.
+    resolveBoneAttachments(data.entities, idMap);
+    // Pass 2: create joints between physics bodies
+    createSceneJoints(data.entities, idMap, ctx);
+    // Pass 2.5 (F6): resolve EntityRefSchema component fields (string id ->
+    // live Object3D) — must run after every entity id is in idMap, and before
+    // initAll() so components observe the resolved Object3D in init().
+    if (ctx.componentManager) {
+        resolveEntityRefs(data.entities, idMap, ctx.componentManager);
+    }
+    // Pass 3: initialize GameComponent instances (now that all entities + joints exist)
+    if (ctx.componentManager) {
+        await ctx.componentManager.initAll();
+    }
+    // Try to load pre-baked navmesh from sibling .navmesh file
+    let navMesh;
+    if (url) {
+        const navmeshUrl = url.replace('.vscn.json', '.navmesh');
+        try {
+            const navRes = await fetch(resolveUrl(navmeshUrl));
+            if (navRes.ok) {
+                await initNavigation();
+                const buffer = await navRes.arrayBuffer();
+                navMesh = new NavMeshManager();
+                navMesh.loadFromData(new Uint8Array(buffer));
+            }
+        }
+        catch {
+            // No pre-baked navmesh — continue without one
+        }
+    }
+    // Collect cameras defined in scene entities
+    const cameras = [];
+    ctx.scene.traverse((obj) => {
+        const cam = getUserData(obj, '_camera');
+        if (cam)
+            cameras.push(cam);
+    });
+    return {
+        navMesh,
+        cameras,
+        environment: data.environment,
+        ui: data.ui,
+        entities: idMap,
+        update(dt) {
+            for (const fn of tickFns)
+                fn(dt);
+        },
+        dispose() {
+            for (const mixer of mixers)
+                mixer.stopAllAction();
+            tickFns.length = 0;
+            mixers.length = 0;
+        },
+    };
+}
+async function spawnEntity(def, ctx, tickFns, mixers, idMap, ancestorCtx = ROOT_ANCESTOR_CONTEXT, audioTracker) {
+    // Check for factory-function prefabs (code prefabs registered at runtime)
+    if (def.prefab && ctx.prefabs?.has(def.prefab)) {
+        // R1c — the factory function receives NO ancestor context (no world
+        // matrix, no moving-ancestor info), unlike the JSON-prefab/primitive path
+        // below which composes it for physics spawn. If this code-prefab is
+        // nested under a transformed ancestor, its own transform/physics are
+        // built by the factory as if it were at the scene root — they will NOT
+        // reflect the ancestor's position/rotation/scale. Warn loudly (once per
+        // entity, naturally once per scene load since each entity is visited once)
+        // rather than silently producing a wrong-looking result.
+        if (!ancestorCtx.worldMatrix.equals(ROOT_ANCESTOR_CONTEXT.worldMatrix)) {
+            log.scene.warn(`Code-prefab entity "${entityLabel(def)}" (factory "${def.prefab}") is nested under an ` +
+                'ancestor with a non-identity world transform. The runtime ctx.prefabs factory API ' +
+                "doesn't yet receive ancestor context, so this entity's own transform/physics are " +
+                "built as if it were at the scene root — they will NOT compose the ancestor's " +
+                'position/rotation/scale. Move this entity to the scene root, or wait for ancestor-' +
+                'context support in the code-prefab factory API.', { entityId: def.id });
+        }
+        const object3d = ctx.prefabs.get(def.prefab)(ctx, def);
+        // Same entity-metadata contract as the main path below (see the comment
+        // there): `entity` userData is written unconditionally so queries find
+        // code-prefab instances too; only `entityId`/idMap stay id-gated.
+        object3d.name = def.name;
+        setUserData(object3d, 'entity', def);
+        if (def.id) {
+            setUserData(object3d, 'entityId', def.id);
+            if (idMap)
+                idMap.set(def.id, object3d);
+        }
+        // Apply JSON components on top of prefab defaults
+        if (def.components && ctx.componentRegistry && ctx.componentManager) {
+            applyComponents(ctx.componentRegistry, object3d, def.components, ctx.componentManager);
+        }
+        return object3d;
+    }
+    // Check for JSON prefab files (.prefab.json)
+    if (def.prefab) {
+        const prefabDef = await loadPrefabFile(def.prefab, ctx);
+        const merged = mergePrefabInstance(prefabDef.root, def);
+        return spawnEntity(merged, ctx, tickFns, mixers, idMap, ancestorCtx, audioTracker);
+    }
+    // Transform
+    const pos = def.transform?.position ?? DEFAULTS.transform.position;
+    const rot = def.transform?.rotation ?? DEFAULTS.transform.rotation;
+    const scl = def.transform?.scale ?? DEFAULTS.transform.scale;
+    // T1.1 — compose this entity's WORLD transform (parent chain × own local
+    // transform) for physics spawn purposes. Cheap (one 4x4 multiply) and done
+    // unconditionally so children can thread it further down regardless of
+    // whether THIS entity has physics.
+    const localMatrix = new THREE.Matrix4().compose(new THREE.Vector3(pos[0], pos[1], pos[2]), new THREE.Quaternion(rot[0], rot[1], rot[2], rot[3]), new THREE.Vector3(scl[0], scl[1], scl[2]));
+    const worldMatrix = ancestorCtx.worldMatrix.clone().multiply(localMatrix);
+    // Create Three.js object — the Object3D IS the entity.
+    let object3d = new THREE.Group();
+    if (def.mesh) {
+        if (def.mesh.type === 'gltf' && def.mesh.src) {
+            // Load GLTF model
+            const { scene: gltfScene, animations } = await loadGLTF(def.mesh.src);
+            if (def.shadow?.enabled) {
+                gltfScene.traverse((child) => {
+                    if (child instanceof THREE.Mesh) {
+                        child.castShadow = true;
+                        child.receiveShadow = true;
+                    }
+                });
+            }
+            // F4 — mesh.node: resolve a single sub-node to instantiate as this
+            // entity's geometry instead of the whole file (shared geometry, no
+            // copy — see resolveGltfNode). Must run before import correction below
+            // so the correction applies to whatever we actually wrap.
+            let content = gltfScene;
+            if (def.mesh.node) {
+                content = resolveGltfNode(gltfScene, def.mesh.node, def.mesh.src);
+                // wrapper.add() below detaches `content` from the glTF hierarchy.
+                // Reset its local transform to identity — the entity's own transform
+                // (applied to `wrapper`) is the sole positioner; the node's offset
+                // within the source file's hierarchy is not carried over (this
+                // instantiates the node "as this entity's geometry", not as a
+                // placed sub-scene).
+                content.position.set(0, 0, 0);
+                content.rotation.set(0, 0, 0);
+                content.scale.set(1, 1, 1);
+            }
+            else if (def.mesh.lod?.length) {
+                // F7 — mesh.lod: multi-level distance-keyed glTF sub-node swap, gated
+                // by the environment.rendering.lod master toggle (per-entity cascade
+                // via resolveRenderSettings — the first real reader of that toggle).
+                // Mutually exclusive with `node`/`instances`/`instancer` (schema refine).
+                const lodOn = resolveRenderSettings(ctx.sceneRendering, def.render)['lod'] !== false;
+                const levels = [...def.mesh.lod].sort((a, b) => a.distance - b.distance);
+                if (lodOn) {
+                    const lod = new THREE.LOD();
+                    for (const level of levels) {
+                        const n = resolveGltfNode(gltfScene, level.node, def.mesh.src);
+                        n.position.set(0, 0, 0);
+                        n.rotation.set(0, 0, 0);
+                        n.scale.set(1, 1, 1);
+                        lod.addLevel(n, level.distance);
+                    }
+                    content = lod;
+                }
+                else {
+                    // Master gate off — degrade to the closest (highest-detail) level
+                    // only, no THREE.LOD.
+                    const closest = levels[0];
+                    const n = resolveGltfNode(gltfScene, closest.node, def.mesh.src);
+                    n.position.set(0, 0, 0);
+                    n.rotation.set(0, 0, 0);
+                    n.scale.set(1, 1, 1);
+                    content = n;
+                }
+            }
+            // Apply import correction from asset registry
+            const meta = getAssetMeta(def.mesh.src);
+            if (meta?.importCorrection) {
+                const ic = meta.importCorrection;
+                if (ic.scale !== undefined) {
+                    content.scale.multiplyScalar(ic.scale);
+                }
+                if (ic.rotation) {
+                    content.rotation.set(THREE.MathUtils.degToRad(ic.rotation[0]), THREE.MathUtils.degToRad(ic.rotation[1]), THREE.MathUtils.degToRad(ic.rotation[2]));
+                }
+            }
+            // Wrap in a group so entity transform and import correction are separated.
+            // `content` carries import correction; wrapper carries entity transform.
+            const wrapper = new THREE.Group();
+            wrapper.add(content);
+            object3d = wrapper;
+            // Set up animation if defined. Always build the mixer + clip map (and
+            // expose both via userData) whenever the entity has clips — not just
+            // when `autoplay` is set — so a GameComponent (e.g. an XState-driven
+            // character controller, E5's replacement for the removed AnimGraph) can
+            // pick up `_animMixer`/`_animClips` in its own `init()` and drive the
+            // SAME mixer via `bindXStateAnimation` (xstate-animation-binding.ts).
+            // Only `autoplay` self-ticks here (`tickFns`) — a component driving its
+            // own binding calls `mixer.update(dt)` itself (inside the binding's
+            // `tick`), so auto-ticking unconditionally would double-advance it.
+            if (def.animation && animations.length > 0) {
+                const clipMap = buildClipMap(animations, def.animation.clipAliases);
+                const mixer = new THREE.AnimationMixer(gltfScene);
+                setUserData(object3d, '_animMixer', mixer);
+                setUserData(object3d, '_animClips', clipMap);
+                setUserData(object3d, '_availableClips', [...clipMap.keys()]);
+                mixers.push(mixer);
+                if (def.animation.autoplay) {
+                    // Simple clip autoplay
+                    const clip = clipMap.get(def.animation.autoplay);
+                    if (clip) {
+                        const action = mixer.clipAction(clip);
+                        const loop = def.animation.loop ?? DEFAULTS.animation.loop;
+                        action.setLoop(loop ? THREE.LoopRepeat : THREE.LoopOnce, Infinity);
+                        action.clampWhenFinished = !loop;
+                        action.play();
+                        tickFns.push((dt) => mixer.update(dt));
+                    }
+                }
+            }
+        }
+        else {
+            const geometry = createGeometry(def.mesh);
+            const resolvedMat = await resolveMaterial(def, ctx);
+            const material = createMaterial(resolvedMat);
+            let mesh;
+            if (def.mesh.instances) {
+                // F3 — declarative/authored instancing: fetch+parse the referenced
+                // .instances.json and build one InstancedMesh from its tuples.
+                const tuples = await loadInstancesFile(def.mesh.instances, ctx);
+                mesh = buildInstancedMeshFromTuples(geometry, material, tuples);
+            }
+            else if (def.mesh.instancer) {
+                mesh = buildInstancedMesh(geometry, material, def.mesh.instancer, def.mesh.instancerParams ?? {});
+            }
+            else {
+                mesh = new THREE.Mesh(geometry, material);
+            }
+            if (def.shadow?.enabled) {
+                mesh.castShadow = true;
+                mesh.receiveShadow = true;
+            }
+            object3d = mesh;
+        }
+    }
+    if (def.light) {
+        const light = createLight(def.light);
+        if (def.shadow?.enabled && 'shadow' in light) {
+            const shadowLight = light;
+            shadowLight.castShadow = true;
+            // Default to DEFAULTS.shadow.mapSize (1024) rather than Three's 512 so the
+            // runtime matches the documented single-source default.
+            shadowLight.shadow.mapSize.setScalar(def.shadow.mapSize ?? DEFAULTS.shadow.mapSize);
+            if (def.shadow.camera) {
+                const cam = def.shadow.camera;
+                if (cam.left !== undefined)
+                    shadowLight.shadow.camera.left = cam.left;
+                if (cam.right !== undefined)
+                    shadowLight.shadow.camera.right = cam.right;
+                if (cam.top !== undefined)
+                    shadowLight.shadow.camera.top = cam.top;
+                if (cam.bottom !== undefined)
+                    shadowLight.shadow.camera.bottom = cam.bottom;
+            }
+            if (def.shadow.radius !== undefined) {
+                shadowLight.shadow.radius = def.shadow.radius;
+            }
+            if (def.shadow.bias !== undefined) {
+                shadowLight.shadow.bias = def.shadow.bias;
+            }
+        }
+        object3d = light;
+    }
+    if (def.camera) {
+        const camera = createCamera(def.camera);
+        // Wrap in a group so entity transform and camera are separated (same pattern as editor)
+        const wrapper = new THREE.Group();
+        wrapper.add(camera);
+        setUserData(wrapper, '_camera', camera);
+        object3d = wrapper;
+    }
+    // Audio source
+    if (def.audio && ctx.audioListener) {
+        const audioDef = def.audio;
+        const dAudio = DEFAULTS.audio;
+        const spatial = audioDef.spatial ?? dAudio.spatial;
+        const audioObj = spatial
+            ? new THREE.PositionalAudio(ctx.audioListener)
+            : new THREE.Audio(ctx.audioListener);
+        audioObj.setVolume(audioDef.volume ?? dAudio.volume);
+        audioObj.setLoop(audioDef.loop ?? dAudio.loop);
+        if (spatial && audioObj instanceof THREE.PositionalAudio) {
+            audioObj.setRefDistance(audioDef.refDistance ?? dAudio.refDistance);
+            audioObj.setRolloffFactor(audioDef.rolloffFactor ?? dAudio.rolloffFactor);
+            audioObj.setMaxDistance(audioDef.maxDistance ?? dAudio.maxDistance);
+        }
+        // R1c — track every THREE.Audio this spawn creates (when the caller
+        // supplied a tracker; only spawnPrefab's dispose() does) so dispose() can
+        // stop() it, and guard the async load callback so a still-in-flight
+        // AudioLoader request can't setBuffer/play on an already-disposed audio
+        // object (the callback captures `audioObj`, which outlives dispose() —
+        // Three.js gives no other hook to cancel an in-flight AudioLoader request).
+        audioTracker?.audios.push(audioObj);
+        if (audioDef.src) {
+            const loader = new THREE.AudioLoader(loadingManager);
+            loader.load(audioDef.src, (buffer) => {
+                if (audioTracker?.disposed.value)
+                    return;
+                audioObj.setBuffer(buffer);
+                if (audioDef.autoplay ?? dAudio.autoplay)
+                    audioObj.play();
+            });
+        }
+        object3d.add(audioObj);
+    }
+    // Particles — instantiate the three.quarks system and register it with the
+    // runtime BatchedRenderer (mirrors the editor entity-factory + scene-sync).
+    if (def.particles) {
+        try {
+            const { emitter, system } = createParticleSystemFromData(def.particles);
+            object3d.add(emitter);
+            setUserData(object3d, '_particleSystem', system);
+            if (ctx.particleRenderer)
+                ctx.particleRenderer.addSystem(system);
+        }
+        catch (err) {
+            log.scene.warn(`Failed to create particle system for entity "${def.name}"`, {
+                entityId: def.id,
+                error: String(err),
+            });
+        }
+    }
+    // Spline — build a CatmullRomCurve3 and stash it for gameplay code (path
+    // following, etc.). The editor renders an interactive gizmo for splines; at
+    // runtime the curve itself is the load-bearing artifact.
+    if (def.spline) {
+        const curve = createCurveFromSpline(def.spline);
+        if (curve)
+            setUserData(object3d, 'splineCurve', curve);
+    }
+    // Tag navigation role for runtime navmesh collection
+    if (def.navigation?.role) {
+        setUserData(object3d, 'navRole', def.navigation.role);
+    }
+    // Tag pivot for runtime code that needs to rotate/scale around it
+    if (def.pivot) {
+        setUserData(object3d, 'pivot', def.pivot);
+    }
+    // Tag entity metadata (used by editor hierarchy/inspector when viewing game
+    // scene, and by gameplay queries like queryByComponent/queryByTag which read
+    // component/tag names off `userData.entity`). Write `entity` unconditionally
+    // — NOT only when `def.id` is set: id-less prefab instances (e.g. the RTS
+    // units) still attach components (below), so gating entity metadata on `id`
+    // made those components undiscoverable by name.
+    //
+    // The scene schema declares `id` optional with "auto-generated if omitted",
+    // so `entityId` is unconditional too (auto-generating when absent) rather
+    // than skipped: without this, hand-authored scenes (which rarely carry ids)
+    // load into an EMPTY play-mode hierarchy even though they render fine. This
+    // mirrors the editor store, which fills missing ids on load
+    // (`if (!e.id) e.id = crypto.randomUUID()`). Populating idMap for every
+    // entity is safe — it's only read by joint-target resolution keyed on an
+    // authored `joint.target` id, which can't collide with a random UUID.
+    object3d.name = def.name;
+    if (!def.id)
+        def.id = crypto.randomUUID();
+    setUserData(object3d, 'entity', def);
+    setUserData(object3d, 'entityId', def.id);
+    if (idMap)
+        idMap.set(def.id, object3d);
+    // Apply transform
+    object3d.position.set(pos[0], pos[1], pos[2]);
+    object3d.quaternion.set(rot[0], rot[1], rot[2], rot[3]);
+    object3d.scale.set(scl[0], scl[1], scl[2]);
+    // Visibility (mirrors editor: visible unless explicitly false)
+    object3d.visible = def.visible ?? DEFAULTS.entity.visible;
+    // Physics — stores {body, collider} in the physics registry keyed by object3d.
+    // T1.1: the body is created at the COMPOSED WORLD transform (ancestorCtx's
+    // world matrix × this entity's own local transform), not the raw authored
+    // local transform — Rapier knows nothing about the Three.js parent chain.
+    if (def.physics) {
+        // R1c: this used to only throw for a "dynamic" child body — but a
+        // "fixed"/"kinematic" child nested under a moving (dynamic/kinematic)
+        // ancestor is equally unsupported: Rapier has no parent/child body
+        // relationship at all, so ANY nested body (whatever its own type) gets its
+        // world transform baked in ONCE at spawn time and then never follows the
+        // ancestor's body again — the transform writer only pins the child's
+        // VISUAL Object3D to its OWN (stale, non-moving) body pose, so both the
+        // mesh and collider silently fall behind the moving ancestor.
+        if (ancestorCtx.movingAncestor) {
+            throw new Error(`Entity "${entityLabel(def)}" has a "${def.physics.bodyType}" physics body nested under ` +
+                `"${ancestorCtx.movingAncestor.name}", which itself has a "${ancestorCtx.movingAncestor.bodyType}" ` +
+                `physics body. Rapier has no parent/child body relationship, so a moving ` +
+                `(dynamic/kinematic) ancestor cannot carry ANY nested physics body with it, regardless of ` +
+                `the nested body's own type — the child body's world position would immediately drift out ` +
+                `of sync with its visual parent. This configuration is unsupported: move ` +
+                `"${entityLabel(def)}" out from under "${ancestorCtx.movingAncestor.name}", or make the ` +
+                `ancestor's body "fixed" (a fixed/static ancestor's transform is fine to compose).`);
+        }
+        const worldPos = new THREE.Vector3();
+        const worldQuat = new THREE.Quaternion();
+        const worldScale = new THREE.Vector3();
+        worldMatrix.decompose(worldPos, worldQuat, worldScale);
+        createPhysicsBody(def.physics, [worldPos.x, worldPos.y, worldPos.z], [worldQuat.x, worldQuat.y, worldQuat.z, worldQuat.w], ctx, object3d, [worldScale.x, worldScale.y, worldScale.z], entityLabel(def));
+    }
+    // Apply custom GameComponents from scene data
+    if (def.components && ctx.componentRegistry && ctx.componentManager) {
+        applyComponents(ctx.componentRegistry, object3d, def.components, ctx.componentManager);
+    }
+    // Children — parent each child Object3D directly under this one. Threads the
+    // composed world matrix + nearest moving-ancestor (T1.1) down: a
+    // dynamic/kinematic body ON THIS entity becomes the nearest moving ancestor
+    // for its own children (overriding any further-up ancestor, since it's the
+    // closer/more relevant one to report); otherwise the existing ancestor
+    // context is passed through unchanged.
+    if (def.children) {
+        const childAncestorCtx = {
+            worldMatrix,
+            ...(def.physics &&
+                (def.physics.bodyType === 'dynamic' || def.physics.bodyType === 'kinematic')
+                ? { movingAncestor: { name: entityLabel(def), bodyType: def.physics.bodyType } }
+                : ancestorCtx.movingAncestor
+                    ? { movingAncestor: ancestorCtx.movingAncestor }
+                    : {}),
+        };
+        for (const childDef of def.children) {
+            const childObj = await spawnEntity(childDef, ctx, tickFns, mixers, idMap, childAncestorCtx, audioTracker);
+            object3d.add(childObj);
+        }
+    }
+    return object3d;
+}
+/** Find the first mesh geometry in an Object3D subtree (for trimesh colliders). */
+function findMeshGeometry(object3d) {
+    let geometry = null;
+    object3d.traverse((child) => {
+        if (!geometry && child instanceof THREE.Mesh && child.geometry) {
+            geometry = child.geometry;
+        }
+    });
+    return geometry;
+}
+function createPhysicsBody(physics, worldPos, worldRot, ctx, object3d, worldScale, label) {
+    const rapier = ctx.rapier;
+    // Create rigid body
+    let bodyDesc;
+    switch (physics.bodyType) {
+        case 'fixed':
+            bodyDesc = rapier.RigidBodyDesc.fixed();
+            break;
+        case 'kinematic':
+            bodyDesc = rapier.RigidBodyDesc.kinematicPositionBased();
+            break;
+        default:
+            bodyDesc = rapier.RigidBodyDesc.dynamic();
+            break;
+    }
+    bodyDesc.setTranslation(worldPos[0], worldPos[1], worldPos[2]);
+    bodyDesc.setRotation({ x: worldRot[0], y: worldRot[1], z: worldRot[2], w: worldRot[3] });
+    const body = ctx.rapierWorld.createRigidBody(bodyDesc);
+    // Create collider. T1.2: dimensions are baked from the entity's composed
+    // WORLD scale (self × ancestors) — Rapier colliders have no notion of a
+    // parent Object3D's scale, so this is what keeps the physical shape
+    // matching whatever's visually on screen (which scales for free via the
+    // normal Three.js hierarchy). See collider-dimensions.ts (shared with the
+    // editor's collider gizmo) for the exact per-type math + round-collider
+    // non-uniform-scale error.
+    let colliderDesc;
+    const col = physics.collider;
+    switch (col.type) {
+        case 'cuboid': {
+            const dims = computeColliderWorldDimensions(col, worldScale, label);
+            const he = dims.halfExtents;
+            colliderDesc = rapier.ColliderDesc.cuboid(he[0], he[1], he[2]);
+            break;
+        }
+        case 'ball': {
+            const dims = computeColliderWorldDimensions(col, worldScale, label);
+            colliderDesc = rapier.ColliderDesc.ball(dims.radius);
+            break;
+        }
+        case 'capsule': {
+            const dims = computeColliderWorldDimensions(col, worldScale, label);
+            colliderDesc = rapier.ColliderDesc.capsule(dims.halfHeight, dims.radius);
+            break;
+        }
+        case 'trimesh': {
+            // Build a triangle-mesh collider from the entity's own mesh geometry.
+            // NEVER silently fall back to a cuboid — wrong physics with no warning is
+            // a classic AI trap. If geometry isn't available we throw loudly.
+            const geometry = findMeshGeometry(object3d);
+            if (!geometry) {
+                throw new Error(`Entity "${object3d.name}" declares a "trimesh" collider but has no mesh geometry to build it from. ` +
+                    `Trimesh colliders require a mesh (primitive or GLTF) on the same entity.`);
+            }
+            const posAttr = geometry.getAttribute('position');
+            if (!posAttr) {
+                throw new Error(`Entity "${object3d.name}" declares a "trimesh" collider but its mesh geometry has no position attribute.`);
+            }
+            const vertices = new Float32Array(posAttr.array);
+            // T1.2: pre-scale vertices per-axis by the composed world scale — the
+            // geometry's raw vertex data is in local (unscaled) space.
+            for (let i = 0; i < vertices.length; i += 3) {
+                vertices[i] *= worldScale[0];
+                vertices[i + 1] *= worldScale[1];
+                vertices[i + 2] *= worldScale[2];
+            }
+            let indices;
+            if (geometry.index) {
+                indices = new Uint32Array(geometry.index.array);
+            }
+            else {
+                // Non-indexed geometry: every 3 consecutive vertices form a triangle.
+                indices = new Uint32Array(posAttr.count);
+                for (let i = 0; i < posAttr.count; i++)
+                    indices[i] = i;
+            }
+            colliderDesc = rapier.ColliderDesc.trimesh(vertices, indices);
+            break;
+        }
+        default:
+            colliderDesc = rapier.ColliderDesc.cuboid(0.5, 0.5, 0.5);
+    }
+    // Mass precedence: an explicit `physics.mass` always wins. When mass is set we
+    // skip setDensity entirely, otherwise Rapier's later setDensity would recompute
+    // (and silently defeat) the requested mass.
+    if (physics.mass !== undefined) {
+        colliderDesc.setMass(physics.mass);
+    }
+    if (col.friction !== undefined) {
+        colliderDesc.setFriction(col.friction);
+    }
+    if (col.restitution !== undefined) {
+        colliderDesc.setRestitution(col.restitution);
+    }
+    if (col.density !== undefined && physics.mass === undefined) {
+        colliderDesc.setDensity(col.density);
+    }
+    // T1.2/R1c: the offset is a physics-engine translation with no notion of the
+    // parent Object3D's scale (same reasoning as the dimensions above) — scale it
+    // by the entity's composed world scale, or it silently drifts off its visual
+    // anchor point under any non-1 scale.
+    const worldOffset = computeColliderWorldOffset(col.offset, worldScale);
+    if (worldOffset) {
+        colliderDesc.setTranslation(worldOffset[0], worldOffset[1], worldOffset[2]);
+    }
+    if (col.isSensor) {
+        colliderDesc.setSensor(true);
+    }
+    // All scene-loaded colliders opt into collision events — sensors need them for
+    // onTriggerEnter/onTriggerExit, and solid colliders need them for onCollision
+    // (matches the world2d loader's unconditional setActiveEvents; see T1.3).
+    colliderDesc.setActiveEvents(rapier.ActiveEvents.COLLISION_EVENTS);
+    if (col.collisionGroups !== undefined || col.collisionFilter !== undefined) {
+        const groups = col.collisionGroups ?? 0xffff;
+        const filter = col.collisionFilter ?? 0xffff;
+        colliderDesc.setCollisionGroups((groups << 16) | filter);
+    }
+    const collider = ctx.rapierWorld.createCollider(colliderDesc, body);
+    // Register in the physics registry: object3d → {body, collider} and the
+    // colliderHandle → object3d reverse index (used for collision/trigger dispatch).
+    ctx.physics.add(object3d, body, collider);
+}
+/** Walk all entities in a scene tree recursively. */
+function walkEntities(entities, fn) {
+    for (const e of entities) {
+        fn(e);
+        if (e.children)
+            walkEntities(e.children, fn);
+    }
+}
+/** Reparent scene-authored entities to named bones/sockets in loaded GLTF skeletons. */
+function resolveBoneAttachments(entities, idMap) {
+    walkEntities(entities, (def) => {
+        const attachment = def.boneAttachment;
+        if (!attachment || !def.id)
+            return;
+        const object = idMap.get(def.id);
+        if (!object)
+            return;
+        const target = idMap.get(attachment.target);
+        if (!target) {
+            throw new Error(`Bone attachment target "${attachment.target}" not found for entity "${entityLabel(def)}".`);
+        }
+        if (target === object) {
+            throw new Error(`Entity "${entityLabel(def)}" cannot attach to its own skeleton.`);
+        }
+        const socket = target.getObjectByName(attachment.bone);
+        if (!socket) {
+            const available = [];
+            target.traverse((node) => {
+                if (node.name && node instanceof THREE.Bone) {
+                    available.push(node.name);
+                }
+            });
+            const suffix = available.length > 0 ? ` Available bones: ${available.sort().join(', ')}` : '';
+            throw new Error(`Bone/socket "${attachment.bone}" was not found on target "${attachment.target}" for entity "${entityLabel(def)}".${suffix}`);
+        }
+        socket.add(object);
+    });
+}
+/** Create Rapier joints for all entities that define them. */
+function createSceneJoints(entities, idMap, ctx) {
+    const rapier = ctx.rapier;
+    walkEntities(entities, (def) => {
+        if (!def.joints || !def.id)
+            return;
+        const objA = idMap.get(def.id);
+        if (!objA)
+            return;
+        const bodyA = ctx.physics.get(objA)?.body;
+        if (!bodyA)
+            return;
+        for (const joint of def.joints) {
+            const targetObj = idMap.get(joint.target);
+            if (!targetObj) {
+                log.scene.warn(`Joint target "${joint.target}" not found for entity "${def.name}"`, {
+                    entityId: def.id,
+                });
+                continue;
+            }
+            const bodyB = ctx.physics.get(targetObj)?.body;
+            if (!bodyB)
+                continue;
+            const a1 = joint.anchor ?? [0, 0, 0];
+            const a2 = joint.targetAnchor ?? [0, 0, 0];
+            const anchor1 = { x: a1[0], y: a1[1], z: a1[2] };
+            const anchor2 = { x: a2[0], y: a2[1], z: a2[2] };
+            let params;
+            switch (joint.type) {
+                case 'fixed': {
+                    const frame1 = { x: 0, y: 0, z: 0, w: 1 };
+                    const frame2 = { x: 0, y: 0, z: 0, w: 1 };
+                    params = rapier.JointData.fixed(anchor1, frame1, anchor2, frame2);
+                    break;
+                }
+                case 'revolute': {
+                    const ax = joint.axis ?? [0, 1, 0];
+                    params = rapier.JointData.revolute(anchor1, anchor2, { x: ax[0], y: ax[1], z: ax[2] });
+                    if (joint.limits) {
+                        const deg2rad = Math.PI / 180;
+                        const lp = params;
+                        lp.limitsEnabled = true;
+                        lp.limits = [joint.limits.min * deg2rad, joint.limits.max * deg2rad];
+                    }
+                    break;
+                }
+                case 'prismatic': {
+                    const ax = joint.axis ?? [0, 1, 0];
+                    params = rapier.JointData.prismatic(anchor1, anchor2, { x: ax[0], y: ax[1], z: ax[2] });
+                    if (joint.limits) {
+                        const lp = params;
+                        lp.limitsEnabled = true;
+                        lp.limits = [joint.limits.min, joint.limits.max];
+                    }
+                    break;
+                }
+                case 'spherical':
+                    params = rapier.JointData.spherical(anchor1, anchor2);
+                    break;
+                case 'spring': {
+                    const rest = joint.restLength ?? 1;
+                    const stiff = joint.stiffness ?? 10;
+                    const damp = joint.damping ?? 1;
+                    params = rapier.JointData.spring(rest, stiff, damp, anchor1, anchor2);
+                    break;
+                }
+                default:
+                    continue;
+            }
+            ctx.rapierWorld.createImpulseJoint(params, bodyA, bodyB, true);
+        }
+    });
+}
+/**
+ * F6 (`docs/VSCN-STRUCTURAL-GAPS-DESIGN.md`) — resolve `EntityRefSchema`
+ * component fields from the authored string id to the live `Object3D`.
+ *
+ * Modeled directly on `createSceneJoints` above (same walk, same `idMap`,
+ * same "missing target" shape) — the difference is WHAT gets resolved
+ * (a component field, discovered via the component's own static schema)
+ * and HOW a miss is handled: a joint with a missing target logs a warning
+ * and skips it; a missing entity-ref id is a loud load error (throw) per
+ * the design doc's AC, because a component that expects a live `Object3D`
+ * at `init()` cannot safely run with a dangling string in that field.
+ *
+ * Must run AFTER every entity is spawned (idMap is complete — components are
+ * attached during spawn too, so by this point every instance's ref field
+ * still holds its raw authored string id) and BEFORE
+ * `componentManager.initAll()`, so `init()` observes the resolved
+ * `Object3D`, not the string. Resolves through the SAME `idMap`
+ * `createSceneJoints` uses — no new registry (G3).
+ */
+export function resolveEntityRefs(entities, idMap, manager) {
+    walkEntities(entities, (def) => {
+        if (!def.id || !def.components)
+            return;
+        const node = idMap.get(def.id);
+        if (!node)
+            return;
+        for (const inst of manager.getComponents(node)) {
+            const schema = inst.constructor.schema;
+            if (!schema)
+                continue;
+            for (const [field, fieldSchema] of Object.entries(schema.shape)) {
+                if (!isEntityRefSchema(fieldSchema))
+                    continue;
+                const record = inst;
+                const value = record[field];
+                // Optional ref, not authored on this instance — nothing to resolve.
+                if (value === undefined)
+                    continue;
+                if (typeof value !== 'string' || value.length === 0)
+                    continue;
+                const resolved = idMap.get(value);
+                if (!resolved) {
+                    throw new Error(`Entity ref "${field}" on component "${inst.constructor.name}" (entity ` +
+                        `"${entityLabel(def)}") points at missing entity id "${value}".`);
+                }
+                record[field] = resolved;
+            }
+        }
+    });
+}
+/** Fetch and cache a .mat.json file. Validated via Zod (T4.6) — a malformed material asset
+ * throws a `SceneParseError` naming the file, not a deep TypeError once the bad data reaches
+ * material-factory.ts. */
+async function loadMaterialFile(url, ctx) {
+    if (!ctx.materialFileCache)
+        ctx.materialFileCache = new Map();
+    const cached = ctx.materialFileCache.get(url);
+    if (cached)
+        return cached;
+    const res = await fetch(resolveUrl(url));
+    if (!res.ok)
+        throw new Error(`Failed to load material: ${url} (${res.status})`);
+    const data = parseMaterialFile(await res.json(), url);
+    ctx.materialFileCache.set(url, data);
+    return data;
+}
+/** Fetch and cache a .instances.json file (F3). Validated via Zod — a malformed instance-
+ * transform asset throws a `SceneParseError` naming the file. */
+async function loadInstancesFile(url, ctx) {
+    if (!ctx.instancesFileCache)
+        ctx.instancesFileCache = new Map();
+    const cached = ctx.instancesFileCache.get(url);
+    if (cached)
+        return cached;
+    const res = await fetch(resolveUrl(url));
+    if (!res.ok)
+        throw new Error(`Failed to load instances: ${url} (${res.status})`);
+    const data = parseInstancesFile(await res.json(), url);
+    ctx.instancesFileCache.set(url, data);
+    return data;
+}
+/** Resolve material for an entity — load from .mat.json ref or use inline material. */
+async function resolveMaterial(def, ctx) {
+    if (def.materialRef) {
+        try {
+            const file = await loadMaterialFile(def.materialRef, ctx);
+            return file.material;
+        }
+        catch (err) {
+            log.scene.warn(`Failed to load material ref: ${def.materialRef}`, {
+                entityId: def.id,
+                error: String(err),
+            });
+            return def.material;
+        }
+    }
+    return def.material;
+}
+/** Fetch and cache a .prefab.json file. Validated via Zod (T4.6) — a malformed prefab file
+ * throws a `SceneParseError` naming the file, not a deep TypeError once the bad data reaches
+ * spawnEntity. */
+async function loadPrefabFile(url, ctx) {
+    if (!ctx.prefabFileCache)
+        ctx.prefabFileCache = new Map();
+    const cached = ctx.prefabFileCache.get(url);
+    if (cached)
+        return cached;
+    const res = await fetch(resolveUrl(url));
+    if (!res.ok)
+        throw new Error(`Failed to load prefab: ${url} (${res.status})`);
+    const data = parsePrefabFile(await res.json(), url);
+    ctx.prefabFileCache.set(url, data);
+    return data;
+}
+/**
+ * Spawn a prefab instance at runtime from gameplay code.
+ *
+ * Returns a {@link SpawnedPrefab}. The previous version passed throwaway
+ * tickFns/mixers arrays, so a runtime-spawned prefab's `animation.autoplay`
+ * never advanced. Now the tick functions are captured and exposed via
+ * `update()`, consistent with how loadScene's SceneInstance.update drives
+ * animations.
+ *
+ * Usage:
+ *   const crate = await spawnPrefab('/data/prefabs/crate.prefab.json', ctx, {
+ *     transform: { position: [x, y, z] },
+ *     components: { Health: { current: 50 } },
+ *   });
+ *   // each frame (only needed for autoplay clips):
+ *   crate.update(dt);
+ */
+export async function spawnPrefab(prefabUrl, ctx, overrides) {
+    const instance = {
+        name: 'Instance',
+        prefab: prefabUrl,
+        ...overrides,
+    };
+    const tickFns = [];
+    const mixers = [];
+    const audioTracker = { audios: [], disposed: { value: false } };
+    const object3D = await spawnEntity(instance, ctx, tickFns, mixers, undefined, ROOT_ANCESTOR_CONTEXT, audioTracker);
+    ctx.scene.add(object3D);
+    // Run init() on any GameComponents the prefab attached. attach() only queues
+    // them in pendingInit + the per-phase tick list; without this, update() fires
+    // every frame while init() never runs (mirrors loadScene's pass-3 initAll).
+    if (ctx.componentManager)
+        await ctx.componentManager.initAll();
+    return {
+        object3D,
+        update(dt) {
+            for (const fn of tickFns)
+                fn(dt);
+        },
+        // ---------------------------------------------------------------------
+        // R1c CLASS INVENTORY — everything spawnEntity can register into a
+        // `ctx` map/system/registry for a spawned subtree, and what dispose()
+        // below does about each one. (This is the acceptance criterion for the
+        // "spawnPrefab().dispose() completeness" task — keep it in sync with
+        // spawnEntity whenever a new registration point is added.)
+        //
+        //  - ctx.physics (Object3D -> {body, collider})   DISPOSED — root AND
+        //    every nested descendant's Rapier body is removed from the world
+        //    AND the registry (pre-existing, T1.4).
+        //  - ctx.componentManager (GameComponent instances)   DISPOSED —
+        //    detach() runs on root + every descendant, firing each component's
+        //    own dispose() and stopping its tick (pre-existing, T1.4).
+        //  - mixers (THREE.AnimationMixer, simple `animation.autoplay` clips)
+        //    DISPOSED — stopAllAction() on every mixer this spawn created
+        //    (pre-existing).
+        //  - tickFns (standalone `animation.autoplay` mixer tick closures)
+        //    DISPOSED — array cleared so update() becomes a no-op (pre-existing).
+        //  - ctx.particleRenderer (three.quarks BatchedRenderer, when provided)
+        //    NEWLY-DISPOSED — every particle system tagged via the
+        //    `_particleSystem` userData key (mirrors editor scene-sync's own
+        //    registration convention) anywhere in the subtree is removed with
+        //    `deleteSystem` (probe1: previously kept rendering/simulating after
+        //    the visual object was gone).
+        //  - THREE.Audio/PositionalAudio objects (added as children of entities
+        //    with `def.audio`)   NEWLY-DISPOSED — every audio object this spawn
+        //    created is `stop()`-ed, AND the `disposed` flag is set so a
+        //    still-in-flight `AudioLoader.load()` callback (which captures the
+        //    audio object and can resolve after dispose()) skips setBuffer/play
+        //    instead of reviving already-torn-down audio.
+        //  - `entity`/`entityId`/`navRole`/`pivot`/`splineCurve`/`_camera`
+        //    userData tags   DELIBERATELY NOT DISPOSED — these are plain data
+        //    tags on Object3Ds that get garbage-collected with the subtree once
+        //    `ctx.scene.remove(object3D)` drops the last reference; there is no
+        //    separate ctx-level registry entry to leak.
+        //  - GLTF/texture asset caches (asset-loaders.ts, module-level)
+        //    DELIBERATELY NOT DISPOSED — these are shared, URL-keyed caches
+        //    across the whole runtime session (P1.8 contract: repeated
+        //    spawns/loads of the same asset must NOT re-fetch or re-parse), not
+        //    per-spawn state; they're only released by `clearAssetCaches()` on
+        //    full runtime teardown.
+        // ---------------------------------------------------------------------
+        dispose() {
+            // Detach components on the root AND every descendant (a prefab tree can
+            // attach components anywhere, not just at the root) — fires each
+            // instance's dispose() + stops it ticking.
+            object3D.traverse((node) => {
+                ctx.componentManager?.detach(node);
+            });
+            // Remove any Rapier bodies this prefab tree created (root or nested) from
+            // both the physics world and the physics registry — otherwise the body
+            // keeps simulating/colliding after the visual object is gone (orphan body).
+            object3D.traverse((node) => {
+                const refs = ctx.physics.get(node);
+                if (!refs)
+                    return;
+                ctx.rapierWorld.removeRigidBody(refs.body);
+                ctx.physics.remove(node);
+            });
+            // Unregister any particle systems this subtree registered with the
+            // shared BatchedRenderer — otherwise they keep simulating/rendering
+            // after the visual object is gone. `_particleSystem` is the same
+            // userData tag the editor's scene-sync uses for the same purpose.
+            if (ctx.particleRenderer) {
+                const particleRenderer = ctx.particleRenderer;
+                object3D.traverse((node) => {
+                    const system = getUserData(node, '_particleSystem');
+                    if (!system)
+                        return;
+                    try {
+                        particleRenderer.deleteSystem(system);
+                    }
+                    catch {
+                        // Already removed — nothing left to do.
+                    }
+                });
+            }
+            // Stop every THREE.Audio/PositionalAudio object this spawn created, and
+            // flag `disposed` so an AudioLoader request still in flight (its
+            // callback captured `audioObj`, which outlives this dispose() call)
+            // skips setBuffer/play on audio that's already torn down.
+            audioTracker.disposed.value = true;
+            for (const audio of audioTracker.audios)
+                audio.stop();
+            ctx.scene.remove(object3D);
+            for (const mixer of mixers)
+                mixer.stopAllAction();
+            tickFns.length = 0;
+            mixers.length = 0;
+        },
+    };
+}