@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/core/detached-surface.js

@@ -0,0 +1,104 @@
+/**
+ * The surface behind `createGame({ overlay: false })` (ws/core-9): the letterbox maths of
+ * `Surface` on a virtual container, with no canvas, no root element and no DOM listener. The
+ * container is the design size until `resizeContainer` changes it, at a pixel ratio of 1, so
+ * client px are design px by default. Internal: it implements the `Surface` interface with no
+ * cast (ws/platform-surface), and `ctx.surface` is typed `Surface`; reading its `root` or
+ * `canvas` throws.
+ */
+import { clientToLogical, computeBackbuffer, computeLetterbox, logicalToClient, } from '../platform/index.js';
+export class DetachedSurface {
+    logicalWidth;
+    logicalHeight;
+    rect = { x: 0, y: 0, width: 0, height: 0, scale: 0 };
+    fitRect = { x: 0, y: 0, width: 0, height: 0, scale: 0 };
+    backbuffer = { width: 1, height: 1, pixelRatio: 1 };
+    containerW;
+    containerH;
+    frame = null;
+    maxDpr;
+    maxPixels;
+    listeners = new Set();
+    constructor(opts = {}) {
+        this.logicalWidth = opts.logicalWidth ?? 1920;
+        this.logicalHeight = opts.logicalHeight ?? 1080;
+        this.maxDpr = opts.maxDpr ?? 2;
+        this.maxPixels = opts.maxPixels ?? 2560 * 1440;
+        this.containerW = this.logicalWidth;
+        this.containerH = this.logicalHeight;
+        this.layout();
+    }
+    get root() {
+        throw new Error(NO_DOM('ctx.surface.root'));
+    }
+    get canvas() {
+        throw new Error(NO_DOM('ctx.surface.canvas'));
+    }
+    /** The virtual container's size in CSS px (a test's viewport); lays out again at once. */
+    resizeContainer(width, height) {
+        this.containerW = width;
+        this.containerH = height;
+        this.layout();
+    }
+    onResize(fn) {
+        this.listeners.add(fn);
+        fn({ rect: this.rect, backbuffer: this.backbuffer });
+        return () => this.listeners.delete(fn);
+    }
+    /** The container sits at the client origin, so client coordinates are container ones. */
+    clientToLogical(clientX, clientY, out) {
+        return clientToLogical(this.rect, this.logicalWidth, this.logicalHeight, clientX, clientY, out);
+    }
+    logicalToClient(x, y, out) {
+        return logicalToClient(this.rect, this.logicalWidth, this.logicalHeight, x, y, out);
+    }
+    containsLogical(p) {
+        return p.x >= 0 && p.y >= 0 && p.x <= this.logicalWidth && p.y <= this.logicalHeight;
+    }
+    setFrame(frame) {
+        const f = this.frame;
+        if (f === frame ||
+            (f &&
+                frame &&
+                f.x === frame.x &&
+                f.y === frame.y &&
+                f.width === frame.width &&
+                f.height === frame.height))
+            return;
+        this.frame = frame
+            ? { x: frame.x, y: frame.y, width: frame.width, height: frame.height }
+            : null;
+        this.layout();
+    }
+    layout() {
+        const cw = this.containerW;
+        const ch = this.containerH;
+        this.fitRect = computeLetterbox(cw, ch, this.logicalWidth, this.logicalHeight);
+        const fr = this.frame;
+        const w = fr ? Math.max(1, Math.min(fr.width, cw)) : cw;
+        const h = fr ? Math.max(1, Math.min(fr.height, ch)) : ch;
+        let rect = fr ? computeLetterbox(w, h, this.logicalWidth, this.logicalHeight) : this.fitRect;
+        if (fr)
+            rect = { ...rect, x: rect.x + fr.x, y: rect.y + fr.y };
+        const bb = computeBackbuffer(rect.width, rect.height, 1, this.maxDpr, this.maxPixels);
+        const r = this.rect;
+        const b = this.backbuffer;
+        if (rect.x === r.x &&
+            rect.y === r.y &&
+            rect.width === r.width &&
+            rect.height === r.height &&
+            bb.width === b.width &&
+            bb.height === b.height)
+            return;
+        this.rect = rect;
+        this.backbuffer = bb;
+        const size = { rect, backbuffer: bb };
+        for (const fn of this.listeners)
+            fn(size);
+    }
+    destroy() {
+        this.listeners.clear();
+    }
+}
+/** The error a DOM-only member throws with `overlay: false`. */
+export const NO_DOM = (what) => `${what}: this game was created with \`overlay: false\`, which has no overlay and no DOM`;

package/dist/core/events.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Tiny typed event emitter.
+ *
+ * ```ts
+ * const bus = new Emitter<{ resize: { w: number; h: number }; tick: undefined }>();
+ * const off = bus.on('resize', ({ w }) => ...);
+ * bus.emit('resize', { w: 1, h: 2 });
+ * ```
+ *
+ * Listener arrays are copy-on-write, so `emit` never allocates and listeners may safely
+ * subscribe/unsubscribe during dispatch (changes apply from the next emit).
+ */
+export type EventMap = Record<string, any>;
+type Listener<T> = (payload: T) => void;
+export declare class Emitter<M extends EventMap> {
+    private readonly map;
+    on<K extends keyof M>(type: K, fn: Listener<M[K]>): () => void;
+    once<K extends keyof M>(type: K, fn: Listener<M[K]>): () => void;
+    off<K extends keyof M>(type: K, fn: Listener<M[K]>): void;
+    emit<K extends keyof M>(type: K, ...payload: M[K] extends void ? [] : [M[K]]): void;
+    listenerCount(type: keyof M): number;
+    clear(): void;
+}
+export {};

package/dist/core/events.js

@@ -0,0 +1,43 @@
+export class Emitter {
+    map = new Map();
+    on(type, fn) {
+        const prev = this.map.get(type) ?? [];
+        this.map.set(type, [...prev, fn]);
+        return () => this.off(type, fn);
+    }
+    once(type, fn) {
+        const off = this.on(type, (p) => {
+            off();
+            fn(p);
+        });
+        return off;
+    }
+    off(type, fn) {
+        const prev = this.map.get(type);
+        if (!prev)
+            return;
+        const i = prev.indexOf(fn);
+        if (i < 0)
+            return;
+        const next = prev.slice();
+        next.splice(i, 1);
+        if (next.length)
+            this.map.set(type, next);
+        else
+            this.map.delete(type);
+    }
+    emit(type, ...payload) {
+        const list = this.map.get(type);
+        if (!list)
+            return;
+        const p = payload[0];
+        for (let i = 0; i < list.length; i++)
+            list[i](p);
+    }
+    listenerCount(type) {
+        return this.map.get(type)?.length ?? 0;
+    }
+    clear() {
+        this.map.clear();
+    }
+}

package/dist/core/game.d.ts

@@ -0,0 +1,409 @@
+/// <reference path="../platform/xr-types.d.ts" preserve="true" />
+/**
+ * `createGame` (D-041 Phase 1): the noun-free wiring every ThunderClap game starts from.
+ *
+ * It blocks browser zoom, boots WebGPU on a letterboxed surface and builds, in this order:
+ * renderer, post stack, particles, host, the game's save (if any), overlay and pad navigation,
+ * audio (mixer persisted through the host), the game's tick clock, input with its gestures (on
+ * that clock) and pointer router, the scene stack and the frame loop (frames come from the
+ * host). It also wires the page lifecycle (hide, pagehide and freeze stop frames and flush the
+ * save; show resumes), the host's app lifecycle (`background` stops frames and flushes the save,
+ * `active` resumes) and device loss (the reload screen, then loop, audio and captions halt for
+ * good).
+ *
+ * The surface letterboxes the design space; what the overlay's layout leaves free of UI is
+ * `ctx.ui.layout.freeRect`, and a 2D game frames its world into it with
+ * `ctx.camera.fitFreeRect(worldRect, ctx.ui.layout.freeRect, ctx.surface)`. Scenes draw through
+ * `ctx.camera` (`Scene.render(frame, camera, alpha)`); the loop calls
+ * `renderer.render(frame, ctx.camera)` once per frame.
+ *
+ * Two parts are opt-in, so a pure client of a server-authoritative game (VISION pillar 6) uses
+ * the same wiring: `save` (omit it and `ctx.save` is null, and nothing touches `host.storage`)
+ * and the fixed-step sim (`sim: false` runs the loop at render rate, `hooks.frame` each frame).
+ *
+ * Games add their nouns by extending the returned object (`Object.assign(ctx, { ... })`): the
+ * scene stack hands scenes this same object, so a scene typed against the game's own ctx sees
+ * them. Game logic plugs into the frame and the lifecycle through `ctx.hooks`.
+ *
+ * Headless (ws/core-8): given `gpu` (a fake device in a test) `createGame` skips the WebGPU
+ * boot and its fatal screens and mounts the surface without a GPU canvas context; with `clock`
+ * the game runs on that tick clock and with `host` on that host's frames. `root` may then be
+ * left out. The overlay still needs a DOM (happy-dom in Vitest). `@thunderclap-engine/engine/testing`
+ * `createTestGame` wires the fakes in.
+ *
+ * VR is one call (`ctx.xr.enter()`, ws/xr): frames then come from the session through an XR
+ * host, the scenes record once through the surface's head camera and the renderer draws each
+ * eye into the surface's HDR scene target and resolves it through the post stack into the
+ * session's layer (ws/xr-post); controllers and hands join `ctx.pointers`. Leaving (`exit()` or
+ * the session ending) puts everything back; a game that never enters runs the same code as before.
+ */
+import { AudioEngine } from '../audio/index.js';
+import { ParticleSystem, type ParticleSystemOptions } from '../fx/index.js';
+import { type Host, type HostLifecycleState } from '../host/index.js';
+import { type Bindings, type GamepadLike, type Gestures, type HitTester, Input, type InputPlayback, type InputPlaybackOptions, type InputRecording, type MagnifyOptions, type PointerRouter, type TickClock } from '../input/index.js';
+import { type GpuContext, type Surface, type SurfaceOptions, XrSurface } from '../platform/index.js';
+import { type PostSettingsPatch, PostStack } from '../post/index.js';
+import { type Camera, type Frame, Renderer, type SceneTargetAux } from '../render/index.js';
+import { type LayoutSpec, type Overlay, PadNav, type ThemeOverrides } from '../ui/index.js';
+import type { Time } from './loop.js';
+import { GameLoop } from './loop.js';
+import { SceneStack } from './scene.js';
+/**
+ * What `createGame` needs from a game's save: it is flushed on hide (and `host.lifecycle`
+ * going to `background`) and on device loss.
+ */
+export interface FlushableSave {
+    flush(): void;
+}
+/** Why the page is going away: `visibilitychange` to hidden, `pagehide` or `freeze`. */
+export type HideReason = 'hidden' | 'pagehide' | 'freeze';
+/** Why the page is back: `visibilitychange` to visible, `pageshow` or `resume`. */
+export type ShowReason = 'visible' | 'pageshow' | 'resume';
+/**
+ * The fixed-step sim (`CreateGameOptions.sim`). `step` is in seconds (default 1/60); `false`
+ * runs the loop at render rate only, for a client that applies server state each frame.
+ */
+export type SimOption = {
+    step?: number;
+} | false;
+/** Game logic plugged into the frame loop and the lifecycle. Set fields on `ctx.hooks`. */
+export interface GameHooks {
+    /**
+     * Each fixed step, after input and pad navigation, before particles and the scenes. Not
+     * called with `sim: false` (see `frame`).
+     */
+    update?(dt: number): void;
+    /**
+     * `sim: false` only: once per rendered frame with the real frame delta, after input and pad
+     * navigation, before particles, the scenes (`update(dt)` with the same delta) and render.
+     * Apply the latest server state here.
+     */
+    frame?(dt: number): void;
+    /** Each rendered frame, before `renderer.beginFrame`. */
+    beforeRender?(time: Time): void;
+    /** Each rendered frame, after `renderer.endFrame`. */
+    afterRender?(time: Time): void;
+    /**
+     * The page is hidden, paged out or frozen: after the loop stops, before the save flushes.
+     * Can fire several times in a row (hidden, then pagehide, then freeze).
+     */
+    hide?(reason: HideReason): void;
+    /** The page is back and visible: after the loop restarts (not after a device loss). */
+    show?(reason: ShowReason): void;
+    /**
+     * The host's lifecycle changed (`host.lifecycle`, ws/host-mobile): `background` after the loop
+     * stops and the save flushes (autosave here), `active` after it restarts. On the web host this
+     * follows the same page events as `hide`/`show`; in a store app it follows the shell.
+     */
+    lifecycle?(state: HostLifecycleState): void;
+    /** The GPU device was lost: after the loop halts, before audio halts and the save flushes. */
+    deviceLost?(info: GPUDeviceLostInfo): void;
+}
+export interface CreateGameOptions<A extends string, S extends FlushableSave | null = null, P = any> {
+    /**
+     * Element the canvas and overlay mount into. Required unless `gpu` is given; a headless game
+     * without it mounts into a new detached `<div>` of `document`.
+     */
+    root?: HTMLElement;
+    /**
+     * Headless (ws/core-8): the GPU to build on, instead of booting WebGPU on the canvas. Nothing
+     * is asked of `navigator.gpu`, the unsupported and device-lost screens are never shown, and the
+     * canvas gets no context; device loss is read from `gpu.device.lost` where the device has it
+     * (a lost device reaches `hooks.deviceLost` and `ctx.onDeviceLost` as usual). A test passes the
+     * fake GPU (`@thunderclap-engine/engine/testing`); `createTestGame` does.
+     */
+    gpu?: GpuContext;
+    /**
+     * `false` (ws/core-9): no overlay and no DOM at all, for a game run in plain Node (a test, a
+     * server-side sim). Needs `gpu` and `host`. Nothing touches `document` or `window`: no
+     * overlay, panels, captions or `styles`, no canvas or root (`root` is not used, and
+     * `ctx.surface` letterboxes a virtual container of the design size at a pixel ratio of 1, so
+     * client px are design px; its `root` and `canvas` throw), no zoom block, no page lifecycle
+     * or audio unlock listeners, and the input is attached to nothing (feed it with `keyDown`,
+     * `pointerAt` and the rest, or a replay's key, button, pointer and pad lanes; recorded
+     * pointer events and overlay clicks have nothing to reach). Reading `ctx.ui` throws.
+     * `ctx.padNav` exists and never owns the pad. The host's own lifecycle (`host.lifecycle`) and
+     * device loss work as usual. Default true.
+     */
+    overlay?: boolean;
+    /**
+     * The game's tick clock (`ctx.clock`, ws/core-8). Default `createTickClock()`. The loop
+     * advances it by the fixed step (`clock.advance(step × 1000)`) before each fixed update; a
+     * test passes `createFixedClock(step × 1000)`, which counts each such advance as one whole step.
+     */
+    clock?: TickClock;
+    /** The game's name, shown as the eyebrow on the fatal screens. */
+    title?: string;
+    /** Logical design size the renderer, surface and overlay share. Default 1920×1080. */
+    design?: {
+        width: number;
+        height: number;
+    };
+    /** Surface options other than the design size (DPR cap, pixel cap, bar colour). */
+    surface?: Omit<SurfaceOptions, 'logicalWidth' | 'logicalHeight'>;
+    /** Initial post settings (`PostStack` patch). */
+    post?: PostSettingsPatch;
+    /**
+     * Aux attachments of the renderer's scene target (`RendererOptions.aux`, ws/core-7): `{
+     * velocity: true }` gives `post.motionBlur` per-object motion (lists and batches with
+     * `velocity`/`prevMatrices`, drawn with an `aux` material such as the standard one) instead
+     * of camera motion only; `{ roughMetal: true }` feeds SSR's per-surface fade. They reach the
+     * post stack as `PostInputs.velocity` / `roughMetal`. Default none: the target, pipelines and
+     * frames are what they were without the option. The XR scene target has none.
+     */
+    aux?: SceneTargetAux;
+    particles?: ParticleSystemOptions;
+    /** The page the game runs in. Default `createWebHost()`. */
+    host?: Host;
+    /**
+     * Builds the game's save from the host's storage; it is flushed on hide, on `host.lifecycle`
+     * going to `background` (a store app's shell) and on device loss.
+     * Omit it (a client whose state lives on a server) and `ctx.save` is null, typed `null`, and
+     * the engine never touches `host.storage` (leave `mixerKey` out too for that).
+     */
+    save?(host: Host): S;
+    /**
+     * The fixed-step sim. Default `{ step: 1 / 60 }`: `hooks.update` and the scenes run in fixed
+     * steps. `false`: the loop runs at render rate only, calling `hooks.frame(dt)` and the scenes'
+     * `update(dt)` once per frame with the real delta (input, pad navigation and particles too).
+     */
+    sim?: SimOption;
+    /**
+     * The key the audio mixer (volumes, mutes) persists under: `thunderclap:<mixerKey>:audio`.
+     * Omit to keep the mixer in memory.
+     */
+    mixerKey?: string;
+    input: {
+        /**
+         * The base action map. `A` is the full action union: the map may leave out actions a pushed
+         * context binds (ws/input-12; `createGame<'jump' | 'back'>({ input: { bindings: { jump } } })`,
+         * then `ctx.input.pushContext('menu', { bindings: { back } })`).
+         */
+        bindings: Partial<Bindings<A>>;
+        /** See `InputOptions.globalKeys`. */
+        globalKeys?: Iterable<string>;
+        /** See `InputOptions.buttonKeys`. */
+        buttonKeys?: Iterable<string>;
+        /** Extra block on top of "a modal panel is open". */
+        blocked?: () => boolean;
+        /**
+         * Gamepad source for both the action map (`InputOptions.getGamepads`) and the pad
+         * navigation of modal panels (`PadNavOptions.getGamepads`). Default: `navigator.getGamepads()`,
+         * guarded. A test passes a fake pad here and drives `ctx.padNav` with it.
+         */
+        getGamepads?: () => readonly (GamepadLike | null)[];
+        /**
+         * Loupe and snap for small touch targets, passed to the `Gestures` `createGame` builds
+         * (`GestureOptions.magnify`); see `input/magnify.ts`. Omit for no magnify.
+         */
+        magnify?: MagnifyOptions;
+        /**
+         * Record everything the input is fed (ws/input-replay): `ctx.input.recorder` is the
+         * `InputRecorder`; `stop()` it for the `InputRecording`. Default false.
+         */
+        record?: boolean;
+        /**
+         * Run from a recording instead of the DOM (ws/input-replay): the input is not attached to the
+         * canvas or the window, and before each fixed step `ctx.input.playback.step()` feeds that
+         * tick's keys, buttons, pointer, wheel and pads. Once the recording is done the input holds
+         * its last state.
+         */
+        replay?: InputRecording;
+    };
+    /**
+     * Injects the game's stylesheets. Runs before the overlay adds the engine's, so the cascade
+     * (engine sheets after game sheets) is the same in every game.
+     */
+    styles?(doc: Document): void;
+    /**
+     * The overlay's layout: region tracks per form factor, the form-factor rule and each form's
+     * units (see `Layout`; read it as `ctx.ui.layout`).
+     */
+    layout?: LayoutSpec;
+    /**
+     * Token overrides on the overlay's `defaultTheme` (ws/api-core; `OverlayOptions.theme`, sizes
+     * in design px). Later changes: `ctx.ui.setTheme`.
+     */
+    theme?: ThemeOverrides;
+    /**
+     * The overlay's text scale, 1 = 100% (ws/api-core): `applyTextScale(ctx.ui.root, textScale,
+     * ctx.ui.setTheme)` at boot. Default 1 (nothing applied).
+     */
+    textScale?: number;
+    /** Called once WebGPU is up, before anything else is built (load-timing marks). */
+    onGpuReady?(gpu: GpuContext): void;
+    /** Stop double-tap, pinch and ctrl+wheel from zooming the page (`blockBrowserZoom`). Default true. */
+    blockBrowserZoom?: boolean;
+    /** Dev aid: show the unsupported screen as if WebGPU were missing. */
+    forceUnsupported?: boolean;
+    /** VR (ws/xr): the reference space and session callbacks `ctx.xr.enter()` uses. */
+    xr?: XrOptions;
+    /**
+     * The pointer router's first hit testers (ws/input-12; `PointerRouterOptions.testers`). Their
+     * target type is `P`, so `createGame` infers the router's type from them: `ctx.pointers` is a
+     * `PointerRouter<P>` and its hits' `target`s are typed without naming `P`.
+     */
+    pointers?: {
+        testers?: readonly HitTester<P>[];
+    };
+}
+/** `CreateGameOptions.xr`: how `ctx.xr.enter()` sets the session up. */
+export interface XrOptions {
+    /**
+     * The reference space poses and pointer rays are expressed in. Default `local-floor` (the
+     * origin on the floor; standing play), `local` (at the headset's start) or `viewer`.
+     */
+    referenceSpace?: 'local-floor' | 'local' | 'viewer';
+    /** The session is up and frames come from it. */
+    onEnter?(session: XRSession): void;
+    /** The session ended (by `exit()` or the headset); frames come from the page again. */
+    onExit?(): void;
+}
+/**
+ * `ctx.xr`: entering and leaving VR. `supported()` is false and `enter()` rejects where the
+ * browser has no WebXR or no WebXR/WebGPU binding, so the same build runs on the page and in a
+ * headset.
+ */
+export interface XrControl {
+    /** Whether `enter()` can work here: WebXR with the WebGPU binding and `immersive-vr`. */
+    supported(): Promise<boolean>;
+    /**
+     * Request an `immersive-vr` session (call from a user gesture) and move the game into it: the
+     * loop's frames come from the session, each eye renders into the session's layer, controllers
+     * and hands are pointers. Resolves once the first frame can run; rejects when the browser
+     * refuses. A call while active resolves at once.
+     */
+    enter(): Promise<void>;
+    /** End the session and return to the page; resolves when everything is restored. */
+    exit(): Promise<void>;
+    /** True while a session runs. */
+    readonly active: boolean;
+    /** The running session, or null. */
+    readonly session: XRSession | null;
+    /** The XR surface (eye views, head camera, layer) while active, or null. */
+    readonly surface: XrSurface | null;
+}
+/**
+ * `ctx.replay(recording, opts)`: ticks per `step()` and ms per fed tick (`InputPlaybackOptions`),
+ * and `onEnd`.
+ */
+export interface ReplayOptions extends Pick<InputPlaybackOptions, 'speed' | 'tickMs'> {
+    /**
+     * The recording ended (ws/core-7): called once, on the fixed step where the loop uninstalls
+     * the replay (the first step after its last tick), after the input is reattached and before
+     * that step's input update and `hooks.update`. Not called on `stop()`, nor when a second
+     * `ctx.replay` replaces this one. A `ctx.replay` started here is stepped from the next step.
+     */
+    onEnd?(): void;
+}
+/**
+ * What `ctx.replay` returns: the `InputPlayback` installed on `ctx.input` (it is
+ * `ctx.input.playback`), driving `ctx.clock`. `stop()` (or `detach()`, the same call) uninstalls
+ * it and reattaches the input to the canvas at once; the loop does the same on the first step
+ * after the recording ends.
+ */
+export interface GameReplay extends InputPlayback {
+    /** Uninstall the playback and give the input back to the player. Idempotent. */
+    stop(): void;
+}
+/**
+ * Everything noun-free a scene may use. `A` is the game's action names, `S` its save, `C` the
+ * ctx the scene stack hands to scenes (the game's own ctx type, which extends this one) and `P`
+ * what the pointer router's hits carry (`ctx.pointers`' testers' `target`s). `createGame` infers
+ * `P` from `pointers.testers` (else `unknown`, or name it: `createGame<A, S, C, P>`). The default
+ * is `any`, so `EngineCtx<A>` takes a ctx whatever its `P` (the router is covariant in its target
+ * since ws/input-12, so `unknown` would too; it stays `any` under the 1.x freeze and may tighten
+ * to `unknown` in 2.0).
+ * A game created without `save` gets `S = null`: `ctx.save` is then typed `null`, so a client
+ * cannot reach for one. The default `S` is `FlushableSave | null` (ws/api-core), so code written
+ * against `EngineCtx<A>` takes a ctx with a save or without one; name the save type
+ * (`EngineCtx<A, MySave>`) to read it.
+ */
+export interface EngineCtx<A extends string = string, S extends FlushableSave | null = FlushableSave | null, C = unknown, P = any> {
+    readonly design: {
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly surface: Surface;
+    readonly gpu: GpuContext;
+    readonly renderer: Renderer;
+    /**
+     * The camera the scenes draw through (`renderer.camera`, `Camera.ortho2d(design)` by default):
+     * the loop passes it to `Scene.render(frame, camera, alpha)` and `renderer.render`, the
+     * pointer rays and `ui.anchors()` go through it. Re-aim it in place (`fitRect`,
+     * `setPerspective`, `lookAt`), or swap it with `setCamera`.
+     */
+    readonly camera: Camera;
+    /**
+     * Swap the camera (ws/api-core): `ctx.setCamera(Camera.perspective(fovY, aspect, near, far))`.
+     * `ctx.camera` and `renderer.camera` read it from now; the next frame, the next pointer
+     * update and the overlay's anchors use it.
+     */
+    setCamera(camera: Camera): void;
+    readonly post: PostStack;
+    /** Shared GPU particle pool; updated by the loop, drawn by views. */
+    readonly particles: ParticleSystem;
+    readonly input: Input<A>;
+    /**
+     * The game's tick clock (ws/core-4), in ms: it moves by the fixed step before each fixed
+     * update (by the frame delta with `sim: false`) and stands still while `loop.paused` is set
+     * or the loop is stopped. `ctx.gestures` reads it, so long-press and double-tap run on game
+     * time and a recording replays them on the same ticks. Gestures or a `Look` the game builds
+     * itself take it as `{ clock: ctx.clock }`, and so does a playback (`createInputPlayback`'s
+     * `clock`), which is why it is typed `TickClock`; only the loop or a playback advances it.
+     */
+    readonly clock: TickClock;
+    /**
+     * Replay `recording` from now (a replay started from a menu, ws/core-6): installs an
+     * `InputPlayback` on `input`, driven by `clock`, and detaches the input from the canvas and the
+     * window for its length, so the real player cannot disturb it; the recorded pointers still
+     * reach `gestures` and `pointers`. From the next fixed step the loop steps it. When the
+     * recording ends (the first step after its last tick) or `stop()` is called, the playback is
+     * uninstalled and the input reattached as before. A second call stops the first replay; a
+     * playback from `input.replay` is replaced (the input then returns to its detached element).
+     */
+    replay(recording: InputRecording, opts?: ReplayOptions): GameReplay;
+    /**
+     * Tap, double tap, long-press, pan, drag and pinch, linked to `input` (shared block and
+     * transform, advanced in `input.update()`), so `{ gesture }` bindings work out of the box.
+     * Read a gesture's position here (`gestures.tap`) when an action fires.
+     */
+    readonly gestures: Gestures;
+    /**
+     * Pointer rays through `ctx.camera` (mouse, pen, touch; a `PadCursor` when added; the XR
+     * controllers and hands, through the head camera, while `xr` is active): register hit testers
+     * on it and listen for `hover`/`select`. Linked to `input`, which polls it each update and
+     * shares its block and pointer transform. `P` types the hits' `target`s
+     * (`createGame<Action, Save, GameCtx, Target>`); the router itself does not check them.
+     */
+    readonly pointers: PointerRouter<P>;
+    /** Drives modal panels from the pad (d-pad moves focus, A activates, B closes). */
+    readonly padNav: PadNav;
+    readonly audio: AudioEngine;
+    /** The DOM overlay, CSS px, with its layout (`ui.layout`); `ui.padOwner` says who has the pad. */
+    readonly ui: Overlay;
+    /**
+     * The page the game runs in: frames, links, copying, fullscreen, save storage, and where the
+     * host has them the app lifecycle (`host.lifecycle`, `hooks.lifecycle`), haptics
+     * (`host.haptics`) and the safe area (`host.safeArea`, which pads `ui.layout`).
+     */
+    readonly host: Host;
+    /** The game's save, or null when `createGame` was given none (`S` is then `null`). */
+    readonly save: S;
+    readonly stack: SceneStack<C, Frame, Camera>;
+    readonly loop: GameLoop;
+    /** Game logic in the frame and lifecycle; see `GameHooks`. */
+    readonly hooks: GameHooks;
+    /** Runs `fn` after the device-lost screen and the engine's halt. Returns unsubscribe. */
+    onDeviceLost(fn: (info: GPUDeviceLostInfo) => void): () => void;
+    /** Entering and leaving VR; see `XrControl`. */
+    readonly xr: XrControl;
+}
+/**
+ * Boots WebGPU and builds the engine ctx. Resolves `null` when WebGPU is unavailable: the
+ * engine has already shown the unsupported screen and there is nothing more to do.
+ *
+ * Nothing runs until the game calls `ctx.loop.start()`, except the lifecycle handlers (a show
+ * starts the loop) and resize, which keeps the renderer and overlay in step.
+ */
+export declare function createGame<A extends string, S extends FlushableSave | null = null, C = unknown, P = unknown>(opts: CreateGameOptions<A, S, P>): Promise<EngineCtx<A, NoInfer<S>, C, P> | null>;