@vgai/engine 0.5.22 → 0.5.24

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
@@ -294,10 +370,28 @@ export interface DebugRegistry {
    *  error in that case rather than silently no-op-ing — see
    *  `debug-bridge.ts`'s `runTicks` method. */
   getRunTicksTarget(): RunTicksTarget | null;
+  /**
+   * Register a WORLD-SETTLED probe: `false` while this game is intentionally
+   * between worlds — a scene remount in flight (`reload_current_scene`'s
+   * React remount commits asynchronously). The game declares it through the
+   * `settled` key of its `debug` entry export (`native-debug-module.ts`);
+   * session tick drivers ({@link runTicksWhenSettled} behind BOTH run-ticks
+   * doors) wait for every probe to answer `true` before each tick, so WHICH
+   * tick first runs a freshly remounted scene is a function of the sim, not
+   * of wall timing between driver calls — measured before this seam: the
+   * same drive script produced 7 or 8 post-respawn walked ticks depending on
+   * how long the driver idled between ticks. Returns the deregistration.
+   */
+  registerWorldSettledProbe(probe: () => boolean): () => void;
+  /** `true` when every registered probe answers `true` (and vacuously with
+   *  none registered). A probe that THROWS counts as settled=false — a
+   *  broken probe must stall the driver loudly (its bounded wait names the
+   *  timeout), never silently un-gate it. */
+  worldSettled(): boolean;
   /** 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). */
@@ -382,6 +476,7 @@ export function createDebugRegistry(opts: {
   const inputTraceSources = new Map<string, () => InputTraceSnapshot>();
   const virtualInputTargets = new Map<string, DebugVirtualInputTarget>();
   let runTicksTarget: RunTicksTarget | null = null;
+  const worldSettledProbes = new Set<() => boolean>();
   let attachedRoom: DebugRoomHandle | null = null;
   const pendingServerCommands = new Map<string, PendingServerCommand>();
   let requestCounter = 0;
@@ -831,6 +926,24 @@ export function createDebugRegistry(opts: {
     getRunTicksTarget() {
       return runTicksTarget;
     },
+    registerWorldSettledProbe(probe: () => boolean) {
+      worldSettledProbes.add(probe);
+      return () => {
+        worldSettledProbes.delete(probe);
+      };
+    },
+    worldSettled() {
+      for (const probe of worldSettledProbes) {
+        try {
+          if (!probe()) return false;
+        } catch {
+          // A throwing probe stalls the driver LOUDLY (the bounded wait's
+          // timeout names it) rather than silently un-gating the tick.
+          return false;
+        }
+      }
+      return true;
+    },
     getGameTick() {
       return opts.getTick();
     },

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

@@ -33,9 +33,9 @@
  * `strip` to actually do it.
  */
 
+import type { HostGameHandle } from '../adapter/host-context';
 import { getSeededRandom } from '../core/seeded-random';
 import type { DebugRegistry } from './debug-registry';
-import type { GameInternal } from './game';
 
 /** The conventional input-map location every scaffolded project ships
  *  (`public/inputmaps/default.inputmap.json`). */
@@ -44,7 +44,7 @@ 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?: GameInternal | null | undefined;
+  readonly game?: HostGameHandle | null | undefined;
   readonly headless?: boolean | undefined;
 }