@threenative/core 0.1.0 → 0.2.0

package/dist/playtest.d.ts

@@ -1,11 +1,33 @@
 import { JsonValue } from '@threenative/playtest';
-import { b as GamePluginHooks } from './game-DRPs3M7r.js';
+import { c as IGamePluginHooks } from './game-DRt1Qhq3.js';
 import 'three';
 import 'zustand/vanilla';
 
-declare function playtest<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined>(options?: PlaytestOptions): GamePluginHooks<TState, TPhysics>;
-interface PlaytestOptions {
+declare function playtest<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined>(options?: IPlaytestOptions): IGamePluginHooks<TState, TPhysics>;
+declare const PLAYTEST_ATTACH_TIMEOUT_MS = 30000;
+/**
+ * Resolves when a runner first calls `describe()`, the handshake every runner performs before
+ * it observes anything.
+ *
+ * Without this, a scenario races the game: a proof that does finite work at startup can finish
+ * before the runner takes its first observation, and the assertion then reports
+ * TN_PLAYTEST_ASSERTION_TRIVIAL or a zero-delta failure depending only on how fast the device
+ * booted. Opt-in, because a game that holds for a runner that never arrives is worse than the
+ * race for every non-test caller.
+ *
+ * Fails closed: if no runner attaches within the timeout, setup throws rather than quietly
+ * starting anyway and reproducing the race it was added to remove.
+ */
+/** The global a playtest runner sets before the page loads, so a game can tell one is coming. */
+declare const PLAYTEST_RUNNER_EXPECTED_GLOBAL = "__THREENATIVE_PLAYTEST_RUNNER_EXPECTED__";
+interface IPlaytestOptions {
     readonly events?: () => JsonValue[];
+    /**
+     * Hold the frame loop until a runner attaches. Default false.
+     */
+    readonly holdUntilAttached?: boolean;
+    /** Milliseconds to wait when `holdUntilAttached` is set. Default {@link PLAYTEST_ATTACH_TIMEOUT_MS}. */
+    readonly attachTimeoutMs?: number;
 }
 
-export { type PlaytestOptions, playtest };
+export { type IPlaytestOptions, PLAYTEST_ATTACH_TIMEOUT_MS, PLAYTEST_RUNNER_EXPECTED_GLOBAL, playtest };

package/dist/playtest.js

@@ -17,10 +17,11 @@ var PLAYTEST_CAPABILITY_REGISTRY = [
   capability("runtime.audio", "Samples application-owned audio runtime state."),
   capability("runtime.components", "Samples registered JSON-safe component state."),
   capability("runtime.contacts", "Samples bounded collision and trigger contacts."),
-  capability("runtime.diagnostics", "Samples application-owned runtime diagnostics."),
+  capability("runtime.diagnostics", "Captures application runtime errors."),
   capability("runtime.events", "Drains bounded application event observations."),
   capability("runtime.fixedStep", "Advances an application-owned deterministic tick."),
   capability("runtime.physics", "Samples bounded application-owned physics observations."),
+  capability("runtime.performance", "Samples bounded per-render frame cost and renderer counts."),
   capability("runtime.resources", "Reads and writes registered JSON-safe application state."),
   capability("runtime.state", "Samples application-owned state-machine state."),
   capability("runtime.tags", "Samples bounded application-owned entity tags."),
@@ -129,6 +130,7 @@ function sampleThreeObservations(input, request) {
   input.camera.updateMatrixWorld(true);
   const rendererSize = input.renderer.getDrawingBufferSize(new Vector2());
   const entities = input.registry.select(request.entities).map(({ id, object }) => observeEntity(id, object, input.camera, rendererSize.x, rendererSize.y));
+  const renderPerformance = rendererPerformance(input.renderer);
   return {
     clock: {
       mode: input.clockMode,
@@ -137,9 +139,24 @@ function sampleThreeObservations(input, request) {
     ...input.diagnostics === void 0 ? {} : { diagnostics: input.diagnostics() },
     entities,
     ...input.gameplay === void 0 ? {} : { gameplay: input.gameplay() },
+    ...renderPerformance === void 0 ? {} : { performance: renderPerformance },
+    ...input.runtimeDiagnosticsSeries === void 0 ? {} : { runtimeDiagnosticsSeries: input.runtimeDiagnosticsSeries().map((sample) => ({ ...sample })) },
     ...input.resources === void 0 ? {} : { resources: input.resources() }
   };
 }
+function rendererPerformance(renderer) {
+  const render = renderer.info?.render;
+  const drawCalls = finiteNumber(render?.drawCalls) ? render.drawCalls : void 0;
+  const triangles = finiteNumber(render?.triangles) ? render.triangles : void 0;
+  if (drawCalls === void 0 && triangles === void 0) return void 0;
+  return {
+    ...drawCalls === void 0 ? {} : { drawCalls },
+    ...triangles === void 0 ? {} : { triangles }
+  };
+}
+function finiteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
 function observeEntity(id, object, camera, viewportWidth, viewportHeight) {
   const position = object.getWorldPosition(new Vector3());
   const bounds = projectedBounds(object, camera, viewportWidth, viewportHeight);
@@ -182,6 +199,49 @@ function projectedBounds(object, camera, viewportWidth, viewportHeight) {
     y: (1 - maxY) * 0.5 * viewportHeight
   };
 }
+var PLAYTEST_PHYSICS_BODY_LIMIT = 100;
+var PLAYTEST_PHYSICS_SAMPLE_LIMIT = 100;
+var ThreePlaytestPhysicsRecorder = class {
+  #physics;
+  #series = [];
+  constructor(physics) {
+    this.#physics = physics;
+  }
+  sample(request, tick) {
+    if (request.label !== void 0) {
+      if (this.#series.some(({ label }) => label === request.label))
+        throw new Error(`TN_PLAYTEST_PHYSICS_LABEL_DUPLICATE: '${request.label}' was already sampled.`);
+      if (this.#series.length >= PLAYTEST_PHYSICS_SAMPLE_LIMIT)
+        throw new Error(`TN_PLAYTEST_PHYSICS_SAMPLE_LIMIT: at most ${PLAYTEST_PHYSICS_SAMPLE_LIMIT} labelled samples are retained.`);
+      this.#series.push({ label: request.label, snapshot: physicsSnapshot(this.#physics.bodies()), tick });
+    }
+    return this.#series.map((sample) => ({ ...sample }));
+  }
+};
+function physicsSnapshot(bodies) {
+  if (!Array.isArray(bodies))
+    throw new Error("TN_PLAYTEST_PHYSICS_BODIES: the physics provider must return an array of bodies.");
+  const retained = bodies.slice(0, PLAYTEST_PHYSICS_BODY_LIMIT);
+  const seen = /* @__PURE__ */ new Set();
+  const primitives = retained.flatMap((body) => {
+    if (typeof body?.id !== "string" || body.id.length === 0)
+      throw new Error("TN_PLAYTEST_PHYSICS_BODY_ID: every observed physics body needs a non-empty string id.");
+    if (seen.has(body.id))
+      throw new Error(`TN_PLAYTEST_PHYSICS_BODY_DUPLICATE: body id '${body.id}' was reported twice in one sample.`);
+    seen.add(body.id);
+    if (typeof body.sleeping !== "boolean")
+      throw new Error(`TN_PLAYTEST_PHYSICS_BODY_SLEEPING: body '${body.id}' must report sleeping as a boolean.`);
+    if (!isFiniteVec3(body.position))
+      throw new Error(`TN_PLAYTEST_PHYSICS_BODY_POSITION: body '${body.id}' must report a finite [x, y, z] position.`);
+    const sleep = { category: "sleep", entity: body.id, value: body.sleeping ? 1 : 0 };
+    const centerOfMass = { category: "center-of-mass", entity: body.id, position: [...body.position] };
+    return [sleep, centerOfMass];
+  });
+  return { artifact: { overflow: { omittedBodies: bodies.length - retained.length }, primitives } };
+}
+function isFiniteVec3(value) {
+  return Array.isArray(value) && value.length === 3 && value.every((component) => typeof component === "number" && Number.isFinite(component));
+}
 var BRIDGE_METHODS = /* @__PURE__ */ new Set([
   "advance",
   "applySetup",
@@ -339,11 +399,15 @@ function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function installThreePlaytestBridge(options) {
+  if (options.fixedStep === void 0 !== (options.tick === void 0))
+    throw new Error("fixedStep and its authoritative tick provider must be installed together.");
+  if (options.physics !== void 0 && options.tick === void 0)
+    throw new Error("A physics provider requires the authoritative tick provider, and therefore fixedStep.");
+  const recorder = options.physics === void 0 ? void 0 : new ThreePlaytestPhysicsRecorder(options.physics);
   const host = globalThis;
   const previous = host[PLAYTEST_BRIDGE_GLOBAL];
   const registry = new ThreePlaytestEntityRegistry();
   syncEntities(registry, options.entities);
-  let tick = 0;
   const capabilities = () => [
     "camera.observe",
     "entity.bounds",
@@ -355,17 +419,23 @@ function installThreePlaytestBridge(options) {
     ...Object.keys(options.components?.() ?? {}).length === 0 ? [] : ["runtime.components"],
     ...options.events === void 0 ? [] : ["runtime.events"],
     ...options.gameplay === void 0 ? [] : ["runtime.animation", "runtime.state"],
+    ...options.physics === void 0 ? [] : ["runtime.physics"],
+    ...options.runtimeDiagnosticsSeries === void 0 ? [] : ["runtime.performance"],
     ...options.gameplayChannels?.().includes("runtime.contacts") === true ? ["runtime.contacts"] : [],
-    ...options.gameplayChannels?.().includes("runtime.tags") === true ? ["runtime.tags"] : []
+    ...options.gameplayChannels?.().includes("runtime.tags") === true ? ["runtime.tags"] : [],
+    ...options.gameplayChannels?.().includes("runtime.world") === true ? ["runtime.world"] : []
   ];
   const bridge = {
     ...options.fixedStep === void 0 ? {} : {
       advance: async (ticks) => {
         if (!Number.isInteger(ticks) || ticks <= 0) throw new Error("advance ticks must be a positive integer.");
+        const startTick = options.tick();
         await options.fixedStep(ticks);
-        const startTick = tick;
-        tick += ticks;
-        return { clock: { mode: "fixed-step", tick }, ticks: tick - startTick };
+        const tick = options.tick();
+        const advanced = tick - startTick;
+        if (advanced !== ticks)
+          throw new Error(`fixedStep advanced ${advanced} actual ticks; expected ${ticks}.`);
+        return { clock: { mode: "fixed-step", tick }, ticks: advanced };
       }
     },
     applySetup: async (request) => applySetup(registry, options.resources, request),
@@ -391,14 +461,16 @@ function installThreePlaytestBridge(options) {
         clockMode: options.fixedStep === void 0 ? "render-frame" : "fixed-step",
         diagnostics: options.diagnostics,
         gameplay: options.gameplay,
+        runtimeDiagnosticsSeries: options.runtimeDiagnosticsSeries,
         registry,
         renderer: options.renderer,
         resources: options.resources === void 0 ? void 0 : () => options.resources.read(),
         scene: options.scene,
-        tick: options.fixedStep === void 0 ? void 0 : tick
+        tick: options.tick?.()
       }, request);
       const components = options.components?.();
-      const result = components === void 0 || Object.keys(components).length === 0 ? snapshot : { ...snapshot, components };
+      const withComponents = components === void 0 || Object.keys(components).length === 0 ? snapshot : { ...snapshot, components };
+      const result = recorder === void 0 || request.include?.includes("physicsDebugSeries") !== true ? withComponents : { ...withComponents, physicsDebugSeries: recorder.sample(request, options.tick()) };
       assertJsonSafe2(result);
       return result;
     }
@@ -454,10 +526,10 @@ var CORE_VERSION = "0.1.0";
 var currentAgent = typeof navigator === "undefined" ? "node" : navigator.userAgent;
 function playtest(options = {}) {
   let dispose;
+  let attached;
   let contactHistory = [];
   return {
-    setup: (ctx, runtime) => {
-      const diagnostics = [];
+    setup: async (ctx, runtime) => {
       const seed = runtime?.seed ?? null;
       const replayRuntime = runtime?.seed === null || runtime?.seed === void 0 ? void 0 : {
         agent: currentAgent,
@@ -468,10 +540,10 @@ function playtest(options = {}) {
       };
       const installation = installThreePlaytestBridge({
         camera: ctx.camera,
-        diagnostics: () => [...diagnostics],
         entities: () => bridgeEntities(ctx),
         components: () => componentObservations(ctx.entities.snapshot()),
-        ...runtime === void 0 ? {} : { fixedStep: (ticks) => advance(runtime, ticks) },
+        ...runtime === void 0 ? {} : { fixedStep: runtime.fixedStep, tick: runtime.tick },
+        ...runtime?.runtimeDiagnosticsSeries === void 0 ? {} : { runtimeDiagnosticsSeries: runtime.runtimeDiagnosticsSeries },
         ...options.events === void 0 ? {} : { events: options.events },
         gameplay: () => gameplayObservations(ctx, contactHistory, seed, replayRuntime),
         gameplayChannels: () => gameplayChannels(),
@@ -479,27 +551,93 @@ function playtest(options = {}) {
         resources: stateResources(ctx),
         scene: ctx.scene
       });
-      installRuntimeChannels(installation.bridge);
+      installRuntimeChannels(installation.bridge, runtime);
       dispose = installation.dispose;
-      return () => {
+      attached = holdUntilAttached(installation.bridge, options);
+      const cleanup = () => {
         dispose?.();
         dispose = void 0;
+        attached = void 0;
         contactHistory = [];
       };
+      if (attached !== void 0) {
+        const gate = attached.catch((error) => {
+          cleanup();
+          throw error;
+        });
+        if (runtime?.holdStart === void 0) await gate;
+        else runtime.holdStart(gate);
+      }
+      return cleanup;
     }
   };
 }
-function installRuntimeChannels(bridge) {
+var PLAYTEST_ATTACH_TIMEOUT_MS = 3e4;
+var PLAYTEST_RUNNER_EXPECTED_GLOBAL = "__THREENATIVE_PLAYTEST_RUNNER_EXPECTED__";
+function shouldHoldUntilAttached(options) {
+  if (options.holdUntilAttached !== void 0) return options.holdUntilAttached;
+  return globalThis[PLAYTEST_RUNNER_EXPECTED_GLOBAL] === true;
+}
+function holdUntilAttached(bridge, options) {
+  if (!shouldHoldUntilAttached(options)) return void 0;
+  const timeoutMs = options.attachTimeoutMs ?? PLAYTEST_ATTACH_TIMEOUT_MS;
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new Error(`TN_PLAYTEST_ATTACH_TIMEOUT_INVALID: ${String(options.attachTimeoutMs)}`);
+  }
   const describe = bridge.describe;
-  bridge.describe = () => Promise.resolve(describe()).then((description) => addRuntimeCapabilities(description));
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(
+        new Error(
+          `TN_PLAYTEST_ATTACH_TIMEOUT: no playtest runner called describe() within ${timeoutMs}ms.`
+        )
+      );
+    }, timeoutMs);
+    timer.unref?.();
+    bridge.describe = () => {
+      clearTimeout(timer);
+      resolve();
+      return describe();
+    };
+  });
+}
+function installRuntimeChannels(bridge, runtime) {
+  const describe = bridge.describe;
+  bridge.describe = () => Promise.resolve(describe()).then(
+    (description) => addRuntimeCapabilities(description, runtime?.observations.contributions() ?? [])
+  );
+  const sample = bridge.sample;
+  bridge.sample = (request) => Promise.resolve(sample(request)).then(
+    (snapshot) => addRuntimeObservations(snapshot, request, runtime?.observations.contributions() ?? [])
+  );
 }
-function addRuntimeCapabilities(description) {
+function addRuntimeCapabilities(description, contributions) {
   const capabilities = [...description.capabilities];
-  for (const capability2 of ["runtime.audio", "runtime.world"]) {
+  const contributed = contributions.flatMap(({ capabilities: capabilities2 }) => capabilities2);
+  for (const capability2 of ["runtime.audio", "runtime.world", ...contributed]) {
     if (!capabilities.includes(capability2)) capabilities.push(capability2);
   }
   return { ...description, capabilities };
 }
+function addRuntimeObservations(snapshot, request, contributions) {
+  const result = { ...snapshot };
+  for (const contribution of contributions) {
+    const slice = contribution.sample(request);
+    if (typeof slice !== "object" || slice === null || Array.isArray(slice)) {
+      throw new TypeError("A runtime observation contribution must return a top-level object.");
+    }
+    assertJsonSafe(slice, "$.runtimeContribution");
+    for (const [key, value] of Object.entries(slice)) {
+      if (Object.hasOwn(result, key)) {
+        throw new Error(
+          `TN_PLAYTEST_OBSERVATION_COLLISION: top-level key '${key}' already exists.`
+        );
+      }
+      result[key] = value;
+    }
+  }
+  return result;
+}
 function runtimeObservation(seed, replayRuntime) {
   return {
     audio: audioRuntimeSnapshot(),
@@ -509,9 +647,6 @@ function runtimeObservation(seed, replayRuntime) {
     }
   };
 }
-function advance(runtime, ticks) {
-  runtime.fixedStep(ticks);
-}
 function bridgeEntities(ctx) {
   return [
     { id: "camera.main", object: ctx.camera },
@@ -606,9 +741,12 @@ function stateResources(ctx) {
       const state = ctx.state.getState();
       assertJsonSafe(state);
       const value = state;
-      return { GameState: value, state: value };
+      return Object.fromEntries([
+        ["GameState", value],
+        ["state", value]
+      ]);
     }
   };
 }
 
-export { playtest };
+export { PLAYTEST_ATTACH_TIMEOUT_MS, PLAYTEST_RUNNER_EXPECTED_GLOBAL, playtest };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@threenative/core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The small vanilla Three.js game runtime foundation.",
   "type": "module",
   "files": [
@@ -30,6 +30,7 @@
   "sideEffects": false,
   "dependencies": {
     "three": "0.185.1",
+    "three-mesh-bvh": "0.9.14",
     "zustand": "5.x"
   },
   "devDependencies": {
@@ -37,7 +38,7 @@
     "publint": "0.3.22",
     "tsup": "8.5.1",
     "typescript": "5.9.3",
-    "@threenative/playtest": "0.1.0"
+    "@threenative/playtest": "0.2.0"
   },
   "scripts": {
     "build": "tsup --config tsup.config.ts && publint",

package/dist/game-DRPs3M7r.d.ts

@@ -1,269 +0,0 @@
-import { Texture, Vector2, Object3D, Camera, Vector3, Scene as Scene$1 } from 'three';
-import { StoreApi } from 'zustand/vanilla';
-
-interface AssetLoaderOptions {
-    readonly basePath?: string;
-    readonly model?: (url: string) => Promise<unknown>;
-    readonly texture?: (url: string) => Promise<Texture>;
-    readonly audio?: (url: string) => Promise<AudioBuffer>;
-}
-interface AssetLoader {
-    model<T = unknown>(path: string): Promise<T>;
-    texture(path: string): Promise<Texture>;
-    audio(path: string): Promise<AudioBuffer>;
-    release(kind: "audio" | "model" | "texture", path: string): boolean;
-    clear(): void;
-}
-declare function createAssetLoader(options?: AssetLoaderOptions): AssetLoader;
-
-interface InputAction {
-    readonly buttons?: readonly number[];
-    readonly down?: readonly string[];
-    readonly left?: readonly string[];
-    readonly pointer?: boolean;
-    readonly right?: readonly string[];
-    readonly up?: readonly string[];
-}
-type InputBindings = Record<string, InputAction>;
-interface InputGamepad {
-    readonly axes: ArrayLike<number>;
-    readonly buttons: readonly {
-        readonly pressed: boolean;
-    }[];
-}
-type InputPlatformSource = () => readonly (InputGamepad | null)[];
-interface RawInputState {
-    readonly keys: ReadonlySet<string>;
-    readonly pointer: {
-        buttons: number;
-        down: boolean;
-        readonly position: Vector2;
-    };
-    readonly gamepad: {
-        axes: readonly number[];
-        buttons: readonly boolean[];
-    };
-}
-declare class InputMap {
-    #private;
-    readonly raw: RawInputState;
-    constructor(bindings?: InputBindings, target?: EventTarget, pointerTarget?: EventTarget, source?: InputPlatformSource);
-    vector(name: string): Vector2;
-    pressed(name: string): boolean;
-    justPressed(name: string): boolean;
-    justReleased(name: string): boolean;
-    tick(): void;
-    clear(): void;
-    dispose(): void;
-}
-declare function input(bindings?: InputBindings, target?: EventTarget, pointerTarget?: EventTarget, source?: InputPlatformSource): InputMap;
-
-interface Random {
-    (): number;
-    pick<T>(items: readonly T[]): T;
-    range(min: number, max: number): number;
-    state: number;
-}
-declare function createRandom(seed?: number): Random;
-
-type RendererKind = "webgpu" | "webgl2";
-interface RendererLike {
-    readonly domElement: HTMLCanvasElement;
-    readonly kind: RendererKind;
-    readonly raw: unknown;
-    compute(node: unknown): void;
-    render(scene: Object3D, camera: Camera): void;
-    setOutputNode(node: unknown): void;
-    setSize(width: number, height: number, updateStyle?: boolean): void;
-    dispose(): void;
-}
-interface RendererPlatformSource {
-    createCanvas(): HTMLCanvasElement;
-    hasWebGPU(): boolean;
-    observeResize(canvas: HTMLCanvasElement, resize: () => void): () => void;
-    readSize(canvas: HTMLCanvasElement): readonly [width: number, height: number];
-}
-interface RendererOptions {
-    canvas?: HTMLCanvasElement;
-    preferWebGPU?: boolean;
-    source?: RendererPlatformSource;
-    webgpuFactory?: (canvas: HTMLCanvasElement) => Promise<unknown> | unknown;
-    webgl2Factory?: (canvas: HTMLCanvasElement) => unknown;
-}
-declare function createRenderer(options?: RendererOptions): Promise<RendererLike>;
-
-type EntitySnapshot = Record<string, Record<string, unknown> & {
-    tags?: string[];
-}>;
-interface Debuggable {
-    debug(): Record<string, unknown>;
-}
-declare function autoFields(entity: object): Record<string, unknown>;
-declare class Registry {
-    #private;
-    add<T extends object>(name: string, entity: T): T;
-    get<T extends object = object>(name: string): T | undefined;
-    remove(name: string): void;
-    clear(): void;
-    snapshot(): EntitySnapshot;
-}
-
-type ScheduleHandle = (() => void) & {
-    cancel(): void;
-    readonly active: boolean;
-};
-type TweenProperties<T extends object> = {
-    [K in keyof T]?: number;
-};
-declare class Scheduler {
-    #private;
-    get size(): number;
-    after(delay: number, callback: () => void): ScheduleHandle;
-    every(callback: (dt: number) => void): ScheduleHandle;
-    tween<T extends object>(target: T, properties: TweenProperties<T>, duration: number): Promise<void>;
-    tick(dt: number): void;
-    clear(): void;
-}
-
-type StatePatch<T extends Record<string, unknown>> = Partial<T> | ((state: T) => Partial<T>);
-type GameStore<T extends Record<string, unknown>> = StoreApi<T> & {
-    set(patch: StatePatch<T>): void;
-    flush(): void;
-    start(): void;
-    stop(): void;
-};
-declare function createGameStore<T extends Record<string, unknown>>(initial: T, intervalMs?: number): GameStore<T>;
-
-interface ViewportSize {
-    readonly aspect: number;
-    readonly height: number;
-    readonly width: number;
-}
-interface ViewportOptions {
-    readonly camera: Camera;
-    readonly renderer: RendererLike;
-    readonly source?: ViewportPlatformSource;
-}
-type ViewportResizeHandler = (size: ViewportSize) => void;
-interface ViewportPlatformSource {
-    observeResize(canvas: HTMLCanvasElement, resize: () => void): () => void;
-    readSize(canvas: HTMLCanvasElement): ViewportSize;
-}
-declare class Viewport {
-    #private;
-    readonly camera: Camera;
-    readonly renderer: RendererLike;
-    constructor(options: ViewportOptions);
-    get size(): ViewportSize;
-    projectPosition(screen: Vector2, z?: number): Vector3;
-    unprojectPosition(world: Vector3): Vector2;
-    onResize(handler: ViewportResizeHandler): () => void;
-    resize(): void;
-    dispose(): void;
-}
-
-declare abstract class Scene<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> {
-    static readonly initialState: Record<string, unknown> | undefined;
-    load(_ctx: Ctx<TState, TPhysics>): void | Promise<void>;
-    enter(_ctx: Ctx<TState, TPhysics>): SceneEnterResult<TState, TPhysics>;
-    exit(_ctx: Ctx<TState, TPhysics>): void;
-    update(_ctx: Ctx<TState, TPhysics>, _dt: number): void;
-    render(_ctx: Ctx<TState, TPhysics>): void;
-}
-type SceneConstructor<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> = new () => Scene<TState, TPhysics>;
-type SceneFrame<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> = (ctx: Ctx<TState, TPhysics>, dt: number) => void;
-type SceneEnterResult<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> = // biome-ignore lint/suspicious/noConfusingVoidType: void preserves existing Scene.enter overrides.
-void | SceneFrame<TState, TPhysics>;
-interface Ctx<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> {
-    readonly fps: number;
-    readonly renderer: RendererLike;
-    readonly viewport: Viewport;
-    readonly scene: Scene$1;
-    readonly camera: Camera;
-    readonly entities: Registry;
-    readonly add: (object: Object3D) => Object3D;
-    readonly input: InputMap;
-    readonly assets: AssetLoader;
-    readonly after: (delay: number, callback: () => void) => ScheduleHandle;
-    readonly every: (callback: (dt: number) => void) => ScheduleHandle;
-    readonly state: GameStore<TState>;
-    readonly tween: <T extends object>(target: T, properties: {
-        [K in keyof T]?: number;
-    }, duration: number) => Promise<void>;
-    readonly random: Random;
-    readonly goto: (name: string) => Promise<void>;
-    physics: TPhysics;
-}
-
-type PluginCleanup = () => void;
-interface GamePluginRuntime {
-    fixedStep(ticks: number): number;
-    readonly random?: Pick<Random, "state">;
-    rapier?: string | null;
-    readonly seed: number | null;
-    readonly step: number;
-}
-interface GamePlatformSource {
-    readonly devToolsHost?: Record<string, unknown>;
-    readonly input: NonNullable<ConstructorParameters<typeof InputMap>[3]>;
-    readonly inputTarget?: EventTarget;
-    readonly renderer: NonNullable<RendererOptions["source"]>;
-    readonly viewport: NonNullable<ViewportOptions["source"]>;
-    mountCanvas(canvas: HTMLCanvasElement, container?: HTMLElement): void;
-    unmountCanvas(canvas: HTMLCanvasElement): void;
-}
-type GamePluginFunction<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> = (ctx: Ctx<TState, TPhysics>) => undefined | PluginCleanup;
-interface GamePluginHooks<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> {
-    setup?(ctx: Ctx<TState, TPhysics>, runtime?: GamePluginRuntime): undefined | PluginCleanup | Promise<undefined | PluginCleanup>;
-    beforeUpdate?(ctx: Ctx<TState, TPhysics>, dt: number): void;
-    update?(ctx: Ctx<TState, TPhysics>, dt: number): void;
-    sceneExit?(ctx: Ctx<TState, TPhysics>): void;
-    dispose?(ctx: Ctx<TState, TPhysics>): void;
-}
-type GamePlugin<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> = GamePluginFunction<TState, TPhysics> | GamePluginHooks<TState, TPhysics>;
-interface GameConfig<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> {
-    readonly assets?: AssetLoaderOptions;
-    readonly camera?: CameraConfig;
-    readonly canvas?: HTMLCanvasElement;
-    readonly container?: HTMLElement;
-    readonly input?: InputBindings;
-    readonly initialState?: TState;
-    readonly inputTarget?: EventTarget;
-    readonly maxSteps?: number;
-    readonly platform?: GamePlatformSource;
-    readonly plugins?: readonly GamePlugin<TState, TPhysics>[];
-    readonly render?: Pick<RendererOptions, "preferWebGPU">;
-    readonly renderer?: RendererOptions;
-    readonly seed?: number;
-    readonly scenes: Record<string, SceneConstructor<TState, TPhysics>>;
-    readonly step?: number;
-    readonly start: string;
-    readonly stateFlushMs?: number;
-}
-interface PerspectiveCameraConfig {
-    readonly projection: "perspective";
-    readonly fov?: number;
-    readonly near?: number;
-    readonly far?: number;
-}
-interface OrthogonalCameraConfig {
-    readonly projection: "orthogonal";
-    readonly size: number;
-    readonly near?: number;
-    readonly far?: number;
-}
-type CameraConfig = PerspectiveCameraConfig | OrthogonalCameraConfig;
-interface Game<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> {
-    readonly ctx: Ctx<TState, TPhysics> | undefined;
-    readonly scene: Scene<TState, TPhysics> | undefined;
-    readonly state: GameStore<TState>;
-    /** Rebuilds the requested scene from the game's declared initial state. */
-    goto(name: string): Promise<void>;
-    start(): Promise<void>;
-    pause(): void;
-    resume(): void;
-    stop(): void;
-}
-declare function defineGame<TState extends Record<string, unknown>, TPhysics = undefined>(config: GameConfig<TState, TPhysics>): Game<TState, TPhysics>;
-
-export { type AssetLoader as A, autoFields as B, type CameraConfig as C, type Debuggable as D, type EntitySnapshot as E, createAssetLoader as F, type Game as G, createGameStore as H, type InputAction as I, createRandom as J, createRenderer as K, defineGame as L, input as M, type OrthogonalCameraConfig as O, type PerspectiveCameraConfig as P, type RendererLike as R, Scene as S, Viewport as V, type GamePluginRuntime as a, type GamePluginHooks as b, type AssetLoaderOptions as c, type Ctx as d, type GameConfig as e, type GamePlatformSource as f, type GamePlugin as g, type GamePluginFunction as h, type GameStore as i, type InputBindings as j, InputMap as k, type PluginCleanup as l, type Random as m, type RawInputState as n, Registry as o, type RendererKind as p, type RendererOptions as q, type SceneConstructor as r, type SceneEnterResult as s, type SceneFrame as t, type ScheduleHandle as u, Scheduler as v, type StatePatch as w, type ViewportOptions as x, type ViewportResizeHandler as y, type ViewportSize as z };