@vgai/engine 0.5.1 → 0.5.3

package/src/world3d-react/renderer-config.ts

@@ -0,0 +1,137 @@
+/**
+ * world3d-react/renderer-config.ts — the seam a WORLD uses to state how its own frame is rendered.
+ *
+ * The host owns the `WebGLRenderer` (`ThreeHostContext.renderer`) and configures it with this
+ * engine's defaults: ACES tone mapping, sRGB output, PCF-soft shadows. Those defaults are right for
+ * a world authored against them and WRONG for a world that was authored against a different
+ * engine's pipeline — an imported Godot 3 GLES2 game does gamma-space lighting with no tonemapper
+ * at all, so ACES quietly desaturates and darkens every colour its author picked.
+ *
+ * So a world may DECLARE the pipeline it was authored for, and `createR3FAdapter` applies it to the
+ * host's renderer for the life of the mount, restoring what it found on dispose. Three properties
+ * of that shape are load-bearing:
+ *
+ *  - **It is per-renderer, never engine-wide.** Every field here is a `WebGLRenderer` instance
+ *    property, and a play root gets its own renderer (`create-runtime.ts`). Nothing here reaches a
+ *    module-level three global, so one world's declaration cannot change how the editor's own
+ *    viewport, another root, or a thumbnail bake renders.
+ *  - **Absent means "leave the host's value alone".** Every field is optional and an omitted one
+ *    is never written, so declaring a tone mapping does not silently reset the clear colour.
+ *  - **It is restored on dispose.** The renderer outlives the mount, so a world that did not put
+ *    back what it found would leak its pipeline into whatever mounts next.
+ *
+ * This is deliberately NOT a general render-settings system. It carries what a world can honestly
+ * state about its own colour pipeline and nothing else; a property the host fixes at CONSTRUCTION
+ * (the WebGL context's `antialias` attribute, and therefore the MSAA sample count) cannot be
+ * declared here, because there would be no honest moment to apply it.
+ */
+
+import type * as THREE from 'three';
+
+/** The tone-mapping operators three exposes, named as data rather than as three's numeric enum. */
+export type WorldToneMapping =
+  | 'none'
+  | 'linear'
+  | 'reinhard'
+  | 'cineon'
+  | 'aces'
+  | 'agx'
+  | 'neutral';
+
+/**
+ * The output transfer function the frame is written with.
+ *
+ *  - `srgb` — three's own default and this engine's: linear lighting, sRGB encode on output.
+ *  - `srgb-linear` — NO output transform. This is what a gamma-space renderer needs: the shading
+ *    result is already in display space and encoding it a second time washes the frame out.
+ */
+export type WorldOutputColorSpace = 'srgb' | 'srgb-linear';
+
+/** What a world may declare about the renderer that draws it. Every field is optional; see header. */
+export interface WorldRendererConfig {
+  readonly toneMapping?: WorldToneMapping | undefined;
+  readonly toneMappingExposure?: number | undefined;
+  readonly outputColorSpace?: WorldOutputColorSpace | undefined;
+  /**
+   * The colour the frame is cleared to, as a CSS hex string. The renderer's existing clear ALPHA
+   * is preserved: a stacked canvas is transparent on purpose (`create-runtime.ts` gives every
+   * non-bottom root `alpha: true`), and forcing it opaque here would hide every layer below.
+   */
+  readonly clearColor?: string | undefined;
+}
+
+/**
+ * Apply `config` to `renderer`, returning the restore function that puts back what was there.
+ *
+ * `three` is passed in rather than imported for values so the enum constants come from the HOST's
+ * three instance — the same identity rule `r3f-adapter.tsx` follows for the scene and camera.
+ */
+export function applyWorldRendererConfig(
+  three: typeof THREE,
+  renderer: THREE.WebGLRenderer,
+  config: WorldRendererConfig,
+): () => void {
+  // A host that mounts a world WITHOUT rasterizing it hands the adapter a duck-typed renderer —
+  // the editor's design session (`createDesignTimeRenderer`: four members, deliberately never
+  // widened) and jsdom test harnesses both do. Such a surface has no colour pipeline to configure:
+  // the frame the user sees is drawn by a DIFFERENT renderer (the editor's own), so applying the
+  // world's config there is meaningless — and calling `getClearColor` on it is a TypeError that
+  // unmounts the whole world at edit time (measured: every Godot port's edit viewport blanked with
+  // '"world" failed to mount — renderer.getClearColor is not a function'). Detect the real
+  // `WebGLRenderer` surface by the one method this function must call, and no-op otherwise.
+  if (typeof renderer.getClearColor !== 'function') {
+    return () => {};
+  }
+  const toneMappings: Record<WorldToneMapping, THREE.ToneMapping> = {
+    none: three.NoToneMapping,
+    linear: three.LinearToneMapping,
+    reinhard: three.ReinhardToneMapping,
+    cineon: three.CineonToneMapping,
+    aces: three.ACESFilmicToneMapping,
+    agx: three.AgXToneMapping,
+    neutral: three.NeutralToneMapping,
+  };
+  const colorSpaces: Record<WorldOutputColorSpace, THREE.ColorSpace> = {
+    srgb: three.SRGBColorSpace,
+    'srgb-linear': three.LinearSRGBColorSpace,
+  };
+
+  const restores: (() => void)[] = [];
+
+  if (config.toneMapping !== undefined) {
+    const previous = renderer.toneMapping;
+    renderer.toneMapping = toneMappings[config.toneMapping];
+    restores.push(() => {
+      renderer.toneMapping = previous;
+    });
+  }
+  if (config.toneMappingExposure !== undefined) {
+    const previous = renderer.toneMappingExposure;
+    renderer.toneMappingExposure = config.toneMappingExposure;
+    restores.push(() => {
+      renderer.toneMappingExposure = previous;
+    });
+  }
+  if (config.outputColorSpace !== undefined) {
+    const previous = renderer.outputColorSpace;
+    renderer.outputColorSpace = colorSpaces[config.outputColorSpace];
+    restores.push(() => {
+      renderer.outputColorSpace = previous;
+    });
+  }
+  if (config.clearColor !== undefined) {
+    const previousColor = new three.Color();
+    renderer.getClearColor(previousColor);
+    // Alpha is READ BACK and re-passed, never assumed: see `clearColor`'s doc above.
+    const alpha = renderer.getClearAlpha();
+    renderer.setClearColor(new three.Color(config.clearColor), alpha);
+    restores.push(() => {
+      renderer.setClearColor(previousColor, alpha);
+    });
+  }
+
+  return () => {
+    // Reverse order, so a field written twice (it cannot be, today) unwinds correctly.
+    for (let i = restores.length - 1; i >= 0; i--) restores[i]?.();
+  };
+}

package/src/world3d-react/world-context.ts

@@ -1,18 +1,18 @@
 /**
- * `createR3FWorldContext` — the ENGINE runtime an R3F world owns, split out of
+ * `createR3FRootContext` — the ENGINE runtime an R3F world owns, split out of
  * `./r3f-adapter.tsx` so it stays react-free and headlessly unit-testable
  * (`test/world3d-react-context-parity.test.tsx`).
  *
  * Context parity with the classic first-party adapter
- * (`../adapter/vgai-scene-game-adapter.ts`) — closed here after a dogfood
+ * (`../adapter/setup-three-root-adapter.ts`) — closed here after a dogfood
  * build had to shim around three silent gaps:
  *
  *  1. **`ctx.debug` / `ctx.random` / `ctx.game` / `ctx.roots` are wired**
  *     exactly the way the classic adapter wires them: the ONE game-scoped
  *     debug registry (`getDebugRegistry(host.game)`) provides
- *     `ctx.debug = registry.forWorld(id)`, so a Behavior-attached component's
- *     `init(ctx)` can `ctx.debug.registerStateProvider(...)` and be visible
- *     to `vgai e2e`/the editor's debug panels — previously a silent no-op.
+ *     `ctx.debug = registry.forRoot(id)`, so a component's
+ *     effect can `ctx.debug.registerStateProvider(...)` and be visible
+ *     to `vgai eval`/the editor's debug panels — previously a silent no-op.
  *  2. **`ctx.input` is the game-owned `InputManager`** (`host.game.input` —
  *     the same instance the classic adapter uses when hosted), and this
  *     module registers the SAME per-world debug-registry seams the classic
@@ -25,40 +25,89 @@
  *     LOUDLY (console.error naming the path and what breaks) without
  *     failing the mount — an R3F tree with no actions (e.g. a pure
  *     OrbitControls demo, `examples/r3f-first-party`) is legal.
- *  3. **Absent subsystems fail loudly at the ctx surface.** An R3F world
- *     builds no Rapier world, composer, audio, particles, or debug-draw —
- *     reading those `ctx` fields used to yield `undefined` (then fail
- *     somewhere downstream, or silently no-op). They are now throwing
- *     getters naming the limitation and the sanctioned alternative.
- *
- * The `ComponentManager` built here is also exposed on the mounted world
- * (`MountedWorldBase.components`) so `Game.queryByComponent` aggregates R3F
- * Behavior components exactly like scene-authored ones — see
- * `runtime/game.ts`.
- */
+ *  3. **Absent subsystems are absent from the TYPE.** An R3F world builds no
+ *     Rapier world, composer, audio, particles, or debug-draw, and
+ *     {@link R3FGameContext} — the type `useGameContext()` hands back — simply
+ *     does not have those fields. Reaching for one is a compile error at the
+ *     call site, with the sanctioned alternative in that type's doc comment.
+ * */
 
 import type * as THREE from 'three';
-import type { HostContext } from '../adapter';
+import type { ThreeHostContext } from '../adapter';
 import type { SystemAdapters } from '../adapter/system-adapter';
 import {
   createSeededRandom,
   DEFAULT_SEEDED_RANDOM_SEED,
   getSeededRandom,
 } from '../core/seeded-random';
+import { createSimClock, getSimClock, type SimClockInternal } from '../core/sim-clock';
 import { createSystemRunner } from '../core/system-runner';
-import { type ComponentManager, createComponentManager } from '../ecs/component-manager';
+import { createSceneIndex, type SceneIndex } from '../ecs/scene-index';
 import {
   createDebugRegistry,
   type DebugRegistry,
   getDebugRegistry,
 } from '../runtime/debug-registry';
+import { disposeDebrisSubtree } from '../runtime/game';
 import type { GameContext } from '../runtime/types';
 
 /** The classic adapter's default input-map path — the conventional location
  *  every scaffolded project ships (`public/inputmaps/default.inputmap.json`). */
 export const DEFAULT_INPUT_MAP_PATH = '/inputmaps/default.inputmap.json';
 
-export interface R3FWorldContextOptions {
+/**
+ * The engine context an R3F world genuinely provides — what
+ * `useGameContext()` hands back.
+ *
+ * An EXPLICIT `Pick`, never an `Omit`: a field added to `GameContext` later
+ * must be deliberately admitted here, so this surface can never silently widen
+ * into something an R3F mount does not build.
+ *
+ * **What an R3F world does NOT have, and what to reach for instead.** These
+ * are not oversights — the mount builds none of them, so they are absent from
+ * this type and naming one is a compile error rather than a crash mid-render:
+ *
+ * - **Physics** (`rapierWorld`, `rapier`, `physics`, `collisions`) — an R3F
+ *   world does not build the first-party Rapier runtime. Use a physics
+ *   solution inside the fiber tree (e.g. `@react-three/rapier`), or an
+ *   imperative three root whose `setup(ctx)` receives the first-party Rapier
+ *   runtime.
+ * - **`composer`** — R3F renders through react-three-fiber against the host
+ *   renderer; there is no postprocessing `EffectComposer` here. Use
+ *   fiber-native postprocessing inside the tree.
+ * - **`audio`** — no first-party audio context is built. Own a Web Audio graph
+ *   inside the tree (or use drei's audio helpers) and register it as this
+ *   world's `SystemAdapters.audio` via
+ *   `ctx.registerSystemAdapter('audio', …)`, so host mute/pause can still
+ *   silence it — `examples/third-person/src/lib/audio/sfx.ts` is the worked
+ *   reference.
+ * - **`particles`** — no three.quarks particle runtime. Drive particles from
+ *   the fiber tree.
+ * - **`debugDraw`** — no debug-draw helper. Add helper objects to the fiber
+ *   tree directly.
+ *
+ * For the full classic runtime, use an imperative three root instead: a module
+ * exporting `setup(ctx): Promise<GameCleanup>`, which `SetupThreeRootAdapter`
+ * mounts with the complete {@link GameContext}.
+ */
+export type R3FGameContext = Pick<
+  GameContext,
+  | 'scene'
+  | 'camera'
+  | 'sceneIndex'
+  | 'input'
+  | 'assets'
+  | 'systems'
+  | 'clock'
+  | 'debug'
+  | 'random'
+  | 'game'
+  | 'roots'
+  | 'playtest'
+  | 'registerSystemAdapter'
+>;
+
+export interface R3FRootContextOptions {
   /** World id — provenance for every debug-registry registration (matches the
    *  manifest root id by the same convention the classic adapter follows). */
   readonly id: string;
@@ -72,18 +121,14 @@ export interface R3FWorldContextOptions {
   readonly inputMapPath?: string | null | undefined;
 }
 
-/** What {@link createR3FWorldContext} returns — the engine runtime one R3F
+/** What {@link createR3FRootContext} returns — the engine runtime one R3F
  *  world owns, plus the wiring hooks `createR3FAdapter`'s `mount()` drives. */
-export interface R3FWorldRuntime {
-  /** The (partial, loud-on-absence) `GameContext` handed to every attached
-   *  GameComponent. See this module's header for exactly what is present. */
-  readonly ctx: GameContext;
+export interface R3FRootRuntime {
+  /** The context this world's components read through `useGameContext()` —
+   *  see {@link R3FGameContext} for exactly what an R3F world provides. */
+  readonly ctx: R3FGameContext;
   /** The world-local phase runner `mount().update(dt)` ticks. */
   readonly systems: ReturnType<typeof createSystemRunner>;
-  /** The engine's REAL ComponentManager for this world — `<Behavior>`
-   *  attaches through it; expose it as `mounted.components` so
-   *  `Game.queryByComponent` spans this world. */
-  readonly components: ComponentManager;
   /** The mounted world's `SystemAdapters` bag (`mounted.systems`) —
    *  `ctx.registerSystemAdapter` writes into it; `debug` is pre-seeded. */
   readonly systemAdapters: SystemAdapters;
@@ -101,68 +146,48 @@ export interface R3FWorldRuntime {
   dispose(): void;
 }
 
-/** Install a throwing getter for a `GameContext` field this world genuinely
- *  does not build — a component reaching for it fails LOUDLY at its own call
- *  site, naming the limitation, instead of reading `undefined` and breaking
- *  somewhere downstream (or silently no-op-ing). Non-enumerable so spreads/
- *  serialization of the ctx never trip it. */
-function defineAbsentCtxField(
-  target: Record<string, unknown>,
-  worldId: string,
-  key: string,
-  why: string,
-): void {
-  Object.defineProperty(target, key, {
-    configurable: true,
-    enumerable: false,
-    get(): never {
-      throw new Error(
-        `R3F world "${worldId}": ctx.${key} is not available — ${why} ` +
-          '(An R3F world ctx provides: scene, camera, input, assets, systems, components, ' +
-          'debug, random, game, roots, registerSystemAdapter. For the full classic runtime, ' +
-          'use a .vscn scene root instead.)',
-      );
-    },
-  });
-}
-
 /**
- * Build the engine runtime for one R3F world from a `HostContext` — the same
- * wiring, at the same layer, as the classic `VgaiSceneGameAdapter.mount()`
+ * Build the engine runtime for one R3F world from a `ThreeHostContext` — the same
+ * wiring, at the same layer, as the classic `SetupThreeRootAdapter.mount()`
  * performs for the subsystems an R3F world shares with it (debug, input,
- * random, components); loud throwing getters for the ones it doesn't.
+ * random). The ones it does not build are not on
+ * {@link R3FGameContext} at all.
  */
-export function createR3FWorldContext(
-  host: HostContext,
-  options: R3FWorldContextOptions,
-): R3FWorldRuntime {
+export function createR3FRootContext(
+  host: ThreeHostContext,
+  options: R3FRootContextOptions,
+): R3FRootRuntime {
   const { id, inputMapPath = DEFAULT_INPUT_MAP_PATH } = options;
 
   // Same observer threading as the classic adapter — profiler sees this
   // world's phases under the shared game profiler when hosted.
-  const systems = createSystemRunner(host.game?.profiler.systemObserver, 'threejs');
+  const systems = createSystemRunner(host.game?.profiler.systemObserver, 'three');
 
   // The mounted world's adapter surface (`mounted.systems`) — declared before
   // ctx so `ctx.registerSystemAdapter` can close over it (classic parity: a
   // game-owned capability like networking registers here from component code).
   const systemAdapters: SystemAdapters = {};
 
+  // The world's live scene index — built in `setSceneCamera` (below), because
+  // fiber resolves the scene after this function returns. Same lifetime as
+  // `ctx.scene`, which is backfilled at the same moment.
+  let sceneIndex: SceneIndex | null = null;
+
   const ctxRaw: Record<string, unknown> = {
     systems,
     assets: host.assets,
     registerSystemAdapter: (kind: keyof SystemAdapters, adapter: SystemAdapters[typeof kind]) => {
       // biome-ignore lint/suspicious/noExplicitAny: same per-key record write the classic adapter performs; correct by construction
       (systemAdapters as any)[kind] = adapter;
+      host.game?.notifySystemAdaptersChanged();
     },
   };
-  const ctx = ctxRaw as unknown as GameContext;
+  const ctx = ctxRaw as unknown as R3FGameContext;
   if (host.game) {
     ctx.game = host.game;
     ctx.roots = host.game.roots;
+    ctx.playtest = host.game.playtest ?? null;
   }
-  const components = createComponentManager(ctx);
-  ctxRaw['components'] = components;
-
   // --- ctx.debug (gap 1) — the ONE registry per Game root, shared across
   // every world mounted onto it; a bare mount with no Game shell gets a
   // private, mount-local registry instead (same absence precedent as the
@@ -171,11 +196,24 @@ export function createR3FWorldContext(
     (host.game ? getDebugRegistry(host.game) : null) ??
     createDebugRegistry({ getTick: () => 0, getSimT: () => 0 });
   systemAdapters.debug = debugRegistry.adapter;
-  ctx.debug = debugRegistry.forWorld(id);
+  ctx.debug = debugRegistry.forRoot(id);
   ctx.random =
     (host.game ? getSeededRandom(host.game) : null) ??
     createSeededRandom(DEFAULT_SEEDED_RANDOM_SEED);
 
+  // --- ctx.clock (P3) — every world has a sim clock, R3F included. Same
+  // game-scoped reach-in as `ctx.random` above; a bare mount with no Game
+  // shell gets a private, mount-local clock that nothing flushes (there is no
+  // fixed loop to bind timers to). The mount-local fallback uses the SAME
+  // `disposeDebrisSubtree` the hosted path uses — it drops
+  // the subtree and disposes geometry/materials, with no Rapier owners
+  // because this ctx carries no `physics`/`rapierWorld` (the
+  // honest "this world owns no bodies").
+  const gameClock: SimClockInternal | null = host.game ? getSimClock(host.game) : null;
+  const clock: SimClockInternal =
+    gameClock ?? createSimClock({ dispose: (obj) => disposeDebrisSubtree(obj, []) });
+  ctx.clock = clock;
+
   // --- ctx.input + the debug-registry input seams (gap 3) — the game-owned
   // InputManager, polled by the game-scoped runner each frame; this world
   // registers the SAME per-world seams the classic adapter registers so
@@ -228,63 +266,55 @@ export function createR3FWorldContext(
       });
     }
   } else {
-    defineAbsentCtxField(
-      ctxRaw,
-      id,
-      'input',
-      'input is game-owned and this mount has no Game host (host.game is absent — bare ' +
-        'harness/foreign host); mount through the vgai host to get the shared InputManager.',
-    );
+    // `input` IS a field of every R3F world's ctx — it is game-owned, and this
+    // particular mount has no Game to own it (a bare harness or a foreign
+    // host). A throwing getter names that at the read, instead of handing back
+    // `undefined` that breaks deep inside a frame callback. Non-enumerable so
+    // spreads/serialization of the ctx never trip it.
+    Object.defineProperty(ctxRaw, 'input', {
+      configurable: true,
+      enumerable: false,
+      get(): never {
+        throw new Error(
+          `R3F world "${id}": ctx.input is game-owned and this mount has no Game host ` +
+            '(host.game is absent — bare harness/foreign host); mount through the vgai host ' +
+            'to get the shared InputManager.',
+        );
+      },
+    });
   }
 
-  // --- Loud absence for the classic-only subsystems (gap 1's honesty rule:
-  // a thrown error naming the limitation beats a silent undefined). ---
-  const rapierWhy =
-    'R3F worlds do not build the first-party Rapier physics runtime; use a physics ' +
-    'solution inside the fiber tree (e.g. @react-three/rapier) or a classic .vscn world root.';
-  defineAbsentCtxField(ctxRaw, id, 'rapierWorld', rapierWhy);
-  defineAbsentCtxField(ctxRaw, id, 'rapier', rapierWhy);
-  defineAbsentCtxField(ctxRaw, id, 'physics', rapierWhy);
-  defineAbsentCtxField(ctxRaw, id, 'collisions', rapierWhy);
-  defineAbsentCtxField(
-    ctxRaw,
-    id,
-    'composer',
-    'R3F worlds render through react-three-fiber against the host renderer; there is no ' +
-      'postprocessing EffectComposer here (use fiber-native postprocessing inside the tree).',
-  );
-  defineAbsentCtxField(
-    ctxRaw,
-    id,
-    'audio',
-    'R3F worlds build no first-party audio context; use Web Audio directly (or drei audio ' +
-      'helpers) inside the tree.',
-  );
-  defineAbsentCtxField(
-    ctxRaw,
-    id,
-    'particles',
-    'R3F worlds build no three.quarks particle runtime; drive particles from the fiber tree.',
-  );
-  defineAbsentCtxField(
-    ctxRaw,
-    id,
-    'debugDraw',
-    'R3F worlds build no debug-draw helper; add helper objects to the fiber tree directly.',
-  );
-
   return {
     ctx,
     systems,
-    components,
     systemAdapters,
     inputMapReady,
     setSceneCamera(scene, camera): void {
+      const sameScene = ctxRaw['scene'] === scene && sceneIndex !== null;
       ctxRaw['scene'] = scene;
       ctxRaw['camera'] = camera;
+      // The live scene index (P2 `observe`) is a REAL value here, not a
+      // throwing getter — every three world has one. It can only be built once
+      // fiber has resolved the scene, which is the same moment `ctx.scene`
+      // itself becomes readable, so index and scene share one lifetime. A
+      // second commit (fiber handing back a different scene) replaces it.
+      //
+      // Keyed on the SCENE, so a camera-only backfill (a world swapping the
+      // default camera after mount) leaves the index — and every `observe`
+      // subscription hanging off it — alone.
+      if (sameScene) return;
+      sceneIndex?.dispose();
+      sceneIndex = createSceneIndex(scene);
+      ctxRaw['sceneIndex'] = sceneIndex;
     },
     dispose(): void {
-      components.clear();
+      // Same ownership rule as the classic adapter's teardown: dispose ONLY a
+      // clock this mount created. The game-scoped one belongs to
+      // `GameInternal.dispose()` — killing it here would freeze sim time and
+      // cancel every SIBLING world's timers.
+      if (!gameClock) clock.dispose();
+      sceneIndex?.dispose();
+      sceneIndex = null;
       // Scoped strip when a Game hosts this world (sibling roots stay live);
       // a bare standalone mount owns its private registry and clears it all.
       if (host.game) debugRegistry.strip(id);