@vgai/engine 0.2.0

package/src/runtime/game.ts

@@ -0,0 +1,1003 @@
+/**
+ * Game root — T7.1 slice 1 ("introduce Game internally") + slice 2 ("world
+ * registry + ordered frame algorithm"), extended in T7.3 slice 1 with real
+ * `'pixijs'`-kind `WorldInstance` support (`stage`/`physics2d`/`collisions2d`,
+ * a real `pixiRoot()`) so `world2d/pixi-game-adapter.ts` can register its
+ * world onto a real `Game` instead of driving its own loop, and in T7.3
+ * slice 2 with a construction-time stage check (symmetric with the
+ * threejs/scene check) and the two-world (threejs + pixijs) proof
+ * (`test/game-three-plus-pixi.test.ts`). T6.2 slice 1 adds real `'react'`-kind
+ * `WorldInstance` support (`container`, a real `reactRoot()`) — the DOM-root
+ * world surface `runtime/create-runtime.ts`'s worlds path now mounts (see
+ * `docs/REACT-WORLD-DESIGN.md` §1.B); react worlds host no `ComponentManager`
+ * (D8 — components attaching to a react-kind manager already throw,
+ * `ecs/component-manager.ts`), so `physics`/`collisions`/`camera`/`frame`
+ * stay `undefined` for them exactly like an opaque/foreign mount.
+ *
+ * See `docs/GAME-ROOT-DESIGN.md` (D6), particularly §4 (the frame algorithm)
+ * and §8 stage 2, for the full target shape. This file holds the Game/
+ * WorldInstance shell, the NEW game-scoped `SystemRunner`, and the
+ * host-facing `runFrame` frame executor. The public surface is NOT frozen
+ * yet — do not add these exports to a barrel/index; only the in-scope
+ * runtime/adapter files import this module directly. The `gpu` per-world
+ * cache is the one remaining slice-1 omission.
+ */
+
+// TYPE-ONLY pixi import (T7.3 slice 1): `game.ts` must never value-import
+// `pixi.js` — a value import would pull the Pixi runtime into 3D-only
+// bundles that never touch world2d. Every pixi-typed field below is erased
+// at compile time; nothing here constructs or calls into Pixi.
+import type * as PIXI from 'pixi.js';
+import type * as THREE from 'three';
+import type { MountedWorld } from '../adapter/game-adapter';
+import { formatAudioGateMessage, formatLoopGateMessage } from '../adapter/loop-gate-report';
+import type { SystemAdapters } from '../adapter/system-adapter';
+import type { VgaiMountedGame } from '../adapter/vgai-scene-game-adapter';
+import type { WorldKind as WorldKindLeaf } from '../adapter/world-kind';
+import type { AssetCache } from '../assets';
+import type { createGameLoop } from '../core/game-loop';
+import { createSystemRunner, type SystemRunner } from '../core/system-runner';
+import { PHASE_ORDER, SystemPhase, type SystemPhaseName } from '../core/types';
+import type { ComponentManager } from '../ecs/component-manager';
+import type { GameComponent } from '../ecs/game-component';
+import type { InputManager } from '../input/input-manager';
+import type { CollisionSystem } from '../physics/collision-system';
+import type { PhysicsRegistry } from '../physics/physics-registry';
+import type { AudioContext as GameAudio } from '../setup/setup-audio';
+// TYPE-ONLY (same rule as the pixi import above): these live under
+// `world2d/`, but `game.ts` only ever names their TYPES.
+import type { Collision2DSystem } from '../world2d/collision-2d';
+import type { Physics2DRegistry } from '../world2d/physics2d-registry';
+import { createStateBridge, type GameStateBridge } from './state-bridge';
+
+/** The one loop type — `createGameLoop`'s return shape (D1, fixed-step). */
+export type GameLoop = ReturnType<typeof createGameLoop>;
+
+/**
+ * Game-level play-state control surface (D10, T7.6 — `docs/DECISIONS-PENDING.md`
+ * §D10): pause/resume/step as ONE control surface on the running game, with
+ * PER-WORLD `pausable` semantics (`WorldInstance.pausable`) — a menu/HUD world
+ * declaring `pausable: false` keeps ticking (input, components, physics) while
+ * every `pausable: true` world freezes. Interacts with D1 (deliberate
+ * fixed-rate rendering): a paused-and-pausable world's `render` phase still
+ * runs every substep (with `dt` forced to `0`, so time-based render effects —
+ * e.g. a post-processing pass with its own internal clock — don't silently
+ * keep animating under a "frozen" scene) — simulation freezes, the screen does
+ * not go black. `GameLoop.timeScale` (unaffected by this) remains the
+ * orthogonal "speed up/slow down" axis — pausing never touches it, so the
+ * host's accumulator/rAF loop keeps ticking at its normal cadence and keeps
+ * calling `runFrame`, which is what makes "paused still renders" possible
+ * (the previous `GameSession.pause()` implementation set `loop.timeScale = 0`,
+ * which — per D1 — starves the accumulator and stops rendering too; that was
+ * the bug this control surface replaces, not a compatible behavior to keep).
+ */
+export interface PlayState {
+  /** Whether the game is currently paused (game-level — see the per-world
+   *  `pausable` caveat above: a `pausable: false` world ignores this). */
+  readonly paused: boolean;
+  /**
+   * Freeze every `pausable` world's simulation (idempotent — a second call
+   * while already paused is a no-op) and, for every `pausable`, self-driven
+   * (`drivesOwnLoop`) world, invoke its loop-gate capability
+   * (`mounted.setPaused(true)`) — reporting loudly, once per world, when that
+   * capability is absent (an honest "cannot gate" instead of a silent no-op,
+   * `docs/CAPABILITY-TIERS.md` §d). Also silences every `pausable` world's
+   * audio via its `SystemAdapters.audio` (absent ⇒ the same loud, once-only
+   * report).
+   */
+  pause(): void;
+  /** Resume every `pausable` world — the inverse of `pause()`, same
+   *  idempotency and loop-gate/audio fan-out (no re-reporting; a world that
+   *  couldn't be gated on pause simply never was, so resume has nothing to
+   *  undo for it). */
+  resume(): void;
+  /**
+   * Advance exactly the currently-FROZEN worlds by one fixed substep: the
+   * `pausable`, host-driven (`!drivesOwnLoop`) worlds while `paused` is
+   * true. While NOT paused this is a whole-call no-op — under D10 the loop
+   * never stops, so every non-frozen world is already being ticked; an
+   * unconditional extra tick was the §7.1-2 double-tick bug (probe4). A
+   * `pausable`, self-driven world that was actually gated by `pause()`
+   * (adapter has `setPaused`) steps via its own loop-gate `step()`
+   * capability instead (absent ⇒ the same loud report as `pause()`); a
+   * self-driven world the gate couldn't reach is still running and is left
+   * alone. `dt` defaults to the engine's fixed timestep (1/60s — every real
+   * host constructs its loop with this value; see `create-runtime.ts`).
+   */
+  step(dt?: number): void;
+}
+
+/**
+ * The kinds of render surface a world can be. `'threejs'` and `'pixijs'`
+ * worlds are real as of T7.3 slice 1 (`create-runtime.ts`'s default threejs
+ * world; `world2d/pixi-game-adapter.ts`'s pixi world); `'react'` is named
+ * here so the type is already shaped for T7.4 and no caller has to widen a
+ * union later.
+ *
+ * Re-exported from `adapter/world-kind.ts` (T7.5) — moved there so
+ * `adapter/game-adapter.ts`'s kind-tagged `MountedWorld` types can name it
+ * without an import cycle back to this file. This re-export keeps every
+ * existing `import type { WorldKind } from '../runtime/game'` call site
+ * (`ecs/game-component.ts`, `ecs/component-manager.ts`) compiling unchanged.
+ */
+export type WorldKind = WorldKindLeaf;
+
+/**
+ * A world's per-phase frame hooks (GAME-ROOT-DESIGN §4, T7.1 slice 2).
+ * Populated on a `WorldInstance` only for first-party mounts — an opaque/
+ * foreign mount has no phase-partitioned entry point, so it stays
+ * `undefined` and the Game's frame executor (`GameInternal.runFrame`) falls
+ * back to calling its single `mounted.update(dt)` once per substep instead.
+ */
+export interface WorldFrameHooks {
+  /** Run this world's engine systems + component ticks + world-bound game
+   *  systems for one phase. For a first-party world this delegates to the
+   *  SAME `SystemRunner.runPhase` its (legacy) `mounted.update` uses. */
+  runPhase(phase: SystemPhaseName, dt: number): void;
+  /** Run once per substep, after ALL phases have run for ALL worlds this
+   *  substep (mirrors where `mounted.update`'s post-`systems.run` work sat
+   *  today — e.g. `input.endFrame()`). Optional: a world may have nothing
+   *  to do here. */
+  endFrame?(): void;
+}
+
+/**
+ * A single world instance: the unit of adaptation (GAME-ROOT-DESIGN §3).
+ * Slice-1 subset — `gpu` (per-world GPU resource cache, §6.2) is omitted
+ * until the slice that builds it.
+ */
+export interface WorldInstance {
+  /** Manifest id (T3.1). Slice 1 always registers exactly one: `'main'`. */
+  readonly id: string;
+  readonly kind: WorldKind;
+  /** Per-world play/pause semantics (D10, T7.6). Slice 1 always `true`. */
+  readonly pausable: boolean;
+  /** The GameAdapter that produced `mounted` — first-party or external.
+   *  Deliberately narrower than `GameAdapter<K>` (T7.5): this field is only
+   *  ever read for `.id` (`Game.registerWorld`'s diagnostic message below) —
+   *  never re-invoked — and `GameAdapter<K>`'s `mount` signature legitimately
+   *  differs per kind's host type (a pixijs adapter's `World2DHost`, a react
+   *  adapter's `ReactWorldHost`, vs a threejs adapter's `HostContext`), so
+   *  requiring the FULL interface here would force a cast at every non-
+   *  threejs registration site for no behavioral gain — see `AdapterHandle`
+   *  below. */
+  readonly adapter: AdapterHandle;
+  /** The live mounted surface — one of `MountedWorld`'s kind-tagged shapes
+   *  (T7.5; `MountedThreeWorld` for a threejs world, `MountedPixiWorld` for
+   *  pixijs, `MountedReactWorld` for react). */
+  readonly mounted: MountedWorld;
+  /** Kind-narrowed accessor: throws a descriptive error when this world is
+   *  not a threejs world. */
+  threeRoot(): THREE.Scene;
+  /** Kind-narrowed accessor for pixijs worlds (T7.3): returns the stage
+   *  passed to `createWorldInstance` for a `'pixijs'`-kind world. Throws
+   *  descriptively for a non-pixijs world, or a pixijs world built without
+   *  a `stage` (see `WorldInstanceInit.stage`). */
+  pixiRoot(): PIXI.Container;
+  /** Kind-narrowed accessor for react worlds (T6.2 slice 1,
+   *  `docs/REACT-WORLD-DESIGN.md` §1.B): returns the DOM-root layer
+   *  `<div>` the host mounted this world's react tree into (the SAME
+   *  element passed as `container` to `createWorldInstance` — identity
+   *  matters, mirroring `threeRoot()`/`pixiRoot()`'s "same instance the
+   *  adapter mounted" contract). Throws descriptively for a non-react
+   *  world, or a react world built without a `container` (see
+   *  `WorldInstanceInit.container`). */
+  reactRoot(): HTMLElement;
+  /** Present only when the world's mount is first-party (Rapier3D for
+   *  threejs worlds). */
+  readonly physics?: PhysicsRegistry | undefined;
+  readonly collisions?: CollisionSystem | undefined;
+  /** Present only when the world's mount is a first-party pixijs world
+   *  (Rapier2D, T7.3) — the 2D analog of `physics`/`collisions` above. Kept
+   *  as separate fields (not folded into `physics`/`collisions` as a union)
+   *  so 3D call sites keep their non-union `PhysicsRegistry`/`CollisionSystem`
+   *  typing unchanged. */
+  readonly physics2d?: Physics2DRegistry | undefined;
+  readonly collisions2d?: Collision2DSystem | undefined;
+  /** Kind-typed via `mounted` in T7.5; `unknown` here deliberately. */
+  readonly camera?: unknown;
+  /** Phase-partitioned frame entry point (T7.1 slice 2) — present only for
+   *  first-party mounts. `undefined` for an opaque/foreign mount, which
+   *  `GameInternal.runFrame` drives via its single `mounted.update` call
+   *  instead (unless it `drivesOwnLoop`, in which case it isn't ticked at
+   *  all — see `runFrame`). */
+  readonly frame?: WorldFrameHooks | undefined;
+}
+
+/**
+ * Minimal identity surface `WorldInstance.adapter` needs (T7.5) — see that
+ * field's doc comment for why it's narrower than `GameAdapter<K>`. Any real
+ * adapter object (a NAMED type, not a fresh object literal) — `GameAdapter<K>`,
+ * `Pixi2DGameAdapter`, `ReactWorldAdapter`, or a project's own custom adapter —
+ * satisfies this trivially (extra members beyond `id` are always fine for a
+ * non-literal source); a bare `{ id, mount }` object literal built INLINE at
+ * a `createWorldInstance`/`registerXWorld` call site needs an intermediate
+ * `const` (excess-property checking only special-cases fresh literals).
+ */
+export interface AdapterHandle {
+  readonly id: string;
+}
+
+/** Inputs to {@link createWorldInstance}. */
+export interface WorldInstanceInit {
+  readonly id: string;
+  readonly kind: WorldKind;
+  /** Defaults to `true` (D10's per-world default). */
+  readonly pausable?: boolean;
+  readonly adapter: AdapterHandle;
+  readonly mounted: MountedWorld;
+  /** Required when `kind === 'threejs'` — backs `threeRoot()`. */
+  readonly scene?: THREE.Scene | undefined;
+  /** Required when `kind === 'pixijs'` — backs `pixiRoot()` (T7.3 slice 2,
+   *  symmetric with `scene` for threejs above). */
+  readonly stage?: PIXI.Container | undefined;
+  /** Required when `kind === 'react'` — backs `reactRoot()` (T6.2 slice 1,
+   *  symmetric with `scene`/`stage` above): the DOM-root layer `<div>` this
+   *  world's react tree is mounted into. */
+  readonly container?: HTMLElement | undefined;
+  readonly physics?: PhysicsRegistry | undefined;
+  readonly collisions?: CollisionSystem | undefined;
+  readonly physics2d?: Physics2DRegistry | undefined;
+  readonly collisions2d?: Collision2DSystem | undefined;
+  readonly camera?: unknown;
+  readonly frame?: WorldFrameHooks | undefined;
+}
+
+/**
+ * Build a `WorldInstance` whose kind-narrowed accessors throw descriptively
+ * on kind mismatch (GAME-ROOT-DESIGN §3). This is the one place that builds
+ * `threeRoot`/`pixiRoot`, so every world (however it's constructed, in this
+ * slice or later ones) gets identical throw behavior.
+ */
+export function createWorldInstance(init: WorldInstanceInit): WorldInstance {
+  const {
+    id,
+    kind,
+    pausable = true,
+    adapter,
+    mounted,
+    scene,
+    stage,
+    container,
+    physics,
+    collisions,
+    physics2d,
+    collisions2d,
+    camera,
+    frame,
+  } = init;
+
+  // A threejs world with no scene has nothing for `threeRoot()` to return —
+  // fail loudly HERE, at construction, rather than letting `threeRoot()`
+  // throw its generic "not a threejs world" message later for a world whose
+  // kind IS threejs (checklist item 5; a misleading error for this case).
+  if (kind === 'threejs' && !scene) {
+    throw new Error(
+      `WorldInstance "${id}" (kind: threejs): a threejs world requires a scene — ` +
+        'pass `scene` in WorldInstanceInit.',
+    );
+  }
+
+  // Symmetric check for pixijs (T7.3 slice 2) — a pixijs world with no stage
+  // has nothing for `pixiRoot()` to return; fail loudly here, at
+  // construction, same as the threejs/scene check above.
+  if (kind === 'pixijs' && !stage) {
+    throw new Error(
+      `WorldInstance "${id}" (kind: pixijs): a pixijs world requires a stage — ` +
+        'pass `stage` in WorldInstanceInit.',
+    );
+  }
+
+  // Symmetric check for react (T6.2 slice 1, docs/REACT-WORLD-DESIGN.md
+  // §1.B) — a react world with no container has nothing for `reactRoot()`
+  // to return; fail loudly here, at construction, same as the two checks
+  // above.
+  if (kind === 'react' && !container) {
+    throw new Error(
+      `WorldInstance "${id}" (kind: react): a react world requires a container — ` +
+        'pass `container` in WorldInstanceInit.',
+    );
+  }
+
+  // Disposed-world guard (GAME-ROOT-DESIGN §8 stage 3 / T7.1 slice 3). There
+  // is no `unregisterWorld` (decision 4 — worlds are manifest-declared; a
+  // whole Game is disposed, not one world out of its registry), so a caller
+  // that disposes ONE world's `mounted` directly (e.g. ending a sub-session)
+  // leaves that `WorldInstance` sitting in `Game.worlds` — and `runFrame`
+  // would otherwise keep invoking its (now-torn-down) frame hooks every
+  // subsequent frame. `MountedGame` has no public "am I disposed" flag to
+  // read, so this wraps `mounted.dispose` in place (mutating the SAME mount
+  // object every holder of `mounted` shares — calling `mounted.dispose()`
+  // directly, exactly like calling `world.mounted.dispose()`, trips this)
+  // to flip a private flag, and wraps the frame hooks so they silently no-op
+  // once that flag is set. `runFrame` itself needs no knowledge of disposal
+  // — a disposed world is skipped by construction from the next call
+  // onward. (The opaque-world `mounted.update` fallback path is unaffected
+  // by this guard — no opaque-mount two-world scenario exists yet to need it.)
+  let disposed = false;
+  const originalDispose = mounted.dispose.bind(mounted);
+  mounted.dispose = () => {
+    disposed = true;
+    originalDispose();
+  };
+  const guardedFrame: WorldFrameHooks | undefined = frame
+    ? {
+        runPhase(phase, dt) {
+          if (disposed) return;
+          frame.runPhase(phase, dt);
+        },
+        endFrame() {
+          if (disposed) return;
+          frame.endFrame?.();
+        },
+      }
+    : undefined;
+
+  return {
+    id,
+    kind,
+    pausable,
+    adapter,
+    mounted,
+    physics,
+    collisions,
+    physics2d,
+    collisions2d,
+    camera,
+    frame: guardedFrame,
+    threeRoot(): THREE.Scene {
+      if (kind !== 'threejs' || !scene) {
+        throw new Error(
+          `WorldInstance "${id}" (kind: ${kind}): threeRoot() requested but this world is not ` +
+            'a threejs world',
+        );
+      }
+      return scene;
+    },
+    pixiRoot(): PIXI.Container {
+      // The `!stage` branch a pixijs world could hit here is now unreachable
+      // (T7.3 slice 2): construction above throws for `kind === 'pixijs'`
+      // with no `stage`, symmetric with `threeRoot()`'s `scene` guard.
+      if (kind !== 'pixijs' || !stage) {
+        throw new Error(
+          `WorldInstance "${id}" (kind: ${kind}): pixiRoot() requested but this world is not ` +
+            'a pixijs world',
+        );
+      }
+      return stage;
+    },
+    reactRoot(): HTMLElement {
+      // The `!container` branch a react world could hit here is now
+      // unreachable (T6.2 slice 1): construction above throws for
+      // `kind === 'react'` with no `container`, symmetric with
+      // `threeRoot()`/`pixiRoot()`'s guards.
+      if (kind !== 'react' || !container) {
+        throw new Error(
+          `WorldInstance "${id}" (kind: ${kind}): reactRoot() requested but this world is not ` +
+            'a react world',
+        );
+      }
+      return container;
+    },
+  };
+}
+
+/**
+ * Type guard for whether a `MountedGame` is a first-party
+ * `VgaiSceneGameAdapter` mount (has a live `GameContext` at `.ctx`). Used to
+ * decide whether a world's `physics`/`collisions`/`camera` (and, on `Game`,
+ * `components`/`input`/`audio`) can be populated from it — an external
+ * adapter's mount has none of these first-party handles.
+ *
+ * Checks the `firstParty: true` brand (checklist item 1), NOT `'ctx' in
+ * mounted` — world2d's `MountedGame2D` (`world2d/pixi-game-adapter.ts`) also
+ * has a `ctx` key (a `World2DContext`, unrelated to `GameContext`), so a
+ * structural `'ctx' in mounted` check would misfire once T7.3 registers 2D
+ * worlds onto the same `Game`. The probe is a plain property read, not an
+ * `instanceof`/value import of `vgai-scene-game-adapter.ts` — the
+ * `VgaiMountedGame` import above stays type-only.
+ */
+export function isFirstPartyMounted(mounted: MountedWorld): mounted is VgaiMountedGame {
+  return (mounted as { firstParty?: unknown }).firstParty === true;
+}
+
+/**
+ * The Game root (GAME-ROOT-DESIGN §3). Owns the one loop, the raw-asset
+ * cache, the world registry, and (T7.1 slice 2) the game-scoped
+ * `SystemRunner`. `components`/`input`/`audio` remain slice-1 late
+ * additions: they delegate to the default world's first-party mount so
+ * existing single-world call sites keep working; hoisting them to true
+ * Game ownership (GAME-ROOT-DESIGN §3's target shape) is a later slice's
+ * work, not this one's.
+ */
+export interface Game {
+  readonly loop: GameLoop;
+  readonly assets: AssetCache;
+  /**
+   * The game-scoped `SystemRunner` (GAME-ROOT-DESIGN §4, T7.1 slice 2) — a
+   * NEW bucket, separate from any world's own runner. Within each phase,
+   * `GameInternal.runFrame` runs THIS runner's `runPhase` first, before any
+   * world's engine systems/component ticks/world-bound game systems (e.g.
+   * `ctx.systems.add`, which stays world-bound to the default world — see
+   * `runtime/types.ts`). Empty for every existing game (nothing registers
+   * against it yet), so `runFrame`'s behavior for a single-world game is
+   * unchanged by its presence.
+   */
+  readonly systems: SystemRunner;
+  /** Declaration-ordered. Slice 1 registers exactly one (the default
+   *  threejs world) — this is the SAME array reference `registerWorld`
+   *  mutates, not a snapshot, so holders (e.g. `GameContext.worlds`) observe
+   *  later registrations. */
+  readonly worlds: ReadonlyArray<WorldInstance>;
+  world(id: string): WorldInstance | null;
+  /** First threejs world, else first world. Throws descriptively when no
+   *  world has been registered yet. */
+  readonly defaultWorld: WorldInstance;
+  /**
+   * Game-scoped aggregation of every world's `SystemAdapters` (§7.1-3,
+   * `docs/GAME-ROOT-DESIGN.md` §3: "`registerSystemAdapter` is game-scoped" —
+   * the recorded decision this getter finally implements; probe1). Each
+   * mounted world builds its OWN `mounted.systems` object (a game registers
+   * capabilities like `networking` from ITS OWN `setup()`, via
+   * `ctx.registerSystemAdapter`, per-world) — this merges every world's
+   * `mounted.systems` into ONE `SystemAdapters`, in `worlds` REGISTRATION
+   * order, first registration wins per key. A later world registering the
+   * SAME kind (e.g. two worlds both exposing `networking`) does not
+   * override the first — instead this warns ONCE per (game instance, key)
+   * naming both world ids, matching this file's `[game] world "<id>" …`
+   * console idiom (see `registerWorld` below). NOT to be confused with
+   * `Game.systems` (the game-scoped `SystemRunner` bucket, an entirely
+   * different concept — see that field's doc comment) — this name was
+   * deliberately chosen not to collide with it.
+   *
+   * A plain getter (recomputed on every read, not cached) so a LATER
+   * `registerWorld` call (or a world's setup registering a NEW adapter kind
+   * after this was first read) is always reflected — only the COLLISION
+   * warning is deduped (once per key, for the lifetime of this `Game`).
+   * Includes every world regardless of first-party-ness — `mounted.systems`
+   * is a capability any adapter (first-party or foreign) may expose.
+   */
+  readonly systemAdapters: SystemAdapters;
+  /** Delegates to the default world's first-party `ComponentManager`.
+   *  Throws when the default world is not a first-party mount. */
+  readonly components: ComponentManager;
+  /** Delegates to the default world's first-party `InputManager`. Throws
+   *  when the default world is not a first-party mount. */
+  readonly input: InputManager;
+  /** Delegates to the default world's first-party audio context. Throws
+   *  when the default world is not a first-party mount. */
+  readonly audio: GameAudio;
+  /**
+   * Frame-versioned state bridge (T7.4 slice 1 — `docs/REACT-STATE-BRIDGE.md`
+   * §2). Bumped once per completed `runFrame`, after all phases of all
+   * worlds and all `endFrame` hooks (see `runFrame`'s tail below). This is
+   * the ONE subscription surface `useGameState`
+   * (`packages/editor/template/src/ui/game-state.tsx`) — or any
+   * other frame-versioned consumer — subscribes to; `state-bridge.ts` itself
+   * has no react import, matching the rest of `runtime/`.
+   */
+  readonly state: GameStateBridge;
+  /** Game-level play-state control surface (D10, T7.6) — see {@link PlayState}. */
+  readonly play: PlayState;
+  /**
+   * Cross-world component query (GAME-ROOT-DESIGN §5, T7.1 slice 3) — the
+   * game-level half; `ComponentManager.queryByComponent` (`ecs/
+   * component-manager.ts`) is the per-world half this aggregates.
+   *
+   * Iterates `worlds` in declaration order, skipping any world whose mount
+   * is not first-party (an opaque/foreign mount has no `ComponentManager`
+   * to query), applying `opts.worldId`/`opts.kind` as world-level filters,
+   * and concatenating each remaining world's `queryByComponent(cls)`
+   * result. No filter (`opts` omitted) spans **every** world — that is the
+   * whole point of this API existing (D7's "cross-world flow is ordinary
+   * component access", e.g. a pixi minimap component querying the 3D
+   * world's tank components).
+   *
+   * Returns component **instances**, not nodes — `inst.world`/typed node
+   * accessors (`inst.object3D`, the generic `inst.node`) are T7.2's; this
+   * API's contract freezes HERE. The physical ONE-`ComponentManager`
+   * unification (partitioning one manager by (phase, world) instead of one
+   * manager per world) lands with T7.2/T7.3 — this per-world-aggregation
+   * implementation is the compatible interim: callers written against this
+   * signature keep working unchanged once the manager is unified
+   * underneath.
+   *
+   * `T extends GameComponent<WorldKind>` (not the bare default-`'threejs'`
+   * `GameComponent`, T7.3 slice 2) — the whole point of a CROSS-WORLD query
+   * is spanning every kind in one call (the T7.3 AC,
+   * `test/game-three-plus-pixi.test.ts`), so a `GameComponent<'pixijs'>`
+   * subclass must type-check here exactly like a default-kind one does.
+   */
+  queryByComponent<T extends GameComponent<WorldKind>>(
+    cls: new () => T,
+    opts?: { worldId?: string; kind?: WorldKind },
+  ): T[];
+}
+
+/**
+ * Host-internal extension of {@link Game}: adds `registerWorld` (the host's
+ * wiring surface for populating the world registry) and `runFrame` (the
+ * frame executor). NEITHER is part of the game-facing `Game` surface —
+ * games/components never call either directly; the host loop
+ * (`createGameRuntime`) and `GameSession.step()` are the only callers of
+ * `runFrame`.
+ */
+export interface GameInternal extends Game {
+  /** Append a world in declaration order. Throws on a duplicate id. */
+  registerWorld(world: WorldInstance): void;
+  /**
+   * Run ONE fixed substep across every phase and every world
+   * (GAME-ROOT-DESIGN §4):
+   *
+   * ```
+   * for phase in PHASE_ORDER:
+   *   game.systems.runPhase(phase, dt)        // game-scoped, first
+   *   for world in worlds (declaration order):
+   *     if world.mounted.drivesOwnLoop: continue
+   *     world.frame?.runPhase(phase, dt)
+   * for world in worlds:                       // after ALL phases
+   *   if world.mounted.drivesOwnLoop: continue
+   *   if world.frame: world.frame.endFrame?.()
+   *   else: world.mounted.update?.(dt)          // opaque world fallback
+   * ```
+   *
+   * For today's single first-party world this is byte-identical to the
+   * legacy `mounted.update(dt)` (`game.systems` is empty; the one world's
+   * `frame.runPhase` delegates to the SAME `SystemRunner.runPhase` its
+   * `update` used; `endFrame` is the same `postFrame` call). A
+   * `drivesOwnLoop` world is never ticked here at all — matching its
+   * exclusion from the legacy `!mountedRef.drivesOwnLoop` guard. An opaque
+   * host-driven world (no `frame`) gets exactly one `update(dt)` call per
+   * substep, after the phase loop — unchanged cadence from today.
+   *
+   * D10/T7.6 play-state addendum: when `Game.play.paused` is true, every
+   * `pausable` (and non-`drivesOwnLoop`) world skips every phase EXCEPT
+   * `render` (still called, every substep, with `dt` forced to `0`) and skips
+   * its `endFrame`/opaque-`update` call entirely — a `pausable: false` world
+   * is completely unaffected. `opts.ignorePause` runs this call as if nothing
+   * were paused, regardless of the live `paused` flag; kept for external
+   * byte-compatibility (no first-party caller passes it today — grep finds
+   * none) but is no longer how `Game.play.step()` works (§7.1-2 fix,
+   * probe4: the old `ignorePause` full-frame re-run double-ticked every
+   * already-running `pausable: false` world, since D10's ordinary loop never
+   * stops ticking them). `Game.play.step()` now drives this function via the
+   * internal-only `onlyFrozen` mode instead (see `runFrameImpl` — not part of
+   * this public, host-facing signature): it ticks EXACTLY the currently
+   * frozen set (host-driven, `pausable`, and `paused`) through every phase +
+   * `endFrame` with the real `dt` (not the render-phase's forced `0`), and
+   * touches no other world at all — a natural no-op while not paused, since
+   * the frozen set is then empty.
+   */
+  runFrame(dt: number, opts?: { ignorePause?: boolean }): void;
+}
+
+function describeMismatch(handle: 'components' | 'input' | 'audio', world: WorldInstance): string {
+  return (
+    `Game.${handle}: default world "${world.id}" (kind: ${world.kind}) is not a first-party ` +
+    "mount — hoisting these to true Game ownership is a later slice's work; available only " +
+    'via a first-party default world today'
+  );
+}
+
+/**
+ * Construct the (host-internal) Game shell. Callers: `createGameRuntime`
+ * builds this BEFORE mounting its one adapter, then registers the default
+ * threejs world once mount resolves (see `registerDefaultThreeWorld` in
+ * `create-runtime.ts`).
+ */
+export function createGame(opts: { loop: GameLoop; assets: AssetCache }): GameInternal {
+  const worlds: WorldInstance[] = [];
+  const systems = createSystemRunner();
+  const stateBridge = createStateBridge();
+
+  function requireDefaultWorld(): WorldInstance {
+    if (worlds.length === 0) {
+      throw new Error('Game.defaultWorld: no worlds registered yet');
+    }
+    return worlds.find((w) => w.kind === 'threejs') ?? worlds[0]!;
+  }
+
+  function requireFirstPartyCtx(handle: 'components' | 'input' | 'audio') {
+    const world = requireDefaultWorld();
+    if (!isFirstPartyMounted(world.mounted)) {
+      throw new Error(describeMismatch(handle, world));
+    }
+    return world.mounted.ctx;
+  }
+
+  // --- Game.systemAdapters aggregation (§7.1-3, probe1) --------------------
+  // Warn-once-per-colliding-key state, scoped to this Game instance (a fresh
+  // Game gets a fresh warn history) — deliberately NOT reset by anything
+  // short of a new `createGame` call, matching `reportedGateShortfalls`
+  // above's "once per game instance" idiom.
+  const warnedSystemAdapterKeys = new Set<string>();
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one cohesive merge-with-collision-report walk (per-world × per-key); splitting the collision-warn branch out would obscure that it's part of the same pass, not reduce real complexity
+  function computeSystemAdapters(): SystemAdapters {
+    const result: SystemAdapters = {};
+    const ownerWorldId = new Map<string, string>();
+    for (const world of worlds) {
+      const adapters = world.mounted.systems;
+      if (!adapters) continue;
+      for (const key of Object.keys(adapters) as (keyof SystemAdapters)[]) {
+        if (adapters[key] === undefined) continue;
+        const existingOwner = ownerWorldId.get(key);
+        if (existingOwner !== undefined) {
+          if (!warnedSystemAdapterKeys.has(key)) {
+            warnedSystemAdapterKeys.add(key);
+            // biome-ignore lint/suspicious/noConsole: structured, greppable — mirrors this file's own reportGateShortfallOnce's deliberate direct console.warn just above
+            console.warn(
+              `[game] systemAdapters: "${key}" is registered by both world "${existingOwner}" and ` +
+                `world "${world.id}" — the FIRST registration ("${existingOwner}") wins; the later ` +
+                'one is shadowed (docs/GAME-ROOT-DESIGN.md §3: game-scoped system adapters).',
+            );
+          }
+          continue;
+        }
+        // biome-ignore lint/suspicious/noExplicitAny: SystemAdapters is a plain optional-field record; the per-key copy is correct by construction (same key on both sides), just not expressible without a cast
+        (result as any)[key] = adapters[key];
+        ownerWorldId.set(key, world.id);
+      }
+    }
+    return result;
+  }
+
+  // --- D10/T7.6 play-state (Game.play) -------------------------------------
+  let paused = false;
+  // Dedupe loop-gate/audio-gate shortfall warnings to ONCE per (world, kind)
+  // — `pause()` fans out over every world every call; without this a
+  // multi-second play session would re-log the same "can't gate" shortfall
+  // every time the user hits Pause.
+  const reportedGateShortfalls = new Set<string>();
+  function reportGateShortfallOnce(kind: 'loop' | 'audio', worldId: string, reason: string): void {
+    const key = `${kind}:${worldId}`;
+    if (reportedGateShortfalls.has(key)) return;
+    reportedGateShortfalls.add(key);
+    const message =
+      kind === 'loop'
+        ? formatLoopGateMessage({ worldId, reason })
+        : formatAudioGateMessage({ worldId, reason });
+    // Other native `console.warn`/`console.error` call sites in this file are
+    // unsuppressed and already counted in the lint baseline (see `runFrame`'s
+    // impl below); this one is a NEW site, so it's suppressed to keep this
+    // task's diff at zero NEW warnings (same reasoning as `overlay-report.ts`'s
+    // identical suppression).
+    // biome-ignore lint/suspicious/noConsole: see comment above
+    console.warn(message);
+  }
+
+  /** Fan out a loop-gate (self-driven worlds) + audio-gate call over every
+   *  `pausable` world, reporting honestly (once) wherever the capability is
+   *  absent — shared by `pause()`/`resume()` below (same fan-out, opposite
+   *  boolean). */
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: fans out TWO independent capability gates (loop, audio) with the same "call it, else report once" shape per world — splitting the two gates into separate loops would duplicate the fan-out, not reduce real complexity
+  function setWorldGates(next: boolean): void {
+    for (const world of worlds) {
+      if (!world.pausable) continue; // pausable:false worlds are untouched by design
+      if (world.mounted.drivesOwnLoop) {
+        if (world.mounted.setPaused) {
+          world.mounted.setPaused(next);
+        } else if (next) {
+          reportGateShortfallOnce(
+            'loop',
+            world.id,
+            'self-driven world, adapter declares no setPaused capability',
+          );
+        }
+      }
+      const audio = world.mounted.systems?.audio;
+      if (audio) {
+        audio.setMuted(next);
+      } else if (next) {
+        reportGateShortfallOnce('audio', world.id, 'no SystemAdapters.audio on this world');
+      }
+    }
+  }
+
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: the frame algorithm (GAME-ROOT-DESIGN §4, now with D10's per-world pause gate + the onlyFrozen step()-only mode) is one cohesive nested loop over phases/worlds — splitting it would obscure the ordering contract documented on GameInternal.runFrame
+  function runFrameImpl(
+    dt: number,
+    frameOpts?: { ignorePause?: boolean; onlyFrozen?: boolean },
+  ): void {
+    const ignorePause = frameOpts?.ignorePause ?? false;
+    // `onlyFrozen` is internal-only (not part of the public `GameInternal.runFrame`
+    // signature — no external caller sets it) — `Game.play.step()` below is the
+    // one and only caller. It ticks EXACTLY the currently-frozen set (host-driven,
+    // `pausable`, and `paused`) through every phase + `endFrame`, with the REAL
+    // `dt` (not the render-phase's forced `0`), and touches no other world at all
+    // — §7.1-2 fix, probe4: the previous `ignorePause` full-frame re-run ticked
+    // EVERY host-driven world, double-ticking every already-running
+    // `pausable: false` world (D10's ordinary loop never stops ticking them).
+    const onlyFrozen = frameOpts?.onlyFrozen ?? false;
+    // Checklist item 7: snapshot the world count ONCE at entry and iterate
+    // by index in both loops below. A world registered mid-frame (e.g. from
+    // a game-scoped system's side effect) joins at the NEXT `runFrame` call,
+    // not this one — `for (const world of worlds)` would otherwise pick up
+    // a world pushed during this very frame. This also drops the two
+    // per-phase `for...of` iterator allocations.
+    const n = worlds.length;
+
+    // §7.1-11 fix (probe5): `stateBridge.bump()` must fire iff at least one
+    // world actually advanced this call — not unconditionally. `advanced`
+    // covers rule (a) below (host-driven worlds this call actually ticked);
+    // rule (b): a self-driven world that is RUNNING — which is every
+    // self-driven world while not paused, and, while paused, the ones the
+    // gate can't reach (`pausable: false`, or no `setPaused` capability) —
+    // checked once, up front, over the same `worlds` array (no extra
+    // allocation, matching every other loop here). Rule (b) is skipped in
+    // `onlyFrozen` mode: a `step()` call bumps iff it ticked a frozen world
+    // — self-driven notifications belong to the loop's own `runFrame`s.
+    let advanced = false;
+    if (!onlyFrozen) {
+      for (let i = 0; i < n; i++) {
+        const world = worlds[i]!;
+        if (!world.mounted.drivesOwnLoop) continue;
+        if (!paused || !world.pausable || !world.mounted.setPaused) {
+          advanced = true;
+          break;
+        }
+      }
+    }
+
+    if (onlyFrozen) {
+      // step(): the frozen set is host-driven + pausable + currently paused.
+      // While NOT paused this set is empty by construction, so this whole
+      // branch is a natural no-op — `Game.play.step()`'s "no-op while
+      // running" behavior falls straight out of this, no separate guard
+      // needed.
+      for (const phase of PHASE_ORDER) {
+        for (let i = 0; i < n; i++) {
+          const world = worlds[i]!;
+          if (world.mounted.drivesOwnLoop) continue;
+          if (!(paused && world.pausable)) continue; // only the frozen set
+          try {
+            world.frame?.runPhase(phase, dt);
+          } catch (err) {
+            console.error(
+              `[game] world "${world.id}" (kind: ${world.kind}) runPhase("${phase}") threw ` +
+                '(step()):',
+              err,
+            );
+          }
+        }
+      }
+      for (let i = 0; i < n; i++) {
+        const world = worlds[i]!;
+        if (world.mounted.drivesOwnLoop) continue;
+        if (!(paused && world.pausable)) continue;
+        advanced = true;
+        if (world.frame) {
+          try {
+            world.frame.endFrame?.();
+          } catch (err) {
+            console.error(
+              `[game] world "${world.id}" (kind: ${world.kind}) endFrame() threw (step()):`,
+              err,
+            );
+          }
+        } else {
+          try {
+            world.mounted.update?.(dt);
+          } catch (err) {
+            console.error(
+              `[game] world "${world.id}" (kind: ${world.kind}) update() threw (step()):`,
+              err,
+            );
+          }
+        }
+      }
+    } else {
+      for (const phase of PHASE_ORDER) {
+        systems.runPhase(phase, dt);
+        for (let i = 0; i < n; i++) {
+          const world = worlds[i]!;
+          if (world.mounted.drivesOwnLoop) continue;
+          // D10/T7.6: a `pausable` world under an active (non-ignored) pause
+          // skips every phase except `render` — its render still runs, every
+          // substep, but with `dt` forced to `0` (deterministic: no
+          // time-based render effect silently keeps animating a "frozen"
+          // scene). A `pausable: false` world (or any world while
+          // `ignorePause`) is unaffected.
+          const frozen = !ignorePause && paused && world.pausable;
+          if (frozen && phase !== SystemPhase.RENDER) continue;
+          const phaseDt = frozen ? 0 : dt;
+          // Checklist item 2: isolate each world's per-phase work — one
+          // world's `runPhase` throwing must not starve sibling worlds still
+          // due this phase, nor abort the frame. Mirrors `runOne`'s style in
+          // `core/system-runner.ts` (loud console.error, never swallowed).
+          try {
+            world.frame?.runPhase(phase, phaseDt);
+          } catch (err) {
+            console.error(
+              `[game] world "${world.id}" (kind: ${world.kind}) runPhase("${phase}") threw:`,
+              err,
+            );
+          }
+        }
+      }
+      for (let i = 0; i < n; i++) {
+        const world = worlds[i]!;
+        if (world.mounted.drivesOwnLoop) continue;
+        // A fully-frozen world gets no `endFrame`/opaque-`update` call either —
+        // there is nothing to "end the frame" of when nothing ran this substep.
+        const frozen = !ignorePause && paused && world.pausable;
+        if (frozen) continue;
+        advanced = true;
+        if (world.frame) {
+          try {
+            world.frame.endFrame?.();
+          } catch (err) {
+            console.error(
+              `[game] world "${world.id}" (kind: ${world.kind}) endFrame() threw:`,
+              err,
+            );
+          }
+        } else {
+          // Checklist item 2: same isolation for the opaque-world fallback —
+          // one foreign mount's `update` throwing must not starve its
+          // siblings' `endFrame`/`update` calls this same loop.
+          try {
+            world.mounted.update?.(dt);
+          } catch (err) {
+            console.error(`[game] world "${world.id}" (kind: ${world.kind}) update() threw:`, err);
+          }
+        }
+      }
+    }
+
+    // T7.4 slice 1 (REACT-STATE-BRIDGE.md §2): bump + notify LAST, after
+    // every phase of every world and every world's endFrame/update above —
+    // subscribers must only ever observe post-frame state. Bumped at most
+    // once per completed `runFrame`/`step()` call, never per phase/world —
+    // and, per §7.1-11's fix, only when `advanced` (see above) is true: a
+    // fully-gated paused game produces no notifications at all.
+    if (advanced) stateBridge.bump();
+  }
+
+  return {
+    loop: opts.loop,
+    assets: opts.assets,
+    systems,
+    get worlds() {
+      return worlds;
+    },
+    world(id: string): WorldInstance | null {
+      return worlds.find((w) => w.id === id) ?? null;
+    },
+    get defaultWorld() {
+      return requireDefaultWorld();
+    },
+    get systemAdapters() {
+      return computeSystemAdapters();
+    },
+    get components() {
+      return requireFirstPartyCtx('components').components;
+    },
+    get input() {
+      return requireFirstPartyCtx('input').input;
+    },
+    get audio() {
+      return requireFirstPartyCtx('audio').audio;
+    },
+    state: stateBridge,
+    play: {
+      get paused() {
+        return paused;
+      },
+      pause() {
+        if (paused) return;
+        paused = true;
+        setWorldGates(true);
+      },
+      resume() {
+        if (!paused) return;
+        paused = false;
+        setWorldGates(false);
+      },
+      step(dt = 1 / 60) {
+        // Self-driven pausable worlds advance via their adapter's `step()`
+        // capability — but only the ones that are actually FROZEN: the game
+        // must be paused, and the world must have been gate-able in the
+        // first place (`setPaused` present — a world the gate couldn't reach
+        // never stopped, so "stepping" it would double-tick a still-running
+        // loop, the same §7.1-2 class as the host-driven fix below). While
+        // not paused, nothing here runs — step() is a whole-call no-op.
+        if (paused) {
+          for (const world of worlds) {
+            if (!world.pausable || !world.mounted.drivesOwnLoop) continue;
+            if (!world.mounted.setPaused) continue; // never gated — still running
+            if (world.mounted.step) {
+              world.mounted.step();
+            } else {
+              reportGateShortfallOnce(
+                'loop',
+                world.id,
+                'self-driven world, adapter declares no step capability',
+              );
+            }
+          }
+        }
+        // §7.1-2 fix (probe4): tick EXACTLY the frozen (host-driven, pausable,
+        // paused) set — not `{ ignorePause: true }`, which re-ran a FULL
+        // extra frame for every host-driven world (including already-running
+        // `pausable: false` ones — a double-tick, since D10's ordinary loop
+        // never stops ticking them). See `runFrameImpl`'s `onlyFrozen` mode.
+        runFrameImpl(dt, { onlyFrozen: true });
+      },
+    },
+    queryByComponent<T extends GameComponent<WorldKind>>(
+      cls: new () => T,
+      opts?: { worldId?: string; kind?: WorldKind },
+    ): T[] {
+      // Checklist item 8a: a `worldId` naming a world that doesn't exist is a
+      // caller error (typo'd id, wrong manifest) — degrade loudly, matching
+      // repo habit, rather than silently returning `[]`. A worldId that DOES
+      // exist but isn't first-party legitimately answers "no components"
+      // below (the loop's `!isFirstPartyMounted` `continue`), which stays
+      // silent — that's a real, not a mistaken, empty result.
+      if (opts?.worldId !== undefined && !worlds.some((w) => w.id === opts.worldId)) {
+        throw new Error(`Game.queryByComponent: unknown worldId "${opts.worldId}"`);
+      }
+      const result: T[] = [];
+      for (const world of worlds) {
+        if (!isFirstPartyMounted(world.mounted)) continue;
+        if (opts?.worldId !== undefined && world.id !== opts.worldId) continue;
+        if (opts?.kind !== undefined && world.kind !== opts.kind) continue;
+        // Checklist item 8b: a plain for-loop push instead of
+        // `result.push(...arr)` — spread-as-arguments can hit engine/runtime
+        // argument-count limits once a world's instance count gets large.
+        const instances = world.mounted.ctx.components.queryByComponent(cls);
+        for (const inst of instances) result.push(inst);
+      }
+      return result;
+    },
+    registerWorld(world: WorldInstance): void {
+      if (worlds.some((w) => w.id === world.id)) {
+        throw new Error(`Game.registerWorld: duplicate world id "${world.id}"`);
+      }
+      // Checklist item 6: the SAME `mounted` object registered under two
+      // world ids would be double-ticked by `runFrame` (its `frame.runPhase`/
+      // `endFrame` called once per registration) and double-dispose-wrapped
+      // (`createWorldInstance` wraps `mounted.dispose` in place — a second
+      // wrap would flip `disposed` and call through on ITS OWN wrapped
+      // `originalDispose`, which is harmless today only by accident of
+      // `VgaiSceneGameAdapter.dispose` being idempotent; a foreign adapter
+      // has no such guarantee). Reject it outright instead.
+      if (worlds.some((w) => w.mounted === world.mounted)) {
+        throw new Error(
+          `Game.registerWorld: world "${world.id}" shares its \`mounted\` object with an ` +
+            `already-registered world ("${worlds.find((w) => w.mounted === world.mounted)!.id}") — ` +
+            'the same mount cannot be registered twice.',
+        );
+      }
+      worlds.push(world);
+      // T7.4 slice 2 (REACT-STATE-BRIDGE.md §4): a NON-first-party mount
+      // (an ingested/foreign world — first-party mounts are exempt, they're
+      // observed via `Game.state`/`useGameState` instead) with no `observe`
+      // has no state bridge at all — react HUDs cannot subscribe to it, and
+      // silently returning `undefined` forever would hide that. Report ONCE
+      // per mount, at registration time, matching this file's existing
+      // `[game] world "<id>" (kind: <kind>) ...` console idiom (see
+      // `runFrame` below).
+      //
+      // §7.1-15: a `kind: 'react'` world is ALSO exempt — it has no `observe`
+      // BY DESIGN (D8/REACT-WORLD-DESIGN.md: a react world's own mounted tree
+      // reads state via `Game.state`/`useGameState`, the SAME first-party
+      // bridge a threejs/pixijs world's HUD uses, never `WorldStateObserver`
+      // — that hook is scoped to the ingested/foreign-world case). Without
+      // this exemption every production react world logged a false-positive
+      // "no state bridge" warning at registration (probe: every real react
+      // world mount), eroding the signal for a genuinely un-observable
+      // ingested world.
+      if (!isFirstPartyMounted(world.mounted) && world.kind !== 'react' && !world.mounted.observe) {
+        console.warn(
+          `[game] world "${world.id}" (kind: ${world.kind}, adapter: "${world.adapter.id}"): ` +
+            'no state bridge — this mounted game has no `observe` (WorldStateObserver); ' +
+            'react HUDs/useWorldObservation cannot subscribe to its state (docs/REACT-STATE-BRIDGE.md §4).',
+        );
+      }
+    },
+    runFrame(dt: number, frameOpts?: { ignorePause?: boolean }): void {
+      runFrameImpl(dt, frameOpts);
+    },
+  };
+}