@vgai/engine 0.5.21 → 0.5.23

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

@@ -1,358 +0,0 @@
-/**
- * `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/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.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` when a Game hosts the
- *     root** (`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`.
- *     A bare/foreign mount receives `null`, visibly in the type, rather than
- *     a getter that throws later inside a frame callback.
- *     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 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 { 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 { createSceneIndex, type SceneIndex } from '../ecs/scene-index';
-import {
-  createDebugRegistry,
-  type DebugRegistry,
-  getDebugRegistry,
-} from '../runtime/debug-registry';
-import { disposeDebrisSubtree } from '../runtime/game';
-import type { ComponentContextBase, 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';
-
-/**
- * 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 = ComponentContextBase &
-  Pick<GameContext, 'scene' | 'sceneIndex' | 'assets' | 'clock'> & {
-    /** Fiber may install either a perspective or orthographic camera. */
-    camera: THREE.Camera;
-  };
-
-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;
-  /**
-   * 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 createR3FRootContext} returns — the engine runtime one R3F
- *  world owns, plus the wiring hooks `createR3FAdapter`'s `mount()` drives. */
-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 mounted world's `SystemAdapters` bag (`mounted.systems`) —
-   *  `ctx.registerSystemAdapter` writes into it; `debug` is pre-seeded here,
-   *  and the R3F mount adds renderer-backed engine capabilities after commit. */
-  readonly systemAdapters: SystemAdapters;
-  /** The registry every registration of this world's lands in — the game's
-   *  own when a `Game` hosts it, a private mount-local one otherwise. Exposed
-   *  (rather than re-derived by the caller) because `createR3FAdapter` seeds
-   *  the render-vitals door onto THIS registry after fiber's first commit
-   *  resolves the scene, and two `getDebugRegistry` calls that are "obviously"
-   *  the same object is exactly the second source of truth the classic
-   *  adapter's single `debugRegistry` local avoids. */
-  readonly debugRegistry: DebugRegistry;
-  /** 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;
-}
-
-/**
- * The GAME-SCOPED input wiring one three root owns — and the half that has
- * nothing to do with the vgai runtime context.
- *
- * Two things happen here, both of them HOST work performed from outside the
- * world's own tree:
- *
- *  1. the project's input map is loaded through `Game.loadInputMap` (game-owned,
- *     load-once), so the actions the project declared exist;
- *  2. this root's seams are registered on the game-scoped debug registry
- *     (`setVirtualInputTarget`/`setInputActionsSource`/`setInputTraceSource`),
- *     which is what makes `game.input.hold/tap/...` (the bot/`vgai eval` input
- *     doctrine) and the built-in `input.actions`/`input.trace` providers
- *     resolve to this world instead of throwing `DEBUG_INPUT_UNAVAILABLE`.
- *
- * It is called on BOTH three-root paths, and that is the point: a world that
- * mounts as a default-exported component receives no vgai runtime context
- * (`engineRuntime: false` — see `r3f-root-factory.tsx`), but "no context in the
- * tree" was never meant to say "the host does not wire this game's input". It
- * was read that way, and the cost was measured on a fresh scaffold: the
- * declared map never loaded and every `game.input.*` door threw, so the QA
- * bot, autoplay routes and `vgai eval` could not drive the ONE world shape
- * `vgai create` produces. Same split, same reasoning, as `WorldProvider`
- * riding `host.game` rather than the runtime (see `r3f-adapter.tsx`).
- *
- * `optionalInputMap` is the CONVENTIONAL-PATH probe used when the project
- * never named a map: an absent file is the ordinary state of a brand-new
- * project, so it resolves quietly instead of printing an error on every boot.
- * A map that exists and fails to parse is as loud as ever.
- *
- * LIFETIME, honestly: `registry.strip(id)` runs on the mount's dispose (both
- * paths), but it walks providers/commands only — the three seams set here
- * survive it, keyed by this world's id, until a remount of the same id
- * overwrites them. That residue is inert rather than hidden: every closure
- * below reads GAME-scoped state (`game.input`, `game.loop.fixedDt`, the game's
- * seed), so a stale entry actuates exactly what a live one would. See the
- * dispose comment in `r3f-adapter.tsx` for the full accounting.
- */
-export function wireGameInputSeams(
-  host: ThreeHostContext,
-  registry: DebugRegistry,
-  options: {
-    readonly id: string;
-    readonly inputMapPath?: string | null | undefined;
-    readonly optionalInputMap?: boolean | undefined;
-  },
-): Promise<void> {
-  const { id, inputMapPath = DEFAULT_INPUT_MAP_PATH, optionalInputMap = false } = options;
-  if (!host.game) return Promise.resolve();
-  const game = host.game;
-  const input = game.input;
-  registry.setInputActionsSource(id, () =>
-    input.actionNames().map((name) => ({ name, valueType: input.getActionValueType(name) })),
-  );
-  registry.setInputTraceSource(id, () => {
-    const raw = input.getInputTrace();
-    return {
-      version: raw.version,
-      seed: getSeededRandom(game)?.seed ?? null,
-      fixedDt: game.loop.fixedDt,
-      ticks: raw.ticks,
-    };
-  });
-  registry.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) return Promise.resolve();
-  // Load-once through the game-owned path (competing paths across roots throw
-  // THERE, loudly). A FAILED load (missing/bad file) must not fail the mount:
-  // a three world with no declared actions is legal. It degrades loudly
-  // instead — naming exactly what breaks.
-  // The non-optional call passes ONE argument, exactly as it always has — a
-  // trailing `undefined` is a different call to any observer of it.
-  const load = optionalInputMap
-    ? game.loadInputMap(inputMapPath, { optional: true })
-    : game.loadInputMap(inputMapPath);
-  return load.catch((err: unknown) => {
-    // biome-ignore lint/suspicious/noConsole: deliberate loud degrade — the documented alternative to failing the mount (see comment above)
-    console.error(
-      `three 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)}`,
-    );
-  });
-}
-
-/**
- * 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). The ones it does not build are not on
- * {@link R3FGameContext} at all.
- */
-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, '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,
-    input: host.game?.input ?? null,
-    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 R3FGameContext;
-  if (host.game) {
-    ctx.game = host.game;
-    ctx.roots = host.game.roots;
-    ctx.playtest = host.game.playtest ?? null;
-  }
-  // --- 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.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) — see
-  // `wireGameInputSeams` below; `ctx.input` is that same game-owned manager. ---
-  const inputMapReady = wireGameInputSeams(host, debugRegistry, { id, inputMapPath });
-
-  return {
-    ctx,
-    systems,
-    systemAdapters,
-    debugRegistry,
-    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 {
-      // 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);
-      else debugRegistry.strip();
-    },
-  };
-}