@vgai/engine 0.5.4 → 0.5.6

package/src/dev/instruments.ts

@@ -0,0 +1,302 @@
+/**
+ * THE UNIVERSAL INSTRUMENTS — time scale, pause/frame-step, collider draw and
+ * frame time, furnished by the ENGINE for every game before it has written a
+ * line.
+ *
+ * These are physics of the medium, not genre ontology. Time runs; it can run
+ * slower or stop; a frame can be stepped; colliders can be drawn; frames take
+ * time. None of that is a decision any particular game makes, so none of it
+ * belongs in a game's own declarations — and none of it belongs on the game's
+ * own dev panel either, which shows ONLY what the game itself declared
+ * (`stat()`, `cheat()`). They publish as DOORS: an agent drives them through
+ * `game.state()`/`game.command()`, and a human drives the same controls from
+ * the editor chrome that already owns them — pause and frame-step on the
+ * transport, frame time on the stats overlay, colliders in the play-adopted
+ * Scene viewport.
+ *
+ * WHAT IS NOT HERE, and why: a FREE CAMERA. The editor already ships one
+ * (owner, 2026-08-10): play adoption swaps the live game scene into the editor
+ * viewport (`enterPlayScene`), so the Scene view during play IS a free orbit
+ * camera over the running game — no game-side camera override needed, and the
+ * game's own camera writes never fight it because the game keeps rendering
+ * through its own canvas untouched. Per the non-redundancy rule that governs
+ * this list, a control the editor's own chrome furnishes gets no instrument;
+ * agents reach that camera through the editor half of `vgai eval`, not the
+ * game registry.
+ *
+ * ── THE DOOR ────────────────────────────────────────────────────────────────
+ * This module is IMPLEMENTATION ONLY. It publishes nothing itself: the dev-menu
+ * capability's own registry adopts this list (`installDevMenuInstruments`) and
+ * publishes each instrument through the SAME door every declaration in that
+ * capability uses — one provider per reading (`instrument.timescale`), one
+ * command per action (`instrument.timescale.set`), plus the `dev-menu` index
+ * provider. That is deliberate and load-bearing: the registry IS the product,
+ * so every reader of an instrument reaches the SAME registration.
+ *
+ * ── DEGRADING ───────────────────────────────────────────────────────────────
+ * An instrument whose subject this game does not have (no physics adapter ⇒ no
+ * colliders) READS `null` — honest emptiness rather than a fabricated value.
+ * Its ACTION, invoked anyway, THROWS and names what is missing. Silence is the
+ * one thing forbidden: an agent that calls `instrument.colliders.toggle` and
+ * gets `undefined` back learns nothing.
+ *
+ * ── RESOURCE OWNERSHIP, STATED ONCE ─────────────────────────────────────────
+ * {@link createDevInstruments} owns everything it allocates: the frame-time
+ * ring buffer and its ONE `game.onRenderStep` subscription. SHARER: the
+ * dev-menu capability's `DevMenuBridge`, which creates one set per mounted
+ * game. TEARDOWN: the returned {@link DevInstrumentSet.dispose} — the ONE path
+ * that ends it. Nothing else here holds a resource; the time-scale, pause and
+ * collider instruments only drive state that `Game` already owns.
+ */
+
+import { z } from 'zod';
+import { clampTimeScale, TIME_SCALE_RANGE } from '../core/frame-pacing';
+import type { Game } from '../runtime/game';
+
+/** What shape an instrument's reading is, and what drives it. Data, not
+ *  layout: a reader learns how to interpret and actuate an instrument without
+ *  having to recognise it by name. */
+export type DevInstrumentControl =
+  /** A value only. */
+  | { readonly kind: 'reading' }
+  /** On/off, driven by the named action. */
+  | { readonly kind: 'toggle'; readonly action: string }
+  /** A continuous value, driven by the named action (one numeric argument). */
+  | {
+      readonly kind: 'scale';
+      readonly action: string;
+      readonly min: number;
+      readonly max: number;
+      readonly step: number;
+    }
+  /** A {@link FrameTimeReading} — a window of samples, not a scalar. */
+  | { readonly kind: 'plot' };
+
+/** One instrument verb. Every action declares an args tuple — `z.tuple([])`
+ *  for a verb that takes none — so the debug registry REJECTS an unexpected
+ *  argument at the door instead of passing it through to a handler that
+ *  ignores it. */
+export interface DevInstrumentAction {
+  /** Second half of the command name: `instrument.<id>.<this>`. */
+  readonly id: string;
+  readonly label: string;
+  readonly hint: string;
+  readonly args: z.ZodTuple;
+  run(values: readonly unknown[]): unknown;
+}
+
+export interface DevInstrument {
+  /** Second half of the provider name: `instrument.<this>`. */
+  readonly id: string;
+  readonly label: string;
+  readonly hint: string;
+  /** Trailing unit for a scalar reading (`x`, `ms`). */
+  readonly unit?: string;
+  readonly control: DevInstrumentControl;
+  readonly actions: readonly DevInstrumentAction[];
+  /** This instant's value, or `null` when this game has no such subject. */
+  read(): unknown;
+}
+
+export interface DevInstrumentSet {
+  readonly instruments: readonly DevInstrument[];
+  /** See the ownership note above — the ONE teardown path. */
+  dispose(): void;
+}
+
+/**
+ * How many display frames the frame-time reading keeps. ~1 second at 60 Hz —
+ * long enough that a hitch is still in the window when you look, short enough
+ * that the mean tracks what the game is doing NOW.
+ */
+export const FRAME_TIME_WINDOW = 60;
+
+/** What `instrument.frame-time` reads. `null`s (rather than zeros) before the
+ *  first sampled frame: a stopped game has no frame time, and `0 ms / 0 fps`
+ *  would read as a measurement. */
+export interface FrameTimeReading {
+  /** Mean wall-clock milliseconds per display frame over the window. */
+  readonly ms: number | null;
+  /** Frames per second implied by {@link ms}. */
+  readonly fps: number | null;
+  /** The worst single frame in the window — the hitch the mean hides. */
+  readonly worstMs: number | null;
+  /** Oldest first, for the plot. */
+  readonly samples: readonly number[];
+}
+
+/** Pure: the whole frame-time reading from a window of samples. */
+export function summarizeFrameTimes(samples: readonly number[]): FrameTimeReading {
+  if (samples.length === 0) return { ms: null, fps: null, worstMs: null, samples: [] };
+  let total = 0;
+  let worst = 0;
+  for (const sample of samples) {
+    total += sample;
+    if (sample > worst) worst = sample;
+  }
+  const ms = total / samples.length;
+  return {
+    ms: round(ms, 2),
+    fps: ms > 0 ? round(1000 / ms, 1) : null,
+    worstMs: round(worst, 2),
+    samples: samples.map((sample) => round(sample, 2)),
+  };
+}
+
+function round(value: number, places: number): number {
+  const factor = 10 ** places;
+  return Math.round(value * factor) / factor;
+}
+
+const NO_COLLIDERS =
+  'No physics adapter on this game implements setDebugDrawEnabled, so nothing can draw its ' +
+  'colliders. A first-party three root with Rapier physics registers one; a game with no ' +
+  'physics has no colliders to draw.';
+
+const NO_ARGS = z.tuple([]);
+
+/**
+ * Build this game's universal instrument set. One call per mounted game; the
+ * caller owns the returned {@link DevInstrumentSet.dispose}.
+ */
+export function createDevInstruments(game: Game): DevInstrumentSet {
+  // --- Frame time: one subscription, one ring buffer ------------------------
+  const samples: number[] = [];
+  let previousFrameAt = now();
+  const stopSampling = game.onRenderStep(() => {
+    const at = now();
+    samples.push(at - previousFrameAt);
+    previousFrameAt = at;
+    if (samples.length > FRAME_TIME_WINDOW) samples.shift();
+  });
+
+  // --- Collider draw: the adapter has a setter and no getter, so the ON/OFF
+  // state is ours to remember. It is only ever written through the one action
+  // below, which is also the only thing that calls the adapter.
+  let collidersDrawn = false;
+  const colliderDraw = () => {
+    const adapter = game.systemAdapters.physics;
+    return adapter?.setDebugDrawEnabled ? adapter : null;
+  };
+
+  const instruments: readonly DevInstrument[] = [
+    {
+      id: 'timescale',
+      label: 'Time scale',
+      hint: 'Sim speed multiplier. 1 is real time, 0 freezes the simulation while the game keeps drawing.',
+      unit: 'x',
+      control: {
+        kind: 'scale',
+        action: 'set',
+        min: TIME_SCALE_RANGE.min,
+        max: TIME_SCALE_RANGE.max,
+        step: 0.05,
+      },
+      actions: [
+        {
+          id: 'set',
+          label: 'Set',
+          hint: `Set the sim speed multiplier (${TIME_SCALE_RANGE.min}–${TIME_SCALE_RANGE.max}).`,
+          args: z.tuple([z.number()]),
+          run: (values) => {
+            // The LOOP clamps and warns; asking for the clamp here too would
+            // be a second opinion about the same range. It reads back the
+            // value that actually took effect, never the one requested.
+            game.loop.timeScale = clampTimeScale(values[0] as number);
+            return game.loop.timeScale;
+          },
+        },
+      ],
+      read: () => game.loop.timeScale,
+    },
+    {
+      id: 'paused',
+      label: 'Paused',
+      hint: 'Freeze the simulation. The game keeps drawing, so you can look at a frozen frame.',
+      control: { kind: 'toggle', action: 'toggle' },
+      actions: [
+        {
+          id: 'toggle',
+          label: 'Toggle',
+          hint: 'Pause or resume the simulation.',
+          args: NO_ARGS,
+          run: () => {
+            if (game.play.paused) game.play.resume();
+            else game.play.pause();
+            return game.play.paused;
+          },
+        },
+        {
+          id: 'step',
+          label: 'Step',
+          hint: 'Advance exactly one fixed substep. Pauses first if the game is running.',
+          args: NO_ARGS,
+          run: () => {
+            // Frame advance implies pause — `Game.play.step()` is a
+            // deliberate whole-call no-op while running, and a button that
+            // silently does nothing is the failure this instrument exists to
+            // avoid.
+            if (!game.play.paused) game.play.pause();
+            game.play.step();
+            return game.play.paused;
+          },
+        },
+      ],
+      read: () => game.play.paused,
+    },
+    {
+      id: 'colliders',
+      label: 'Colliders drawn',
+      hint: "Draw the physics colliders over the world, through the game's own physics adapter.",
+      control: { kind: 'toggle', action: 'toggle' },
+      actions: [
+        {
+          id: 'toggle',
+          label: 'Toggle',
+          hint: 'Turn collider wireframes on or off.',
+          args: NO_ARGS,
+          run: () => {
+            const adapter = colliderDraw();
+            if (!adapter) throw new Error(NO_COLLIDERS);
+            collidersDrawn = !collidersDrawn;
+            adapter.setDebugDrawEnabled?.(collidersDrawn);
+            return collidersDrawn;
+          },
+        },
+      ],
+      read: () => (colliderDraw() === null ? null : collidersDrawn),
+    },
+    {
+      id: 'frame-time',
+      label: 'Frame time',
+      hint: 'Wall-clock milliseconds per display frame, newest last. The window is where a hitch shows; the mean hides it.',
+      unit: 'ms',
+      control: { kind: 'plot' },
+      actions: [
+        {
+          id: 'clear',
+          label: 'Clear',
+          hint: 'Forget the sampled window and start measuring again.',
+          args: NO_ARGS,
+          run: () => {
+            samples.length = 0;
+            return null;
+          },
+        },
+      ],
+      read: () => summarizeFrameTimes(samples),
+    },
+  ];
+
+  return {
+    instruments,
+    dispose() {
+      stopSampling();
+      samples.length = 0;
+    },
+  };
+}
+
+function now(): number {
+  return typeof performance === 'undefined' ? Date.now() : performance.now();
+}

package/src/runtime/mount-game.ts

@@ -22,6 +22,7 @@ import type { ResolvedAdapterRoot } from '../manifest/load';
 import type { GameSession } from './create-runtime';
 import { type MountEntry, mountManifestRoots, resolveManifest } from './mount-manifest';
 import type { GameSetupFn } from './types';
+import { assertExportedOrInEditor } from './unexported-game-trap';
 
 // ---------------------------------------------------------------------------
 // The host contract (design/26 §5 D1's `ManifestHost`)
@@ -232,6 +233,11 @@ export async function mountGameFromManifest(
   host: ManifestHost,
   opts: MountGameOptions = {},
 ): Promise<GameSession> {
+  // Owner invariant: an unexported game never mounts outside the editor. The
+  // editor mounts through its own resolver, so every caller of THIS function
+  // is a standalone page — and on a dev server, that page refuses to boot
+  // (see unexported-game-trap.ts for why this is a trap and not a rule).
+  assertExportedOrInEditor();
   const manifest = resolveManifest(manifestInput);
   const entries: Record<string, MountEntry> = { ...opts.entries };
 

package/src/runtime/unexported-game-trap.ts

@@ -0,0 +1,82 @@
+/**
+ * THE UNEXPORTED-GAME TRAP: a dev-served standalone game page REFUSES to boot.
+ *
+ * Owner decision (2026-08-09): until a game is EXPORTED, it is never played
+ * outside the editor. The editor is the one authoring, viewing and
+ * verification surface; the standalone page exists to serve the exported
+ * artifact, not to be a second door during development.
+ *
+ * Why this is a trap in CODE and not a rule in prose: the rule already
+ * existed, and it drifted. When an editor session broke mid-task, an agent
+ * "temporarily" switched to `npm run game`, the fallback fed its whole
+ * feedback loop (pixels for screenshots), nothing broken ever pushed it back,
+ * and hours of verification ran outside the editor without anyone deciding
+ * that. A workaround whose cost lands outside the loop that chose it is
+ * sticky; the only fix that holds is for the workaround PATH ITSELF to fail
+ * immediately, loudly, and with the way back in its hands. That is this file.
+ *
+ * The boundary is DEV-SERVED vs EXPORTED, decided by the bundler: a Vite dev
+ * server strips nothing, so `import.meta.env.DEV` is true; a production build
+ * (`vite build` — what `vgai deploy` runs) compiles it false and this module
+ * costs an exported game nothing. Headless contexts (unit tests, playtest's
+ * node leg) have no real browser page and never trip it — the check requires
+ * a document whose `defaultView` is the window, which no test stub wires up.
+ *
+ * There is deliberately NO opt-out flag, env var, or query param. An escape
+ * hatch an agent can reach for is the workaround again, one hop later.
+ */
+
+/** What the refusal says — one place, so the page and the thrown Error agree. */
+const REFUSAL = [
+  'UNEXPORTED GAME, OUTSIDE THE EDITOR — refusing to mount.',
+  '',
+  'This game has not been exported. Until it is, the ONLY way to run, see,',
+  'or drive it is the editor:',
+  '',
+  '    vgai edit .        open (or reuse) the editor for this project',
+  '    vgai play          enter play mode from the terminal',
+  "    vgai eval '<js>'   drive and read the running game",
+  '',
+  'The standalone page serves EXPORTED builds only (`vgai deploy`, or the',
+  'production build it runs). Do not script around this page — no headless',
+  'browsers, bots, or screenshots against the dev server. Every agent',
+  'workflow goes through the editor session.',
+].join('\n');
+
+/** True only on a real, dev-served browser page — the one context the trap is for. */
+function isDevServedBrowserPage(): boolean {
+  if (typeof window === 'undefined' || typeof document === 'undefined') return false;
+  // Test stubs install a bare `document` object; only a real page has the
+  // document↔window linkage.
+  if (document.defaultView !== window) return false;
+  return Boolean(import.meta.env?.DEV);
+}
+
+/**
+ * Throws (and paints a full-screen refusal, so a human at the tab sees it as
+ * immediately as a harness watching the console does) when an unexported game
+ * is being mounted on a dev-served page. Called by `mountGameFromManifest`
+ * before any root is resolved; exported builds and headless tests pass
+ * through untouched.
+ */
+export function assertExportedOrInEditor(): void {
+  if (!isDevServedBrowserPage()) return;
+
+  const screen = document.createElement('pre');
+  screen.textContent = REFUSAL;
+  screen.style.cssText = [
+    'position:fixed',
+    'inset:0',
+    'z-index:2147483647',
+    'margin:0',
+    'padding:48px',
+    'background:#1A0E0E',
+    'color:#FF9B8A',
+    'font:600 15px/1.7 ui-monospace,SFMono-Regular,Menlo,monospace',
+    'white-space:pre-wrap',
+  ].join(';');
+  document.body.appendChild(screen);
+  document.title = 'UNEXPORTED — use the editor';
+
+  throw new Error(`mountGameFromManifest: ${REFUSAL}`);
+}

package/src/setup/setup-renderer.ts

@@ -1,3 +1,5 @@
+/// <reference path="../types-n8ao.d.ts" />
+
 import { N8AOPostPass } from 'n8ao';
 import {
   BloomEffect,

package/src/world3d-react/index.ts

@@ -29,6 +29,15 @@
  *    to use instead.
  *  - `EngineBridge` / `EngineBridgeValue` — the context contract, exported
  *    for advanced adopters building their own bridge.
+ *
+ * Deliberately NOT re-exported here: `<RapierPhysicsBridge>`
+ * (`@engine/world3d-react/rapier-physics-bridge`), which registers an R3F
+ * world's `@react-three/rapier` physics as the game's
+ * `SystemAdapters.physics` — so the dev menu's colliders instrument and the
+ * editor's transform coordination can see it. It imports
+ * `@react-three/rapier`, and only a world that already depends on that library
+ * should pull it into its graph; a deep import keeps this barrel's peer
+ * contract to `react`/`@react-three/fiber`/`three` alone.
  */
 
 export { EngineBridge, type EngineBridgeValue, useGameContext } from './engine-bridge';

package/src/world3d-react/rapier-physics-bridge.tsx

@@ -0,0 +1,137 @@
+/**
+ * `<RapierPhysicsBridge>` — the one line that makes an R3F world's
+ * `@react-three/rapier` physics VISIBLE to the engine's editor/dev seams.
+ *
+ * WHY IT EXISTS. `SystemAdapters.physics` is what the editor's transform
+ * coordination (`freeze → apply → unfreeze`) and the dev menu's universal
+ * "Colliders drawn" instrument (`@engine/dev/instruments`) read. The
+ * first-party imperative three root registers one from
+ * `../adapter/setup-three-root-adapter.ts`; an R3F world builds no first-party
+ * Rapier runtime at all (see `R3FGameContext`'s doc comment) — it does physics
+ * with `@react-three/rapier` INSIDE the fiber tree, where nothing engine-side
+ * can see it. Result, before this: the colliders instrument read `null` (an
+ * em-dash) and its toggle threw "no physics adapter" in every shipped example
+ * and every scaffolded game.
+ *
+ * NOT A WRAPPER. This registers an adapter and gets out of the way: the world
+ * still writes `<Physics>` itself, with the library's own props, and every
+ * `<RigidBody>`/collider call stays `@react-three/rapier`'s own API. The one
+ * thing it cannot do for you is flip the library's debug rendering, because
+ * `@react-three/rapier@2` exposes that ONLY as the `debug` boolean PROP on
+ * `<Physics>` (its `<Debug>` component is internal and unexported). A prop is
+ * the parent's to own, so the world holds the state and this bridge hands the
+ * setter to the instrument — which is why `onDebugChange` is required:
+ *
+ * ```tsx
+ * const [physicsDebug, setPhysicsDebug] = useState(false);
+ * // …
+ * <Physics debug={physicsDebug}>
+ *   <RapierPhysicsBridge onDebugChange={setPhysicsDebug} />
+ *   …
+ * </Physics>
+ * ```
+ *
+ * Nothing draws colliders here: the wireframes are the library's own
+ * `world.debugRender()` output, rendered by its own component.
+ *
+ * ANTI-SHIM. `debugDraw()` and `contactPoints()` are OMITTED, not stubbed —
+ * the library owns its debug line segments inside the tree and hands out no
+ * handle to them, so claiming the capability would be a fabrication. Absence
+ * is how a `SystemAdapters` member says "not supported".
+ *
+ * ── RESOURCE OWNERSHIP, STATED ONCE ─────────────────────────────────────────
+ * OWNER: this component owns exactly ONE `SystemAdapters.physics` registration,
+ * on the R3F root it is mounted in. It allocates nothing else — no timers, no
+ * subscriptions, no per-frame work (see the phase note below), and no Rapier
+ * objects: the bodies it edits belong to `<Physics>`.
+ * SHARERS: every reader of `game.systemAdapters.physics` — the dev menu's
+ * colliders instrument, the editor's transform coordination. They read; they
+ * never dispose.
+ * TEARDOWN: the effect's cleanup, and nothing else — it clears the SAME key it
+ * set (`registerSystemAdapter('physics', undefined)`, which
+ * `Game.computeSystemAdapters` skips), so a play stop/start, a hot restart, or
+ * a world that unmounts `<Physics>` leaves no stale adapter behind. Two
+ * bridges in one root would fight over that one key; mount exactly one.
+ *
+ * PHASE ORDERING: none to respect — this component registers pull-only
+ * callbacks and runs no per-frame work. Every method it exposes is invoked
+ * BETWEEN frames, by an editor gesture or a dev-menu command, never from a
+ * phase.
+ */
+
+import { type RapierRigidBody, useRapier } from '@react-three/rapier';
+import { useEffect } from 'react';
+import type * as THREE from 'three';
+import {
+  createRapierBodyEditing,
+  type RapierEditableBody,
+} from '../adapter/rapier-physics-adapter';
+import type { PhysicsAdapter } from '../adapter/system-adapter';
+import { useGameContext } from './engine-bridge';
+
+export interface RapierPhysicsBridgeProps {
+  /**
+   * Set the `debug` prop of the SAME `<Physics>` this bridge is mounted in.
+   * The dev menu's "Colliders drawn" toggle calls it; the world's own state is
+   * what `<Physics debug={…}>` reads, so the library's debug rendering is the
+   * only thing that ever draws a collider.
+   */
+  readonly onDebugChange: (debug: boolean) => void;
+}
+
+/**
+ * Register this R3F world's `@react-three/rapier` physics as the game's
+ * `SystemAdapters.physics`. Mount it once, INSIDE `<Physics>` (it reads
+ * `useRapier()`). Renders nothing.
+ */
+export function RapierPhysicsBridge({ onDebugChange }: RapierPhysicsBridgeProps): null {
+  const ctx = useGameContext();
+  const { rigidBodyStates } = useRapier();
+  const registerSystemAdapter = ctx.registerSystemAdapter;
+
+  useEffect(() => {
+    if (!registerSystemAdapter) return;
+
+    /**
+     * node id → the Rapier body driving it, in two hops the library and the
+     * engine each already own:
+     *
+     *  1. id → `Object3D`, through the live scene index — `userData.entityId`
+     *     is this stack's identity convention (the editor's R3F authoring
+     *     adapter stamps it; `../adapter/setup-three-root-adapter.ts` resolves
+     *     the same way for the imperative root).
+     *  2. `Object3D` → body, through `rigidBodyStates` — the library's OWN
+     *     body↔object map, carried on the `RapierContext` `useRapier()`
+     *     returns. Walking ANCESTORS matters: `<RigidBody>` owns a subtree, so
+     *     the selected mesh is usually a descendant of the object the state
+     *     names.
+     *
+     * Both maps are live, so this is computed per call rather than cached —
+     * calls arrive at gesture rate (a gizmo drag start/end, a dev command),
+     * never per frame. `ctx.sceneIndex` is read AT CALL TIME, never captured:
+     * the R3F root backfills it once fiber resolves the scene, which can land
+     * after this component's first effect (`world-context.ts`'s
+     * `setSceneCamera`), so a destructured copy would be permanently absent.
+     */
+    const bodyFor = (nodeId: string): RapierEditableBody | undefined => {
+      const object = ctx.sceneIndex?.byEntityId(nodeId);
+      if (!object) return undefined;
+      const byObject = new Map<THREE.Object3D, RapierRigidBody>();
+      for (const state of rigidBodyStates.values()) byObject.set(state.object, state.rigidBody);
+      for (let node: THREE.Object3D | null = object; node; node = node.parent) {
+        const body = byObject.get(node);
+        if (body) return body;
+      }
+      return undefined;
+    };
+
+    const adapter: PhysicsAdapter = {
+      ...createRapierBodyEditing(bodyFor),
+      setDebugDrawEnabled: (enabled) => onDebugChange(enabled),
+    };
+    registerSystemAdapter('physics', adapter);
+    return () => registerSystemAdapter('physics', undefined);
+  }, [ctx, registerSystemAdapter, rigidBodyStates, onDebugChange]);
+
+  return null;
+}