@vgai/engine 0.5.0 → 0.5.2

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

@@ -1,249 +0,0 @@
-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

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