hayao 0.2.0 → 0.4.0

package/dist/world.d.ts

@@ -1,10 +1,10 @@
 import { Clock, type ClockConfig } from './core/clock';
 import { EventBus } from './core/events';
 import { Rng } from './core/rng';
-import { InputState } from './input/actions';
+import { InputState, type AxisFrame } from './input/actions';
 import { Node, type WorldContext } from './scene/node';
 import type { Camera2D } from './scene/nodes';
-import { type Transform } from './core/math';
+import { type Transform, type Vec2 } from './core/math';
 import type { DrawCommand } from './render/commands';
 export interface WorldConfig {
     seed?: number;
@@ -12,12 +12,20 @@ export interface WorldConfig {
     /** Design-space dimensions (default 1280×720). */
     width?: number;
     height?: number;
+    /** Resolved tuning values (see app/tuning.ts). Sim state: hashed + snapshotted. */
+    tuning?: Record<string, number | string>;
+    /**
+     * Dev guard: during each step(), `Math.random`/`Date.now` are wrapped so a
+     * stray call inside the sim warns ONCE (with a stack hint) instead of
+     * silently breaking determinism. Never throws; safe to leave on in tests.
+     */
+    guardDeterminism?: boolean;
 }
 /** Default engine event map; games extend it with their own keys. */
 export interface CoreEvents {
     [key: string]: unknown;
 }
-export declare class World implements WorldContext {
+export declare class World<TState extends Record<string, unknown> = Record<string, unknown>> implements WorldContext {
     readonly rng: Rng;
     readonly clock: Clock;
     readonly input: InputState;
@@ -29,15 +37,45 @@ export declare class World implements WorldContext {
      * `hash()` and `snapshot()`, so hidden state here cannot escape determinism
      * checks the way ad-hoc module variables can.
      */
-    state: Record<string, unknown>;
+    state: TState;
     readonly width: number;
     readonly height: number;
+    /**
+     * Pause switch. While true, only `pauseMode: 'always'` subtrees update —
+     * rendering, input sampling, and the clock keep ticking, so a pause menu
+     * (an 'always' subtree) stays live. Sim state: hashed + snapshotted, but
+     * only when true, so pinned hashes of unpaused games are unchanged.
+     */
+    paused: boolean;
+    /**
+     * Sim-time multiplier: the tree receives `clock.dt * timeScale` (slow-mo /
+     * fast-forward), while `'always'` subtrees get the unscaled dt so UI keeps
+     * realtime feel. The clock itself ticks normally. Hashed/snapshotted only
+     * when ≠ 1.
+     */
+    timeScale: number;
     root: Node;
     activeCamera: Camera2D | null;
     private seed;
     private freeQueue;
     private started;
+    private tuningValues;
+    private guardDeterminism;
+    private warnedClamp;
+    private warnedNondet;
     constructor(config?: WorldConfig);
+    /**
+     * Read a tuning value resolved at world creation (declared default unless
+     * overridden). Throws on an undeclared key — a typo here would otherwise
+     * silently read `undefined` into the sim.
+     */
+    tune<T extends number | string = number>(key: string): T;
+    /**
+     * Read a shared resource by key. Throws on a missing key (listing what IS
+     * available) — a typo here would otherwise silently read `undefined` into
+     * the sim, exactly like an undeclared tuning knob.
+     */
+    resource<T>(key: string): T;
     get time(): number;
     get frame(): number;
     /** Replace the scene root, entering the tree. */
@@ -48,12 +86,69 @@ export declare class World implements WorldContext {
      * Advance exactly one fixed step with the given actions held down.
      * This is THE deterministic transition — call it from Node or the browser loop.
      */
-    step(actionsDown?: Iterable<string>): void;
-    /** Feed real elapsed ms; runs 0+ fixed steps. Returns steps run. */
-    advance(realMs: number, actionsDown?: Iterable<string>): number;
-    private flushFree;
+    step(actionsDown?: Iterable<string>, axes?: AxisFrame): void;
+    /**
+     * Wrap `Math.random`/`Date.now` for the duration of a step so a stray call
+     * inside the sim warns ONCE per world (with a stack hint) — the values still
+     * flow through, so nothing breaks mid-frame. Returns the restore function;
+     * properly nested re-entry (a world stepped inside another's step) is safe
+     * because each install restores exactly what it replaced.
+     */
+    private installGuard;
+    /**
+     * Feed REAL elapsed ms; runs 0+ fixed steps. Returns steps run. This is the
+     * realtime driver entry point — it CLAMPS realMs to the clock's maxFrameMs
+     * (default 250) to avoid a spiral of death, so `advance(1200)` runs ~15 steps,
+     * not 72. For headless tests/harnesses that want to fast-forward an exact
+     * number of steps, use `runSteps(n)` or `step()` — never `advance` with a big ms.
+     */
+    advance(realMs: number, actionsDown?: Iterable<string>, axes?: AxisFrame): number;
+    /**
+     * Run exactly `n` fixed steps — the deterministic fast-forward for tests and
+     * headless drivers (unlike `advance`, no realtime clamp). Pass `actionsFor(i)`
+     * to script the input per step; omit it to hold nothing down.
+     */
+    runSteps(n: number, actionsFor?: (i: number) => Iterable<string>, axesFor?: (i: number) => AxisFrame | undefined): void;
+    /**
+     * Run pending frees NOW instead of at the end of the step. `free()` is
+     * deferred (safe during iteration), which means freed nodes survive until
+     * the step ends — during a scene swap that lets old nodes contaminate the
+     * first frame of the new scene. Pattern: `oldRoot.free(); world.flushFree();
+     * buildNewScene()`. Called automatically at the end of every step.
+     */
+    flushFree(): void;
+    /** Visit every live node depth-first (root first, child-index order). */
+    walk(fn: (node: Node) => void): void;
+    /** Total live nodes in the tree (root included). */
+    get nodeCount(): number;
+    /**
+     * One indented line per node — `name (type) [flags] @x,y` — for quick tree
+     * audits in a REPL or test failure message.
+     */
+    debugTree(): string;
+    /** The active camera's world position + zoom, or null (see WorldContext.camera). */
+    camera(): {
+        pos: {
+            x: number;
+            y: number;
+        };
+        zoom: number;
+    } | null;
     /** The view transform (inverse of the active camera), mapping world → screen. */
     viewTransform(): Transform;
+    /**
+     * Map a world-space point to screen/design space (the forward view transform).
+     * With no active camera this is the identity, so world == screen.
+     */
+    worldToScreen(p: Vec2): Vec2;
+    /**
+     * Map a screen/design-space point back to world space — the inverse of the
+     * view transform. Use this to turn a pointer position (in design units) into
+     * a world coordinate under a scrolled/zoomed camera. Keep raw pointer values
+     * OUT of the sim: convert at the host edge and feed the result in as a
+     * quantized action/axis, or determinism breaks (see docs/CONVENTIONS.md).
+     */
+    screenToWorld(p: Vec2): Vec2;
     /** Project the whole scene to a display list (already camera-applied). */
     render(): DrawCommand[];
     /** Deterministic structural hash of the whole sim state. */
@@ -72,4 +167,10 @@ export interface WorldSnapshot {
     input: ReturnType<InputState['getState']>;
     state: Record<string, unknown>;
     tree: ReturnType<Node['serialize']>;
+    /** Resolved tuning values (absent in pre-tuning saves). */
+    tuning?: Record<string, number | string>;
+    /** Pause flag (absent when false — keeps old snapshots byte-identical). */
+    paused?: boolean;
+    /** Sim-time multiplier (absent when 1). */
+    timeScale?: number;
 }