@vgai/engine 0.5.21 → 0.5.22

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

@@ -1,253 +0,0 @@
-/**
- * `createCanvasRootContext` — the ENGINE runtime a canvas world owns, split out
- * of `./pixi-react-adapter.tsx` so it stays react-free and headlessly
- * unit-testable (`test/canvas-react-context-parity.test.tsx`).
- *
- * This is the canvas surface's answer to the same question
- * `world3d-react/world-context.ts` answers for three: what does a component
- * inside the world tree reach when it asks the engine for something?
- *
- *  1. **`ctx.debug` / `ctx.random` / `ctx.game` / `ctx.roots` are wired** from
- *     the ONE game-scoped registry (`getDebugRegistry(host.game)`), so a
- *     component's effect can `ctx.debug.registerStateProvider(...)` and be
- *     visible to `vgai eval`/the editor's debug panels.
- *  2. **`ctx.input` is the game-owned `InputManager` when a Game hosts the
- *     root** (`host.game.input` — the
- *     same instance every sibling root shares), and this module registers the
- *     per-world debug-registry seams (`setVirtualInputTarget`/
- *     `setInputActionsSource`/`setInputTraceSource`) that make `game.input.*`
- *     (the bot-input doctrine) resolve instead of throwing
- *     `DEBUG_INPUT_UNAVAILABLE`. The project's input map loads through
- *     `Game.loadInputMap` (the game-owned, load-once path every root shares).
- *     A missing/unparseable map degrades LOUDLY without failing the mount — a
- *     canvas world with no declared actions is legal. A bare/foreign mount
- *     receives `null`, visibly in the type, rather than a throwing getter.
- *  3. **Absent subsystems are absent from the type.** A canvas world builds no
- *     THREE scene/camera, Rapier world, composer, first-party audio/particles/
- *     debug-draw, or Three-flavoured `AssetCache`. Its explicit
- *     {@link CanvasGameContext} cannot name those fields, so misuse fails at
- *     the call site during typechecking instead of from a throwing getter at
- *     runtime.
- *
- * The Pixi handles themselves are deliberately NOT re-exposed here: a component
- * reaches the live `Application` (and therefore `app.stage`, `app.renderer`,
- * `app.ticker`) through `@pixi/react`'s own `useApplication()`, and its assets
- * through Pixi's own `Assets`. Re-publishing them on `ctx` would be a wrapper
- * standing between the author and the library.
- */
-
-import type { Application } from 'pixi.js';
-import type { CanvasHostContext } from '../adapter';
-import type { SystemAdapters } from '../adapter/system-adapter';
-import {
-  createSeededRandom,
-  DEFAULT_SEEDED_RANDOM_SEED,
-  getSeededRandom,
-} from '../core/seeded-random';
-import type { SimClock } from '../core/sim-clock';
-import { createSimClock, getSimClock, type SimClockInternal } from '../core/sim-clock';
-import { createSystemRunner } from '../core/system-runner';
-import {
-  createDebugRegistry,
-  type DebugRegistry,
-  getDebugRegistry,
-} from '../runtime/debug-registry';
-import type { ComponentContextBase } from '../runtime/types';
-
-/** The conventional input-map location every scaffolded project ships. Shared
- *  verbatim with the three lane — a project has ONE input map, whatever surface
- *  reads it. */
-export const DEFAULT_INPUT_MAP_PATH = '/inputmaps/default.inputmap.json';
-
-export interface CanvasRootContextOptions {
-  /** World id — provenance for every debug-registry registration (matches the
-   *  manifest root id). */
-  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}. Pass `null` to
-   * skip loading (a world with no actions). Ignored when no `host.game` is
-   * present.
-   */
-  readonly inputMapPath?: string | null | undefined;
-}
-
-/** The engine services a Canvas component genuinely receives. Pixi's own
- * `useApplication()` and `Assets` remain the doors to rendering and assets.
- * `disposeAfter` is excluded because it accepts a `THREE.Object3D`; Canvas
- * code schedules `displayObject.destroy()` with `clock.after()` instead. */
-export type CanvasGameContext = ComponentContextBase & {
-  readonly clock: Omit<SimClock, 'disposeAfter'>;
-};
-
-/** What {@link createCanvasRootContext} returns — the engine runtime one canvas
- *  world owns, plus the wiring hooks the adapter's `mount()` drives. */
-export interface CanvasRootRuntime {
-  /** The explicit Canvas context this world's components read through
-   *  `useGameContext`. See {@link CanvasGameContext}. */
-  readonly ctx: CanvasGameContext;
-  /** 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. */
-  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 the live `Application` once `@pixi/react` has initialized it —
-   *  before any tick can run. Read back via {@link CanvasRootRuntime.app}. */
-  setApplication(app: Application): void;
-  /** The live `Application`, or `null` before the first commit resolves it. */
-  readonly app: Application | null;
-  /** Strip this world's debug registrations (scoped, so sibling roots and
-   *  react-door registrations are untouched when a Game hosts this world) and
-   *  dispose a clock this mount created. */
-  dispose(): void;
-}
-
-/**
- * Build the engine runtime for one canvas world from a `CanvasHostContext`.
- * React-free on purpose: everything here is plain engine wiring the adapter
- * threads into the `@pixi/react` tree through `EngineBridge`.
- */
-export function createCanvasRootContext(
-  host: CanvasHostContext,
-  options: CanvasRootContextOptions,
-): CanvasRootRuntime {
-  const { id, inputMapPath = DEFAULT_INPUT_MAP_PATH } = options;
-
-  // Same observer threading as the three lane — this world's phases show up
-  // under the shared game profiler when hosted.
-  const systems = createSystemRunner(host.game?.profiler.systemObserver, 'canvas');
-
-  // The mounted world's adapter surface (`mounted.systems`) — declared before
-  // ctx so `ctx.registerSystemAdapter` can close over it (a game-owned
-  // capability like networking registers here from component code).
-  const systemAdapters: SystemAdapters = {};
-
-  let app: Application | null = null;
-
-  const ctxRaw: Record<string, unknown> = {
-    systems,
-    input: host.game?.input ?? null,
-    registerSystemAdapter: (kind: keyof SystemAdapters, adapter: SystemAdapters[typeof kind]) => {
-      // biome-ignore lint/suspicious/noExplicitAny: same per-key record write the three lane performs; correct by construction
-      (systemAdapters as any)[kind] = adapter;
-      host.game?.notifySystemAdaptersChanged();
-    },
-  };
-  const ctx = ctxRaw as unknown as CanvasGameContext;
-  if (host.game) {
-    ctx.game = host.game;
-    ctx.roots = host.game.roots;
-    ctx.playtest = host.game.playtest ?? null;
-  }
-
-  // --- ctx.debug — 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. ---
-  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 — a REAL value, never a throwing getter: every world has a
-  // sim clock. A bare mount with no Game shell gets a private, mount-local one.
-  // `SimClock.disposeAfter` takes a THREE.Object3D, so the mount-local
-  // fallback's disposer is a loud refusal rather than a fabricated no-op: a
-  // canvas world's debris is a `PIXI.Container`, destroyed with its own
-  // `container.destroy()`.
-  const gameClock: SimClockInternal | null = host.game ? getSimClock(host.game) : null;
-  const clock: SimClockInternal =
-    gameClock ??
-    createSimClock({
-      dispose: () => {
-        throw new Error(
-          `canvas world "${id}": clock.disposeAfter() disposes a THREE.Object3D and has no ` +
-            'meaning in a canvas world — destroy a display object with its own ' +
-            '`container.destroy({ children: true })`, scheduled with `clock.after(seconds, ...)`.',
-        );
-      },
-    });
-  ctxRaw['clock'] = clock;
-
-  // --- ctx.input + the debug-registry input seams — the game-owned
-  // InputManager, polled by the game-scoped runner each frame; this world
-  // registers the per-world seams 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;
-    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 (competing paths across roots
-      // throw THERE, loudly). A FAILED load must not fail this mount: a canvas
-      // world with no declared actions is legal. It degrades loudly instead.
-      inputMapReady = game.loadInputMap(inputMapPath).catch((err: unknown) => {
-        // biome-ignore lint/suspicious/noConsole: deliberate loud degrade — the documented alternative to failing the mount
-        console.error(
-          `canvas 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 ' +
-            `createPixiReactAdapter (null to opt out). Cause: ${err instanceof Error ? err.message : String(err)}`,
-        );
-      });
-    }
-  }
-
-  return {
-    ctx,
-    systems,
-    systemAdapters,
-    inputMapReady,
-    get app(): Application | null {
-      return app;
-    },
-    setApplication(next): void {
-      app = next;
-    },
-    dispose(): void {
-      // Same ownership rule the three lane follows: 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();
-      app = 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();
-    },
-  };
-}

package/src/world3d-react/engine-bridge.ts

@@ -1,86 +0,0 @@
-/**
- * `@engine/world3d-react` — the React context that carries this R3F world's
- * engine runtime into its fiber tree: the world's `R3FGameContext`, read
- * with {@link useGameContext}.
- *
- * Upstreamed from `examples/r3f-first-party/src/engine-bridge.ts` (R4).
- * The bridge value
- * is built by `createR3FAdapter`'s `mount()` (./r3f-adapter.tsx): a real
- * `createSystemRunner` whose phases the adapter's `update(dt)` runs under the
- * HOST loop — so registered systems tick in engine phase order, pause included
- * (no update while the world is frozen).
- *
- * Behavior in an R3F world is components and hooks: `useGameContext` is how a
- * component reaches engine services.
- */
-
-import { createContext, useContext } from 'react';
-import { useOptionalGame } from '../react/world-state';
-import type { R3FGameContext } from './world-context';
-
-export interface EngineBridgeValue {
-  /** This root's context — `input`, `debug`, `random`, `game`, `roots`, … .
-   *  Present so ordinary components can reach engine services with a HOOK
-   *  (see {@link useGameContext}). */
-  readonly ctx?: R3FGameContext | undefined;
-}
-
-export const EngineBridge = createContext<EngineBridgeValue | null>(null);
-
-/**
- * This R3F root's context, for use inside any component in the tree — an
- * {@link R3FGameContext}, which is exactly the subsystems an R3F world builds.
- * The ones it does not build are absent from the type, so reaching for one is
- * a compile error at the call site; that type's doc comment says what to reach
- * for instead.
- *
- * An ordinary component does what a model would write:
- *
- * ```tsx
- * function Player({ speed = 4.5 }) {
- *   const { input } = useGameContext();
- *   const ref = useRef<THREE.Group>(null);
- *   useFrame((_, dt) => { if (input?.isPressed('move_forward')) … });
- *   return <group ref={ref}><PlayerCharacter /></group>;
- * }
- * ```
- *
- * Throws when called outside an R3F root mounted by `createR3FAdapter` —
- * absent context is a wiring bug, and a silent `null` would surface as a
- * mystery `undefined` deep in a frame callback.
- */
-export function useGameContext(): R3FGameContext {
-  const bridge = useContext(EngineBridge);
-  // Read unconditionally (rules of hooks) — used only to shape the throw below.
-  const hostedByGame = useOptionalGame() !== null;
-  if (!bridge?.ctx) {
-    // NAME THE REAL CAUSE. This throw used to say "check that the component is
-    // rendered inside your world entry" — advice a scaffolded game has already
-    // followed, because the shape `vgai create` produces (`export default
-    // function World()`) mounts as a COMPONENT ROOT and receives no vgai
-    // runtime context at all: `r3f-root-factory.tsx` passes
-    // `engineRuntime: false` deliberately, so this hook can never resolve
-    // there however the component is nested. A world whose first render calls
-    // it dies with "fiber crashed before its first commit" and a fix
-    // instruction that cannot work. The `Game` in scope tells the two cases
-    // apart: present means a vgai-mounted world, absent means no root at all.
-    throw new Error(
-      hostedByGame
-        ? 'useGameContext(): this world mounts as a COMPONENT ROOT (the default-exported ' +
-            'shape `vgai create` scaffolds) and receives no vgai runtime context — by design, ' +
-            'so nesting cannot fix it. Game-scoped services are on the Game handle instead: ' +
-            '`useGame().input` (from @vgai/engine/react/world-state) is the game-owned ' +
-            "InputManager the host already loaded this project's input map into and the same " +
-            'one `game.input.hold/tap` drives; `useDebugProvider`/`useDebugCommand`/' +
-            '`useWorldState` are the state/command doors. If this world genuinely needs the ' +
-            'imperative runtime (`ctx.systems`, adapter options like `inputMapPath`), export ' +
-            '`adapter = createR3FAdapter({ id, content: <World/> })` from the entry instead of ' +
-            'default-exporting the component.'
-        : 'useGameContext(): no engine root context and no Game in scope — this component is ' +
-            'rendering outside any mounted vgai root (a standalone <Canvas>, a story, or a ' +
-            "bare test render). Mount it through your project's three root, or read services " +
-            'the component root way (native hooks and project-owned state).',
-    );
-  }
-  return bridge.ctx;
-}