@vgai/engine 0.5.0-canary.20260719.0 → 0.5.0

package/dist/runtime/create-runtime.d.ts

@@ -0,0 +1,249 @@
+import * as THREE from 'three';
+import type { GameAdapter, MountedGame, MountedReactWorld } from '../adapter/game-adapter';
+import type { MountedGame2D, World2DHost } from '../world2d/pixi-game-adapter';
+import { type Game, type GameInternal, type WorldInstance } from './game';
+export { adoptSceneCamera } from '../adapter/vgai-scene-game-adapter';
+/**
+ * Register a threejs world onto the Game shell. `opts.id` defaults to
+ * `'main'` — the single-world callers (`createGameRuntime`, slice-1/2 tests)
+ * are unaffected; a second/third world (T7.1 slice 3's two-world proof, and
+ * real multi-world manifests later) pass an explicit id. This is the ONE
+ * registration code path for a threejs world, whatever its id.
+ */
+export declare function registerThreeWorld(game: GameInternal, adapter: GameAdapter, mounted: MountedGame, opts?: {
+    id?: string | undefined;
+    pausable?: boolean | undefined;
+}): WorldInstance;
+export declare function registerPixiWorld(game: GameInternal, adapter: Pixi2DGameAdapter, mounted: MountedGame2D, opts?: {
+    id?: string | undefined;
+    pausable?: boolean | undefined;
+}): WorldInstance;
+/**
+ * Register a react world onto the Game shell (T6.2 slice 1,
+ * `docs/REACT-WORLD-DESIGN.md` §1.B) — the react analog of
+ * {@link registerThreeWorld}/{@link registerPixiWorld}. A react world has no
+ * `ComponentManager` to adopt (D8: react entities host no GameComponents —
+ * there is nothing for `adoptWorld` to backfill, unlike the three/pixi
+ * siblings above) and no `frame` hooks (react's own `createRoot` schedules
+ * its commits; `GameInternal.runFrame` correctly leaves a world with no
+ * `frame` untouched by its opaque-`update` fallback too, since
+ * `MountedReactGame` declares no `update`). `adapter` is typed as the real
+ * {@link ReactRootAdapter} shape (T7.5, same reasoning as
+ * `registerPixiWorld`'s doc comment above) — `WorldInstance.adapter` only
+ * needs `.id`, so this passes through with zero cast.
+ */
+export declare function registerReactWorld(game: GameInternal, adapter: ReactRootAdapter, mounted: MountedReactGame, container: HTMLElement, opts?: {
+    id?: string | undefined;
+    pausable?: boolean | undefined;
+}): WorldInstance;
+/**
+ * A pixijs-shaped adapter — the structural contract `WorldMountSpec`'s
+ * `pixijs` variant requires. `PixiSceneGameAdapter` (`world2d/
+ * pixi-game-adapter.ts`) satisfies this today; it is deliberately NOT named
+ * here as a concrete type so an external pixi adapter can satisfy the same
+ * shape without importing the first-party implementer.
+ */
+export interface Pixi2DGameAdapter {
+    readonly id: string;
+    mount(host: World2DHost): Promise<MountedGame2D>;
+}
+/**
+ * One world to mount in the {@link WorldsRuntimeConfig} roots path (T6.1
+ * slice 1) — the host-facing mirror of `manifest/load.ts`'s
+ * `ResolvedAdapterRoot` (same `id`/`zOrder`/`pausable`/`loop` fields; the
+ * manifest-to-host translation itself is the editor's job, not this file's).
+ *
+ * `react` (T6.2 slice 1, `docs/REACT-WORLD-DESIGN.md`) mounts as a DOM-root
+ * layer `<div>` in the SAME stack instead of a canvas — see
+ * {@link ReactWorldMountSpec}/{@link ReactRootAdapter} below.
+ */
+export interface WorldMountSpecBase {
+    /** Manifest id — must be unique within one `roots` array. */
+    readonly id: string;
+    /** Canvas stacking order (COMPOSITION-DESIGN D5 §1); ties broken by array
+     *  order, mirroring `manifest/load.ts`'s `loadGameManifest` sort. Defaults
+     *  to `0`. */
+    readonly zOrder?: number | undefined;
+    /** Whether play-mode pause/step applies to this world (D10). Defaults to `true`. */
+    readonly pausable?: boolean | undefined;
+    /** `'gated'` (host-driven, default) or `'self-driven'` (this world drives
+     *  its own loop — D5's "composited, unsynchronized" tier). Carried through
+     *  for parity with `ResolvedAdapterRoot`; T6.1 slice 1 does not yet
+     *  validate it against the mounted adapter's actual `drivesOwnLoop` (that
+     *  cross-check, if ever needed, is T7.6's loop-gate surface). */
+    readonly loop?: 'gated' | 'self-driven' | undefined;
+    /**
+     * Optional claim predicate for the delegating input router (D5 §2a), over
+     * a point RELATIVE TO THE CONTAINER. Absent means: this world claims only
+     * if it ends up the bottom (lowest zOrder) world — see
+     * `input-router.ts`'s `resolveClaimingWorld`. A pixijs world with no
+     * explicit `hitTest` gets a REAL default derived from its own mounted
+     * stage's `EventBoundary.hitTest` (see `derivePixiHitTest` below) — a
+     * threejs world with no explicit `hitTest` gets no default (three has no
+     * cheap universal "is this pixel interactive" answer).
+     */
+    readonly hitTest?: ((x: number, y: number) => boolean) | undefined;
+}
+export interface ThreeWorldMountSpec extends WorldMountSpecBase {
+    readonly kind: 'threejs';
+    readonly adapter: GameAdapter;
+}
+export interface PixiWorldMountSpec extends WorldMountSpecBase {
+    readonly kind: 'pixijs';
+    readonly adapter: Pixi2DGameAdapter;
+}
+/**
+ * The host-facing surface handed to a {@link ReactRootAdapter}'s `mount`
+ * (T6.2 slice 1, `docs/REACT-WORLD-DESIGN.md` §1.B) — the react analog of
+ * {@link World2DHost}. `container` is the absolutely-positioned, z-ordered
+ * DOM-root layer `<div>` the host already created and stacked (same box/
+ * z-order rules as a canvas per COMPOSITION-DESIGN D5 §1) — the adapter's
+ * `mount` renders its react tree INTO this exact element via `createRoot`;
+ * it must never create its own root element (mirrors `HostContext`'s
+ * "the world's runtime renders into the surface it is handed" rule for
+ * canvases, `docs/GAME-ROOT-DESIGN.md` §2).
+ */
+export interface ReactWorldHost {
+    readonly container: HTMLElement;
+    /**
+     * The Game this world is being mounted into — symmetric with
+     * `HostContext.game`; what a react adapter hands to `<GameProvider>` so
+     * `useGameState` selectors read live state (T7.4 bridge).
+     *
+     * Optional as of D-V3 (docs/WAVE5-MULTIWORLD-INGEST-DESIGN.md, F24
+     * composite): a `default-react` sibling mounted BESIDE an ingest world
+     * (`packages/editor/src/ingest-siblings.ts`) has no native `Game` to hand
+     * it — there is no first-party `GameContext`/loop for the sibling to join,
+     * only the ingested world's own foreign runtime — so its host carries no
+     * `game` at all rather than fabricating an empty one (anti-shim rule); the
+     * sibling mounts its entry component bare, with no `<GameProvider>` wrap.
+     * `mountOneReactWorld` below (the NATIVE multi-world runtime path) still
+     * ALWAYS supplies a real `game` — this optionality is reached only by the
+     * composite sibling's own hand-built host, never by weakening the native
+     * path's guarantee.
+     */
+    readonly game?: Game;
+}
+/**
+ * A live, mounted react world (T6.2 slice 1) — the react analog of
+ * {@link MountedGame2D}. React roots host no ticking components (D8 —
+ * `ecs/component-manager.ts` already throws on any attach to a react-kind
+ * manager) and render from game state via the T7.4 bridge instead of a
+ * per-frame `update`, so this shape carries no `update`/`fixedUpdate`/
+ * `ctx`/`frame` — `drivesOwnLoop` is always `false` (react's `createRoot`
+ * schedules its OWN commits; the host's fixed-step loop never drives it,
+ * and it is correctly skipped by `GameInternal.runFrame`'s per-world
+ * `frame`-hooks/opaque-`update` dispatch — see `registerReactWorld` below,
+ * which registers this `WorldInstance` with no `frame`, same as any other
+ * opaque mount with nothing to tick).
+ *
+ * Deliberately carries NO `firstParty: true` brand: that brand specifically
+ * means "has a `.ctx: GameContext`" (`isFirstPartyMounted`,
+ * `runtime/game.ts`) — a react world has no Rapier/ComponentManager/
+ * GameContext at all, so branding it first-party would be a type lie.
+ * `Game.registerWorld`'s "no state bridge" console warning
+ * (`docs/REACT-STATE-BRIDGE.md` §4) explicitly exempts `kind: 'react'`
+ * (§7.1-15): a react world has no `observe` BY DESIGN — that hook is scoped
+ * to `useWorldObservation` (the ingested/foreign-world case), not
+ * `useGameState` (`ui/game-state.tsx`), which a react world's own mounted
+ * tree uses instead — it reads `Game.state` directly (T7.4's actual bridge
+ * for first-party-observable state), never a per-world `observe`.
+ *
+ * `kind`/`container` (T7.5) satisfy `MountedReactWorld` (`adapter/
+ * game-adapter.ts`) — `container` is the SAME `ReactWorldHost.container` the
+ * adapter's `mount` was handed (identity matters, mirroring `threeRoot()`/
+ * `pixiRoot()`'s "same instance the adapter mounted" contract); every
+ * `ReactRootAdapter` implementer echoes it back here so `mounted` alone
+ * (with no separately-threaded `container`) satisfies the union
+ * `WorldInstanceInit.mounted`/`WorldInstance.mounted` with zero cast.
+ */
+export interface MountedReactGame extends MountedReactWorld {
+    readonly drivesOwnLoop: false;
+}
+/**
+ * A react-shaped adapter — the structural contract `WorldMountSpec`'s
+ * `react` variant requires. Mirrors {@link Pixi2DGameAdapter}: deliberately
+ * NOT tied to a concrete implementer here so an editor-resolved adapter (the
+ * `default-react` resolver branch, T6.2's editor-side follow-up) can satisfy
+ * this shape without this file importing react-dom or any editor code.
+ */
+export interface ReactRootAdapter {
+    readonly id: string;
+    mount(host: ReactWorldHost): Promise<MountedReactGame>;
+}
+export interface ReactWorldMountSpec extends WorldMountSpecBase {
+    readonly kind: 'react';
+    readonly adapter: ReactRootAdapter;
+}
+export type WorldMountSpec = ThreeWorldMountSpec | PixiWorldMountSpec | ReactWorldMountSpec;
+/**
+ * Mount N adapter roots (threejs + pixijs + react)
+ * on ONE `Game`, stacked in `container` per COMPOSITION-DESIGN D5 §1.
+ * `roots[0]` participates in `Game.defaultWorld`'s existing "first threejs
+ * root, else first root" rule.
+ */
+export interface WorldsRuntimeConfig {
+    /** The host creates one absolutely-positioned surface per world inside
+     *  this element (D5 §1) — a canvas for threejs/pixijs, a DOM-root `<div>`
+     *  layer for react — plus one shared UI overlay above all of them. */
+    container: HTMLElement;
+    roots: WorldMountSpec[];
+    width?: number | undefined;
+    height?: number | undefined;
+    /**
+     * Mirrors `HostContext.headless` (Node conformance tests — no GPU): skips
+     * real `WebGLRenderer` construction for every threejs world in this
+     * session (a stand-in renderer is used instead, exactly as
+     * `VgaiSceneGameAdapter.mount` already special-cases `host.headless`
+     * internally). Pixijs roots are unaffected — Pixi already falls back to
+     * a 2D canvas renderer with no GPU. Never set `true` in a real host.
+     */
+    headless?: boolean | undefined;
+    /** D15 (T-D15.1) — the root seed `ctx.random` boots from on every world
+     *  mounted onto this session's Game, forwarded to `createGame` BEFORE any
+     *  world's `mount()`/`setup()` runs (this function constructs the Game
+     *  first — see `createWorldsGameRuntime`). The manifest-aware boot path
+     *  (`mount-manifest.ts`'s `mountManifestWorlds`) is the real caller that
+     *  resolves this from `manifest.determinism`/`?vgai-seed=`/its own
+     *  explicit-config leg; a caller building `WorldsRuntimeConfig` by hand
+     *  (a test, a bespoke host) may also set it directly. Omitting it falls
+     *  back to `createGame`'s own fixed default. */
+    seed?: number | undefined;
+}
+/**
+ * Handle returned by createGameRuntime() for controlling the running game.
+ *
+ * This is the GENERIC host handle — it has no first-party concepts (no
+ * `GameContext`, no `GameSetupFn`). First-party features (the live `GameContext`,
+ * warm-restart hot reload) are reached by casting `mounted` to `VgaiMountedGame`
+ * (the editor does this for HMR/physics-sync — those are inherently first-party).
+ *
+ * `scene`/`camera`/`mounted` alias the Game's `defaultWorld`: it is the first
+ * threejs root (else the first
+ * world) by DECLARATION order, per `Game.defaultWorld`'s existing rule —
+ * independent of `zOrder`/canvas stacking, which is a rendering-only concern.
+ */
+export interface GameSession {
+    stop(): void;
+    pause(): void;
+    resume(): void;
+    step(): void;
+    resize(width: number, height: number): void;
+    readonly scene: THREE.Scene;
+    readonly camera: THREE.PerspectiveCamera;
+    /** The mounted game (interface surface). Cast to `VgaiMountedGame` for first-party extras. */
+    readonly mounted: MountedGame;
+    /** The Game root (T6.1 slice 1) — the multi-world entry point
+     *  (`game.roots`/`game.world(id)`/`game.queryByComponent`) for callers
+     *  that need more than the default-world aliases above. */
+    readonly game: Game;
+}
+/**
+ * Bootstrap the game host and mount a game adapter.
+ *
+ * `createGameRuntime` is the universal HOST: it owns the root surfaces,
+ * renderers, loop, and asset cache. Every game — including a one-root game —
+ * uses the same explicit adapter-root path.
+ */
+export declare function createGameRuntime(config: WorldsRuntimeConfig): Promise<GameSession>;
+//# sourceMappingURL=create-runtime.d.ts.map

package/dist/runtime/create-runtime.d.ts.map

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