@vgai/engine 0.2.0 → 0.3.0

package/dist/runtime/render-seed.js

@@ -0,0 +1,74 @@
+/**
+ * Deterministic `Math.random` seeding for render-control mode (I2 AC,
+ * `docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md` §15 I2: "`Math.random`
+ * is deterministically seeded/stubbed page-wide before any game module
+ * executes").
+ *
+ * Deliberately a ZERO-IMPORT module (no `three`, no other engine file) so
+ * its own evaluation is instantaneous — a render-mode entry page loads this
+ * as its FIRST `<script type="module">` tag, before the tag that pulls in
+ * the actual game/runtime modules. Per the HTML module-script ordering
+ * rules, sibling `<script type="module">` tags without `async` execute in
+ * document order, and each one's own dependency graph (here, empty) is
+ * fully evaluated before the browser moves to the next tag — so calling
+ * {@link maybeInstallRenderModeRandom} from this module's importer, in a
+ * script tag placed before the game's own entry tag, guarantees every
+ * subsequent module's top-level code (and everything it does at runtime)
+ * observes the seeded generator, never the platform's real
+ * cryptographically-random `Math.random`.
+ *
+ * This module does not decide WHETHER to seed on its own (importing it has
+ * no side effect) — the caller decides, by calling
+ * {@link maybeInstallRenderModeRandom} (query-param gated) or
+ * {@link installDeterministicRandom} (unconditional) from a tiny bootstrap
+ * entry. See `packages/engine/e2e/fixture/render-seed-entry.ts` for the
+ * worked bootstrap this module is designed to be loaded from.
+ */
+/**
+ * mulberry32 — a small, fast, deterministic 32-bit PRNG. Not cryptographic;
+ * this is explicitly a determinism tool (reproducible capture), not a
+ * security primitive. Returns a function with the same call signature as
+ * `Math.random` (no arguments, `[0, 1)` float).
+ */
+export function createMulberry32(seed) {
+    let state = seed >>> 0;
+    return function mulberry32() {
+        state = (state + 0x6d2b79f5) | 0;
+        let t = state;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/**
+ * Replace the global `Math.random` with a seeded, deterministic generator.
+ * Idempotent to call more than once (each call re-seeds from scratch — the
+ * last call wins), which matters for HMR-style re-execution the same way
+ * `main.ts`'s `registerWorldKind` guard does elsewhere in this runtime.
+ */
+export function installDeterministicRandom(seed) {
+    Math.random = createMulberry32(seed);
+}
+/** Query-param name that opts a page into render-control mode (I2 AC 4: the
+ *  mode must be unavailable/protected in normal production gameplay unless
+ *  explicitly enabled). Shared with `render-control.ts`'s own production
+ *  guard so both checks agree on the same flag. */
+export const RENDER_MODE_QUERY_PARAM = 'vgai-render';
+/** Optional query param to pin a specific seed (default below when absent). */
+export const RENDER_SEED_QUERY_PARAM = 'vgai-seed';
+const DEFAULT_RENDER_SEED = 0x9e3779b9; // golden-ratio constant — an arbitrary but fixed default
+/**
+ * Seed `Math.random` iff the page's URL opts into render mode
+ * (`?vgai-render=1`), reading an optional `?vgai-seed=<int>` override.
+ * Returns whether it seeded, purely for the caller's own diagnostics/log —
+ * the bootstrap entry doesn't need to branch on it.
+ */
+export function maybeInstallRenderModeRandom(location = window.location) {
+    const params = new URLSearchParams(location.search);
+    if (params.get(RENDER_MODE_QUERY_PARAM) !== '1')
+        return false;
+    const seedParam = params.get(RENDER_SEED_QUERY_PARAM);
+    const seed = seedParam !== null && seedParam !== '' ? Number(seedParam) : DEFAULT_RENDER_SEED;
+    installDeterministicRandom(Number.isFinite(seed) ? seed : DEFAULT_RENDER_SEED);
+    return true;
+}

package/dist/runtime/scene-ui-bridge.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Scene-UI render bridge (B1, widened design/24-scene-ui.md D3) — the injection
+ * seam that keeps the engine React-free.
+ *
+ * The engine knows the scene carries a `ui` tree (data), but it does NOT know how to
+ * render React. An editor-side module registers a renderer here (a thin wrapper over
+ * the React `mountSceneUI`); the first-party scene adapter calls it at game-time to
+ * mount the scene's UI into `host.ui` and disposes it on teardown. Fully decoupled:
+ * the engine treats `sceneUI` and the handle as opaque. The optional third `services`
+ * argument carries game-sourced data/components/events/projector (D2-D7) — still
+ * opaque to the engine, still zero React import here.
+ */
+/**
+ * Structural match for `@vgai/scene-ui`'s `UIDataSource` — engine stays React-free
+ * (this interface is duck-typed against the real one, not imported from it).
+ */
+export interface SceneUIDataSourceLike {
+    get(path: string): unknown;
+    set(path: string, value: unknown): void;
+    subscribe(listener: () => void): () => void;
+    version(): number;
+}
+/**
+ * Game-time services fed into a scene's UI mount (D2's "dynamic" layer). Every
+ * field is optional: a renderer falls back to its own registration-time registry
+ * (D2 merge rule) or built-in default when a field is absent. `components`/
+ * `transforms`/`strings` stay `unknown`-valued here — they're React things the
+ * scene-ui renderer casts to its real `UIComponentRegistry`/`TransformRegistry`/
+ * `StringTables`.
+ */
+export interface SceneUIGameServices {
+    /** Reactive game state the UI binds against (D4's `gameStateDataSource`, or a
+     *  game's own bus). Absent -> the renderer falls back to an empty static store. */
+    data?: SceneUIDataSourceLike;
+    /** `kind:"component"` leaf implementations, keyed by the name authored in the scene. */
+    components?: Record<string, unknown>;
+    /** Named binding transforms (`$bind.transform`). */
+    transforms?: Record<string, unknown>;
+    /** Localized string tables, keyed by locale then textKey. */
+    strings?: Record<string, Record<string, string>>;
+    locale?: string;
+    /** Routes a `kind:"button"` (etc.) `events.onClick` handler id to the game.
+     *  Absent -> a loud console.warn per event (D6 — no magic engine event bus). */
+    onEvent?: (handlerId: string, payload?: unknown) => void;
+    /** Projects an entity id to a screen-space point for world-tracked canvases
+     *  (D5). Returns null when the entity is unknown or behind the camera. */
+    worldProjector?: (entityId: string) => {
+        x: number;
+        y: number;
+    } | null;
+}
+export interface SceneUIHandle {
+    dispose(): void;
+    /** Re-render with new services without a remount (a late `setSceneUIServices`
+     *  call after the initial mount, D7). Optional — a renderer that can't update
+     *  in place may omit it; callers dispose+remount instead. */
+    update?(services: SceneUIGameServices): void;
+}
+/**
+ * Renderer signature — `sceneUI` is the scene's `ui` array (opaque to the engine).
+ * `services` is optional so existing 2-arg renderer functions keep working
+ * unchanged (back-compat, D3/D5 §5).
+ */
+export type SceneUIRenderer = (container: HTMLElement, sceneUI: unknown, services?: SceneUIGameServices) => SceneUIHandle;
+/** Register the React renderer (called once by the editor/runtime host). */
+export declare function setSceneUIRenderer(renderer: SceneUIRenderer | null): void;
+/** Render a scene's UI into `container` if a renderer is registered, else no-op. */
+export declare function renderSceneUI(container: HTMLElement, sceneUI: unknown, services?: SceneUIGameServices): SceneUIHandle | null;
+//# sourceMappingURL=scene-ui-bridge.d.ts.map

package/dist/runtime/scene-ui-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-ui-bridge.d.ts","sourceRoot":"","sources":["../../src/runtime/scene-ui-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACxC,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IAC5C,OAAO,IAAI,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC;uFACmF;IACnF,IAAI,CAAC,EAAE,qBAAqB,CAAC;IAC7B,wFAAwF;IACxF,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;oFACgF;IAChF,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACzD;8EAC0E;IAC1E,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACxE;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,IAAI,IAAI,CAAC;IAChB;;iEAE6D;IAC7D,MAAM,CAAC,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAAC;CAC9C;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,SAAS,EAAE,WAAW,EACtB,OAAO,EAAE,OAAO,EAChB,QAAQ,CAAC,EAAE,mBAAmB,KAC3B,aAAa,CAAC;AAInB,4EAA4E;AAC5E,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,GAAG,IAAI,CAEzE;AAED,oFAAoF;AACpF,wBAAgB,aAAa,CAC3B,SAAS,EAAE,WAAW,EACtB,OAAO,EAAE,OAAO,EAChB,QAAQ,CAAC,EAAE,mBAAmB,GAC7B,aAAa,GAAG,IAAI,CAGtB"}

package/dist/runtime/scene-ui-bridge.js

@@ -0,0 +1,23 @@
+/**
+ * Scene-UI render bridge (B1, widened design/24-scene-ui.md D3) — the injection
+ * seam that keeps the engine React-free.
+ *
+ * The engine knows the scene carries a `ui` tree (data), but it does NOT know how to
+ * render React. An editor-side module registers a renderer here (a thin wrapper over
+ * the React `mountSceneUI`); the first-party scene adapter calls it at game-time to
+ * mount the scene's UI into `host.ui` and disposes it on teardown. Fully decoupled:
+ * the engine treats `sceneUI` and the handle as opaque. The optional third `services`
+ * argument carries game-sourced data/components/events/projector (D2-D7) — still
+ * opaque to the engine, still zero React import here.
+ */
+let _renderer = null;
+/** Register the React renderer (called once by the editor/runtime host). */
+export function setSceneUIRenderer(renderer) {
+    _renderer = renderer;
+}
+/** Render a scene's UI into `container` if a renderer is registered, else no-op. */
+export function renderSceneUI(container, sceneUI, services) {
+    if (!_renderer || sceneUI == null)
+        return null;
+    return _renderer(container, sceneUI, services);
+}

package/dist/runtime/scene-ui-data.d.ts

@@ -0,0 +1,13 @@
+import type { ComponentRegistry } from '../scene/component-registry';
+import type { Game } from './game';
+import type { SceneUIDataSourceLike } from './scene-ui-bridge';
+/**
+ * Build the default `SceneUIDataSourceLike` over a game's live components.
+ *
+ * `subscribe`/`version` are driven by `game.state` (bumps once per completed
+ * frame, after every world's phases — see `state-bridge.ts`) PLUS a local
+ * bump on `set()`, so a two-way control's own write echoes immediately
+ * instead of waiting for the next frame.
+ */
+export declare function gameStateDataSource(game: Game, registry: ComponentRegistry): SceneUIDataSourceLike;
+//# sourceMappingURL=scene-ui-data.d.ts.map

package/dist/runtime/scene-ui-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-ui-data.d.ts","sourceRoot":"","sources":["../../src/runtime/scene-ui-data.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAiB/D;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,iBAAiB,GAC1B,qBAAqB,CAuEvB"}

package/dist/runtime/scene-ui-data.js

@@ -0,0 +1,92 @@
+function splitRoot(path) {
+    const dot = path.indexOf('.');
+    return dot === -1 ? [path, ''] : [path.slice(0, dot), path.slice(dot + 1)];
+}
+function readRest(obj, rest) {
+    if (!rest)
+        return obj;
+    let cur = obj;
+    for (const key of rest.split('.')) {
+        if (cur == null || typeof cur !== 'object')
+            return undefined;
+        cur = cur[key];
+    }
+    return cur;
+}
+/**
+ * Build the default `SceneUIDataSourceLike` over a game's live components.
+ *
+ * `subscribe`/`version` are driven by `game.state` (bumps once per completed
+ * frame, after every world's phases — see `state-bridge.ts`) PLUS a local
+ * bump on `set()`, so a two-way control's own write echoes immediately
+ * instead of waiting for the next frame.
+ */
+export function gameStateDataSource(game, registry) {
+    let version = 0;
+    const listeners = new Set();
+    // Warn-once-per-root-segment (D4/§9 review checklist): a scene author
+    // typo'ing a component name in a binding should be loud exactly once, not
+    // on every `get()` (a bound node re-reads its path every render).
+    const warnedRoots = new Set();
+    const notify = () => {
+        for (const listener of listeners)
+            listener();
+    };
+    /** Resolves a root segment to its live component instance, or undefined. */
+    const resolveInstance = (root) => {
+        const Klass = registry[root];
+        if (!Klass) {
+            if (!warnedRoots.has(root)) {
+                warnedRoots.add(root);
+                console.warn(`scene-ui: data binding root "${root}" is not a registered component name — ` +
+                    'check the binding source against src/scripts/registry.ts.');
+            }
+            return undefined;
+        }
+        // Registered but zero live instances (e.g. not spawned yet this scene) is
+        // an ordinary, expected transient state — stays undefined, no warning.
+        return game.queryByComponent(Klass)[0];
+    };
+    // ONE subscription to the frame-versioned state bridge for this data
+    // source's whole lifetime, fanning out to however many external
+    // subscribers this scene-UI mount has.
+    game.state.subscribe(() => {
+        version++;
+        notify();
+    });
+    return {
+        get(path) {
+            const [root, rest] = splitRoot(path);
+            const inst = resolveInstance(root);
+            return inst === undefined ? undefined : readRest(inst, rest);
+        },
+        set(path, value) {
+            const [root, rest] = splitRoot(path);
+            const inst = resolveInstance(root);
+            if (inst === undefined || !rest)
+                return;
+            const keys = rest.split('.');
+            let cur = inst;
+            for (let i = 0; i < keys.length - 1; i++) {
+                const key = keys[i];
+                const next = cur[key];
+                if (next == null || typeof next !== 'object')
+                    return; // don't invent nested fields on a live instance
+                cur = next;
+            }
+            cur[keys[keys.length - 1]] = value;
+            // Two-way writes echo immediately, not on the next frame (D4).
+            version++;
+            notify();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        version() {
+            return version;
+        },
+    };
+}

package/dist/runtime/state-bridge.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Frame-versioned game state bridge (T7.4 slice 1 — `docs/REACT-STATE-BRIDGE.md`
+ * §2, the D7 remainder). Components mutate state on `this` freely during
+ * ticks — there is no proxy, no dirty tracking, no event per mutation (Track
+ * A: no mirror, no sync layer). So the unit of change a subscriber can
+ * observe is the FRAME: `GameInternal.runFrame` bumps `frameVersion` and
+ * notifies subscribers at most once, at its tail, AFTER every phase of every
+ * world and every world's `endFrame` hook has run (see the wiring in
+ * `runtime/game.ts`) — mirroring the D7 "from `gameLogic` onward, every
+ * world's post-step state is readable" guarantee, extended to "after the
+ * frame, ALL state is readable".
+ *
+ * This file is plain, react-free TypeScript any consumer could use — no
+ * react import here, or anywhere under `runtime/` (the react-facing
+ * `useGameState` hook, which DOES import react, is deliberately colocated
+ * with the `mountUI` seam instead — see `packages/editor/template/src/
+ * ui/game-state.tsx`).
+ */
+/** Frame-versioned, react-free subscription surface — `docs/REACT-STATE-BRIDGE.md` §2. */
+export interface GameStateBridge {
+    /** Monotonic; bumped once per completed `runFrame`. Starts at 0 before the
+     *  first frame has ever completed. */
+    readonly frameVersion: number;
+    /** Notified at most once per frame, after ALL phases of ALL worlds (and
+     *  their `endFrame` hooks) have run. Returns an unsubscribe function. */
+    subscribe(onFrame: () => void): () => void;
+}
+/** Host-internal extension of {@link GameStateBridge}: adds `bump`, the
+ *  method `GameInternal.runFrame` calls at its tail. NOT part of the
+ *  game-facing `Game.state` surface (typed as the narrower
+ *  `GameStateBridge` there) — games/components/hooks never call `bump`
+ *  directly; only the frame executor does. */
+export interface GameStateBridgeInternal extends GameStateBridge {
+    /** Bump `frameVersion` by one and notify every current subscriber, in
+     *  subscription order. Subscriber errors are isolated (per-subscriber
+     *  try/catch, loud `console.error`, never swallowed silently) — mirrors
+     *  the error-isolation idiom in `ecs/component-manager.ts`'s per-component
+     *  `update()` calls: one offending subscriber must not stop its siblings
+     *  from being notified, and must not break the frame loop. */
+    bump(): void;
+}
+/**
+ * Construct a fresh bridge. One per `Game` (created alongside the other
+ * game-scoped state in `createGame`, `runtime/game.ts`).
+ */
+export declare function createStateBridge(): GameStateBridgeInternal;
+//# sourceMappingURL=state-bridge.d.ts.map

package/dist/runtime/state-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-bridge.d.ts","sourceRoot":"","sources":["../../src/runtime/state-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,0FAA0F;AAC1F,MAAM,WAAW,eAAe;IAC9B;0CACsC;IACtC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;6EACyE;IACzE,SAAS,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;CAC5C;AAED;;;;8CAI8C;AAC9C,MAAM,WAAW,uBAAwB,SAAQ,eAAe;IAC9D;;;;;kEAK8D;IAC9D,IAAI,IAAI,IAAI,CAAC;CACd;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,uBAAuB,CA8B3D"}

package/dist/runtime/state-bridge.js

@@ -0,0 +1,53 @@
+/**
+ * Frame-versioned game state bridge (T7.4 slice 1 — `docs/REACT-STATE-BRIDGE.md`
+ * §2, the D7 remainder). Components mutate state on `this` freely during
+ * ticks — there is no proxy, no dirty tracking, no event per mutation (Track
+ * A: no mirror, no sync layer). So the unit of change a subscriber can
+ * observe is the FRAME: `GameInternal.runFrame` bumps `frameVersion` and
+ * notifies subscribers at most once, at its tail, AFTER every phase of every
+ * world and every world's `endFrame` hook has run (see the wiring in
+ * `runtime/game.ts`) — mirroring the D7 "from `gameLogic` onward, every
+ * world's post-step state is readable" guarantee, extended to "after the
+ * frame, ALL state is readable".
+ *
+ * This file is plain, react-free TypeScript any consumer could use — no
+ * react import here, or anywhere under `runtime/` (the react-facing
+ * `useGameState` hook, which DOES import react, is deliberately colocated
+ * with the `mountUI` seam instead — see `packages/editor/template/src/
+ * ui/game-state.tsx`).
+ */
+/**
+ * Construct a fresh bridge. One per `Game` (created alongside the other
+ * game-scoped state in `createGame`, `runtime/game.ts`).
+ */
+export function createStateBridge() {
+    let frameVersion = 0;
+    const subscribers = new Set();
+    return {
+        get frameVersion() {
+            return frameVersion;
+        },
+        subscribe(onFrame) {
+            subscribers.add(onFrame);
+            return () => {
+                subscribers.delete(onFrame);
+            };
+        },
+        bump() {
+            frameVersion++;
+            // Snapshot before iterating (same idiom as ComponentManager's
+            // per-phase `list = byPhase.get(phase)!.slice()`): a subscriber that
+            // subscribes/unsubscribes from WITHIN a notification must not affect
+            // which of ITS SIBLINGS get notified this same bump.
+            const notified = Array.from(subscribers);
+            for (const onFrame of notified) {
+                try {
+                    onFrame();
+                }
+                catch (err) {
+                    console.error('[state-bridge] subscriber threw:', err);
+                }
+            }
+        },
+    };
+}

package/dist/runtime/types.d.ts

@@ -0,0 +1,179 @@
+import type RAPIER from '@dimforge/rapier3d-compat';
+import type { EffectComposer } from 'postprocessing';
+import type * as THREE from 'three';
+import type { SystemAdapters } from '../adapter/system-adapter';
+import type { AssetCache } from '../assets';
+import type { createSystemRunner } from '../core/system-runner';
+import type { createDebugDraw } from '../dev/debug-draw';
+import type { ComponentManager } from '../ecs/component-manager';
+import type { InputManager } from '../input/input-manager';
+import type { CollisionSystem } from '../physics/collision-system';
+import type { PhysicsRegistry } from '../physics/physics-registry';
+import type { SceneFile } from '../scene/scene-types';
+import type { AudioContext as GameAudio } from '../setup/setup-audio';
+import type { ParticlesContext } from '../setup/setup-particles';
+import type { Game, WorldInstance } from './game';
+import type { SceneUIGameServices } from './scene-ui-bridge';
+/**
+ * All engine subsystems, passed to every game `setup(ctx)` and to each
+ * GameComponent lifecycle method (`init`/`update`/`dispose`/trigger callbacks).
+ *
+ * The surface is intentionally split in two:
+ *
+ * - **Raw libraries** — the actual Three.js / Rapier / postprocessing objects.
+ *   Call their documented APIs directly; do NOT build wrappers around them.
+ * - **Engine handles** — thin VGAI-owned managers that bridge those libraries
+ *   into the phase-ordered game loop. Reach for these when you need behavior the
+ *   raw library doesn't provide (physics↔Object3D mapping, system phases, etc.).
+ */
+export interface GameContext {
+    /** Three.js scene graph root. Add/remove any `Object3D` (meshes, lights,
+     *  groups) here. This is THE scene — there is no separate engine scene. */
+    scene: THREE.Scene;
+    /** The single render camera. Move/aim it directly, or (preferred) drive it
+     *  from a camera GameComponent — see the camera-precedence note below. */
+    camera: THREE.PerspectiveCamera;
+    /** The Rapier physics `World`. Step/query it, create bodies & colliders via
+     *  `ctx.rapier`. One shared world for the whole scene. */
+    rapierWorld: RAPIER.World;
+    /** The Rapier module namespace itself (`RigidBodyDesc`, `ColliderDesc`,
+     *  `Vector3`, enums, …). Use to construct physics descriptors. */
+    rapier: typeof RAPIER;
+    /** The `postprocessing` EffectComposer driving the final render. Use to
+     *  add/remove passes (bloom, vignette, …) or reach the underlying
+     *  `WebGLRenderer` via `composer.getRenderer()`. */
+    composer: EffectComposer;
+    /** Keyboard/mouse/gamepad input. Polled once per frame in the `input` phase;
+     *  read action/axis state inside your `update`. */
+    input: InputManager;
+    /** Rapier collision-event dispatcher. Register handlers with
+     *  `collisions.onCollision(...)`; it is drained each `postPhysics`. Prefer a
+     *  GameComponent's `onTriggerEnter/Exit` for per-entity sensor logic. */
+    collisions: CollisionSystem;
+    /** `Object3D ↔ Rapier body/collider` registry (+ collider→Object3D reverse
+     *  index). Use to find an entity's body/collider, or the entity behind a
+     *  raw collision. Inside a component, `this.rigidBody`/`this.collider` are
+     *  pre-resolved from here. */
+    physics: PhysicsRegistry;
+    /** Procedural audio: master gain, listener, and one-shot/impact helpers.
+     *  Use for SFX and music; the listener tracks the camera. */
+    audio: GameAudio;
+    /** three.quarks particle system: the batched renderer + spawn helpers. Use
+     *  to emit runtime particle effects; declarative scene particles register
+     *  here automatically. */
+    particles: ParticlesContext;
+    /** Immediate-mode debug drawing (`line`/`box`/`sphere`/`arrow`). Drawn
+     *  objects persist until you call `debugDraw.clear()` yourself (the
+     *  adapter also clears on scene dispose/hot-reload) — nothing clears it
+     *  automatically per frame. Dev-only visualization — not for shipped
+     *  visuals. */
+    debugDraw: ReturnType<typeof createDebugDraw>;
+    /** Shared GLTF/texture cache. Use `assets.loadGLTF(...)` etc. to load+cache
+     *  models at runtime so repeated loads reuse geometry/material. */
+    assets: AssetCache;
+    /** The phase-ordered system runner. `systems.add(phase, fn)` registers a
+     *  per-frame callback. Reserve this for non-gameplay infra (audio mixers,
+     *  network send); per-entity GAMEPLAY belongs in a GameComponent. */
+    systems: ReturnType<typeof createSystemRunner>;
+    /** Manager for all live GameComponent instances (attach/detach/HMR). The
+     *  scene loader drives this; gameplay code rarely touches it directly. */
+    components: ComponentManager;
+    /** DOM element overlaying the canvas for game UI (React via `mountUI`, or
+     *  vanilla). `pointer-events:none` by default — set `auto` on interactive
+     *  elements. Cleared on scene switch / hot-reload. */
+    uiContainer: HTMLDivElement;
+    /** Register a game-owned `SystemAdapters` capability (networking,
+     *  navigation, …) on the mounted game's adapter surface, so the editor's
+     *  introspection panels (via `getActiveSystems()`) can see it. The engine
+     *  wires the first-party physics/input/assets/animation entries itself;
+     *  capabilities the GAME owns (a Colyseus connection, a NavMeshManager)
+     *  are registered here by the game's setup. Optional capability — absent
+     *  in contexts that expose no adapter surface (some test harnesses);
+     *  call as `ctx.registerSystemAdapter?.(…)`.
+     *
+     *  Ordering contract: **game registrations always win** — the engine seeds
+     *  its first-party entries (physics/input/assets/animation) BEFORE setup()
+     *  runs, so a game that registers any of those same kinds during its own
+     *  setup overrides the engine's entry, not the other way around. This also
+     *  holds across a warm restart (`hotReload`): every kind the outgoing game
+     *  registered is stripped back to the engine's entry (or absent, for
+     *  game-only kinds like networking/navigation) before the incoming game's
+     *  setup runs, so a disposed game's adapter is never left stale on the
+     *  mounted surface. */
+    registerSystemAdapter?<K extends keyof SystemAdapters>(kind: K, adapter: SystemAdapters[K]): void;
+    /**
+     * Register (or replace) this game's scene-UI game-time services — the data
+     * source, custom onEvent handler, and/or worldProjector overrides a scene's
+     * authored UI mounts against (design/24-scene-ui.md D2/D7). Optional, same
+     * precedent as `registerSystemAdapter`: absent in contexts with no scene-UI
+     * surface at all (bare test harnesses).
+     *
+     * Timing is safe by construction: the scene loader awaits
+     * `componentManager.initAll()` before `loadScene`/`loadSceneFromData`
+     * return, and the adapter mounts scene UI only after that — so calling this
+     * from a `GameComponent.init()` always beats the mount (its services are
+     * folded into the FIRST render, not a late update). A call AFTER the mount
+     * (e.g. from a click handler) updates the live mount in place instead
+     * (`SceneUIHandle.update`, or a dispose+remount if the renderer has none).
+     *
+     * Per-key merge (D2): a key set here always wins over both the project's
+     * registration-time registry and the engine's own D4/D5/D6 defaults. Hot
+     * reload strips every game-registered key back to none before the incoming
+     * game's `init()` runs — same contract as `registerSystemAdapter`'s re-seed.
+     */
+    setSceneUIServices?(services: SceneUIGameServices): void;
+    /** The Game root — the loop, the world registry, and game-scoped handles.
+     *  Absent only in bare test harnesses that construct a partial context (the
+     *  host always sets it in `createGameRuntime`). Optional so every existing
+     *  harness that builds a hand-rolled `ctx` object keeps compiling
+     *  unmodified — the same precedent as `registerSystemAdapter`. */
+    game?: Game | undefined;
+    /** Alias for `game.worlds` — the live, declaration-ordered world registry.
+     *  Same optionality/absence rule as `game` above. */
+    worlds?: ReadonlyArray<WorldInstance> | undefined;
+}
+/** Return value from a game setup function. */
+export interface GameCleanup {
+    dispose: () => void;
+}
+/** Context passed to setup() when launched from the editor's play mode. */
+export interface EditorPreview {
+    /** Path of the .vscn.json file the user has open (null if unsaved). */
+    scenePath: string | null;
+    /** The editor's in-memory scene document, including unsaved edits. */
+    sceneData: SceneFile;
+    /** Editor viewport camera transform — use this as the initial game camera viewpoint. */
+    viewportCamera?: {
+        position: [number, number, number];
+        quaternion: [number, number, number, number];
+    };
+    /**
+     * Which bundled example the static/browser build's project picker wants to
+     * run (docs/EXAMPLES-AS-PROJECTS-DESIGN.md §4 — Adjudication H). Only
+     * meaningful to `packages/editor/src/browser-play-entry.ts`'s dispatch over
+     * the generated `SETUP_BY_EXAMPLE_ID` table; every other `GameSetupFn`
+     * consumer ignores it. Undefined ⇒ the generic scene-loader fallback
+     * (today's only reachable behavior — no caller sets this yet, since the
+     * picker itself is a later wave).
+     */
+    exampleId?: string | undefined;
+    /**
+     * Asset prefix for the static/browser build's GENERIC scene-loader fallback,
+     * set INSTEAD of `exampleId` when the editor has a non-default scene of a
+     * bundled example open (hosted `?project=<id>&scene=<project-relative>` —
+     * Track H): the open scene plays via `sceneData`, but its relative asset
+     * refs still live under the example's staged `/examples/<id>/` public root.
+     * Ignored whenever `exampleId` is set; undefined ⇒ root prefix `/`.
+     */
+    assetPrefix?: string | undefined;
+}
+/** A game setup function: receives engine context, returns cleanup.
+ *
+ * This is the MOUNT body of the FIRST-PARTY implementer. The host no longer
+ * depends on it — the host depends on `GameAdapter` (`@engine/adapter`), and
+ * `GameSetupFn` is wrapped into a `VgaiSceneGameAdapter` via `fromSetup`. See
+ * docs/ADAPTER-ARCHITECTURE.md. (The former `GameAdapter` `{ setup, components }`
+ * interface lived here; it is superseded by the real adapter interfaces in
+ * `@engine/adapter`.) */
+export type GameSetupFn = (ctx: GameContext, editor?: EditorPreview) => Promise<GameCleanup>;
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/runtime/types.js

@@ -0,0 +1 @@
+export {};