@vgai/engine 0.2.0

package/src/scene/scene-loader.ts

@@ -0,0 +1,1533 @@
+import type RAPIER from '@dimforge/rapier3d-compat';
+import * as THREE from 'three';
+import { RGBELoader } from 'three/addons/loaders/RGBELoader.js';
+import type { BatchedRenderer } from 'three.quarks';
+import { initNavigation, NavMeshManager } from '../ai/navigation';
+import { AnimGraph } from '../animation/anim-graph';
+import { PropertyTrackRunner } from '../animation/property-track';
+import { log } from '../dev/logger';
+import type { ComponentManager } from '../ecs/component-manager';
+import type { GameComponentClass } from '../ecs/game-component';
+import { loadingManager, resolveUrl } from '../loader';
+import type { PhysicsRegistry } from '../physics/physics-registry';
+import { type RenderScope, resolveRenderSettings } from '../render/render-settings';
+import {
+  assetCacheSizes,
+  clearAssetCaches as clearSharedAssetCaches,
+  loadAnimGraphData,
+  loadGLTF,
+  resolveGltfNode,
+} from './asset-loaders';
+import { getAssetMeta, loadRegistry } from './asset-registry';
+import { computeColliderWorldDimensions, computeColliderWorldOffset } from './collider-dimensions';
+import { applyComponents, type ComponentRegistry } 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 {
+  type InstancesFile,
+  type MaterialFile,
+  mergePrefabInstance,
+  type PrefabFile,
+  type SceneEntity,
+  type SceneEnvironment,
+  type SceneFile,
+  type SceneMaterial,
+  type ScenePhysics,
+  type SceneSpline,
+  type UIRoot,
+} from './scene-types';
+import { isEntityRefSchema } from './schema/entity-ref';
+import { getUserData, setUserData } from './user-data';
+
+// GLTF / texture / animgraph 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<string, THREE.Texture>();
+let pmremGenerator: THREE.PMREMGenerator | null = null;
+
+/**
+ * Clear module-level asset caches (textures, GLTF scenes, anim graphs, IBL env
+ * maps). Call on full runtime teardown to release cached GPU resources and avoid
+ * leaking across editor Play sessions. Delegates the GLTF/texture/animgraph
+ * 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(): void {
+  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: THREE.Scene, camera: THREE.Camera): void {
+  scene.traverse((o) => {
+    if ((o as THREE.LOD).isLOD) (o as THREE.LOD).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(): {
+  textures: number;
+  gltf: number;
+  animGraphs: number;
+  env: number;
+} {
+  const sizes = assetCacheSizes();
+  return {
+    textures: sizes.textures,
+    gltf: sizes.gltf,
+    animGraphs: sizes.animGraphs,
+    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: string, env: SceneEnvironment, ctx: SceneLoadContext): void {
+  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: string,
+  renderer: THREE.WebGLRenderer,
+): Promise<THREE.Texture | null> {
+  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: SceneSpline): THREE.CatmullRomCurve3 | null {
+  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,
+  );
+}
+
+function buildClipMap(
+  animations: THREE.AnimationClip[],
+  aliases?: Record<string, string>,
+): Map<string, THREE.AnimationClip> {
+  const clips = new Map<string, THREE.AnimationClip>();
+  for (const clip of animations) {
+    const raw = clip.name.split('|').pop()?.toLowerCase() ?? clip.name;
+    const name = aliases?.[raw] ?? raw;
+    clips.set(name, clip);
+  }
+  return clips;
+}
+
+export interface SceneLoadContext {
+  scene: THREE.Scene;
+  rapierWorld: RAPIER.World;
+  rapier: typeof RAPIER;
+  /** Object3D ↔ Rapier body/collider registry (keys physics by the Object3D). */
+  physics: PhysicsRegistry;
+  prefabs?: Map<string, (ctx: SceneLoadContext, entity: SceneEntity) => THREE.Object3D>;
+  componentRegistry?: ComponentRegistry;
+  /** Cache for loaded .prefab.json files. Populated on first reference, cleared per scene load. */
+  prefabFileCache?: Map<string, PrefabFile>;
+  /** Cache for loaded .mat.json files. Populated on first reference. */
+  materialFileCache?: Map<string, MaterialFile>;
+  /** Cache for loaded .instances.json files. Populated on first reference (F3). */
+  instancesFileCache?: Map<string, InstancesFile>;
+  /** Supply an AudioListener (attached to camera) to enable audio entity spawning. */
+  audioListener?: THREE.AudioListener;
+  /** AnimGraph registry keyed by Object3D. If provided, loader registers created
+   *  AnimGraphs here (and skips tickFns to avoid double-ticking with the global
+   *  animationSystem). */
+  animGraphs?: Map<THREE.Object3D, AnimGraph>;
+  /** ComponentManager for instantiating GameComponent classes from scene data. */
+  componentManager?: ComponentManager;
+  /** three.quarks BatchedRenderer. If provided, particle systems declared on
+   *  entities are registered here so they render (mirrors the editor). */
+  particleRenderer?: BatchedRenderer;
+  /** WebGLRenderer. Required for skybox/IBL (PMREM). Absent in headless tests,
+   *  where the skybox load is skipped rather than substituting a placeholder. */
+  renderer?: THREE.WebGLRenderer;
+  /** Scene-level render-feature overrides (`environment.rendering`), populated by
+   *  `instantiateScene` once `data.environment` is known. Read by the F7 mesh.lod
+   *  master-gate check (`resolveRenderSettings(ctx.sceneRendering, def.render)`). */
+  sceneRendering?: RenderScope;
+}
+
+/** Handle returned from loadScene — call update() each frame to tick animations. */
+export interface SceneInstance {
+  update(dt: number): void;
+  dispose(): void;
+  /** Pre-baked navmesh loaded from sibling .navmesh file, if present. */
+  navMesh?: NavMeshManager | undefined;
+  /** Cameras defined in the scene file. First entry is typically the "main" camera. */
+  cameras: THREE.Camera[];
+  /** Parsed scene environment, if any — lets the runtime apply post-processing
+   *  (which needs the composer/camera the loader doesn't have). */
+  environment?: SceneEnvironment | undefined;
+  /**
+   * The scene file's top-level `ui` tree (React UI roots/canvases, A1),
+   * carried through verbatim from the parsed `SceneFile` by BOTH `loadScene`
+   * and `loadSceneFromData` (single source of truth — R8 item 7 / B). Opaque
+   * to the loader itself; the adapter passes it to `renderSceneUI` (the
+   * injected React renderer) so scenePath and sceneData mounts render the
+   * SAME scene-authored UI instead of only the sceneData branch special-
+   * casing it. `undefined` when the scene file has no `ui` field.
+   */
+  ui?: UIRoot[] | undefined;
+  /**
+   * Authored entity id -> spawned Object3D (design/24-scene-ui.md D5). The
+   * SAME map `spawnEntity`/`createSceneJoints` build internally (id-less
+   * entities are auto-UUID'd before insertion, so every spawned entity has an
+   * entry) -- exposed so the scene adapter's default `worldProjector` can
+   * resolve a `trackEntity` id to a live Object3D without a second id
+   * registry. Both `loadScene` and `loadSceneFromData` funnel through the one
+   * `instantiateScene` return site, so this is populated identically for both.
+   */
+  entities: ReadonlyMap<string, THREE.Object3D>;
+}
+
+/**
+ * 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: string, ctx: SceneLoadContext): Promise<SceneInstance> {
+  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: SceneFile,
+  ctx: SceneLoadContext,
+): Promise<SceneInstance> {
+  return instantiateScene(data, ctx);
+}
+
+/**
+ * World-transform context threaded down through `spawnEntity` recursion (T1.1).
+ *
+ * `spawnEntity` builds Object3Ds top-down but only parents a child under its
+ * Object3D AFTER the child is fully constructed (see the `children` loop
+ * below) — so a nested entity's `object3d.parent` chain doesn't exist yet at
+ * the moment its own Rapier body would be created, and Three's normal
+ * `getWorldPosition`/`matrixWorld` machinery isn't available. This context
+ * carries the composed ancestor world matrix (position/rotation/scale, built
+ * the same way any correct implementation must: parent world matrix × this
+ * entity's own local matrix) so `createPhysicsBody` can place bodies at the
+ * true world transform instead of the raw authored local transform.
+ */
+interface AncestorPhysicsContext {
+  /** Composed world matrix of the parent chain (identity at the scene root). */
+  worldMatrix: THREE.Matrix4;
+  /** Nearest ancestor with a dynamic/kinematic physics body, if any — used for
+   *  the "moving parent" loud-error check (a dynamic body nested under one of
+   *  these is unsupported: Rapier has no parent/child body relationship, so a
+   *  moving ancestor cannot carry a nested dynamic body with it). */
+  movingAncestor?: { name: string; bodyType: string };
+}
+
+const ROOT_ANCESTOR_CONTEXT: AncestorPhysicsContext = { worldMatrix: new THREE.Matrix4() };
+
+/**
+ * Minimal shape needed to stop a spawned `THREE.Audio`/`THREE.PositionalAudio`
+ * on dispose (R1c). Kept as a tiny duck-typed interface rather than
+ * `THREE.Audio` itself — `PositionalAudio extends Audio<PannerNode>` while
+ * plain `Audio` defaults its generic to `GainNode`, so the two concrete
+ * classes aren't mutually assignable as `THREE.Audio[]`; `stop()` doesn't
+ * depend on that generic at all, so a duck type sidesteps the mismatch.
+ */
+interface DisposableAudio {
+  stop(delay?: number): unknown;
+}
+
+/**
+ * Threaded through `spawnEntity`'s recursion (R1c, `spawnPrefab().dispose()`
+ * completeness — see the CLASS INVENTORY comment above `spawnPrefab`) so a
+ * runtime-spawned prefab's dispose() can stop every `THREE.Audio` it created,
+ * and so the audio-loading network callback (which may still be in flight
+ * when dispose() runs) can check `disposed` before touching an audio object
+ * that's already been torn down. `undefined` for `loadScene`/`loadSceneFromData`
+ * call sites — full SceneInstance teardown doesn't dispose individual audio
+ * objects (out of scope here; see SceneInstance.dispose in `instantiateScene`).
+ */
+interface AudioTracker {
+  audios: DisposableAudio[];
+  disposed: { value: boolean };
+}
+
+/** Human-readable entity identifier for error messages (loud-failure naming). */
+function entityLabel(def: SceneEntity): string {
+  return def.id ? `${def.name} (id: "${def.id}")` : def.name;
+}
+
+// ---------------------------------------------------------------------------
+// T3.9 — bounded-concurrency asset prefetch.
+//
+// Child/asset fetches (prefab files, materials, GLTF models, animgraphs) 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/animgraph
+// caches, 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: Array<() => Promise<unknown>>, limit: number): Promise<void> {
+  let next = 0;
+  async function worker(): Promise<void> {
+    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: SceneEntity,
+  ctx: SceneLoadContext,
+  tasks: Array<() => Promise<unknown>>,
+  seenPrefabUrls: Set<string>,
+): void {
+  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.animation?.animGraph) {
+    const graph = def.animation.animGraph;
+    tasks.push(() => loadAnimGraphData(graph));
+  }
+  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: SceneFile,
+  ctx: SceneLoadContext,
+  url?: string,
+): Promise<SceneInstance> {
+  const tickFns: ((dt: number) => void)[] = [];
+  const mixers: THREE.AnimationMixer[] = [];
+
+  // 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: Array<() => Promise<unknown>> = [];
+  const seenPrefabUrls = new Set<string>();
+  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 as RenderScope;
+  }
+
+  // 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<string, THREE.Object3D>();
+
+  for (const entityDef of data.entities) {
+    const obj = await spawnEntity(entityDef, ctx, tickFns, mixers, idMap);
+    ctx.scene.add(obj);
+  }
+
+  // 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: NavMeshManager | undefined;
+  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: THREE.Camera[] = [];
+  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: number) {
+      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: SceneEntity,
+  ctx: SceneLoadContext,
+  tickFns: ((dt: number) => void)[],
+  mixers: THREE.AnimationMixer[],
+  idMap?: Map<string, THREE.Object3D>,
+  ancestorCtx: AncestorPhysicsContext = ROOT_ANCESTOR_CONTEXT,
+  audioTracker?: AudioTracker,
+): Promise<THREE.Object3D> {
+  // 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: THREE.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: THREE.Object3D = 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 as RenderScope | undefined)[
+            '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
+      if (def.animation && animations.length > 0) {
+        const clipMap = buildClipMap(animations, def.animation.clipAliases);
+
+        if (def.animation.animGraph) {
+          // Full AnimGraph state machine
+          const graphData = await loadAnimGraphData(def.animation.animGraph);
+          const mixer = new THREE.AnimationMixer(gltfScene);
+          const graph = new AnimGraph(mixer, graphData, clipMap);
+          if (def.animation.parameters) {
+            for (const [key, value] of Object.entries(def.animation.parameters)) {
+              graph.setParameter(key, value);
+            }
+          }
+          if (ctx.animGraphs) {
+            // Register in global map (keyed by Object3D); animationSystem ticks it.
+            ctx.animGraphs.set(object3d, graph);
+          } else {
+            // Standalone: tick via scene instance update
+            tickFns.push((dt) => graph.update(dt));
+          }
+          mixers.push(mixer);
+        } else if (def.animation.autoplay) {
+          // Simple clip autoplay
+          const clip = clipMap.get(def.animation.autoplay);
+          if (clip) {
+            const mixer = new THREE.AnimationMixer(gltfScene);
+            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));
+            mixers.push(mixer);
+          }
+        }
+      }
+    } else {
+      const geometry = createGeometry(def.mesh);
+      const resolvedMat = await resolveMaterial(def, ctx);
+      const material = createMaterial(resolvedMat);
+      let mesh: THREE.Mesh | THREE.InstancedMesh;
+      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 as THREE.DirectionalLight;
+      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;
+
+  // F5 — declarative property tracks (docs/VSCN-STRUCTURAL-GAPS-DESIGN.md).
+  // Unlike gltf autoplay/animGraph above (clip-driven, gltf-only), tracks work
+  // on ANY entity — a box, a light, no gltf/clips required — so this lives
+  // OUTSIDE the gltf branch. Registered in the same tickFns list the
+  // AnimationMixers use, so it ticks on the same deterministic dt (honors
+  // pause/timeScale for free — no new clock).
+  if (def.animation?.tracks?.length) {
+    const runner = new PropertyTrackRunner(object3d, def.animation.tracks);
+    tickFns.push((dt) => runner.update(dt));
+  }
+
+  // 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: AncestorPhysicsContext = {
+      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: THREE.Object3D): THREE.BufferGeometry | null {
+  let geometry: THREE.BufferGeometry | null = null;
+  object3d.traverse((child) => {
+    if (!geometry && child instanceof THREE.Mesh && child.geometry) {
+      geometry = child.geometry;
+    }
+  });
+  return geometry;
+}
+
+function createPhysicsBody(
+  physics: ScenePhysics,
+  worldPos: [number, number, number] | number[],
+  worldRot: [number, number, number, number] | number[],
+  ctx: SceneLoadContext,
+  object3d: THREE.Object3D,
+  worldScale: readonly [number, number, number],
+  label: string,
+): void {
+  const rapier = ctx.rapier;
+
+  // Create rigid body
+  let bodyDesc: RAPIER.RigidBodyDesc;
+  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: RAPIER.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: Uint32Array;
+      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: SceneEntity[], fn: (e: SceneEntity) => void): void {
+  for (const e of entities) {
+    fn(e);
+    if (e.children) walkEntities(e.children, fn);
+  }
+}
+
+/** Create Rapier joints for all entities that define them. */
+function createSceneJoints(
+  entities: SceneEntity[],
+  idMap: Map<string, THREE.Object3D>,
+  ctx: SceneLoadContext,
+): void {
+  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: RAPIER.JointData;
+      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 as typeof params & {
+              limitsEnabled: boolean;
+              limits: [number, number];
+            };
+            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 as typeof params & {
+              limitsEnabled: boolean;
+              limits: [number, number];
+            };
+            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: SceneEntity[],
+  idMap: Map<string, THREE.Object3D>,
+  manager: ComponentManager,
+): void {
+  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 as GameComponentClass).schema;
+      if (!schema) continue;
+
+      for (const [field, fieldSchema] of Object.entries(schema.shape)) {
+        if (!isEntityRefSchema(fieldSchema)) continue;
+
+        const record = inst as unknown as Record<string, unknown>;
+        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: string, ctx: SceneLoadContext): Promise<MaterialFile> {
+  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: string, ctx: SceneLoadContext): Promise<InstancesFile> {
+  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: SceneEntity,
+  ctx: SceneLoadContext,
+): Promise<SceneMaterial | undefined> {
+  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: string, ctx: SceneLoadContext): Promise<PrefabFile> {
+  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;
+}
+
+/** Handle returned from spawnPrefab — call update() each frame to tick animations. */
+export interface SpawnedPrefab {
+  /** The Object3D of the spawned prefab root (added to the scene). */
+  object3D: THREE.Object3D;
+  /**
+   * Tick standalone (non-animGraph) animations for this prefab — e.g. a simple
+   * `animation.autoplay` clip. AnimGraphs are registered into `ctx.animGraphs`
+   * (when provided) and ticked by the global animationSystem instead, so this
+   * is a no-op for those. Call once per frame, mirroring SceneInstance.update.
+   */
+  update(dt: number): void;
+  /** Stop any mixers this prefab created. */
+  dispose(): void;
+}
+
+/**
+ * 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`
+ * (or an animGraph with no `ctx.animGraphs`) 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; animGraphs tick globally):
+ *   crate.update(dt);
+ */
+export async function spawnPrefab(
+  prefabUrl: string,
+  ctx: SceneLoadContext,
+  overrides?: Partial<SceneEntity>,
+): Promise<SpawnedPrefab> {
+  const instance: SceneEntity = {
+    name: 'Instance',
+    prefab: prefabUrl,
+    ...overrides,
+  };
+  const tickFns: ((dt: number) => void)[] = [];
+  const mixers: THREE.AnimationMixer[] = [];
+  const audioTracker: 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: number) {
+      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 animGraph/mixer tick closures, only used when
+    //    `ctx.animGraphs` is NOT provided)   DISPOSED — array cleared so
+    //    update() becomes a no-op (pre-existing).
+    //  - ctx.animGraphs (Object3D -> AnimGraph, when provided)
+    //    NEWLY-DISPOSED — every entry whose key is inside the spawned
+    //    subtree is deleted, so the global animationSystem stops ticking a
+    //    despawned graph (probe1: previously leaked forever).
+    //  - 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/animgraph 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 AnimGraphs this subtree registered into the shared,
+      // Object3D-keyed ctx.animGraphs map — otherwise the global
+      // animationSystem keeps ticking a despawned graph forever.
+      if (ctx.animGraphs) {
+        const animGraphs = ctx.animGraphs;
+        object3D.traverse((node) => {
+          animGraphs.delete(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;
+    },
+  };
+}