@vgai/engine 0.5.0 → 0.5.2

package/dist/runtime/game.d.ts

@@ -1,496 +0,0 @@
-/**
- * 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 roots path now mounts (see
- * `docs/REACT-WORLD-DESIGN.md` §1.B); react roots 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.
- */
-import type * as PIXI from 'pixi.js';
-import type * as THREE from 'three';
-import type { AdapterSurface as AdapterSurfaceLeaf } from '../adapter/adapter-surface';
-import type { MountedWorld } from '../adapter/game-adapter';
-import type { SystemAdapters } from '../adapter/system-adapter';
-import type { VgaiMountedGame } from '../adapter/vgai-scene-game-adapter';
-import type { AssetCache } from '../assets';
-import type { createGameLoop } from '../core/game-loop';
-import { type SystemRunner } from '../core/system-runner';
-import { type SystemPhaseName } from '../core/types';
-import { type PerformanceProfiler } from '../dev/performance-profiler';
-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';
-import type { Collision2DSystem } from '../world2d/collision-2d';
-import type { Physics2DRegistry } from '../world2d/physics2d-registry';
-import { type RunTicksOptions } from './debug-registry';
-import { 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 roots by one fixed substep: the
-     * `pausable`, host-driven (`!drivesOwnLoop`) roots 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'`
- * roots 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/adapter-surface.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 { AdapterSurface } from '../runtime/game'` call site
- * (`ecs/game-component.ts`, `ecs/component-manager.ts`) compiling unchanged.
- */
-export type AdapterSurface = AdapterSurfaceLeaf;
-/**
- * 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 roots 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: AdapterSurface;
-    /** 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 roots (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 roots (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 roots). */
-    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`, `ReactRootAdapter`, 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: AdapterSurface;
-    /** 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 declare function createWorldInstance(init: WorldInstanceInit): WorldInstance;
-/**
- * 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
- * roots 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 declare function isFirstPartyMounted(mounted: MountedWorld): mounted is VgaiMountedGame;
-/**
- * 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;
-    /** Per-game diagnostic store. Disabled by default; the editor enables it on demand. */
-    readonly profiler: PerformanceProfiler;
-    /**
-     * 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.roots`) observe
-     *  later registrations. */
-    readonly roots: 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 `roots` REGISTRATION
-     * order, first registration wins per key. A later world registering the
-     * SAME kind (e.g. two roots 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
-     * roots and all `endFrame` hooks (see `runFrame`'s tail below). This is
-     * the ONE subscription surface `useGameState`
-     * (`@vgai/engine/react/game-state`) — 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 `roots` 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<AdapterSurface>` (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<AdapterSurface>>(cls: new () => T, opts?: {
-        worldId?: string;
-        kind?: AdapterSurface;
-    }): 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 roots (declaration order):
-     *     if world.mounted.drivesOwnLoop: continue
-     *     world.frame?.runPhase(phase, dt)
-     * for world in roots:                       // 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;
-    /**
-     * D15/T-D15.3-.4 (`docs/D15-DETERMINISM-DESIGN.md` §2.b) — a deterministic
-     * fast-forward primitive: synchronously call the SAME per-tick pipeline
-     * `runFrame` uses, `n` times in a tight loop, with `dt` fixed to the host
-     * loop's own fixed timestep (`this.loop.fixedDt` — `core/game-loop.ts`).
-     * This generalizes `render-control.ts`'s proven `VgaiRenderHarness.
-     * simulateSubsteps` from the capture-only door (`?vgai-render=1`) to a
-     * Game-level primitive every door can reach (the bridge's
-     * `window.__vgai.runTicks`, the editor relay's `run-ticks` case →
-     * `play.runTicks`) — `simulateSubsteps` itself is UNTOUCHED by this
-     * addition (it may later delegate to this method; not this unit's job).
-     *
-     * Semantics:
-     * - **Decoupled from wall clock and the accumulator.** `runTicks` drives
-     *   `runFrame` DIRECTLY — it never goes through `GameLoop`'s own
-     *   accumulator/spiral-of-death drop path, so `n` ticks always advance
-     *   `tick`/`simT` by exactly `n`/`n * fixedDt`, on any hardware, regardless
-     *   of how slow or fast the call actually took wall-clock-wise. Single-
-     *   threaded-burst note: because JS has one thread, this synchronous burst
-     *   can never interleave with a real rAF frame — but if the host's own
-     *   loop is still running (`loop.start()`), wall-clock time keeps accruing
-     *   in ITS accumulator while this call executes; the NEXT rAF frame after
-     *   the burst sees that gap and the loop's existing `maxAccumulator` clamp
-     *   absorbs it exactly as it would absorb any other slow-frame gap (up to
-     *   8 substeps, additional time dropped) — `runTicks` does not need to
-     *   (and does not) touch the accumulator itself to make this safe.
-     * - **`opts.render`** (default `'last'`): `'last'` skips the `preRender`/
-     *   `render` phases for ticks `0..n-2` and runs the full phase list
-     *   (including `preRender`/`render`) on the final tick only — the GGPO
-     *   tick-without-render pattern. `'all'` renders every tick. `'none'`
-     *   never renders, not even the last tick. `tick`/`simT`/
-     *   `stateBridge.bump()`/the debug event ring advance identically on
-     *   EVERY tick regardless of `render` — only the paint-affecting phases
-     *   are skipped, so state watchers (`useGameState`, debug state providers)
-     *   stay correct even when fast-forwarding with no visible output.
-     * - **Refuses while paused.** Throws a structured `DebugError`
-     *   (`code: 'RUN_TICKS_PAUSED'`) if `Game.play.paused` is true —
-     *   `Game.play.step()` owns stepping the frozen set; `runTicks` is a
-     *   running-game primitive, not a paused-world stepper, and silently
-     *   no-op-ing or silently ignoring pause would violate the "byte-identical
-     *   across doors" contract this primitive exists to provide.
-     * - **Does not bypass the input focus gate.** Every tick's `input` phase
-     *   runs through the SAME `InputManager` every other call to `runFrame`
-     *   does — a gated virtual actuation (page unfocused, Game tab inactive)
-     *   still reports `{delivered: false, reason}` exactly as it would under
-     *   normal play; `runTicks` has no special-cased "force focus" behavior.
-     */
-    runTicks(n: number, opts?: RunTicksOptions): void;
-}
-/**
- * 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 `registerThreeWorld` in
- * `create-runtime.ts`).
- */
-export declare function createGame(opts: {
-    loop: GameLoop;
-    assets: AssetCache;
-    /** D15 (T-D15.1) — the root seed `ctx.random` boots from, on every world
-     *  mounted onto this Game. Defaults to `DEFAULT_SEEDED_RANDOM_SEED` (a
-     *  fixed, non-wall-clock constant — `ctx.random` is always reproducible
-     *  on its own terms, whether or not the project's manifest DECLARES that
-     *  reproducibility as a contract). The manifest-aware boot path
-     *  (`mount-manifest.ts`'s `mountManifestWorlds`) is what actually resolves
-     *  `manifest.determinism.defaultSeed`/`?vgai-seed=`/explicit config and
-     *  passes the result here, BEFORE any world's `mount()`/`setup()` runs —
-     *  `createGameRuntime` always constructs the Game (this call) first (see
-     *  this function's own doc comment below). */
-    seed?: number | undefined;
-}): GameInternal;
-//# sourceMappingURL=game.d.ts.map

package/dist/runtime/game.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"game.d.ts","sourceRoot":"","sources":["../../src/runtime/game.ts"],"names":[],"mappings":"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"}