@vgai/engine 0.4.1 → 0.5.0-canary.20260719.1

package/src/runtime/game.ts

@@ -30,6 +30,7 @@
 import type * as PIXI from 'pixi.js';
 import type * as THREE from 'three';
 import type { AdapterSurface as AdapterSurfaceLeaf } from '../adapter/adapter-surface';
+import { createInputManagerAdapter } from '../adapter/first-party-systems';
 import type { MountedWorld } from '../adapter/game-adapter';
 import { formatAudioGateMessage, formatLoopGateMessage } from '../adapter/loop-gate-report';
 import type { SystemAdapters } from '../adapter/system-adapter';
@@ -46,7 +47,7 @@ import { PHASE_ORDER, SystemPhase, type SystemPhaseName } from '../core/types';
 import { createPerformanceProfiler, type PerformanceProfiler } from '../dev/performance-profiler';
 import type { ComponentManager } from '../ecs/component-manager';
 import type { GameComponent } from '../ecs/game-component';
-import type { InputManager } from '../input/input-manager';
+import { InputManager } from '../input/input-manager';
 import type { CollisionSystem } from '../physics/collision-system';
 import type { PhysicsRegistry } from '../physics/physics-registry';
 import type { AudioContext as GameAudio } from '../setup/setup-audio';
@@ -476,8 +477,7 @@ export interface Game {
   /** Delegates to the default world's first-party `ComponentManager`.
    *  Throws when the default world is not a first-party mount. */
   readonly components: ComponentManager;
-  /** Delegates to the default world's first-party `InputManager`. Throws
-   *  when the default world is not a first-party mount. */
+  /** The one game-owned `InputManager`, shared by every first-party root. */
   readonly input: InputManager;
   /** Delegates to the default world's first-party audio context. Throws
    *  when the default world is not a first-party mount. */
@@ -499,11 +499,14 @@ export interface Game {
    * game-level half; `ComponentManager.queryByComponent` (`ecs/
    * component-manager.ts`) is the per-world half this aggregates.
    *
-   * Iterates `roots` in declaration order, skipping any world whose mount
-   * is not first-party (an opaque/foreign mount has no `ComponentManager`
-   * to query), applying `opts.worldId`/`opts.kind` as world-level filters,
-   * and concatenating each remaining world's `queryByComponent(cls)`
-   * result. No filter (`opts` omitted) spans **every** world — that is the
+   * Iterates `roots` in declaration order, querying each world's
+   * `ComponentManager` — the first-party mount's `ctx.components`, or the
+   * optional `MountedWorldBase.components` capability for a non-first-party
+   * adapter that runs a real manager (e.g. `@engine/world3d-react`'s R3F
+   * mount — its `<Behavior>` components are aggregated here exactly like
+   * scene-authored ones). A mount with neither is skipped (an opaque/foreign
+   * world hosts no `GameComponent`s). `opts.worldId`/`opts.kind` apply as
+   * world-level filters; the per-world results are concatenated. No filter (`opts` omitted) spans **every** world — that is the
    * whole point of this API existing (D7's "cross-world flow is ordinary
    * component access", e.g. a pixi minimap component querying the 3D
    * world's tank components).
@@ -632,6 +635,20 @@ export interface GameInternal extends Game {
    *   normal play; `runTicks` has no special-cased "force focus" behavior.
    */
   runTicks(n: number, opts?: RunTicksOptions): void;
+  /**
+   * ADAPTER-MOUNT surface, not game-facing: an adapter's `mount()` calls
+   * this (via `host.game` — the classic `VgaiSceneGameAdapter` and the R3F
+   * `createR3FWorldContext` both do) to load the game-owned input map ONCE,
+   * even when several roots ask for the same path; competing paths throw
+   * (input is game-owned, so roots cannot load competing maps). GAME code
+   * never calls this — a project's map loads automatically at mount from
+   * the conventional `/inputmaps/default.inputmap.json` (or the adapter's
+   * configured `inputMapPath`); runtime additions go through
+   * `ctx.input.registerAction` instead.
+   */
+  loadInputMap(path: string): Promise<void>;
+  /** Release game-owned resources after every mounted root has disposed. */
+  dispose(): void;
 }
 
 function describeMismatch(handle: 'components' | 'input' | 'audio', world: WorldInstance): string {
@@ -666,6 +683,7 @@ export function createGame(opts: {
   const roots: WorldInstance[] = [];
   const profiler = createPerformanceProfiler();
   const systems = createSystemRunner(profiler.systemObserver, 'game');
+  const input = new InputManager();
   const stateBridge = createStateBridge();
   // D15 (T-D15.1) — the game-scoped seeded-random surface every world's
   // `ctx.random` aliases (see `vgai-scene-game-adapter.ts`'s `ctx.random =
@@ -704,13 +722,14 @@ export function createGame(opts: {
   const debugRegistry = createDebugRegistry({
     getTick: () => tick,
     getSimT: () => simT,
-    // D15/T-D15.5 — "the manifest's first/default world" for the per-world
-    // input-target resolution (`resolveInputWorldId`, `debug-registry.ts`):
-    // the SAME "first threejs world, else first world" rule
+    // D15/T-D15.5 — "the manifest's first/default world" for the debug
+    // registry's world-addressed input-target compatibility surface. Every
+    // first-party root now registers the SAME game-owned InputManager, but the
+    // stable default id still keeps explicit/implicit debug routing coherent.
+    // Use the SAME "first threejs world, else first world" rule
     // `requireDefaultWorld` (declared just below — safe: this closure is
     // only ever CALLED later, once at least one world has mounted) already
-    // defines for `Game.defaultWorld`/`Game.input` — so the debug bridge and
-    // the editor relay resolve the exact same world `Game.input` would.
+    // defines for `Game.defaultWorld`.
     getDefaultWorldId: () => (roots.length > 0 ? requireDefaultWorld().id : null),
     // Issue #175 — the built-in `time` provider's `loopLiveness` field reads
     // the REAL loop, not any UI-level play-state store: `opts.loop` is the
@@ -719,6 +738,18 @@ export function createGame(opts: {
     // the loop is actually ticking.
     getLoopLiveness: () => opts.loop.liveness,
   });
+  const inputAdapter = createInputManagerAdapter(input);
+  let inputFrameActive = false;
+  systems.add(
+    'input',
+    () => {
+      if (inputFrameActive) input.poll(debugRegistry.getGameTick());
+    },
+    { name: 'input.poll' },
+  );
+  input.setDebugEmit((event, detail) => debugRegistry.forWorld('(game)').emit(event, detail));
+  let inputMapPath: string | null = null;
+  let inputMapLoad: Promise<void> | null = null;
 
   function requireDefaultWorld(): WorldInstance {
     if (roots.length === 0) {
@@ -749,8 +780,11 @@ export function createGame(opts: {
     // root may still publish this SAME adapter (the first-party Three/Pixi
     // mounts do); the reference-equality branch below treats that as the
     // intentional shared registration it is.
-    const result: SystemAdapters = { debug: debugRegistry.adapter };
-    const ownerWorldId = new Map<string, string>([['debug', '(game)']]);
+    const result: SystemAdapters = { debug: debugRegistry.adapter, input: inputAdapter };
+    const ownerWorldId = new Map<string, string>([
+      ['debug', '(game)'],
+      ['input', '(game)'],
+    ]);
     for (const world of roots) {
       const adapters = world.mounted.systems;
       if (!adapters) continue;
@@ -870,6 +904,24 @@ export function createGame(opts: {
     // a world pushed during this very frame. This also drops the two
     // per-phase `for...of` iterator allocations.
     const n = roots.length;
+    inputFrameActive = false;
+    for (let i = 0; i < n; i++) {
+      const world = roots[i]!;
+      if (onlyFrozen) {
+        if (paused && world.pausable && !world.mounted.drivesOwnLoop) {
+          inputFrameActive = true;
+          break;
+        }
+      } else if (
+        ignorePause ||
+        (world.mounted.drivesOwnLoop
+          ? !paused || !world.pausable || !world.mounted.setPaused
+          : !paused || !world.pausable)
+      ) {
+        inputFrameActive = true;
+        break;
+      }
+    }
 
     // §7.1-11 fix (probe5): `stateBridge.bump()` must fire iff at least one
     // world actually advanced this call — not unconditionally. `advanced`
@@ -901,6 +953,12 @@ export function createGame(opts: {
       // needed.
       for (const phase of PHASE_ORDER) {
         profiler.beginPhase();
+        // Game-owned systems follow the same one-run-per-phase contract as a
+        // normal frame whenever Step advances at least one frozen world.
+        // In particular, the game-owned InputManager must poll before those
+        // worlds read actions; its matching endFrame remains at the shared
+        // frame tail below.
+        if (inputFrameActive) systems.runPhase(phase, dt);
         for (let i = 0; i < n; i++) {
           const world = roots[i]!;
           if (world.mounted.drivesOwnLoop) continue;
@@ -1017,6 +1075,7 @@ export function createGame(opts: {
     // once per completed `runFrame`/`step()` call, never per phase/world —
     // and, per §7.1-11's fix, only when `advanced` (see above) is true: a
     // fully-gated paused game produces no notifications at all.
+    if (inputFrameActive) input.endFrame();
     if (advanced) {
       stateBridge.bump();
       tick++;
@@ -1046,9 +1105,7 @@ export function createGame(opts: {
     get components() {
       return requireFirstPartyCtx('components').components;
     },
-    get input() {
-      return requireFirstPartyCtx('input').input;
-    },
+    input,
     get audio() {
       return requireFirstPartyCtx('audio').audio;
     },
@@ -1113,13 +1170,23 @@ export function createGame(opts: {
       }
       const result: T[] = [];
       for (const world of roots) {
-        if (!isFirstPartyMounted(world.mounted)) continue;
+        // A world's manager comes from its first-party ctx OR from the
+        // optional `MountedWorldBase.components` capability (a non-first-
+        // party adapter running the engine's REAL ComponentManager — e.g.
+        // `@engine/world3d-react`'s R3F mount, whose `<Behavior>` components
+        // used to be invisible here: the query compiled, ran, and returned
+        // `[]` forever). A mount with NEITHER hosts no GameComponents, so
+        // its silent empty contribution is a real, not a mistaken, result.
+        const manager = isFirstPartyMounted(world.mounted)
+          ? world.mounted.ctx.components
+          : world.mounted.components;
+        if (!manager) continue;
         if (opts?.worldId !== undefined && world.id !== opts.worldId) continue;
         if (opts?.kind !== undefined && world.kind !== opts.kind) continue;
         // Checklist item 8b: a plain for-loop push instead of
         // `result.push(...arr)` — spread-as-arguments can hit engine/runtime
         // argument-count limits once a world's instance count gets large.
-        const instances = world.mounted.ctx.components.queryByComponent(cls);
+        const instances = manager.queryByComponent(cls);
         for (const inst of instances) result.push(inst);
       }
       return result;
@@ -1228,6 +1295,21 @@ export function createGame(opts: {
         runFrameImpl(fixedDt, { skipRenderPhases });
       }
     },
+    loadInputMap(path: string): Promise<void> {
+      if (inputMapPath && inputMapPath !== path) {
+        throw new Error(
+          `Game.loadInputMap: input map is already "${inputMapPath}"; root requested "${path}". ` +
+            'Input is game-owned, so roots cannot load competing maps.',
+        );
+      }
+      inputMapPath = path;
+      inputMapLoad ??= input.loadMap(path);
+      return inputMapLoad;
+    },
+    dispose(): void {
+      input.dispose();
+      debugRegistry.strip();
+    },
   };
 
   // Filed AFTER the shell exists (the WeakMap keys on the Game object

package/src/runtime/mount-manifest.ts

@@ -148,7 +148,7 @@ export interface MountManifestOptions {
    *  never a real host. See `WorldsRuntimeConfig.headless`. */
   readonly headless?: boolean | undefined;
   /**
-   * Task 2.1 (`docs/ACCEPTANCE-DRIVER-BUILD-PLAN.md`,
+   * Task 2.1 (`docs/E2E-TESTING-BUILD-PLAN.md`,
    * `docs/SYNTHETIC-PLAYER-SPEC.md` §3.4): overrides for the `?vgai-debug=1`
    * bridge `mountManifestWorlds` installs at the tail of every mount — the
    * engine-owned install point so every standalone project gets it with zero

package/src/runtime/render-control.ts

@@ -213,6 +213,67 @@ export interface VgaiRenderHarness {
    * than a silently wrong hardcoded `1/60`.
    */
   simulateFixedDt(): number;
+  /**
+   * W3d (F11 perf regression gates) — the `vgai perf` sampling seam. Runs
+   * exactly `steps` FULL fixed-step gameplay frames (the same
+   * `game.runFrame(fixedDt)` path {@link simulateSubsteps} drives — every
+   * phase in `PHASE_ORDER`, including `render`, so `renderer.info`-backed
+   * draw/triangle counters populate per frame) with the game's OWN
+   * `PerformanceProfiler` (`dev/performance-profiler.ts`) enabled, sampling
+   * it after every frame, then restores the profiler's prior enabled state.
+   * Returns per-frame CPU/phase timings + render counters, plus a
+   * structural node/entity count of every threejs/pixijs world's live scene
+   * graph. NOT a parallel instrumentation layer: every number here comes
+   * from the existing profiler (timings, render counters) or the live world
+   * roots themselves (counts).
+   *
+   * Honesty notes, recorded here because this seam is what `vgai perf`
+   * reports: `gpuMs` is whatever the profiler's render reporter measured —
+   * `null` under headless SwiftShader (no usable GPU timer), never a
+   * fabricated 0; CPU timings include the profiler's own (small) phase
+   * bookkeeping, inherent to profiling; warmup belongs OUTSIDE this call
+   * (drive {@link simulateSubsteps} first — profiler disabled, zero
+   * overhead).
+   */
+  perfSample(steps: number): PerfSampleReport;
+}
+
+/** One measured fixed-step frame from {@link VgaiRenderHarness.perfSample}. */
+export interface PerfFrameSample {
+  /** CPU time (ms) for the whole `runFrame` pass (profiler `cpuMs`). */
+  readonly cpuMs: number;
+  /** Per-phase CPU ms (profiler phase timings), keyed by phase name. */
+  readonly phases: Readonly<Record<string, number>>;
+  /** Renderer counters reported during this frame's `render` phase
+   *  (`profiler.reportRender` — renderer.info). All zeros/null for a world
+   *  whose adapter never reports render stats. */
+  readonly render: {
+    readonly gpuMs: number | null;
+    readonly drawCalls: number;
+    readonly triangles: number;
+    readonly geometries: number;
+    readonly textures: number;
+  };
+}
+
+/** Per-world structural counts from {@link VgaiRenderHarness.perfSample}. */
+export interface PerfWorldCount {
+  readonly id: string;
+  readonly kind: string;
+  /** Total scene-graph descendants of the world root (exclusive of the root
+   *  itself). Exact and deterministic under a seed. */
+  readonly nodes: number;
+  /** Descendants carrying `userData.entityId` (the loader/editor entity
+   *  tag). 0 for a hand-built world that tags nothing — an honest count of
+   *  tagged nodes, not a guess at "entities". */
+  readonly entities: number;
+}
+
+export interface PerfSampleReport {
+  readonly frames: readonly PerfFrameSample[];
+  /** threejs/pixijs worlds only — a react/DOM world has no scene-graph node
+   *  count; it is omitted rather than fabricated. */
+  readonly worlds: readonly PerfWorldCount[];
 }
 
 export interface RenderControlHarnessOptions {
@@ -381,6 +442,44 @@ function computeWorldExclusionReasons(game: Game): string[] {
   return reasons;
 }
 
+/** Structural scene-graph walk shared by threejs (`Object3D`) and pixijs
+ *  (`Container`) roots — both expose a `children` array, and threejs nodes
+ *  additionally carry `userData` (where the loader/editor entity tag lives).
+ *  Deliberately duck-typed so this file keeps its type-only three/pixi rule. */
+function countWorldGraph(root: { readonly children?: readonly unknown[] }): {
+  nodes: number;
+  entities: number;
+} {
+  let nodes = 0;
+  let entities = 0;
+  const stack: unknown[] = [...(root.children ?? [])];
+  while (stack.length > 0) {
+    const node = stack.pop() as {
+      readonly children?: readonly unknown[];
+      readonly userData?: Record<string, unknown>;
+    };
+    nodes++;
+    if (node.userData?.['entityId'] !== undefined) entities++;
+    if (node.children) stack.push(...node.children);
+  }
+  return { nodes, entities };
+}
+
+/** See {@link PerfSampleReport.worlds} — threejs/pixijs worlds only; a
+ *  react/DOM world has no scene-graph node count and is omitted, never
+ *  fabricated. */
+function countWorlds(game: Game): PerfWorldCount[] {
+  const counts: PerfWorldCount[] = [];
+  for (const world of game.roots) {
+    if (world.kind === 'threejs') {
+      counts.push({ id: world.id, kind: world.kind, ...countWorldGraph(world.threeRoot()) });
+    } else if (world.kind === 'pixijs') {
+      counts.push({ id: world.id, kind: world.kind, ...countWorldGraph(world.pixiRoot()) });
+    }
+  }
+  return counts;
+}
+
 function nextAnimationFrame(): Promise<void> {
   return new Promise((resolve) => {
     requestAnimationFrame(() => resolve());
@@ -487,6 +586,28 @@ export function installRenderControlHarness(
     simulateFixedDt(): number {
       return simulateFixedDt;
     },
+    perfSample(steps: number): PerfSampleReport {
+      const profiler = game.profiler;
+      const wasEnabled = profiler.enabled;
+      profiler.enabled = true;
+      profiler.clear();
+      const frames: PerfFrameSample[] = [];
+      try {
+        for (let i = 0; i < steps; i++) {
+          game.runFrame(simulateFixedDt);
+          const snapshot = profiler.getSnapshot();
+          const latest = snapshot.frames.at(-1);
+          frames.push({
+            cpuMs: latest?.cpuMs ?? 0,
+            phases: Object.fromEntries((latest?.phases ?? []).map((p) => [p.name, p.ms])),
+            render: { ...snapshot.render },
+          });
+        }
+      } finally {
+        profiler.enabled = wasEnabled;
+      }
+      return { frames, worlds: countWorlds(game) };
+    },
   };
 
   target['__vgaiRender'] = harness;

package/src/runtime/types.ts

@@ -36,7 +36,7 @@ export interface DebugRoomHandle {
 /**
  * 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 —
+ * finding, `docs/E2E-TESTING-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

package/src/scene/asset-loaders.ts

@@ -22,9 +22,10 @@
  * teardown via {@link clearAssetCaches}.
  */
 
+import type { SplatMesh } from '@sparkjsdev/spark';
 import * as THREE from 'three';
 import * as SkeletonUtils from 'three/addons/utils/SkeletonUtils.js';
-import { gltfLoader, textureLoader } from '../loader';
+import { gltfLoader, resolveUrl, textureLoader } from '../loader';
 import { SceneParseError } from './parse';
 import { setUserData } from './user-data';
 
@@ -33,6 +34,7 @@ const gltfCache = new Map<
   string,
   Promise<{ scene: THREE.Group; animations: THREE.AnimationClip[] }>
 >();
+const splatBytesCache = new Map<string, Promise<Uint8Array>>();
 
 /** Load (and cache) a texture via the shared, prefix-aware TextureLoader. */
 export function loadTexture(url: string): THREE.Texture {
@@ -83,6 +85,65 @@ export function loadGLTF(
   });
 }
 
+/**
+ * Load one native Gaussian-splat asset as Spark's own Object3D.
+ *
+ * The URL cache stores immutable source bytes, not a live SplatMesh: every scene
+ * entity needs its own transformable/disposable Object3D, while repeated uses of
+ * the same SPZ must not download the multi-megabyte source more than once.
+ * Spark stays a lazy chunk so games without splats do not pay its bundle cost.
+ */
+export async function loadSplat(url: string, providedBytes?: Uint8Array): Promise<SplatMesh> {
+  let bytes = splatBytesCache.get(url);
+  if (!bytes && providedBytes) {
+    bytes = Promise.resolve(providedBytes);
+    splatBytesCache.set(url, bytes);
+  }
+  if (!bytes) {
+    bytes = fetch(resolveUrl(url)).then(async (response) => {
+      if (!response.ok) {
+        throw new Error(
+          `Failed to load Gaussian splat: ${url} (${response.status} ${response.statusText})`,
+        );
+      }
+      return new Uint8Array(await response.arrayBuffer());
+    });
+    splatBytesCache.set(url, bytes);
+  }
+
+  try {
+    const [{ SplatMesh }, fileBytes] = await Promise.all([import('@sparkjsdev/spark'), bytes]);
+    const mesh = new SplatMesh({ fileBytes, fileName: url, raycastable: true });
+    await mesh.initialized;
+    setUserData(mesh, 'gaussianSplat', { src: url, numSplats: mesh.numSplats });
+    const bounds = mesh.getBoundingBox();
+    if (!bounds.isEmpty()) {
+      // Three's generic Box3.setFromObject only understands geometry-bearing
+      // Object3Ds. Spark intentionally renders without THREE.BufferGeometry,
+      // so give editor/runtime framing a hidden, non-pickable bounds proxy.
+      // It is infrastructure, never authored hierarchy or rendered content.
+      // Include a framing margin. This proxy is consumed by generic editor
+      // focus/selection bounds, while inspectors continue to report Spark's
+      // exact Gaussian bounds directly.
+      const size = bounds.getSize(new THREE.Vector3()).multiplyScalar(1.5);
+      const center = bounds.getCenter(new THREE.Vector3());
+      const proxy = new THREE.Mesh(new THREE.BoxGeometry(size.x, size.y, size.z));
+      proxy.name = '__vgai_splat_bounds';
+      proxy.position.copy(center);
+      proxy.visible = false;
+      proxy.raycast = () => {};
+      setUserData(proxy, 'engineInternal', true);
+      mesh.add(proxy);
+    }
+    return mesh;
+  } catch (error) {
+    // A failed fetch must be retryable after the source is repaired or the
+    // network recovers; successful source bytes remain cached across instances.
+    splatBytesCache.delete(url);
+    throw error;
+  }
+}
+
 /**
  * Resolve a single named node inside an already-loaded glTF scene graph (F4,
  * docs/VSCN-STRUCTURAL-GAPS-DESIGN.md `mesh.node`). Pure and headlessly
@@ -157,6 +218,19 @@ export function resolveGltfNode(
 export function clearAssetCaches(): void {
   textureCache.clear();
   gltfCache.clear();
+  splatBytesCache.clear();
+}
+
+/**
+ * Drop the cached entry for ONE asset URL after its bytes changed on disk
+ * (editor asset-optimization write-back — W4a). Existing clones keep their
+ * shared geometry alive (the cache entry only owns the lookup, not the
+ * buffers), and the next `loadGLTF`/`loadTexture` for this URL re-fetches the
+ * rewritten file instead of serving stale bytes.
+ */
+export function invalidateCachedAsset(url: string): void {
+  textureCache.delete(url);
+  gltfCache.delete(url);
 }
 
 /**
@@ -164,6 +238,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 } {
-  return { textures: textureCache.size, gltf: gltfCache.size };
+export function assetCacheSizes(): { textures: number; gltf: number; splat: number } {
+  return { textures: textureCache.size, gltf: gltfCache.size, splat: splatBytesCache.size };
 }

package/src/scene/instance-mesh.ts

@@ -0,0 +1,25 @@
+import * as THREE from 'three';
+import type { InstancesFile } from './schema/instances';
+
+/** Build one native InstancedMesh from a parsed `.instances.json` tuple array. */
+export function buildInstancedMeshFromTuples(
+  geometry: THREE.BufferGeometry,
+  material: THREE.Material,
+  tuples: InstancesFile,
+): THREE.InstancedMesh {
+  const mesh = new THREE.InstancedMesh(geometry, material, tuples.length);
+  const position = new THREE.Vector3();
+  const quaternion = new THREE.Quaternion();
+  const scale = new THREE.Vector3();
+  const matrix = new THREE.Matrix4();
+  for (let index = 0; index < tuples.length; index += 1) {
+    const tuple = tuples[index]!;
+    position.set(tuple[0], tuple[1], tuple[2]);
+    quaternion.set(tuple[3], tuple[4], tuple[5], tuple[6]);
+    scale.set(tuple[7], tuple[8], tuple[9]);
+    matrix.compose(position, quaternion, scale);
+    mesh.setMatrixAt(index, matrix);
+  }
+  mesh.instanceMatrix.needsUpdate = true;
+  return mesh;
+}

package/src/scene/material-factory.ts

@@ -1,8 +1,6 @@
 import * as THREE from 'three';
 import { loadTexture } from './asset-loaders';
 import { DEFAULTS } from './defaults';
-import { buildGeneratedGeometry } from './geometry-registry';
-import { buildCustomMaterial } from './material-registry';
 import type { SceneMaterial, SceneMesh } from './scene-types';
 
 /**
@@ -13,15 +11,9 @@ import type { SceneMaterial, SceneMesh } from './scene-types';
  * copy-pasted in two places and had to be hand-synced — any new material feature
  * added to one and not the other silently broke that guarantee.
  *
- * Callers must have imported the side-effect registration modules
- * (`./geometries`, `./materials`, plus any custom defs) so `buildGeneratedGeometry`
- * and `buildCustomMaterial` resolve their registries.
  */
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: straightforward type-based switch with fallback args
 export function createGeometry(mesh: SceneMesh): THREE.BufferGeometry {
-  if (mesh.generator) {
-    return buildGeneratedGeometry(mesh.generator, mesh.generatorParams ?? {});
-  }
   const args = mesh.args ?? [];
   switch (mesh.type) {
     case 'box':
@@ -29,7 +21,10 @@ export function createGeometry(mesh: SceneMesh): THREE.BufferGeometry {
     case 'sphere':
       return new THREE.SphereGeometry(args[0] ?? 0.5, args[1] ?? 32, args[2] ?? 16);
     case 'plane':
-      return new THREE.PlaneGeometry(args[0] ?? 1, args[1] ?? 1);
+      // args[2]/args[3] (width/height segments) matter for vertex-displacing
+      // materials (e.g. the Water shader) — they used to be silently dropped,
+      // which collapsed the water demo to a 2-triangle quad.
+      return new THREE.PlaneGeometry(args[0] ?? 1, args[1] ?? 1, args[2] ?? 1, args[3] ?? 1);
     case 'cylinder':
       return new THREE.CylinderGeometry(
         args[0] ?? 0.5,
@@ -187,12 +182,6 @@ export function createMaterial(mat?: SceneMaterial): THREE.Material {
           : {}),
         ...(mat.displacementBias !== undefined ? { displacementBias: mat.displacementBias } : {}),
       });
-    case 'custom': {
-      if (!mat.def) {
-        throw new Error('Custom material requires a "def" (registered material name)');
-      }
-      return buildCustomMaterial(mat.def, mat.uniforms ?? {});
-    }
     default:
       return new THREE.MeshStandardMaterial({
         color: mat.color ?? dMat.color,

package/src/scene/mesh-shadow.ts

@@ -0,0 +1,18 @@
+import * as THREE from 'three';
+
+/**
+ * Apply the authored mesh-shadow contract to every renderable in a model.
+ *
+ * Primitive scene entities contain one Mesh, while glTF entities usually
+ * contain a Group with many Mesh/SkinnedMesh descendants. Keeping this walk
+ * shared prevents editor preview and runtime Play from disagreeing by source
+ * format.
+ */
+export function setMeshShadowEnabled(root: THREE.Object3D, enabled: boolean | undefined): void {
+  if (enabled === undefined) return;
+  root.traverse((object) => {
+    if (!(object instanceof THREE.Mesh)) return;
+    object.castShadow = enabled;
+    object.receiveShadow = enabled;
+  });
+}

package/src/scene/particles-factory.ts

@@ -328,6 +328,65 @@ export function createParticleSystemFromData(data: SceneParticles): ParticleSyst
   return { emitter: ps.emitter, system: ps };
 }
 
+/**
+ * Patch a RUNNING ParticleSystem in place from SceneParticles JSON — the
+ * editor's live-tune path (W1b). Unlike `createParticleSystemFromData`, this
+ * does NOT recreate the system: the particle pool, per-particle ages, and the
+ * emission clock all survive, so a curve-key drag reshapes the live emitter
+ * with no restart stutter.
+ *
+ * Covers the live-tunable subset: lifecycle scalars (duration/looping/
+ * prewarm), emitter shape, start-value generators, emission rates + bursts,
+ * and the behavior stack (behavior instances are rebuilt from JSON — quarks
+ * behaviors read their generators per-update, so existing particles pick the
+ * new curves up on the next frame).
+ *
+ * NOT covered (these change the render batch and must go through the normal
+ * teardown/rebuild path): material, renderMode, tiling/soft-particle render
+ * settings, worldSpace.
+ */
+export function applyParticlesDataLive(system: ParticleSystem, data: SceneParticles): void {
+  if (data.duration != null) system.duration = data.duration;
+  if (data.looping != null) system.looping = data.looping;
+  if (data.prewarm != null) system.prewarm = data.prewarm;
+  if (data.shape) system.emitterShape = createEmitterShape(data.shape);
+  if (data.startLife) system.startLife = valueGen(data.startLife) as any;
+  if (data.startSpeed) system.startSpeed = valueGen(data.startSpeed) as any;
+  if (data.startSize) system.startSize = valueGen(data.startSize) as any;
+  if (data.startRotation) system.startRotation = valueGen(data.startRotation) as any;
+  if (data.startColor) system.startColor = colorGen(data.startColor) as any;
+  if (data.startTileIndex) system.startTileIndex = valueGen(data.startTileIndex) as any;
+  if (data.emissionOverTime) system.emissionOverTime = valueGen(data.emissionOverTime) as any;
+  if (data.emissionOverDistance)
+    system.emissionOverDistance = valueGen(data.emissionOverDistance) as any;
+  system.emissionBursts = (data.emissionBursts ?? []).map((b) => ({
+    time: b.time,
+    count: valueGen(b.count) as any,
+    cycle: b.cycle ?? 1,
+    interval: b.interval ?? 0,
+    probability: b.probability ?? 1,
+  }));
+  system.behaviors = (data.behaviors ?? []).map(createBehavior);
+}
+
+/**
+ * Scrub a ParticleSystem to an absolute time by deterministic re-simulation:
+ * restart, then advance in fixed steps to `time`, then pause. Used by the
+ * editor's emitter-transport time scrub. `update` is TS-private on
+ * ParticleSystem but is exactly what BatchedRenderer.update calls per system.
+ */
+export function scrubParticleSystemTo(system: ParticleSystem, time: number, step = 1 / 60): void {
+  system.restart();
+  const target = Math.max(0, time);
+  let t = 0;
+  while (t < target) {
+    const dt = Math.min(step, target - t);
+    (system as any).update(dt);
+    t += dt;
+  }
+  system.pause();
+}
+
 /**
  * Register a particle system with a BatchedRenderer.
  */