@vgai/engine 0.5.21 → 0.5.23

package/src/runtime/debug-registry.ts

@@ -1,6 +1,6 @@
 /**
  * The game-scoped debug/synthetic-player registry. ONE registry per `Game` root —
- * every world's `ctx.debug` (see `DebugCtxSurface`, `runtime/types.ts`) feeds the
+ * every world's `ctx.debug` (see {@link DebugCtxSurface} below) feeds the
  * SAME registry via {@link DebugRegistry.forRoot}, so a name a game registers is
  * visible (and name-collision-checked) across every world, not just the one that
  * registered it. `createGame` (`runtime/game.ts`) constructs the registry
@@ -10,8 +10,8 @@
  * rather than threading it through every call site.
  *
  * Provenance note: a registration's "world" is the MOUNT's adapter id (the
- * `fromSetup(id, ...)` / `SetupThreeRootConfig.id` a project already names each
- * world's entry with) rather than the `RootInstance.id` `registerThreeRoot`
+ * id a project's root adapter already carries) rather than the
+ * `RootInstance.id` `registerThreeRoot`
  * assigns — that id isn't known until AFTER `mount()` resolves (`create-
  * runtime.ts` calls `registerThreeRoot` with it only once `mount()` returns),
  * which is after every `setup()`-time registration has already run. For the
@@ -25,7 +25,83 @@ import type { DebugAdapter, DebugCommandInfo, TickStampedEvent } from '../adapte
 import { createGameScopedSlot } from '../core/game-scoped-slot';
 import type { GameLoopLiveness } from '../core/types';
 import type { Game } from './game';
-import type { DebugCommandArgs, DebugCtxSurface, DebugRoomHandle } from './types';
+
+/**
+ * The minimal structural shape `ctx.debug.attachRoom` needs from a joined
+ * Colyseus room: just enough to send the reserved `__vgai:debugCommand`
+ * message and listen for its `__vgai:debugCommandResult` reply. Structural,
+ * not a Colyseus type import — the same seam-boundary style every other
+ * `DebugCtxSurface` member uses (no wrapper around Colyseus itself, D2).
+ * `onMessage`'s return type is `unknown` because Colyseus's own return shape
+ * (void in some client versions, an unsubscribe function in others) isn't
+ * load-bearing here: the registry calls it defensively (invokes it on detach
+ * only if it's actually a function).
+ */
+export interface DebugRoomHandle {
+  send(type: string, message?: unknown): void;
+  onMessage(type: string, cb: (message: unknown) => void): unknown;
+}
+
+/**
+ * Infers a `registerCommand`/`registerReactCommand`/`useDebugCommand`
+ * handler's parameter tuple from its declared Zod `args` tuple (dry-run
+ * finding, ledger — "`registerCommand` fn typing forces `unknown[]` casts"):
+ * a real `z.ZodTuple` infers its element types (`z.tuple([z.number(),
+ * z.string()])` → `(n: number, s: string) => ...`), while omitting `args`
+ * (the generic's `undefined` default) resolves to the original permissive
+ * `(...args: unknown[]) => ...` shape every command had before this generic
+ * existed. That permissive fallback is deliberate, not just a placeholder —
+ * it keeps every existing no-schema registration (including ones whose
+ * handler reads positional args the runtime never validates, since
+ * `invoke()` only parses `args` against a schema when one is declared)
+ * compiling byte-for-byte unchanged.
+ */
+export type DebugCommandArgs<T extends z.ZodTuple | undefined = undefined> = T extends z.ZodTuple
+  ? z.infer<T>
+  : unknown[];
+
+/**
+ * The authoring half of the debug/synthetic-player seam — the read/actuate half is
+ * `SystemAdapters.DebugAdapter` (`adapter/system-adapter.ts`). Callable from any
+ * `init` (one file per new provider/command), or from a react world's
+ * `useDebugProvider`/`useDebugCommand`/`useDebugEmit` hooks. Every registration feeds the ONE
+ * game-scoped registry (`runtime/debug-registry.ts`) — never a per-world accumulator.
+ */
+export interface DebugCtxSurface {
+  /** Register (or replace) a named, JSON-serializable state read. Duplicate
+   *  names from the SAME world replace + warn once; the SAME name from a
+   *  DIFFERENT world throws (`DebugError` code `DEBUG_NAME_COLLISION`). */
+  registerStateProvider(
+    name: string,
+    fn: () => unknown,
+    opts?: { tier?: 'observable' | 'assisted' },
+  ): void;
+  /** Register (or replace) an invokable command. `locus` is REQUIRED once the
+   *  project declares a Colyseus room (`DebugRegistry.setRoomDeclared`) — a
+   *  fixture must say whether it mutates authoritative (server) or predicted
+   *  (client) state.
+   *
+   *  Generic over the declared `args` Zod tuple ({@link DebugCommandArgs}) so
+   *  `fn`'s parameters INFER from it: `registerCommand('setHp', { args:
+   *  z.tuple([z.number()]) }, (hp) => ...)` types `hp` as `number` with no
+   *  cast. Leaving `args` off keeps `fn` typed `(...args: unknown[]) => ...`,
+   *  same as before this generic existed. */
+  registerCommand<T extends z.ZodTuple | undefined = undefined>(
+    name: string,
+    spec: { description?: string; args?: T; locus?: 'client' | 'server' },
+    fn: (...args: DebugCommandArgs<T>) => unknown | Promise<unknown>,
+  ): void;
+  /** Push a tick-stamped event onto the debug event ring (spec §3.3) — the
+   *  engine stamps `tick`/`simT` at emission, not at read time. */
+  emit(event: string, detail?: unknown): void;
+  /**
+   * Task 2.2 — server-locus command routing (client leg). Call once your
+   * game code has joined its Colyseus room, so `locus: 'server'` commands
+   * have somewhere to send `__vgai:debugCommand`. Returns a detach function
+   * (call on room leave/dispose) — game-scoped, last-attached room wins.
+   */
+  attachRoom(room: DebugRoomHandle): () => void;
+}
 
 /** Engine-local error for the debug seam — mirrors the `code` + `data` shape
  *  `packages/vgai-sdk/src/errors.ts` uses (no import: the engine does not
@@ -74,7 +150,7 @@ const SERVER_COMMAND_TIMEOUT_MS = 10_000;
  *  actuates through — the SAME three methods `InputManager` exposes
  *  (`setVirtualAction`/`tapVirtualAction`/`clearVirtualActions`, Task 1.4),
  *  typed narrowly here so this module never imports `InputManager` itself.
- *  Wired once by the hosting adapter (`setup-three-root-adapter.ts`, at the
+ *  Wired once by the hosting adapter (`world3d-react/r3f-root-factory.tsx`, at the
  *  same seed spot as `setInputActionsSource`) — absent until then. */
 export interface DebugVirtualInputTarget {
   setVirtualAction(
@@ -187,7 +263,7 @@ interface CommandEntry {
 
 /** What {@link createDebugRegistry} returns — the adapter half (`DebugAdapter`,
  *  for `SystemAdapters.debug`) plus the registration/lifecycle surface the
- *  hosting adapter (`setup-three-root-adapter.ts`) and `createGame` drive. */
+ *  hosting adapter (`world3d-react/r3f-root-factory.tsx`) and `createGame` drive. */
 export interface DebugRegistry {
   /** The `SystemAdapters.debug` implementer — one shared instance, seeded
    *  onto every world's adapter bag. */
@@ -238,7 +314,7 @@ export interface DebugRegistry {
    *  `{version: 1, seed: null, fixedDt: null, ticks: []}`. `seed`/`fixedDt`
    *  are the two replay-critical metadata fields the design doc's format
    *  sketch (§2.c) calls for beside the raw per-tick deltas — the wiring
-   *  adapter (`setup-three-root-adapter.ts`) assembles them from
+   *  adapter (`world3d-react/r3f-root-factory.tsx`) assembles them from
    *  `getSeededRandom(game)?.seed`/`host.game?.loop.fixedDt` alongside
    *  `InputManager.getInputTrace()`'s own `{version, ticks}`. An `engine`
    *  (package version) stamp remains a KNOWN GAP — no build-time version
@@ -297,7 +373,7 @@ export interface DebugRegistry {
   /** D15/T-D15.3/.5 — the CURRENT shared game tick (the same counter the
    *  built-in `time` provider's `tick` field reads), for a per-world
    *  `InputManager.poll(tick)` call to key its `scheduleActionAtTick`
-   *  numbering off — see `setup-three-root-adapter.ts`'s `systems.add('input',
+   *  numbering off — see `world3d-react/r3f-root-factory.tsx`'s `systems.add('input',
    *  ...)` wiring. `0` for a bare `createDebugRegistry()` test stand-in with
    *  no real `Game`/tick counter behind it (matching `getTick`'s own
    *  constructor-supplied default in that case). */

package/src/runtime/dev-build.ts

@@ -9,8 +9,8 @@
  *
  * Ownership, stated in one place (the build rule):
  *  - OWNER: this function. It resolves the answer; nothing else derives it.
- *  - SHARERS: the two three-root adapters (`adapter/setup-three-root-adapter.ts`
- *    and `world3d-react/r3f-adapter.tsx`), which seed live render vitals only
+ *  - SHARERS: the three-root adapter (`world3d-react/r3f-root-factory.tsx`),
+ *    which seeds live render vitals only
  *    under it, and the `static-batch` capability's mutation watch and `Frozen`
  *    warning. Any future dev-only instrument calls this too, with its own
  *    `override`.

package/src/runtime/game-input-seams.ts

@@ -0,0 +1,108 @@
+/**
+ * The GAME-SCOPED input wiring one world mount owns — HOST work performed from
+ * outside the world's own tree, shared verbatim by the three and canvas lanes
+ * (a project has ONE input map and one bot-input doctrine, whatever surface
+ * reads them).
+ *
+ * Two things happen here:
+ *
+ *  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`.
+ *
+ * A world's React tree receives no vgai context — this wiring is precisely the
+ * part that never needed one: every closure below reads GAME-scoped state the
+ * host owns (`game.input`, `game.loop.fixedDt`, the game's seed).
+ *
+ * `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, 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 reads game-scoped state,
+ * so a stale entry actuates exactly what a live one would. What it can still
+ * do is name a dead world in `DEBUG_INPUT_WORLD_NOT_FOUND`'s registered list.
+ * Do not write "the strip clears the input seams" anywhere without changing
+ * `strip` to actually do it.
+ */
+
+import type { HostGameHandle } from '../adapter/host-context';
+import { getSeededRandom } from '../core/seeded-random';
+import type { DebugRegistry } from './debug-registry';
+
+/** The conventional input-map location every scaffolded project ships
+ *  (`public/inputmaps/default.inputmap.json`). */
+export const DEFAULT_INPUT_MAP_PATH = '/inputmaps/default.inputmap.json';
+
+/** The slice of a host context this wiring reads — satisfied structurally by
+ *  both `ThreeHostContext` and `CanvasHostContext`. */
+export interface GameInputSeamHost {
+  readonly game?: HostGameHandle | null | undefined;
+  readonly headless?: boolean | undefined;
+}
+
+export function wireGameInputSeams(
+  host: GameInputSeamHost,
+  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 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(
+      `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 (${DEFAULT_INPUT_MAP_PATH}). ` +
+        `Cause: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  });
+}