@vgai/engine 0.5.2 → 0.5.3

package/src/react/{game-state.tsx → world-state.tsx}

@@ -1,12 +1,11 @@
 /**
- * Canonical `GameProvider`/`useGame`/`useGameState`/`useWorldObservation`
+ * Canonical `WorldProvider`/`useGame`/`useWorldState`/`useRootObservation`
  * entry for React adapter roots. Also home to `useDebugProvider` and
  * `useDebugCommand`/`useDebugEmit`, the React-facing debug seam.
  *
  * This is a SEPARATE, react-value-importing module under
- * `packages/engine/src/react/` — colocated per REACT-STATE-BRIDGE §3's own
- * "colocate the react-facing hooks with the HUD seam, not the react-free
- * core" rule, just now living IN the engine package rather than only in the
+ * `packages/engine/src/react/` — colocated per the "colocate the
+ * react-facing hooks with the HUD seam, not the react-free core" rule, just now living IN the engine package rather than only in the
  * project template. It is imported by NOTHING in the engine core import
  * graph (`packages/engine/src/` outside this `react/` directory) — that
  * invariant is proved by `packages/engine/test/react-core-import-ban.test.ts`
@@ -27,7 +26,7 @@ import {
   useSyncExternalStore,
 } from 'react';
 import type { z } from 'zod';
-import type { WorldStateObserver } from '../adapter';
+import type { RootStateObserver } from '../adapter';
 import { getDebugRegistry } from '../runtime/debug-registry';
 import { createFrameSelectorCache, type Equals, shallow } from '../runtime/frame-selector-cache';
 import type { Game } from '../runtime/game';
@@ -39,7 +38,7 @@ export { shallow };
 
 const GameContext = createContext<Game | null>(null);
 
-/** Provide the `Game` to `useGameState`/`useGame` for everything mounted
+/** Provide the `Game` to `useWorldState`/`useGame` for everything mounted
  *  beneath it. Adapter-root hosts install this provider automatically — see the module doc
  *  comment above for the context-identity rule this hook family depends on.
  *
@@ -48,38 +47,39 @@ const GameContext = createContext<Game | null>(null);
  *  the provider) rather than a bare `{ children: ReactNode }` field: a
  *  required `children` in `P` makes TS's `createElement<P>(type, props?:
  *  Attributes & P, ...children)` overload reject the plain 3-arg call
- *  `React.createElement(GameProvider, { game }, child)` (no JSX transform,
+ *  `React.createElement(WorldProvider, { game }, child)` (no JSX transform,
  *  e.g. a `.ts` main composing a sibling `.tsx` HUD) with "Property
  *  'children' is missing" even though the 3rd arg supplies it — issue #97.
  *  Making `children` optional in the type lets that overload resolve; the
  *  rest-arg children are still wired through to `children` at runtime by
  *  React itself, unchanged. See `test/game-state-create-element-types.test.tsx`. */
-export function GameProvider({ game, children }: PropsWithChildren<{ game: Game }>) {
+export function WorldProvider({ game, children }: PropsWithChildren<{ game: Game }>) {
   return <GameContext.Provider value={game}>{children}</GameContext.Provider>;
 }
 
-/** Read the `Game` provided by the nearest `GameProvider`. Throws
+/** Read the `Game` provided by the nearest `WorldProvider`. Throws
  *  descriptively when called outside one — matching the repo's loud-failure
  *  habit rather than silently returning `null`. */
 export function useGame(): Game {
   const game = useContext(GameContext);
   if (!game) {
     throw new Error(
-      'useGame: no Game in context — wrap this component in <GameProvider game={ctx.game!}>.',
+      'useGame: no Game in context — wrap this component in <WorldProvider game={ctx.game!}>.',
     );
   }
   return game;
 }
 
 /**
- * Subscribe to a selected slice of game state (`docs/REACT-STATE-BRIDGE.md`
- * §3). Re-renders only when the selected value changes: the selector re-runs
- * at most once per completed frame (`game.state.frameVersion`), and
- * `equals` (default `Object.is`; pass {@link shallow} for tuples/objects)
- * gates whether the fresh result actually counts as a change.
+ * Subscribe to a selected slice of game state. Re-renders only when the
+ * selected value changes: the selector re-runs at most once per completed
+ * frame (`game.state.frameVersion`), and `equals` (default `Object.is`; pass
+ * {@link shallow} for tuples/objects) gates whether the fresh result
+ * actually counts as a change.
  *
  * `selector` reads the live graph (e.g.
- * `g => g.queryByComponent(Hp)[0]?.hp`) at post-frame quiescence — no
+ * `g => g.world('main')?.threeScene().getObjectByName('Hero')?.position.y`)
+ * at post-frame quiescence — no
  * copies. A selector that returns a fresh object every call must pass
  * `shallow` (or an equivalent `equals`), or it will re-render every frame.
  *
@@ -88,7 +88,7 @@ export function useGame(): Game {
  * `shallow`/`Object.is`, or a value that doesn't change across renders),
  * not a fresh inline arrow every render.
  */
-export function useGameState<T>(selector: (game: Game) => T, equals: Equals<T> = Object.is): T {
+export function useWorldState<T>(selector: (game: Game) => T, equals: Equals<T> = Object.is): T {
   const game = useGame();
   const cacheRef = useRef<ReturnType<typeof createFrameSelectorCache<T>> | null>(null);
   if (cacheRef.current === null) {
@@ -102,27 +102,27 @@ export function useGameState<T>(selector: (game: Game) => T, equals: Equals<T> =
 }
 
 /**
- * Pure, react-free lookup for the `useWorldObservation` hook below — factored
+ * Pure, react-free lookup for the `useRootObservation` hook below — factored
  * out so the hook body stays a thin `useSyncExternalStore` wrapper. Throws
  * descriptively (loud, not `undefined`-forever) when `worldId` doesn't name a
  * registered world, or that world's mount has no `observe`
- * (`WorldStateObserver`, `@engine/adapter`) — matching the `Game.registerWorld`
+ * (`RootStateObserver`, `@engine/adapter`) — matching the `Game.registerRoot`
  * "no state bridge" report (`runtime/game.ts`) this is the react-side half of.
  */
-export function requireWorldObserver(game: Game, worldId: string): WorldStateObserver {
+export function requireRootObserver(game: Game, worldId: string): RootStateObserver {
   const world = game.world(worldId);
   if (!world) {
     throw new Error(
-      `useWorldObservation: no world registered with id "${worldId}" — check game.roots for the ` +
+      `useRootObservation: no world registered with id "${worldId}" — check game.roots for the ` +
         'ids actually registered.',
     );
   }
   const observer = world.mounted.observe;
   if (!observer) {
     throw new Error(
-      `useWorldObservation: world "${worldId}" (kind: ${world.kind}, adapter: "${world.adapter.id}") ` +
-        'has no state bridge — its mount has no `observe` (WorldStateObserver). This world cannot ' +
-        'be observed from React (docs/REACT-STATE-BRIDGE.md §4).',
+      `useRootObservation: world "${worldId}" (kind: ${world.kind}, adapter: "${world.adapter.id}") ` +
+        'has no state bridge — its mount has no `observe` (RootStateObserver). This world cannot ' +
+        'be observed from React.',
     );
   }
   return observer;
@@ -130,32 +130,31 @@ export function requireWorldObserver(game: Game, worldId: string): WorldStateObs
 
 /**
  * Subscribe to a selected slice of a FOREIGN (non-first-party) world's
- * observed state (`docs/REACT-STATE-BRIDGE.md` §4) — the ingested-world
- * counterpart of `useGameState` above; both are sugar over the same
- * subscribe/snapshot shape, so a react HUD reads native and ingested sources
- * through one mental model.
+ * observed state — the ingested-world counterpart of `useWorldState` above;
+ * both are sugar over the same subscribe/snapshot shape, so a react HUD reads
+ * native and ingested sources through one mental model.
  *
  * `selector` runs over that world's `snapshot()` — NOT the `Game` — since a
- * foreign world hosts no `GameComponent`s to query. Re-renders only when the
+ * foreign world exposes no first-party state. Re-renders only when the
  * selected value changes (`equals`, default `Object.is`; pass {@link shallow}
  * for tuples/objects returned fresh every call).
  *
- * Cadence note: unlike `useGameState`, this does NOT key its cache off
+ * Cadence note: unlike `useWorldState`, this does NOT key its cache off
  * `game.state.frameVersion` — a foreign/self-driven world may notify on its
  * OWN rAF cadence, unrelated to our frame timing (§4's "consumers must not
  * assume our frame timing"). Instead this keeps a local version counter,
  * bumped once per `onChange` notification from the observer itself.
  *
  * Throws (loud, not a silently-undefined subscription) if `worldId` isn't
- * registered, or its mount has no `observe` — see `requireWorldObserver`.
+ * registered, or its mount has no `observe` — see `requireRootObserver`.
  */
-export function useWorldObservation<T>(
+export function useRootObservation<T>(
   worldId: string,
   selector: (snapshot: unknown) => T,
   equals: Equals<T> = Object.is,
 ): T {
   const game = useGame();
-  const observer = requireWorldObserver(game, worldId);
+  const observer = requireRootObserver(game, worldId);
   const cacheRef = useRef<ReturnType<typeof createFrameSelectorCache<T>> | null>(null);
   if (cacheRef.current === null) {
     cacheRef.current = createFrameSelectorCache<T>(equals);
@@ -176,19 +175,18 @@ export function useWorldObservation<T>(
 }
 
 /**
- * The debug seam's react-world registration door (Task 1.5,
- * `docs/SYNTHETIC-PLAYER-SPEC.md` §3.1): react roots have no `setup()`/
- * `ctx.debug` of their own, so this hook registers a named state provider
- * into the SAME game-scoped registry every `GameComponent`'s `ctx.debug`
- * feeds (`getDebugRegistry(game)`, `runtime/debug-registry.ts`), readable
- * through `game.systemAdapters.debug.state(name)` exactly like a
+ * The debug seam's react-world registration door (Task 1.5): react roots
+ * have no `setup()`/ `ctx.debug` of their own, so this hook registers a
+ * named state provider into the SAME game-scoped registry every root's
+ * `ctx.debug` feeds (`getDebugRegistry(game)`, `runtime/debug-registry.ts`),
+ * readable through `game.systemAdapters.debug.state(name)` exactly like a
  * `ctx.debug.registerStateProvider` call.
  *
  * Registers ONCE per mount (keyed on `name`) and unregisters on unmount —
  * silently, like hot-reload's `strip()`. Re-renders never re-register or
  * re-warn: `fn` is kept in a ref updated every render, so the registered
  * closure always calls the CURRENT `fn` without touching the registry.
- * Outside a `<GameProvider>` (or against a bare test `Game` built without a
+ * Outside a `<WorldProvider>` (or against a bare test `Game` built without a
  * registry) this is an inert no-op — it never throws, matching the "no seam
  * without a consumer" degrade every optional `ctx.*` surface follows.
  */
@@ -219,14 +217,14 @@ export function useDebugProvider(
  * Same mount/unmount/ref-latest contract as {@link useDebugProvider}: `spec`
  * (description/args/locus) is captured at registration time, `fn` always
  * calls through to the latest render's closure via a ref, and the hook is an
- * inert no-op with no `<GameProvider>` in scope.
+ * inert no-op with no `<WorldProvider>` in scope.
  *
  * Generic over the declared `args` Zod tuple, same as
  * `DebugCtxSurface.registerCommand` ({@link DebugCommandArgs}, dry-run
- * finding — `docs/E2E-TESTING-BUILD-PLAN.md` Wave 6 ledger): declaring
- * `args: z.tuple([z.number(), z.string()])` types `fn`'s parameters as
- * `(n: number, s: string) => ...` with no `unknown[]` cast; omitting `args`
- * keeps `fn` typed `(...args: unknown[]) => ...` as before.
+ * finding — ledger): declaring `args: z.tuple([z.number(), z.string()])`
+ * types `fn`'s parameters as `(n: number, s: string) => ...` with no
+ * `unknown[]` cast; omitting `args` keeps `fn` typed `(...args: unknown[])
+ * => ...` as before.
  */
 export function useDebugCommand<T extends z.ZodTuple | undefined = undefined>(
   name: string,
@@ -259,7 +257,7 @@ export function useDebugCommand<T extends z.ZodTuple | undefined = undefined>(
  * emit('score-changed', { score });
  * ```
  *
- * It is an inert no-op outside a `<GameProvider>`, matching the optional
+ * It is an inert no-op outside a `<WorldProvider>`, matching the optional
  * behavior of the other React debug hooks. Games never need to import the
  * debug registry or know its internal React provenance id.
  */

package/src/render/auto-batcher.ts

@@ -1,8 +1,7 @@
 import * as THREE from 'three';
 
 /**
- * Transparent auto-batcher (Strategy 1 — see docs/research/THREEJS-NATIVE-COMPILE.md §5
- * and FAST-RENDER-BY-DEFAULT.md).
+ * Transparent auto-batcher (Strategy 1).
  *
  * The framework keeps each entity's Object3D as the logical handle (transform,
  * gameplay, physics, picking) and renders eligible entities through a shared

package/src/{scene → render}/instance-mesh.ts

@@ -1,5 +1,5 @@
 import * as THREE from 'three';
-import type { InstancesFile } from './schema/instances';
+import type { InstancesFile } from '../asset-formats/instances';
 
 /** Build one native InstancedMesh from a parsed `.instances.json` tuple array. */
 export function buildInstancedMeshFromTuples(

package/src/{scene → render}/light-camera-factory.ts

@@ -9,31 +9,32 @@
  * edit to one copy (or to `DEFAULTS`) could silently diverge from the other.
  *
  * This module is now the ONE place that builds a `THREE.Light`/`THREE.Camera`
- * from a `SceneLight`/`SceneCamera` descriptor, reading its fallbacks from
+ * from a `LightDescriptor`/`CameraDescriptor` descriptor, reading its fallbacks from
  * `DEFAULTS` (the single source of truth for scene default values — see
- * `scene/defaults.ts`). Both the loader and the editor import it, so they
+ * `defaults.ts`). Both the loader and the editor import it, so they
  * can no longer disagree.
  */
 
 import * as THREE from 'three';
-// F2 (docs/VSCN-STRUCTURAL-GAPS-DESIGN.md) — area lights. `RectAreaLight`
-// requires its LTC lookup-texture uniforms initialized once before the first
-// instance is constructed; three.js ships that setup as an addon, not part
-// of core. Imported via the `three/addons/*` alias (package.json `exports`:
-// `"./addons/*": "./examples/jsm/*"` — the identical file as
+// Area lights. `RectAreaLight` requires its LTC lookup-texture uniforms
+// initialized once before the first instance is constructed; three.js ships
+// that setup as an addon, not part of core. Imported via the
+// `three/addons/*` alias (package.json `exports`: `"./addons/*":
+// "./examples/jsm/*"` — the identical file as
 // `three/examples/jsm/lights/RectAreaLightUniformsLib.js`) because a literal
 // `/examples/` specifier trips `engine-host-no-game-imports.test.ts`'s
 // game/editor-example guard (a same-substring false positive against this
 // repo's OWN `packages/editor/template/src/examples/` convention, unrelated
 // to three.js's addon folder naming).
 import { RectAreaLightUniformsLib } from 'three/addons/lights/RectAreaLightUniformsLib.js';
-import { DEFAULTS } from './defaults';
-import type { SceneCamera, SceneLight } from './scene-types';
+import type { CameraDescriptor } from '../asset-formats/camera';
+import type { LightDescriptor } from '../asset-formats/light';
+import { DEFAULTS } from '../defaults';
 
 let rectAreaLightUniformsInitialized = false;
 
-/** Build a Three.js light from a `SceneLight` descriptor. */
-export function createLight(def: SceneLight): THREE.Light {
+/** Build a Three.js light from a `LightDescriptor` descriptor. */
+export function createLight(def: LightDescriptor): THREE.Light {
   const d = DEFAULTS.light;
   const color = def.color ?? d.color;
   const intensity = def.intensity ?? d.intensity;
@@ -81,8 +82,8 @@ export function createLight(def: SceneLight): THREE.Light {
   }
 }
 
-/** Build a Three.js camera from a `SceneCamera` descriptor. */
-export function createCamera(def: SceneCamera): THREE.Camera {
+/** Build a Three.js camera from a `CameraDescriptor` descriptor. */
+export function createCamera(def: CameraDescriptor): THREE.Camera {
   const d = DEFAULTS.camera;
   const aspect = (def.width ?? d.width) / (def.height ?? d.height);
   if (def.type === 'orthographic') {

package/src/render/lod.ts

@@ -0,0 +1,17 @@
+import type * as THREE from 'three';
+
+/**
+ * Per-frame LOD tick. `THREE.LOD` only swaps its active level when
+ * `.update(camera)` runs, so every `THREE.LOD` in the scene graph needs this
+ * called once a frame. Wired into the runtime's `preRender` system in
+ * `adapter/setup-three-root-adapter.ts`.
+ *
+ * Format-neutral: it matches THREE's own `isLOD` marker and knows nothing about
+ * how the LOD was built. Formerly `@engine/scene/scene-loader`'s
+ * `updateSceneLODs`, relocated here when WO-8 deleted the `.vscn` scene loader.
+ */
+export function updateSceneLODs(scene: THREE.Object3D, camera: THREE.Camera): void {
+  scene.traverse((o) => {
+    if ((o as THREE.LOD).isLOD) (o as THREE.LOD).update(camera);
+  });
+}

package/src/{scene → render}/material-factory.ts

@@ -1,19 +1,20 @@
 import * as THREE from 'three';
-import { loadTexture } from './asset-loaders';
-import { DEFAULTS } from './defaults';
-import type { SceneMaterial, SceneMesh } from './scene-types';
+import type { MaterialDescriptor } from '../asset-formats/material';
+import type { MeshDescriptor } from '../asset-formats/mesh';
+import { loadTexture } from '../asset-loaders';
+import { DEFAULTS } from '../defaults';
 
 /**
- * Single source of truth for turning a `SceneMesh` / `SceneMaterial` descriptor
+ * Single source of truth for turning a `MeshDescriptor` / `MaterialDescriptor` descriptor
  * into Three.js geometry/material. Both the runtime scene-loader and the editor's
  * entity-factory import these, so the editor preview renders exactly what the game
- * renders (the WYSIWYG guarantee in ARCHITECTURE.md). Previously these were
+ * renders (the WYSIWYG guarantee). Previously these were
  * 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.
  *
  */
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: straightforward type-based switch with fallback args
-export function createGeometry(mesh: SceneMesh): THREE.BufferGeometry {
+export function createGeometry(mesh: MeshDescriptor): THREE.BufferGeometry {
   const args = mesh.args ?? [];
   switch (mesh.type) {
     case 'box':
@@ -40,7 +41,7 @@ export function createGeometry(mesh: SceneMesh): THREE.BufferGeometry {
 }
 
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: flat type-based switch building Three materials
-export function createMaterial(mat?: SceneMaterial): THREE.Material {
+export function createMaterial(mat?: MaterialDescriptor): THREE.Material {
   if (!mat) return new THREE.MeshStandardMaterial({ color: DEFAULTS.material.color });
 
   // Only include texture props when actually defined (Three.js warns on undefined values)

package/src/{scene → render}/particles-factory.ts

@@ -1,6 +1,6 @@
 // biome-ignore-all lint/suspicious/noExplicitAny: quarks' API uses untyped FunctionJSON internally; our Zod types are structurally compatible but TS can't unify them
 /**
- * Converts SceneParticles JSON → three.quarks ParticleSystem.
+ * Converts ParticlesDescriptor JSON → three.quarks ParticleSystem.
  *
  * Shared between the editor entity-factory and the runtime scene-loader.
  * The schema mirrors quarks' native JSON format, so most fields pass through
@@ -15,6 +15,7 @@ import {
   ColorOverLife,
   ConeEmitter,
   DonutEmitter,
+  type EmitterShape,
   ForceOverLife,
   FrameOverLife,
   GravityForce,
@@ -36,13 +37,13 @@ import {
 } from 'quarks.core';
 import * as THREE from 'three';
 import { type BatchedRenderer, ParticleSystem, RenderMode } from 'three.quarks';
-import type { SceneParticles } from './scene-types';
 import type {
   BehaviorJSON,
   ColorGeneratorJSON,
   EmitterShapeJSON,
+  ParticlesDescriptor,
   ValueGeneratorJSON,
-} from './schema/particles';
+} from '../asset-formats/particles';
 
 // --- Render mode mapping ---
 
@@ -203,7 +204,7 @@ function createBehavior(json: BehaviorJSON): any {
 
 // --- Material ---
 
-function createParticleMaterial(mat: SceneParticles['material']): THREE.Material {
+function createParticleMaterial(mat: ParticlesDescriptor['material']): THREE.Material {
   const textures: Record<string, THREE.Texture> = {};
   if (mat.map) textures['map'] = loadParticleTexture(mat.map);
 
@@ -267,14 +268,59 @@ export interface ParticleSystemResult {
 }
 
 /**
- * Create a three.quarks ParticleSystem from SceneParticles JSON data.
+ * The non-JSON companion to a {@link ParticlesDescriptor} — the runtime objects
+ * a JSON document cannot carry, and an authoring toggle. Every field is
+ * optional and the whole argument is optional, so existing single-argument
+ * callers (the editor entity-factory, the runtime scene-loader) are unchanged.
+ *
+ * This is how a caller with fidelity a plain descriptor cannot express reaches
+ * the SAME factory instead of hand-building its own `new ParticleSystem(...)`:
+ * a foreign-engine carry (e.g. Godot CPUParticles) supplies its own
+ * `EmitterShape` and an instancing geometry here, and expresses everything
+ * else — lifecycle, start values, emission, behaviors, material — as descriptor
+ * JSON.
+ */
+export interface ParticleSystemObjects {
+  /**
+   * A pre-built emitter shape for a spawn distribution the JSON `shape` field
+   * cannot express (a `three.quarks` `EmitterShape` plugin instance). When
+   * present it REPLACES `data.shape`.
+   */
+  shape?: EmitterShape;
+  /**
+   * The geometry instanced per particle in `RenderMode.Mesh`. A
+   * `BufferGeometry` is not JSON-serializable, so `renderMode: 'mesh'` requires
+   * the caller to resolve and pass it here.
+   */
+  instancingGeometry?: THREE.BufferGeometry;
+  /**
+   * When the material has no texture `map`, the factory substitutes a soft
+   * radial default sprite so a freshly-authored billboard shows something.
+   * Pass `false` to keep the material's own (map-less) appearance — a faithful
+   * carry of a foreign engine whose particle draws a plain colored quad, and
+   * the way that carry avoids the default-sprite canvas entirely. Defaults to
+   * `true`.
+   */
+  defaultSprite?: boolean;
+}
+
+/**
+ * Create a three.quarks ParticleSystem from ParticlesDescriptor JSON data.
+ *
+ * `objects` carries the pieces a JSON descriptor cannot: a plugin emitter
+ * shape, a mesh-mode instancing geometry, and the default-sprite toggle. It is
+ * optional and additive — a call with only `data` behaves exactly as before.
  */
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: straightforward field-by-field mapping
-export function createParticleSystemFromData(data: SceneParticles): ParticleSystemResult {
+export function createParticleSystemFromData(
+  data: ParticlesDescriptor,
+  objects?: ParticleSystemObjects,
+): ParticleSystemResult {
   const material = createParticleMaterial(data.material);
 
-  // Apply default sprite if no texture specified
-  if (!data.material.map && 'map' in material) {
+  // Apply default sprite if no texture specified (unless the caller opts out to
+  // keep a map-less material faithful to its source).
+  if ((objects?.defaultSprite ?? true) && !data.material.map && 'map' in material) {
     (material as THREE.MeshBasicMaterial).map = getDefaultSpriteTex();
   }
 
@@ -285,7 +331,11 @@ export function createParticleSystemFromData(data: SceneParticles): ParticleSyst
   if (data.looping != null) params['looping'] = data.looping;
   if (data.prewarm != null) params['prewarm'] = data.prewarm;
   if (data.duration != null) params['duration'] = data.duration;
-  if (data.shape) params['shape'] = createEmitterShape(data.shape);
+  // A pre-built shape (a distribution the JSON cannot express) wins over the
+  // descriptor's own shape; otherwise build the shape from JSON.
+  if (objects?.shape) params['shape'] = objects.shape;
+  else if (data.shape) params['shape'] = createEmitterShape(data.shape);
+  if (objects?.instancingGeometry) params['instancingGeometry'] = objects.instancingGeometry;
 
   if (data.startLife) params['startLife'] = valueGen(data.startLife);
   if (data.startSpeed) params['startSpeed'] = valueGen(data.startSpeed);
@@ -329,7 +379,7 @@ export function createParticleSystemFromData(data: SceneParticles): ParticleSyst
 }
 
 /**
- * Patch a RUNNING ParticleSystem in place from SceneParticles JSON — the
+ * Patch a RUNNING ParticleSystem in place from ParticlesDescriptor 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
@@ -345,7 +395,7 @@ export function createParticleSystemFromData(data: SceneParticles): ParticleSyst
  * teardown/rebuild path): material, renderMode, tiling/soft-particle render
  * settings, worldSpace.
  */
-export function applyParticlesDataLive(system: ParticleSystem, data: SceneParticles): void {
+export function applyParticlesDataLive(system: ParticleSystem, data: ParticlesDescriptor): 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;
@@ -410,7 +460,7 @@ export function unregisterParticleSystem(
 /**
  * Default particle data for creating a new particle emitter via AddSectionMenu.
  */
-export function defaultParticlesData(): SceneParticles {
+export function defaultParticlesData(): ParticlesDescriptor {
   return {
     looping: true,
     duration: 2,

package/src/render/render-batch-system.ts

@@ -1,5 +1,5 @@
 import * as THREE from 'three';
-import { getUserData } from '../scene/user-data';
+import { getUserData } from '../ecs/user-data';
 import type { ResolvedRenderSettings } from './render-settings';
 
 /**
@@ -12,9 +12,8 @@ import type { ResolvedRenderSettings } from './render-settings';
  * N logical objects → 1 draw call, ~0 CPU/frame. This is the classic "static
  * batching" technique (cf. Unity/PlayCanvas static batch groups).
  *
- * Strategy 1 (keep identity, don't merge): see docs/research/THREEJS-NATIVE-COMPILE.md §5,
- * FAST-RENDER-BY-DEFAULT.md, RENDER-SETTINGS-UX.md. Moving entities (boids-style,
- * all-frame churn) are a separate concern — see render/auto-batcher.ts (dynamic).
+ * Strategy 1 (keep identity, don't merge). Moving entities (boids-style, all-frame churn) are a separate
+ * concern — see render/auto-batcher.ts (dynamic).
  *
  * Eligibility (anything failing stays an ordinary draw — degrade, don't break):
  *   - plain THREE.Mesh (not Instanced/Skinned/Batched)
@@ -28,8 +27,6 @@ import type { ResolvedRenderSettings } from './render-settings';
  *   - Runs once per scene load (build() is called after loadScene). Entities spawned
  *     AFTER build do not join a batch; call build() again to re-scan. Removing a batched
  *     source leaves a stale instance until rebuild. (Static scenery is load-time stable.)
- *   - Installed for scene-file loads (scenePath/sceneData), not the imperative setup()
- *     path — setup() games manage their own scene/spawning.
  *   - The batch culls as ONE unit (no per-instance frustum culling yet — Tier-2).
  */
 
@@ -61,29 +58,6 @@ const SIG = (m: THREE.Mesh): string =>
   // (the InstancedMesh carries one flag for the whole group).
   `${geoKey(m.geometry as THREE.BufferGeometry)}|${matKey(m.material as THREE.Material)}|${m.castShadow ? 1 : 0}${m.receiveShadow ? 1 : 0}`;
 
-interface EntityDef {
-  render?: { autoBatch?: boolean };
-  physics?: unknown;
-  components?: Record<string, unknown>;
-  animation?: unknown;
-}
-
-/** Nearest self/ancestor entity descriptor, if any. */
-function nearestEntity(obj: THREE.Object3D): EntityDef | undefined {
-  let cur: THREE.Object3D | null = obj;
-  while (cur) {
-    const entity = getUserData(cur, 'entity') as unknown as EntityDef | undefined;
-    if (entity) return entity;
-    cur = cur.parent;
-  }
-  return undefined;
-}
-
-/** Explicit per-entity opt-out (`render.autoBatch === false`). */
-function entityOptOut(obj: THREE.Object3D): boolean {
-  return nearestEntity(obj)?.render?.autoBatch === false;
-}
-
 /** Match Three.js renderer visibility: a hidden ancestor hides the whole subtree. */
 function isEffectivelyVisible(obj: THREE.Object3D): boolean {
   let cur: THREE.Object3D | null = obj;
@@ -103,23 +77,22 @@ function isBatchCandidate(object: THREE.Object3D, batchRoot: THREE.Group): objec
   if (!isEffectivelyVisible(mesh)) return false;
   if (!mesh.geometry || !mesh.material || Array.isArray(mesh.material)) return false;
   if ((mesh.material as THREE.Material).transparent) return false;
-  if (batchRoot === mesh.parent) return false;
-  return !entityOptOut(mesh);
+  return batchRoot !== mesh.parent;
 }
 
 /**
- * Static-batching eligibility: only entities that won't move are safe to freeze
- * and instance. An entity with physics, behavior components, or its own animation
- * is a likely mover → left as an ordinary draw. Plain scenery (no def, or a def
- * with none of those) is eligible. This is the safe, transparent default; a future
- * dynamic-batch path (markMoved-driven) can include movers.
+ * Static-batching eligibility: only objects that won't move are safe to freeze
+ * and instance. An object (or an ancestor) carrying its own animation mixer is
+ * a likely mover → left as an ordinary draw. Plain scenery is eligible. This is
+ * the safe, transparent default; a future dynamic-batch path (markMoved-driven)
+ * can include movers.
  */
 function isLikelyStatic(obj: THREE.Object3D): boolean {
-  const e = nearestEntity(obj);
-  if (!e) return true; // un-tagged scenery
-  if (e.physics) return false;
-  if (e.animation) return false;
-  if (e.components && Object.keys(e.components).length > 0) return false;
+  let cur: THREE.Object3D | null = obj;
+  while (cur) {
+    if (getUserData(cur, '_animMixer')) return false;
+    cur = cur.parent;
+  }
   return true;
 }
 

package/src/render/render-features.ts

@@ -7,7 +7,7 @@ import { z } from 'zod';
  * overlay are all derived from this list, so "everything togglable" stays
  * consistent by construction (same posture as the component/material/instancer
  * registries). Adding a feature here gives it a schema field + cascade entry for
- * free. See docs/research/RENDER-SETTINGS-UX.md.
+ * free..
  */
 
 export type RenderFeatureValue = boolean | number | string;

package/src/render/render-settings.ts

@@ -2,8 +2,7 @@ import { RENDER_FEATURES, type RenderFeatureValue } from './render-features';
 
 /**
  * Cascade resolution for render settings: engine default → scene → entity, with
- * tri-state inherit (an absent value inherits from the next level up). See
- * docs/research/RENDER-SETTINGS-UX.md.
+ * tri-state inherit (an absent value inherits from the next level up)..
  */
 
 /** A partial override map (scene-level or entity-level). Absent key = inherit. */

package/src/render/spark-renderer-lifecycle.ts

@@ -1,6 +1,6 @@
 import type { SparkRenderer } from '@sparkjsdev/spark';
 import type * as THREE from 'three';
-import { hasUserData } from '../scene/user-data';
+import { hasUserData } from '../ecs/user-data';
 
 const IDLE_POLL_MS = 16;
 const MAX_IDLE_WAIT_MS = 3_000;