@vgai/engine 0.4.1 → 0.5.0-canary.20260719.0

package/src/world3d-react/r3f-adapter.tsx

@@ -0,0 +1,303 @@
+/**
+ * `createR3FAdapter` — wraps a react-three-fiber tree as a first-party
+ * `GameAdapter` so an R3F scene mounts as an ordinary `kind: "threejs"`
+ * world: the engine hands `mount()` a `HostContext` (ITS OWN renderer +
+ * canvas + gated loop, per `../adapter/host-context.ts`); this returns a
+ * `MountedThreeWorld` (`../adapter/game-adapter.ts`) whose `scene`/`camera`
+ * are fiber's REAL `THREE.Scene`/`THREE.Camera` instances.
+ *
+ * Upstreamed from `examples/r3f-first-party/src/r3f-adapter.tsx` (R4,
+ * docs/R3F-FOLLOW-THROUGH-SPEC.md — the `@engine/world3d-react` opt-in
+ * module R3F-FIRST-PARTY-DESIGN §1.B Phase 2 names, mirroring how `world2d/`
+ * is pixi's opt-in home). The mount semantics are byte-for-byte the
+ * example's live-proven Phase-1 bridge; the one addition is the optional
+ * `components` registry threaded into `EngineBridge` so `<Behavior>` can
+ * resolve project component classes without the engine importing project
+ * code. External adopters (alien-stories-style) keep the exact same calling
+ * contract.
+ *
+ * three.js identity (docs/ADAPTER-AUTHORING-GUIDE.md §2): this module never
+ * imports `three` itself for scene objects — fiber's internal `import * as
+ * THREE from 'three'` must resolve to the SAME instance the engine's
+ * `HostContext.three` points at, which the importing project guarantees via
+ * its Vite `resolve.dedupe: ['three', 'react', 'react-dom']` (see
+ * `examples/r3f-first-party/vite.config.ts`).
+ */
+
+import { advance, createRoot, extend, type RootState } from '@react-three/fiber';
+import { createElement, type ReactNode } from 'react';
+import type { GameAdapter, HostContext, MountedThreeWorld } from '../adapter';
+import { type BehaviorRegistry, EngineBridge, type EngineBridgeValue } from './engine-bridge';
+import { createR3FWorldContext } from './world-context';
+
+/** What {@link createR3FAdapter} needs to build one `GameAdapter`. */
+export interface CreateR3FAdapterOptions {
+  /** Stable id (telemetry/registry/conformance) — `GameAdapter.id`. */
+  readonly id: string;
+  /** The R3F scene tree to mount — drei helpers, `useFrame` hooks, etc. all
+   *  work unchanged (design §1.C: "drei works unchanged (it is fiber-context
+   *  userland)"). */
+  readonly content: ReactNode;
+  /** The project's behavior registry — `<Behavior type="…">` resolves against
+   *  it through `EngineBridge`. Optional: a tree with no `<Behavior>` usage
+   *  needs none; a `<Behavior>` rendered without it degrades loudly (warn,
+   *  no attach) rather than crashing. */
+  readonly components?: BehaviorRegistry | undefined;
+  /** Input map loaded through the game-owned `Game.loadInputMap` (load-once
+   *  across roots). Defaults to the classic adapter's conventional path,
+   *  `/inputmaps/default.inputmap.json`; `null` opts out (a world with no
+   *  actions). A missing/invalid map degrades loudly without failing the
+   *  mount — see `world-context.ts`. */
+  readonly inputMapPath?: string | null | undefined;
+}
+
+/**
+ * Build a `GameAdapter` that mounts `options.content` through
+ * react-three-fiber, gated entirely by the host's own loop and rendering
+ * through the host's own `WebGLRenderer` — never a second renderer, never a
+ * second `requestAnimationFrame` loop (design §1.C).
+ */
+export function createR3FAdapter(options: CreateR3FAdapterOptions): GameAdapter {
+  const { id, content, components: registry, inputMapPath } = options;
+
+  return {
+    id,
+
+    async mount(host: HostContext): Promise<MountedThreeWorld> {
+      // Headless honesty (design §1.D; `docs/ADAPTER-AUTHORING-GUIDE.md` §2's
+      // "Your `mount()` must work headless" rule): the conformance kit / CI
+      // runs `mount()` in Node — no canvas, no WebGL, no fiber reconciler.
+      // Guard the ENTIRE fiber mount behind `!host.headless` and return a
+      // bare, real scene + camera instead (still `instanceof
+      // host.three.Scene` / `.Camera` — the identity rule holds even here,
+      // since this uses the host's own `three` instance, not a fresh
+      // import). Residual: the hierarchy is empty under headless
+      // conformance — recorded as design O2, not hidden; a react-nil-style
+      // headless reconciler mount is the known fix, out of scope for v1.
+      if (host.headless) {
+        const scene = new host.three.Scene();
+        const camera = new host.three.PerspectiveCamera();
+        return {
+          kind: 'threejs',
+          scene,
+          camera,
+          drivesOwnLoop: false,
+          dispose(): void {
+            /* nothing was ever mounted */
+          },
+        };
+      }
+
+      // Fiber v9 made the THREE catalogue tree-shakeable: `<Canvas>` calls
+      // `extend(THREE)` for you, a bare `createRoot` does NOT — without this,
+      // the FIRST three intrinsic in the tree (`<color>`, `<ambientLight>`,
+      // …) throws "X is not part of the THREE namespace! Did you forget to
+      // extend?" at reconcile time. Extending with `host.three` (not a fresh
+      // `import * as THREE`) keeps the catalogue on the host's deduped three
+      // instance — the same identity rule the returned scene/camera rely on.
+      // `extend` merges into a module-global catalogue, so calling it once
+      // per mount is idempotent.
+      extend(host.three as unknown as Parameters<typeof extend>[0]);
+
+      // W3 (docs/R3F-SURFACE-SPIKE.md) — the engine component runtime this
+      // world OWNS: a real SystemRunner + ComponentManager pair, provided to
+      // the R3F tree via `EngineBridge` so `<Behavior>` (./behavior.tsx) can
+      // attach registry GameComponents with the engine's REAL attach path.
+      // `update(dt)` below runs the phases under the host loop, so attached
+      // components tick in engine phase order and freeze under pause exactly
+      // like `useFrame` work does.
+      //
+      // HONESTY NOTE: the manager's ctx is still a PARTIAL GameContext, but
+      // the shared game-scoped subsystems are now REAL classic-adapter parity
+      // (`./world-context.ts`): `ctx.debug`/`ctx.random`/`ctx.game`/`ctx.roots`,
+      // and `ctx.input` (the game-owned InputManager, with this world's
+      // virtual-input/actions/trace debug seams registered and the project's
+      // input map loaded). The subsystems an R3F world genuinely does not
+      // build (Rapier, composer, audio, particles, debugDraw) are THROWING
+      // getters naming the limitation — never a silent `undefined`.
+      // `scene`/`camera` are backfilled right after fiber's first commit
+      // resolves them, before any tick can run.
+      const runtime = createR3FWorldContext(host, { id, inputMapPath });
+      const { systems, components } = runtime;
+      const bridge: EngineBridgeValue = { components, registry };
+      // Actions must exist before any Behavior component's init() reads them —
+      // wait for the (never-rejecting) input-map load before the first commit.
+      await runtime.inputMapReady;
+
+      const canvas = host.surface.canvas;
+      const root = createRoot(canvas);
+
+      // `RootState` (the live scene/camera/gl fiber built) only arrives via
+      // the `onCreated` callback — `root.render()`'s return value is
+      // TECHNICALLY the same store, but `onCreated` is the hook the design
+      // doc's §1.C sketch names, and waiting for it (rather than assuming
+      // the first commit already ran synchronously) is the honest choice
+      // under React 19's concurrent renderer, which does not guarantee a
+      // synchronous first commit the way legacy ReactDOM.render did.
+      let resolveState!: (state: RootState) => void;
+      const statePromise = new Promise<RootState>((resolve) => {
+        resolveState = resolve;
+      });
+
+      // `root.configure()` is ASYNC in fiber v9 (`Promise<ReconcilerRoot>`)
+      // — the design doc's §1.C sketch shows it called synchronously; the
+      // real v9 API (verified against
+      // `node_modules/@react-three/fiber/dist/declarations/src/core/index.d.ts`)
+      // requires awaiting it before `render()`.
+      await root.configure({
+        // The engine's renderer, not a second one (design §1.C) — fiber
+        // renders THROUGH `host.renderer` instead of constructing its own
+        // `WebGLRenderer`.
+        gl: host.renderer,
+        // The engine's gated loop is the ONLY loop — fiber must never run
+        // its own rAF (that would defeat editor pause; design §1.C's
+        // `drivesOwnLoop: false` contract, guide §2's loop-model note).
+        frameloop: 'never',
+        // `RenderProps.size` types as the FULL `Size` (width/height/top/left),
+        // not `Partial<Size>` — the design sketch's `{ width, height }` alone
+        // does not satisfy fiber v9's real type, so `top`/`left` are pinned
+        // to 0 (this bridge always fills its whole canvas; no offset
+        // viewport in v1).
+        size: { width: host.surface.width, height: host.surface.height, top: 0, left: 0 },
+        // `events` deliberately left at fiber's default (binds to
+        // `gl.domElement`, i.e. `host.surface.canvas`) — design O1's open
+        // question about a delegating multi-canvas input router only
+        // matters for a shell+net composite; this bridge is a genuine
+        // single-canvas world, the case O1 already says is unaffected.
+        onCreated: (state) => resolveState(state),
+      });
+      // No `<StrictMode>` (design §1.C: "no StrictMode: host mounts once")
+      // — this bridge mounts exactly once per `mount()` call; StrictMode's
+      // deliberate double-invoke of effects would double-subscribe
+      // `useFrame` callbacks against a host loop that only ticks once per
+      // frame. The `EngineBridge` provider threads the component runtime
+      // (above) to any `<Behavior>` wrapper in the tree (W3).
+      root.render(createElement(EngineBridge.Provider, { value: bridge }, content));
+      // A reconcile-time crash (e.g. a missing `extend` catalogue entry)
+      // surfaces as an uncaught window error and `onCreated` never fires —
+      // without this guard, `mount()` would await `statePromise` FOREVER and
+      // silently wedge every world declared after this one (roots mount
+      // sequentially). Convert that class of failure into a loud mount error.
+      const state = await new Promise<RootState>((resolve, reject) => {
+        const onError = (event: ErrorEvent) => {
+          cleanup();
+          root.unmount();
+          runtime.dispose();
+          reject(
+            new Error(
+              `r3f-adapter: fiber crashed before its first commit — ${event.message} ` +
+                '(mount() fails loudly instead of hanging on onCreated)',
+            ),
+          );
+        };
+        const timer = setTimeout(() => {
+          cleanup();
+          root.unmount();
+          runtime.dispose();
+          reject(
+            new Error(
+              'r3f-adapter: onCreated did not fire within 10s — the R3F tree never reached ' +
+                'its first commit (mount() fails loudly instead of hanging)',
+            ),
+          );
+        }, 10_000);
+        const cleanup = () => {
+          clearTimeout(timer);
+          window.removeEventListener('error', onError);
+        };
+        window.addEventListener('error', onError);
+        void statePromise.then((s) => {
+          cleanup();
+          resolve(s);
+        });
+      });
+
+      // Clock hardening (field-proven by the first external adopter,
+      // alien-stories' proto): fiber's internal `update()` calls
+      // `state.clock.getDelta()` BEFORE its `frameloop:'never'` branch, and a
+      // RUNNING (or autoStart) `THREE.Clock` accumulates WALL time into
+      // `elapsedTime` as a side effect — skewing the deltas the 'never'
+      // branch derives from the game timestamps `update(dt)` feeds below.
+      // Stopped + autoStart=false makes `getDelta()` a pure no-op, so
+      // `useFrame` deltas come from game time alone.
+      state.clock.autoStart = false;
+      state.clock.stop();
+
+      // Backfill the component runtime's ctx with fiber's real scene/camera
+      // (W3 — see the HONESTY NOTE above). This happens before the first
+      // `update(dt)` tick, so no component ever observes them missing.
+      runtime.setSceneCamera(state.scene, state.camera);
+
+      // The engine drives every `useFrame` through the mounted world's
+      // `update(dt)` hook — NOT `host.loop.onUpdate`. The distinction is the
+      // whole pause story: `runFrameImpl` (`runtime/game.ts`) calls
+      // `mounted.update?.(dt)` per substep for a host-driven
+      // (`drivesOwnLoop: false`) world and SKIPS it while that world is
+      // frozen, and `Game.play.step()` ticks it exactly once — whereas the
+      // raw loop's `onUpdate` extraUpdaters fire unconditionally, pause or
+      // not (they exist for host-level concerns; `create-runtime.ts` runs
+      // them outside `game.runFrame`'s gate). Advancing fiber from
+      // `onUpdate` therefore LOOKS right and silently breaks acceptance
+      // gate 2 — proven by the 36-r3f-first-party e2e, whose paused
+      // instance-matrix samples kept moving until this moved to `update`.
+      //
+      // `advance(timestamp, runGlobalEffects, state)`'s `timestamp` is
+      // consumed as `THREE.Clock.elapsedTime` DIRECTLY when
+      // `frameloop:'never'` (verified against fiber's `update()`
+      // implementation, not just its `.d.ts` — the declared signature alone
+      // doesn't say this): `delta = timestamp - clock.elapsedTime;
+      // clock.elapsedTime = timestamp`. So `timestamp` must be a
+      // monotonically increasing SECONDS value — GAME time, not wall time:
+      // `update` simply isn't called while this world is frozen, so
+      // accumulating its `dt` (seconds; the loop runs a fixed 1/60 timestep)
+      // means fiber's clock does not advance across a pause. Wall clock
+      // (`performance.now()`) would leak the pause duration into the first
+      // resumed frame as one giant `useFrame` delta — the exact "time passed
+      // while frozen" illusion acceptance gate 2 forbids.
+      let elapsed = 0;
+
+      return {
+        kind: 'threejs',
+        // Fiber's REAL `THREE.Scene`/`THREE.Camera` — `three` identity is
+        // deduped to the host's single instance by the project's Vite
+        // config (see this file's header comment), so these pass the
+        // editor's `instanceof THREE.Scene` / `instanceof THREE.Camera`
+        // gates unmodified (design acceptance gate 3). `state.camera`'s
+        // type (`Camera = (OrthographicCamera | PerspectiveCamera) & {
+        // manual?: boolean }`) is a structural subtype of `THREE.Camera`, so
+        // no cast is needed.
+        scene: state.scene,
+        camera: state.camera,
+        drivesOwnLoop: false,
+        // The engine's REAL ComponentManager for this world — what makes
+        // `Game.queryByComponent` see `<Behavior>`-attached components
+        // (`runtime/game.ts` aggregates this optional capability for every
+        // non-first-party mount that exposes one).
+        components,
+        // Adapter surface: `debug` pre-seeded (the shared game registry's
+        // adapter); game code adds capabilities via
+        // `ctx.registerSystemAdapter` exactly as in a classic world.
+        systems: runtime.systemAdapters,
+        update(dt: number): void {
+          elapsed += dt;
+          // Engine phases FIRST (attached GameComponents mutate transforms),
+          // then fiber's advance (useFrame callbacks + the actual render see
+          // the fresh state). Both behavior models — `useFrame` and
+          // `<Behavior>` — are host-gated: neither runs while frozen.
+          systems.run(dt);
+          advance(elapsed, true, state);
+        },
+        resize(width: number, height: number): void {
+          state.setSize(width, height);
+        },
+        dispose(): void {
+          // Unmount FIRST so <Behavior> effect cleanups detach through the
+          // live manager, then tear the runtime down (components.clear +
+          // scoped debug-registry strip).
+          root.unmount();
+          runtime.dispose();
+        },
+      };
+    },
+  };
+}

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

@@ -0,0 +1,294 @@
+/**
+ * `createR3FWorldContext` — 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
+ * 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.
+ *  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
+ *     adapter registers (`setVirtualInputTarget`/`setInputActionsSource`/
+ *     `setInputTraceSource`), which is what makes `game.input.*` (the bot
+ *     input doctrine) work instead of throwing `DEBUG_INPUT_UNAVAILABLE`.
+ *     The project's input map is loaded through `Game.loadInputMap` (the
+ *     game-owned, load-once path every root shares) with the SAME default
+ *     path the classic adapter uses. A missing/unparseable map degrades
+ *     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`.
+ */
+
+import type * as THREE from 'three';
+import type { HostContext } from '../adapter';
+import type { SystemAdapters } from '../adapter/system-adapter';
+import {
+  createSeededRandom,
+  DEFAULT_SEEDED_RANDOM_SEED,
+  getSeededRandom,
+} from '../core/seeded-random';
+import { createSystemRunner } from '../core/system-runner';
+import { type ComponentManager, createComponentManager } from '../ecs/component-manager';
+import {
+  createDebugRegistry,
+  type DebugRegistry,
+  getDebugRegistry,
+} from '../runtime/debug-registry';
+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 {
+  /** World id — provenance for every debug-registry registration (matches the
+   *  manifest root id by the same convention the classic adapter follows). */
+  readonly id: string;
+  /**
+   * Input map to load through `Game.loadInputMap` (game-owned, load-once —
+   * several roots asking for the SAME path share one load; competing paths
+   * throw there). Defaults to {@link DEFAULT_INPUT_MAP_PATH}, the classic
+   * adapter's own default. Pass `null` to skip loading (a world with no
+   * actions). Ignored when no `host.game` is present.
+   */
+  readonly inputMapPath?: string | null | undefined;
+}
+
+/** What {@link createR3FWorldContext} 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;
+  /** 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;
+  /** Resolves once the input map load settles (immediately when skipped).
+   *  Never rejects — a failed load reports loudly and resolves. */
+  readonly inputMapReady: Promise<void>;
+  /** Backfill fiber's real scene/camera onto `ctx` after the first commit
+   *  resolves them — before any tick can run. `camera` is fiber's union
+   *  (perspective OR orthographic) — the ctx surface exposes whatever the
+   *  tree declared, exactly as the mounted world does. */
+  setSceneCamera(scene: THREE.Scene, camera: THREE.Camera): void;
+  /** Detach every component and strip this world's debug registrations
+   *  (scoped, like the classic adapter's teardown — sibling roots and
+   *  react-door registrations are untouched when a Game hosts this world). */
+  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()`
+ * performs for the subsystems an R3F world shares with it (debug, input,
+ * random, components); loud throwing getters for the ones it doesn't.
+ */
+export function createR3FWorldContext(
+  host: HostContext,
+  options: R3FWorldContextOptions,
+): R3FWorldRuntime {
+  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');
+
+  // 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 = {};
+
+  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;
+    },
+  };
+  const ctx = ctxRaw as unknown as GameContext;
+  if (host.game) {
+    ctx.game = host.game;
+    ctx.roots = host.game.roots;
+  }
+  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
+  // classic adapter). ---
+  const debugRegistry: DebugRegistry =
+    (host.game ? getDebugRegistry(host.game) : null) ??
+    createDebugRegistry({ getTick: () => 0, getSimT: () => 0 });
+  systemAdapters.debug = debugRegistry.adapter;
+  ctx.debug = debugRegistry.forWorld(id);
+  ctx.random =
+    (host.game ? getSeededRandom(host.game) : null) ??
+    createSeededRandom(DEFAULT_SEEDED_RANDOM_SEED);
+
+  // --- 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
+  // `game.input.*` (virtual input) and the built-in `input.actions`/
+  // `input.trace` providers resolve to it. ---
+  let inputMapReady: Promise<void> = Promise.resolve();
+  if (host.game) {
+    const game = host.game;
+    const input = game.input;
+    ctxRaw['input'] = input;
+    debugRegistry.setInputActionsSource(id, () =>
+      input.actionNames().map((name) => ({ name, valueType: input.getActionValueType(name) })),
+    );
+    debugRegistry.setInputTraceSource(id, () => {
+      const raw = input.getInputTrace();
+      return {
+        version: raw.version,
+        seed: getSeededRandom(game)?.seed ?? null,
+        fixedDt: game.loop.fixedDt,
+        ticks: raw.ticks,
+      };
+    });
+    debugRegistry.setVirtualInputTarget(id, {
+      setVirtualAction: (action, value) => input.setVirtualAction(action, value),
+      tapVirtualAction: (action) => input.tapVirtualAction(action),
+      clearVirtualActions: () => input.clearVirtualActions(),
+      scheduleActionAtTick: (tick, action, value) =>
+        input.scheduleActionAtTick(tick, action, value),
+      startInputRecording: () => input.startInputRecording(),
+      stopInputRecording: () => input.stopInputRecording(),
+      isInputRecording: () => input.isInputRecording(),
+      injectAxis: (sourceId, value) => input.injectAxis(sourceId, value),
+      injectVector2: (sourceId, value) => input.injectVector2(sourceId, value),
+      injectPointerDelta: (sourceId, delta) => input.injectPointerDelta(sourceId, delta),
+      injectPointerPosition: (sourceId, value) => input.injectPointerPosition(sourceId, value),
+    });
+    if (!host.headless && inputMapPath !== null) {
+      // Load-once through the game-owned path (classic parity — competing
+      // paths across roots throw THERE, loudly). A FAILED load (missing/bad
+      // file) must not fail this mount: an R3F tree with no declared actions
+      // is legal. It degrades loudly instead — naming exactly what breaks.
+      inputMapReady = game.loadInputMap(inputMapPath).catch((err: unknown) => {
+        // biome-ignore lint/suspicious/noConsole: deliberate loud degrade — the documented alternative to failing the mount (see comment above)
+        console.error(
+          `R3F world "${id}": failed to load input map "${inputMapPath}" — declared input ` +
+            'actions and `game.input.*` (bot/virtual input) will not work until a valid map ' +
+            'loads. Ship one at the conventional path or pass `inputMapPath` to ' +
+            `createR3FAdapter (null to opt out). Cause: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      });
+    }
+  } 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.',
+    );
+  }
+
+  // --- 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 {
+      ctxRaw['scene'] = scene;
+      ctxRaw['camera'] = camera;
+    },
+    dispose(): void {
+      components.clear();
+      // 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);
+      else debugRegistry.strip();
+    },
+  };
+}

package/vendor/realism-effects/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 0beqz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/vendor/realism-effects/UPSTREAM.md

@@ -0,0 +1,19 @@
+# realism-effects compatibility fork
+
+This directory vendors the published `realism-effects@1.1.2` distribution
+(MIT license) so `@vgai/engine` remains installable as a self-contained source
+package. The upstream package still imports Three's removed
+`WebGLMultipleRenderTargets` API and has no release compatible with Three r180.
+
+VGAI's fork contains only the mechanical r180 MRT migration:
+
+- `WebGLMultipleRenderTargets(width, height, count, options)` becomes
+  `WebGLRenderTarget(width, height, { ...options, count })`.
+- MRT attachment access moves from `.texture[index]` to `.textures[index]`.
+
+Upstream repository: <https://github.com/0beqz/realism-effects>
+
+Upstream package/version: `realism-effects@1.1.2`
+
+Remove this fork when an upstream release supports Three r180 or newer and the
+isolated packed-engine consumer proof passes against it.