@vgai/engine 0.2.0 → 0.4.0-canary.20260715.0

package/src/runtime/types.ts

@@ -1,9 +1,10 @@
 import type RAPIER from '@dimforge/rapier3d-compat';
 import type { EffectComposer } from 'postprocessing';
 import type * as THREE from 'three';
+import type { z } from 'zod';
 import type { SystemAdapters } from '../adapter/system-adapter';
-import type { AnimGraph } from '../animation/anim-graph';
 import type { AssetCache } from '../assets';
+import type { SeededRandom } from '../core/seeded-random';
 import type { createSystemRunner } from '../core/system-runner';
 import type { createDebugDraw } from '../dev/debug-draw';
 import type { ComponentManager } from '../ecs/component-manager';
@@ -14,7 +15,87 @@ import type { SceneFile } from '../scene/scene-types';
 import type { AudioContext as GameAudio } from '../setup/setup-audio';
 import type { ParticlesContext } from '../setup/setup-particles';
 import type { Game, WorldInstance } from './game';
-import type { SceneUIGameServices } from './scene-ui-bridge';
+
+/**
+ * The minimal structural shape `ctx.debug.attachRoom` needs from a joined
+ * Colyseus room (Task 2.2, `docs/SYNTHETIC-PLAYER-SPEC.md` §3.1's "Multiplayer
+ * locus" note): just enough to send the reserved `__vgai:debugCommand`
+ * message and listen for its `__vgai:debugCommandResult` reply. Structural,
+ * not a Colyseus type import — the same seam-boundary style every other
+ * `DebugCtxSurface` member uses (no wrapper around Colyseus itself, D2).
+ * `onMessage`'s return type is `unknown` because Colyseus's own return shape
+ * (void in some client versions, an unsubscribe function in others) isn't
+ * load-bearing here: the registry calls it defensively (invokes it on detach
+ * only if it's actually a function).
+ */
+export interface DebugRoomHandle {
+  send(type: string, message?: unknown): void;
+  onMessage(type: string, cb: (message: unknown) => void): unknown;
+}
+
+/**
+ * Infers a `registerCommand`/`registerReactCommand`/`useDebugCommand`
+ * handler's parameter tuple from its declared Zod `args` tuple (dry-run
+ * finding, `docs/ACCEPTANCE-DRIVER-BUILD-PLAN.md` Wave 6 ledger —
+ * "`registerCommand` fn typing forces `unknown[]` casts"): a real
+ * `z.ZodTuple` infers its element types (`z.tuple([z.number(), z.string()])`
+ * → `(n: number, s: string) => ...`), while omitting `args` (the generic's
+ * `undefined` default) resolves to the original permissive
+ * `(...args: unknown[]) => ...` shape every command had before this generic
+ * existed. That permissive fallback is deliberate, not just a placeholder —
+ * it keeps every existing no-schema registration (including ones whose
+ * handler reads positional args the runtime never validates, since
+ * `invoke()` only parses `args` against a schema when one is declared)
+ * compiling byte-for-byte unchanged.
+ */
+export type DebugCommandArgs<T extends z.ZodTuple | undefined = undefined> = T extends z.ZodTuple
+  ? z.infer<T>
+  : unknown[];
+
+/**
+ * The authoring half of the debug/synthetic-player seam
+ * (`docs/SYNTHETIC-PLAYER-SPEC.md` §3.1) — the read/actuate half is
+ * `SystemAdapters.DebugAdapter` (`adapter/system-adapter.ts`). Callable from
+ * any GameComponent's `init` (one file per new provider/command), or from a
+ * react world's `useDebugProvider`/`useDebugCommand`/`useDebugEmit` hooks. Every registration
+ * feeds the ONE game-scoped registry (`runtime/debug-registry.ts`) — never a
+ * per-world accumulator.
+ */
+export interface DebugCtxSurface {
+  /** Register (or replace) a named, JSON-serializable state read. Duplicate
+   *  names from the SAME world replace + warn once; the SAME name from a
+   *  DIFFERENT world throws (`DebugError` code `DEBUG_NAME_COLLISION`). */
+  registerStateProvider(
+    name: string,
+    fn: () => unknown,
+    opts?: { tier?: 'observable' | 'assisted' },
+  ): void;
+  /** Register (or replace) an invokable command. `locus` is REQUIRED once the
+   *  project declares a Colyseus room (`DebugRegistry.setRoomDeclared`) — a
+   *  fixture must say whether it mutates authoritative (server) or predicted
+   *  (client) state.
+   *
+   *  Generic over the declared `args` Zod tuple ({@link DebugCommandArgs}) so
+   *  `fn`'s parameters INFER from it: `registerCommand('setHp', { args:
+   *  z.tuple([z.number()]) }, (hp) => ...)` types `hp` as `number` with no
+   *  cast. Leaving `args` off keeps `fn` typed `(...args: unknown[]) => ...`,
+   *  same as before this generic existed. */
+  registerCommand<T extends z.ZodTuple | undefined = undefined>(
+    name: string,
+    spec: { description?: string; args?: T; locus?: 'client' | 'server' },
+    fn: (...args: DebugCommandArgs<T>) => unknown | Promise<unknown>,
+  ): void;
+  /** Push a tick-stamped event onto the debug event ring (spec §3.3) — the
+   *  engine stamps `tick`/`simT` at emission, not at read time. */
+  emit(event: string, detail?: unknown): void;
+  /**
+   * Task 2.2 — server-locus command routing (client leg). Call once your
+   * game code has joined its Colyseus room, so `locus: 'server'` commands
+   * have somewhere to send `__vgai:debugCommand`. Returns a detach function
+   * (call on room leave/dispose) — game-scoped, last-attached room wins.
+   */
+  attachRoom(room: DebugRoomHandle): () => void;
+}
 
 /**
  * All engine subsystems, passed to every game `setup(ctx)` and to each
@@ -75,10 +156,6 @@ export interface GameContext {
    *  automatically per frame. Dev-only visualization — not for shipped
    *  visuals. */
   debugDraw: ReturnType<typeof createDebugDraw>;
-  /** Active animation graphs, keyed by their `Object3D`; ticked in the
-   *  `animation` phase. Look up an entity's `AnimGraph` to set params/triggers.
-   *  GLTF/scene-defined graphs register here automatically. */
-  animGraphs: Map<THREE.Object3D, AnimGraph>;
   /** Shared GLTF/texture cache. Use `assets.loadGLTF(...)` etc. to load+cache
    *  models at runtime so repeated loads reuse geometry/material. */
   assets: AssetCache;
@@ -89,21 +166,17 @@ export interface GameContext {
   /** Manager for all live GameComponent instances (attach/detach/HMR). The
    *  scene loader drives this; gameplay code rarely touches it directly. */
   components: ComponentManager;
-  /** DOM element overlaying the canvas for game UI (React via `mountUI`, or
-   *  vanilla). `pointer-events:none` by default — set `auto` on interactive
-   *  elements. Cleared on scene switch / hot-reload. */
-  uiContainer: HTMLDivElement;
   /** Register a game-owned `SystemAdapters` capability (networking,
    *  navigation, …) on the mounted game's adapter surface, so the editor's
    *  introspection panels (via `getActiveSystems()`) can see it. The engine
-   *  wires the first-party physics/input/assets/animation entries itself;
+   *  wires the first-party physics/input/assets/audio entries itself;
    *  capabilities the GAME owns (a Colyseus connection, a NavMeshManager)
    *  are registered here by the game's setup. Optional capability — absent
    *  in contexts that expose no adapter surface (some test harnesses);
    *  call as `ctx.registerSystemAdapter?.(…)`.
    *
    *  Ordering contract: **game registrations always win** — the engine seeds
-   *  its first-party entries (physics/input/assets/animation) BEFORE setup()
+   *  its first-party entries (physics/input/assets/audio) BEFORE setup()
    *  runs, so a game that registers any of those same kinds during its own
    *  setup overrides the engine's entry, not the other way around. This also
    *  holds across a warm restart (`hotReload`): every kind the outgoing game
@@ -113,27 +186,31 @@ export interface GameContext {
    *  mounted surface. */
   registerSystemAdapter?<K extends keyof SystemAdapters>(kind: K, adapter: SystemAdapters[K]): void;
 
+  /** The debug/synthetic-player authoring surface (`docs/SYNTHETIC-PLAYER-SPEC.md`
+   *  §3.1) — see {@link DebugCtxSurface}. Optional, same absence precedent as
+   *  `registerSystemAdapter`: present on every first-party mount, absent only
+   *  in bare test harnesses that build a hand-rolled `ctx`. */
+  debug?: DebugCtxSurface;
+
   /**
-   * Register (or replace) this game's scene-UI game-time services — the data
-   * source, custom onEvent handler, and/or worldProjector overrides a scene's
-   * authored UI mounts against (design/24-scene-ui.md D2/D7). Optional, same
-   * precedent as `registerSystemAdapter`: absent in contexts with no scene-UI
-   * surface at all (bare test harnesses).
-   *
-   * Timing is safe by construction: the scene loader awaits
-   * `componentManager.initAll()` before `loadScene`/`loadSceneFromData`
-   * return, and the adapter mounts scene UI only after that — so calling this
-   * from a `GameComponent.init()` always beats the mount (its services are
-   * folded into the FIRST render, not a late update). A call AFTER the mount
-   * (e.g. from a click handler) updates the live mount in place instead
-   * (`SceneUIHandle.update`, or a dispose+remount if the renderer has none).
-   *
-   * Per-key merge (D2): a key set here always wins over both the project's
-   * registration-time registry and the engine's own D4/D5/D6 defaults. Hot
-   * reload strips every game-registered key back to none before the incoming
-   * game's `init()` runs — same contract as `registerSystemAdapter`'s re-seed.
+   * D15 (T-D15.1, `docs/D15-DETERMINISM-DESIGN.md` §2.a) — the game-scoped,
+   * named-stream seeded PRNG. `ctx.random()` draws from the `'gameplay'`
+   * stream; `ctx.random.stream('vfx')` (or any other name) draws from an
+   * INDEPENDENT stream, so a cosmetic/VFX draw can never shift the gameplay
+   * draw sequence. Use this instead of raw `Math.random()` for anything a
+   * project wants to keep reproducible; `ctx.random` itself always exists
+   * and is always internally consistent (same seed ⇒ same sequence) whether
+   * or not the project's manifest declares `determinism.seededRandom` — that
+   * flag only gates the BOOT-TIME seeding from
+   * `manifest.determinism.defaultSeed`/`?vgai-seed=`, the burn-down lint
+   * scan, and the dev-mode `Math.random` phase trap (three separate
+   * enforcers, `test/gameplay-rng-ban.test.ts` + `runtime/gameplay-rng-trap.ts`),
+   * never `ctx.random`'s mere presence. Same absence precedent as `debug`
+   * above: present on every first-party mount, optional only for bare test
+   * harnesses that build a hand-rolled `ctx`. `reseed(seed)` (future draws
+   * only) is `play.seed.set`'s eventual target (T-D15.6, not yet wired).
    */
-  setSceneUIServices?(services: SceneUIGameServices): void;
+  random?: SeededRandom;
 
   // ─── Game root (T7.1 slice 1 — GAME-ROOT-DESIGN.md D6) ───
 
@@ -143,9 +220,9 @@ export interface GameContext {
    *  harness that builds a hand-rolled `ctx` object keeps compiling
    *  unmodified — the same precedent as `registerSystemAdapter`. */
   game?: Game | undefined;
-  /** Alias for `game.worlds` — the live, declaration-ordered world registry.
+  /** Alias for `game.roots` — the live, declaration-ordered world registry.
    *  Same optionality/absence rule as `game` above. */
-  worlds?: ReadonlyArray<WorldInstance> | undefined;
+  roots?: ReadonlyArray<WorldInstance> | undefined;
 }
 
 /** Return value from a game setup function. */

package/src/scene/asset-loaders.ts

@@ -1,5 +1,7 @@
 /**
- * Canonical GLTF / texture / animgraph load + cache layer (A2).
+ * Canonical GLTF / texture load + cache layer (A2). (Formerly also hosted the
+ * `.animgraph.json` loader — removed by E5; see
+ * packages/engine/src/animation/xstate-animation-binding.ts.)
  *
  * ONE place that owns the URL-keyed caches and the clone-safety contract, shared
  * by BOTH the engine runtime (scene-loader, create-runtime) AND the editor
@@ -22,9 +24,7 @@
 
 import * as THREE from 'three';
 import * as SkeletonUtils from 'three/addons/utils/SkeletonUtils.js';
-import type { AnimGraphFile } from '../animation/anim-graph-types';
-import { AnimGraphFileSchema } from '../animation/schema';
-import { gltfLoader, resolveUrl, textureLoader } from '../loader';
+import { gltfLoader, textureLoader } from '../loader';
 import { SceneParseError } from './parse';
 import { setUserData } from './user-data';
 
@@ -33,7 +33,6 @@ const gltfCache = new Map<
   string,
   Promise<{ scene: THREE.Group; animations: THREE.AnimationClip[] }>
 >();
-const animGraphCache = new Map<string, Promise<AnimGraphFile>>();
 
 /** Load (and cache) a texture via the shared, prefix-aware TextureLoader. */
 export function loadTexture(url: string): THREE.Texture {
@@ -146,34 +145,10 @@ export function resolveGltfNode(
 }
 
 /**
- * Fetch (and cache) an animgraph JSON file via the shared prefix-aware fetch.
- * Validated via `AnimGraphFileSchema` (T4.6) — a malformed `.animgraph.json`
- * throws a `SceneParseError` naming the file, not a deep TypeError once the
- * bad data reaches `AnimGraph`/`LayerRuntime`.
- */
-export function loadAnimGraphData(src: string): Promise<AnimGraphFile> {
-  let cached = animGraphCache.get(src);
-  if (!cached) {
-    cached = fetch(resolveUrl(src))
-      .then((r) => {
-        if (!r.ok) throw new Error(`Failed to load animgraph: ${src}`);
-        return r.json();
-      })
-      .then((json) => {
-        const result = AnimGraphFileSchema.safeParse(json);
-        if (!result.success) throw new SceneParseError(result.error.issues, src);
-        return result.data;
-      });
-    animGraphCache.set(src, cached);
-  }
-  return cached;
-}
-
-/**
- * Clear the module-level GLTF / texture / animgraph caches. Call on full runtime
- * teardown (create-runtime fullCleanup / hot-reload) to release cached GPU
- * resources and avoid leaking across editor Play sessions. See the lifetime note
- * at the top of this file for why these are NOT cleared per scene load.
+ * Clear the module-level GLTF / texture caches. Call on full runtime teardown
+ * (create-runtime fullCleanup / hot-reload) to release cached GPU resources
+ * and avoid leaking across editor Play sessions. See the lifetime note at the
+ * top of this file for why these are NOT cleared per scene load.
  *
  * NOTE: the IBL/skybox env-map cache lives in scene-loader (it needs a
  * WebGLRenderer for PMREM); scene-loader's `clearAssetCaches` wraps this and
@@ -182,7 +157,6 @@ export function loadAnimGraphData(src: string): Promise<AnimGraphFile> {
 export function clearAssetCaches(): void {
   textureCache.clear();
   gltfCache.clear();
-  animGraphCache.clear();
 }
 
 /**
@@ -190,6 +164,6 @@ export function clearAssetCaches(): void {
  * 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 assetCacheSizes(): { textures: number; gltf: number; animGraphs: number } {
-  return { textures: textureCache.size, gltf: gltfCache.size, animGraphs: animGraphCache.size };
+export function assetCacheSizes(): { textures: number; gltf: number } {
+  return { textures: textureCache.size, gltf: gltfCache.size };
 }

package/src/scene/asset-paths.ts

@@ -75,7 +75,6 @@ export function collectAssetPaths(
     if (e.particles?.material?.map) paths.add(e.particles.material.map);
 
     if (e.audio?.src) paths.add(e.audio.src);
-    if (e.animation?.animGraph) paths.add(e.animation.animGraph);
     if (e.prefab && isFilePrefab(e.prefab)) paths.add(e.prefab);
   });
 
@@ -102,7 +101,6 @@ function renameInEntity(e: SceneEntity, oldPath: string, newPath: string): void
   if (e.particles?.material?.map === oldPath) e.particles.material.map = newPath;
 
   if (e.audio?.src === oldPath) e.audio.src = newPath;
-  if (e.animation?.animGraph === oldPath) e.animation.animGraph = newPath;
   if (e.prefab === oldPath) e.prefab = newPath;
 }
 

package/src/scene/asset-ref-check.ts

@@ -0,0 +1,248 @@
+/**
+ * Shared asset-reference integrity check (B6 follow-up to B2 item #20,
+ * docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §8 B6).
+ *
+ * RELOCATED HERE (from `packages/vgai-cli/src/apply-diff.ts`, where it was
+ * originally built as `dereferenceNewAssetRefs`) so it can be shared by BOTH
+ * `vgai apply-diff` (the file-mode CLI verb) and the SDK's
+ * `project.scene.apply` operation (`packages/vgai-sdk/src/project/scene-operations.ts`)
+ * WITHOUT the SDK importing from the CLI — that would invert the intended
+ * dependency direction (CLI -> SDK -> engine, §3.4). The engine's scene layer
+ * is the correct shared home: both the CLI and the SDK already depend
+ * directly on `@vgai/engine/scene/*` for scene parsing/patching, so this
+ * module sits alongside `parse.ts`/`scene-apply.ts` as one more piece of
+ * scene-layer machinery neither caller re-implements.
+ *
+ * WHAT THIS CATCHES that schema validation alone does not: the Zod scene
+ * schema only checks that e.g. `materialRef` is a STRING — never that the
+ * string points at anything real. A diff introducing
+ * `materialRef: "materials/typo.mat.json"` (nonexistent, or present but
+ * malformed) passes ordinary scene/patch validation and would be written;
+ * the failure would otherwise only surface later, at runtime asset fetch.
+ * `dereferenceNewAssetRefs` closes that gap by re-resolving every asset
+ * reference the diff INTRODUCED (present in `result`, absent from
+ * `inputScene` — deliberately not pre-existing refs, so a scene with
+ * unrelated prior breakage can still receive an unrelated repair;
+ * `validate-scenes` remains the whole-project content gate) against disk,
+ * refusing the write if anything is missing or fails its own schema.
+ *
+ * Reference kinds and their treatment (unchanged from the original CLI-only
+ * implementation):
+ *   - Zod-validated (JSON formats with engine Zod schemas): `materialRef`
+ *     (.mat.json -> parseMaterialFile), `prefab` in its file-path form
+ *     (.prefab.json -> parsePrefabFile). Prefabs are validated ONE level
+ *     deep — the referenced prefab file itself must exist and parse; assets
+ *     IT references are that file's own concern. (`animation.animGraph` ->
+ *     AnimGraphFileSchema was removed by E5 — AnimGraph no longer exists.)
+ *   - Existence-checked only (binary formats with no Zod schema to parse
+ *     them through): gltf `mesh.src`, every material texture-map path
+ *     (including the nested clearcoat/transmission/sheen/iridescence groups),
+ *     `particles.material.map`, `audio.src`, `environment.skybox`.
+ *   - `.inputmap.json` is structurally out of scope: no `.vscn.json`/
+ *     `.prefab.json` field references an input map.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { parseMaterialFile, parsePrefabFile, SceneParseError } from './parse';
+import type { SceneEntity, SceneFile } from './scene-types';
+
+/** One asset reference found in a scene document: where it is + what it points at. */
+export interface AssetRef {
+  /** The authored path string (web-root-relative, optionally /-prefixed). */
+  path: string;
+  /** Human-readable field location for error messages, e.g. `entity "crate" field materialRef`. */
+  field: string;
+  kind: 'material' | 'prefab' | 'binary';
+}
+
+/**
+ * One asset reference that failed to dereference. `reason` is a one-line-or-
+ * more human-readable explanation (schema-validation failures may be
+ * multi-line); `field`/`path` mirror `AssetRef` and `diskPath` is the
+ * resolved absolute path that was checked, so every caller (CLI text report,
+ * SDK structured error data) can build its own presentation from the same
+ * facts without re-deriving them.
+ */
+export interface AssetRefError {
+  field: string;
+  path: string;
+  diskPath: string;
+  reason: string;
+}
+
+/** Material texture-map fields that hold image paths — top-level and nested feature groups. */
+const MATERIAL_MAP_KEYS = [
+  'map',
+  'normalMap',
+  'emissiveMap',
+  'aoMap',
+  'roughnessMap',
+  'metalnessMap',
+  'displacementMap',
+] as const;
+const MATERIAL_GROUP_MAP_KEYS: Record<string, readonly string[]> = {
+  clearcoat: ['clearcoatMap', 'clearcoatRoughnessMap'],
+  transmission: ['transmissionMap'],
+  sheen: ['sheenColorMap', 'sheenRoughnessMap'],
+  iridescence: ['iridescenceMap', 'iridescenceThicknessMap'],
+};
+
+/** Same file-path-vs-registry-id heuristic as `asset-paths.ts`. */
+function isFilePrefab(value: string): boolean {
+  return value.includes('/');
+}
+
+function entityLabel(e: SceneEntity): string {
+  return e.id ? `entity "${e.name}" (id ${e.id})` : `entity "${e.name}"`;
+}
+
+/** Collect every asset reference in a scene document (entities walked recursively + environment), labeled for error messages. */
+export function collectAssetRefs(doc: SceneFile): AssetRef[] {
+  const refs: AssetRef[] = [];
+
+  function walk(entities: SceneEntity[]): void {
+    for (const e of entities) {
+      const label = entityLabel(e);
+      if (e.mesh?.type === 'gltf' && e.mesh.src) {
+        refs.push({ path: e.mesh.src, field: `${label} field mesh.src`, kind: 'binary' });
+      }
+      if (e.material) {
+        const mat = e.material as Record<string, unknown>;
+        for (const key of MATERIAL_MAP_KEYS) {
+          const val = mat[key];
+          if (typeof val === 'string') {
+            refs.push({ path: val, field: `${label} field material.${key}`, kind: 'binary' });
+          }
+        }
+        for (const [group, keys] of Object.entries(MATERIAL_GROUP_MAP_KEYS)) {
+          const groupVal = mat[group];
+          if (groupVal && typeof groupVal === 'object') {
+            for (const key of keys) {
+              const val = (groupVal as Record<string, unknown>)[key];
+              if (typeof val === 'string') {
+                refs.push({
+                  path: val,
+                  field: `${label} field material.${group}.${key}`,
+                  kind: 'binary',
+                });
+              }
+            }
+          }
+        }
+      }
+      if (e.materialRef) {
+        refs.push({ path: e.materialRef, field: `${label} field materialRef`, kind: 'material' });
+      }
+      if (e.particles?.material?.map) {
+        refs.push({
+          path: e.particles.material.map,
+          field: `${label} field particles.material.map`,
+          kind: 'binary',
+        });
+      }
+      if (e.audio?.src) {
+        refs.push({ path: e.audio.src, field: `${label} field audio.src`, kind: 'binary' });
+      }
+      if (e.prefab && isFilePrefab(e.prefab)) {
+        refs.push({ path: e.prefab, field: `${label} field prefab`, kind: 'prefab' });
+      }
+      if (e.children) walk(e.children);
+    }
+  }
+
+  walk(doc.entities);
+  if (doc.environment?.skybox) {
+    refs.push({ path: doc.environment.skybox, field: 'environment.skybox', kind: 'binary' });
+  }
+  return refs;
+}
+
+/**
+ * Resolve the asset root the scene's references are relative to. Asset paths
+ * are web-root-relative (the runtime fetches them from the served `public/`
+ * directory), and scene files conventionally live INSIDE `public/`
+ * (`public/scenes/*.vscn.json`) — so the nearest ancestor directory literally
+ * named `public` is the root. Fallback for scenes not under a `public/`
+ * ancestor: the scene's own directory.
+ */
+export function findAssetRoot(scenePath: string): string {
+  const dir = resolve(dirname(scenePath));
+  let cursor = dir;
+  for (;;) {
+    if (basename(cursor) === 'public') return cursor;
+    const parent = dirname(cursor);
+    if (parent === cursor) return dir;
+    cursor = parent;
+  }
+}
+
+/** Format Zod/scene-parse issues as `path: message`, one per line. */
+function formatIssues(issues: { path: PropertyKey[]; message: string }[]): string {
+  return issues.map((i) => `  ${i.path.join('.')}: ${i.message}`).join('\n');
+}
+
+/**
+ * Dereference every asset reference `result` introduces relative to
+ * `inputScene` (present in the result, absent from the input) against disk,
+ * relative to `scenePath`'s asset root (see `findAssetRoot`). Returns
+ * structured errors (empty = every new reference resolved and validated) —
+ * never throws; callers decide how to present/escalate a non-empty result
+ * (the CLI folds these into one `ApplyDiffCliError` message, the SDK raises
+ * a declared `ASSET_REF_INVALID` `OperationError`).
+ */
+export function dereferenceNewAssetRefs(
+  inputScene: SceneFile,
+  result: SceneFile,
+  scenePath: string,
+): AssetRefError[] {
+  const preexisting = new Set(collectAssetRefs(inputScene).map((r) => r.path));
+  const newRefs = collectAssetRefs(result).filter((r) => !preexisting.has(r.path));
+  if (newRefs.length === 0) return [];
+
+  const assetRoot = findAssetRoot(scenePath);
+  const errors: AssetRefError[] = [];
+
+  for (const ref of newRefs) {
+    const diskPath = join(assetRoot, ref.path.replace(/^\//, ''));
+    if (!existsSync(diskPath)) {
+      errors.push({
+        field: ref.field,
+        path: ref.path,
+        diskPath,
+        reason: `file not found at ${diskPath} (resolved against ${assetRoot})`,
+      });
+      continue;
+    }
+    if (ref.kind === 'binary') continue; // existence-only (see the exclusion note above)
+
+    let json: unknown;
+    try {
+      json = JSON.parse(readFileSync(diskPath, 'utf-8'));
+    } catch (err) {
+      errors.push({
+        field: ref.field,
+        path: ref.path,
+        diskPath,
+        reason: `${diskPath} is not valid JSON: ${err instanceof Error ? err.message : err}`,
+      });
+      continue;
+    }
+    try {
+      if (ref.kind === 'material') {
+        parseMaterialFile(json, diskPath);
+      } else {
+        parsePrefabFile(json, diskPath);
+      }
+    } catch (err) {
+      const detail = err instanceof SceneParseError ? `\n${formatIssues(err.issues)}` : ` ${err}`;
+      errors.push({
+        field: ref.field,
+        path: ref.path,
+        diskPath,
+        reason: `${diskPath} fails schema validation:${detail}`,
+      });
+    }
+  }
+  return errors;
+}

package/src/scene/asset-registry.ts

@@ -5,6 +5,7 @@
  * and editor entity factory import from this module.
  */
 
+import * as THREE from 'three';
 import { resolveUrl } from '../loader';
 
 export interface ImportCorrection {
@@ -18,6 +19,27 @@ export interface AssetMeta {
   importCorrection?: ImportCorrection;
 }
 
+/**
+ * Apply an asset's visual-only import correction to the loaded GLTF content.
+ * Call this on the model child, before placing it under the entity wrapper, so
+ * gameplay transforms, physics, cameras, and movement remain in VGAI's Y-up /
+ * -Z-forward coordinate contract.
+ */
+export function applyImportCorrection(
+  content: THREE.Object3D,
+  correction: ImportCorrection | undefined,
+): void {
+  if (!correction) return;
+  if (correction.scale !== undefined) content.scale.multiplyScalar(correction.scale);
+  if (correction.rotation) {
+    content.rotation.set(
+      THREE.MathUtils.degToRad(correction.rotation[0]),
+      THREE.MathUtils.degToRad(correction.rotation[1]),
+      THREE.MathUtils.degToRad(correction.rotation[2]),
+    );
+  }
+}
+
 type AssetRegistry = Record<string, AssetMeta>;
 
 let registryCache: AssetRegistry | null = null;

package/src/scene/component-registry.ts

@@ -1,13 +1,24 @@
 import type * as THREE from 'three';
 import type { ComponentManager } from '../ecs/component-manager';
-import { GameComponent, type GameComponentClass } from '../ecs/game-component';
+import {
+  GAME_COMPONENT_BRAND,
+  GameComponent,
+  type GameComponentClass,
+} from '../ecs/game-component';
 
 /** A registry mapping component names to GameComponent classes. */
 export type ComponentRegistry = Record<string, GameComponentClass>;
 
-/** Type guard: is this value a GameComponent class? */
+/** Type guard: is this value a GameComponent class? `instanceof` alone is NOT
+ *  enough: a scaffolded project's node-side scripts resolve TWO physical
+ *  copies of the engine (published `@vgai/engine/*` + the `@engine/*` source
+ *  alias), and a class extending the OTHER copy's `GameComponent` fails the
+ *  prototype-chain check — so this also accepts the cross-copy
+ *  {@link GAME_COMPONENT_BRAND}. */
 export function isGameComponentClass(entry: unknown): entry is GameComponentClass {
-  return typeof entry === 'function' && entry.prototype instanceof GameComponent;
+  if (typeof entry !== 'function') return false;
+  if (entry.prototype instanceof GameComponent) return true;
+  return (entry as unknown as Record<symbol, unknown>)[GAME_COMPONENT_BRAND] === true;
 }
 
 /**

package/src/scene/defaults.ts

@@ -40,6 +40,7 @@ export const DEFAULTS = {
     intensity: 1,
     groundColor: '#000000',
     distance: 0,
+    decay: 2,
     angle: Math.PI / 6,
     penumbra: 0,
     // three.js's own RectAreaLight constructor defaults (area lights only).

package/src/scene/light-camera-factory.ts

@@ -42,15 +42,23 @@ export function createLight(def: SceneLight): THREE.Light {
     case 'directional':
       return new THREE.DirectionalLight(color, intensity);
     case 'point':
-      return new THREE.PointLight(color, intensity, def.distance ?? d.distance);
-    case 'spot':
-      return new THREE.SpotLight(
+      return new THREE.PointLight(
+        color,
+        intensity,
+        def.distance ?? d.distance,
+        def.decay ?? d.decay,
+      );
+    case 'spot': {
+      const light = new THREE.SpotLight(
         color,
         intensity,
         def.distance ?? d.distance,
         def.angle ?? d.angle,
         def.penumbra ?? d.penumbra,
       );
+      light.decay = def.decay ?? d.decay;
+      return light;
+    }
     case 'hemisphere':
       return new THREE.HemisphereLight(color, def.groundColor ?? d.groundColor, intensity);
     case 'area': {