@vgai/engine 0.5.0 → 0.5.2

package/dist/scene/scene-loader.js

@@ -1,1211 +0,0 @@
-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 { applyImportCorrection, 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,
-        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
-            applyImportCorrection(content, getAssetMeta(def.mesh.src)?.importCorrection);
-            // 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);
-        // Rapier's DEFAULT omits every non-dynamic pair. Player characters are
-        // commonly position-based kinematic bodies and authored pickups commonly
-        // use fixed sensors, so DEFAULT makes the pair invisible to the physics
-        // event queue even after the KCC correctly excludes sensors from movement
-        // blocking. A sensor's contract is observation, not contact response:
-        // enable every body-type pair so real overlaps consistently reach
-        // onTriggerEnter/Exit.
-        colliderDesc.setActiveCollisionTypes(rapier.ActiveCollisionTypes.ALL);
-    }
-    // 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;
-        },
-    };
-}