@vgai/engine 0.2.0 → 0.4.0-canary.20260715.0

package/src/scene/parse.ts

@@ -23,7 +23,138 @@ export class SceneParseError extends Error {
   }
 }
 
+// ---------------------------------------------------------------------------
+// D8 — removed-format migration guard: declarative property tracks
+// (`animation.tracks`) were deleted (spec §3.2/§10 D8; Theatre — `@theatre/core`
+// — is the sole authored continuous-animation source now). `SceneAnimationSchema`
+// no longer declares a `tracks` field at all (so the generated JSON schema stays
+// clean), which means Zod's default object mode would otherwise silently STRIP
+// an authored `animation.tracks` rather than reporting it — violating Global AC
+// §6 ("Removed formats fail with a concise migration/removal error rather than
+// being partially read"). This walks the RAW pre-Zod JSON (Zod would already
+// have stripped `tracks` by the time any schema-level check could see it) and
+// throws a `SceneParseError` before Zod ever parses the data. Matches on the
+// literal key `animation` (singular, an object) carrying a `tracks` property —
+// this is deliberately narrower than Scene UI's unrelated, RETAINED
+// `ui[].animations[].tracks` (plural `animations`), which this guard must not
+// trip on.
+// ---------------------------------------------------------------------------
+
+/** True when `value` is a plain object (not an array) carrying a `tracks` property — the shape
+ * `SceneAnimationSchema` used to declare before D8 deleted it. */
+function isRemovedTracksAnimation(value: unknown): boolean {
+  return !!value && typeof value === 'object' && !Array.isArray(value) && 'tracks' in value;
+}
+
+function findRemovedPropertyTrackPathInArray(node: unknown[], path: string): string | undefined {
+  for (let i = 0; i < node.length; i++) {
+    const hit = findRemovedPropertyTrackPath(node[i], `${path}[${i}]`);
+    if (hit) return hit;
+  }
+  return undefined;
+}
+
+function findRemovedPropertyTrackPathInObject(
+  obj: Record<string, unknown>,
+  path: string,
+): string | undefined {
+  if (isRemovedTracksAnimation(obj['animation'])) {
+    return `${path ? `${path}.` : ''}animation.tracks`;
+  }
+  for (const [key, value] of Object.entries(obj)) {
+    const hit = findRemovedPropertyTrackPath(value, path ? `${path}.${key}` : key);
+    if (hit) return hit;
+  }
+  return undefined;
+}
+
+function findRemovedPropertyTrackPath(node: unknown, path: string): string | undefined {
+  if (Array.isArray(node)) return findRemovedPropertyTrackPathInArray(node, path);
+  if (node && typeof node === 'object') {
+    return findRemovedPropertyTrackPathInObject(node as Record<string, unknown>, path);
+  }
+  return undefined;
+}
+
+function assertNoRemovedPropertyTracks(json: unknown, filePath?: string): void {
+  const hit = findRemovedPropertyTrackPath(json, '');
+  if (!hit) return;
+  const issue: ZodIssue = {
+    code: 'custom',
+    message:
+      'property tracks were removed; author continuous animation with Theatre (@theatre/core) ' +
+      'instead — see docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §3.2/§10 D8.',
+    path: hit.split('.'),
+  };
+  throw new SceneParseError([issue], filePath);
+}
+
+// ---------------------------------------------------------------------------
+// E5 — removed-format migration guard: the AnimGraph state-machine runtime,
+// `.animgraph.json` format, and `SceneAnimationSchema.animGraph` field were
+// deleted (spec §3.3/§11 E5; XState + native Three `AnimationMixer` — see
+// `xstate-animation-binding.ts` — replace it). `SceneAnimationSchema` no
+// longer declares an `animGraph` field at all (so it carries zero trace in
+// the generated JSON schema), which means Zod's default object mode would
+// otherwise silently STRIP an authored `animation.animGraph` rather than
+// reporting it — violating Global AC §6. Mirrors
+// `assertNoRemovedPropertyTracks` above exactly: walks the RAW pre-Zod JSON
+// and throws a `SceneParseError` before Zod ever parses the data.
+// ---------------------------------------------------------------------------
+
+/** True when `value` is a plain object (not an array) carrying an `animGraph` property — the
+ * shape `SceneAnimationSchema` used to declare before E5 deleted it. */
+function isRemovedAnimGraphAnimation(value: unknown): boolean {
+  return !!value && typeof value === 'object' && !Array.isArray(value) && 'animGraph' in value;
+}
+
+function findRemovedAnimGraphPathInArray(node: unknown[], path: string): string | undefined {
+  for (let i = 0; i < node.length; i++) {
+    const hit = findRemovedAnimGraphPath(node[i], `${path}[${i}]`);
+    if (hit) return hit;
+  }
+  return undefined;
+}
+
+function findRemovedAnimGraphPathInObject(
+  obj: Record<string, unknown>,
+  path: string,
+): string | undefined {
+  if (isRemovedAnimGraphAnimation(obj['animation'])) {
+    return `${path ? `${path}.` : ''}animation.animGraph`;
+  }
+  for (const [key, value] of Object.entries(obj)) {
+    const hit = findRemovedAnimGraphPath(value, path ? `${path}.${key}` : key);
+    if (hit) return hit;
+  }
+  return undefined;
+}
+
+function findRemovedAnimGraphPath(node: unknown, path: string): string | undefined {
+  if (Array.isArray(node)) return findRemovedAnimGraphPathInArray(node, path);
+  if (node && typeof node === 'object') {
+    return findRemovedAnimGraphPathInObject(node as Record<string, unknown>, path);
+  }
+  return undefined;
+}
+
+function assertNoRemovedAnimGraph(json: unknown, filePath?: string): void {
+  const hit = findRemovedAnimGraphPath(json, '');
+  if (!hit) return;
+  const issue: ZodIssue = {
+    code: 'custom',
+    message:
+      'AnimGraph was removed; drive character animation with an XState animation machine instead ' +
+      '— see docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §3.3/§5.6/§11 E5 and ' +
+      'packages/engine/src/animation/xstate-animation-binding.ts.',
+    path: hit.split('.'),
+  };
+  throw new SceneParseError([issue], filePath);
+}
+
 export function parseSceneFile(json: unknown, filePath?: string): SceneFile {
+  assertNoRemovedPropertyTracks(json, filePath);
+  assertNoRemovedAnimGraph(json, filePath);
   const result = SceneFileSchema.safeParse(json);
   if (!result.success) {
     throw new SceneParseError(result.error.issues, filePath);
@@ -36,6 +167,8 @@ export function parseSceneFile(json: unknown, filePath?: string): SceneFile {
 }
 
 export function parsePrefabFile(json: unknown, filePath?: string): PrefabFile {
+  assertNoRemovedPropertyTracks(json, filePath);
+  assertNoRemovedAnimGraph(json, filePath);
   const result = PrefabFileSchema.safeParse(json);
   if (!result.success) {
     throw new SceneParseError(result.error.issues, filePath);

package/src/scene/scene-apply.ts

@@ -114,6 +114,49 @@ function cloneEntity(e: SceneEntity): SceneEntity {
   return JSON.parse(JSON.stringify(e)) as SceneEntity;
 }
 
+/** True iff at least one entity in the tree (at any depth) carries a persisted `id`. */
+function hasAnyPersistedId(entities: SceneEntity[]): boolean {
+  for (const e of entities) {
+    if (e.id) return true;
+    if (e.children && hasAnyPersistedId(e.children)) return true;
+  }
+  return false;
+}
+
+/**
+ * The id-persistence trap, made honest.
+ *
+ * `id` is `z.string().optional()` in the entity schema ("auto-generated if
+ * omitted"), and the ids an agent can actually DISCOVER — `vgai status`' —
+ * are the RUNTIME uuids a live editor session assigns to id-less entities on
+ * load (`editor-store.ts`'s `assignMissingIds`). `applyDiff` resolves ops
+ * against the FILE. So for any scene authored the normal way (hand-written,
+ * or scaffolded — none of which shipped with ids), the only ids on offer
+ * could never resolve here, and the failure read `entity not found` — as if
+ * the CALLER had typo'd the id. It is not a typo: NOTHING in that file could
+ * ever have matched.
+ *
+ * The durable half of the fix makes ids real (the editor now persists
+ * auto-assigned ids back to the scene file on load — see `loadDocument`), so
+ * this message is the safety net for a file that has not been through that
+ * path yet. It fires ONLY when the scene has zero persisted ids at all — a
+ * genuine bad-id typo against an id-carrying scene still gets the plain,
+ * unpadded message.
+ */
+const NO_IDS_HINT =
+  ' — and this scene file has NO persisted entity ids AT ALL, so nothing in it could have ' +
+  'matched, whatever id the op named. This is almost certainly not a typo: `vgai status` ' +
+  'reports RUNTIME ids a live editor session assigns to id-less entities on load, and those ' +
+  'only exist in the FILE once the editor has written them back (it now does that ' +
+  'automatically, via autosave, shortly after the scene loads). Open this scene in the editor ' +
+  '(`vgai edit`), let it autosave, then re-read the ids with `vgai status` and retry. Do not ' +
+  'hand-write ids into the file.';
+
+/** Append the no-ids explanation to a not-found message when (and only when) the file has no ids. */
+function notFound(message: string, sceneHasIds: boolean): string {
+  return sceneHasIds ? message : message + NO_IDS_HINT;
+}
+
 /** Recursively search `list` (and descendants) for `id`; if found, splice it out (subtree intact) and return it. */
 function detachById(list: SceneEntity[], id: string): SceneEntity | undefined {
   for (let i = 0; i < list.length; i++) {
@@ -168,6 +211,9 @@ interface Placement {
 export function applyDiff(scene: SceneFile, diff: SceneDiff): SceneFile {
   const working: SceneFile = JSON.parse(JSON.stringify(scene)) as SceneFile;
   const ops = diff.ops;
+  // Captured from the INPUT scene, before any op mutates `working` — see
+  // `NO_IDS_HINT` above for what this distinguishes and why.
+  const sceneHasIds = hasAnyPersistedId(scene.entities);
 
   // --- Metadata / environment (independent of entity ops) ---
   if (diff.metaChanged && diff.newName !== undefined) {
@@ -227,7 +273,12 @@ export function applyDiff(scene: SceneFile, diff: SceneDiff): SceneFile {
   if (pendingMoves.size > 0) {
     const i = [...pendingMoves][0]!;
     const op = ops[i] as Extract<DiffOp, { type: 'move' }>;
-    throw new ApplyDiffError('entity not found (nothing to move)', i, 'move', op.id);
+    throw new ApplyDiffError(
+      notFound('entity not found (nothing to move)', sceneHasIds),
+      i,
+      'move',
+      op.id,
+    );
   }
 
   // --- Phase 2: removes (a not-found target is fine if it was already swept
@@ -243,7 +294,7 @@ export function applyDiff(scene: SceneFile, diff: SceneDiff): SceneFile {
     }
     if (sweptIds.has(op.id)) return;
     throw new ApplyDiffError(
-      'entity not found (already removed via an ancestor, or an invalid id)',
+      notFound('entity not found (already removed via an ancestor, or an invalid id)', sceneHasIds),
       i,
       'remove',
       op.id,
@@ -311,7 +362,7 @@ export function applyDiff(scene: SceneFile, diff: SceneDiff): SceneFile {
       if (!parentNode) {
         const bad = placements[0]!;
         throw new ApplyDiffError(
-          `parent entity "${parentId}" not found`,
+          notFound(`parent entity "${parentId}" not found`, sceneHasIds),
           bad.opIndex,
           bad.opType,
           bad.entityId,
@@ -341,7 +392,7 @@ export function applyDiff(scene: SceneFile, diff: SceneDiff): SceneFile {
     if (op.type !== 'update') return;
     const node = byId.get(op.id);
     if (!node) {
-      throw new ApplyDiffError('entity not found', i, 'update', op.id);
+      throw new ApplyDiffError(notFound('entity not found', sceneHasIds), i, 'update', op.id);
     }
     const { id: _id, children: _children, ...fields } = op.entity;
     for (const key of Object.keys(node) as (keyof SceneEntity)[]) {

package/src/scene/scene-loader.ts

@@ -3,8 +3,7 @@ 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 { buildClipMap } from '../animation/clip-map';
 import { log } from '../dev/logger';
 import type { ComponentManager } from '../ecs/component-manager';
 import type { GameComponentClass } from '../ecs/game-component';
@@ -14,11 +13,10 @@ import { type RenderScope, resolveRenderSettings } from '../render/render-settin
 import {
   assetCacheSizes,
   clearAssetCaches as clearSharedAssetCaches,
-  loadAnimGraphData,
   loadGLTF,
   resolveGltfNode,
 } from './asset-loaders';
-import { getAssetMeta, loadRegistry } from './asset-registry';
+import { applyImportCorrection, getAssetMeta, loadRegistry } from './asset-registry';
 import { computeColliderWorldDimensions, computeColliderWorldOffset } from './collider-dimensions';
 import { applyComponents, type ComponentRegistry } from './component-registry';
 import { DEFAULTS } from './defaults';
@@ -41,23 +39,22 @@ import {
   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.
+// 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<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
+ * 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
@@ -99,14 +96,12 @@ export function updateSceneLODs(scene: THREE.Scene, camera: THREE.Camera): void
 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,
   };
 }
@@ -176,19 +171,6 @@ function createCurveFromSpline(spline: SceneSpline): THREE.CatmullRomCurve3 | nu
   );
 }
 
-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;
@@ -205,10 +187,6 @@ export interface SceneLoadContext {
   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
@@ -234,16 +212,6 @@ export interface SceneInstance {
   /** 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
@@ -351,15 +319,15 @@ function entityLabel(def: SceneEntity): string {
 // ---------------------------------------------------------------------------
 // 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
+// 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/animgraph
-// caches, and this module's ctx-level prefab/material file caches) with a
+// 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
@@ -416,10 +384,6 @@ function collectPrefetchTasks(
     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);
@@ -502,6 +466,12 @@ async function instantiateScene(
     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);
 
@@ -545,7 +515,6 @@ async function instantiateScene(
     navMesh,
     cameras,
     environment: data.environment,
-    ui: data.ui,
     entities: idMap,
     update(dt: number) {
       for (const fn of tickFns) fn(dt);
@@ -693,20 +662,7 @@ async function spawnEntity(
       }
 
       // 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]),
-          );
-        }
-      }
+      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.
@@ -714,40 +670,33 @@ async function spawnEntity(
       wrapper.add(content);
       object3d = wrapper;
 
-      // Set up animation if defined
+      // 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.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) {
+        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);
           }
         }
       }
@@ -914,17 +863,6 @@ async function spawnEntity(
   // 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
@@ -1135,6 +1073,14 @@ function createPhysicsBody(
   }
   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
@@ -1161,6 +1107,42 @@ function walkEntities(entities: SceneEntity[], fn: (e: SceneEntity) => void): vo
   }
 }
 
+/** Reparent scene-authored entities to named bones/sockets in loaded GLTF skeletons. */
+function resolveBoneAttachments(entities: SceneEntity[], idMap: Map<string, THREE.Object3D>): void {
+  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: string[] = [];
+      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: SceneEntity[],
@@ -1370,10 +1352,10 @@ 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.
+   * Tick standalone `animation.autoplay` clips for this prefab. A GameComponent
+   * that attaches its own XState-driven animation binding (E5 — see
+   * `xstate-animation-binding.ts`) ticks that binding itself, 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. */
@@ -1385,16 +1367,16 @@ export interface SpawnedPrefab {
  *
  * 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.
+ * 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):
+ *   // each frame (only needed for autoplay clips):
  *   crate.update(dt);
  */
 export async function spawnPrefab(
@@ -1445,13 +1427,8 @@ export async function spawnPrefab(
     //  - 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).
+    //  - 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
@@ -1469,7 +1446,7 @@ export async function spawnPrefab(
     //    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)
+    //  - 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
@@ -1492,15 +1469,6 @@ export async function spawnPrefab(
         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

package/src/scene/scene-types.ts

@@ -28,7 +28,6 @@ export type {
   ScenePostProcessing,
   SceneSpline,
   SceneToneMapping,
-  UIRoot,
 } from './schema';
 
 export { mergePrefabInstance } from './schema';