hayao 0.2.0 → 0.4.0

package/dist/input/actions.d.ts

@@ -1,12 +1,50 @@
-/** action name → physical key codes (KeyboardEvent.code strings). */
-export type InputMap = Record<string, string[]>;
+/**
+ * action name → physical bindings (KeyboardEvent.code strings, or pointer
+ * buttons `mouse.left` / `mouse.right` / `mouse.middle`). Readonly on both
+ * levels so `as const` maps type-check without casts.
+ */
+export type InputMap = Readonly<Record<string, readonly string[]>>;
+/** Per-frame analog axis values (already quantized). Recorded into the log + hash. */
+export type AxisFrame = Record<string, number>;
 export declare class InputState {
     private down;
     private prev;
-    /** Analog axes (e.g. from gamepad or pointer), sampled per step. */
+    /**
+     * Analog axes (e.g. from pointer or gamepad), sampled per step. By default
+     * these are LIVE host samples — NOT hashed or logged (see PointerSource).
+     * Axes passed to `beginFrame`'s second argument are the exception: they are
+     * *logged* (enter `getState()` → hash, and the input log), so quantized analog
+     * aim replays bit-exactly. Both live and logged values read back via `axis()`.
+     */
     readonly axes: Map<string, number>;
-    /** Engine: set which actions are down this step (from live input or replay). */
-    beginFrame(actionsDown: Iterable<string>): void;
+    /** The subset of axes that are part of the deterministic log + hash this frame. */
+    private logged;
+    /**
+     * Action names some source has declared it can produce (null until the first
+     * declareActions call). Headless worlds with no sources never declare, so
+     * they never warn — the typo guard only arms once a host wires real input.
+     */
+    private declared;
+    /** Unknown names already warned about (warn ONCE per name). */
+    private warned;
+    /**
+     * Register action names a source (or input map) can produce. The browser
+     * driver declares the keyboard map's actions and the pointer's `mouse.*`
+     * buttons; custom sources should declare theirs too. Once at least one
+     * declaration has happened, querying an undeclared action name via
+     * `isDown`/`justPressed`/`justReleased` logs a console.warn ONCE per name —
+     * catching `isDown('jmup')` typos that would otherwise fail silently.
+     */
+    declareActions(names: Iterable<string>): void;
+    /** Warn-once guard for querying an action no source has declared. O(1). */
+    private checkDeclared;
+    /**
+     * Engine: set which actions are down this step (from live input or replay).
+     * `axes` (optional) are QUANTIZED analog values that become part of the log
+     * and hash for this frame — use `snapAxis`/`quantizeAngle` at the host edge so
+     * replay and lockstep netplay reproduce analog aim exactly.
+     */
+    beginFrame(actionsDown: Iterable<string>, axes?: AxisFrame): void;
     isDown(action: string): boolean;
     justPressed(action: string): boolean;
     justReleased(action: string): boolean;
@@ -16,25 +54,41 @@ export declare class InputState {
     getState(): {
         down: string[];
         prev: string[];
+        axes?: Array<[string, number]>;
     };
     setState(s: {
         down: string[];
         prev: string[];
+        axes?: Array<[string, number]>;
     }): void;
 }
+/**
+ * Quantize an analog value into `buckets` levels across `[min,max]` and return
+ * the SNAPPED value (deterministic — same input → same output on every engine).
+ * Feed the result through `beginFrame`'s axes so analog input is replay-exact.
+ */
+export declare function snapAxis(value: number, buckets: number, min?: number, max?: number): number;
+/** Snap an angle (radians) to the nearest of `buckets` evenly-spaced headings. */
+export declare function quantizeAngle(radians: number, buckets: number): number;
 /** Map a set of raw key codes to the set of actions they trigger. */
 export declare function keysToActions(map: InputMap, keysDown: Set<string>): string[];
 /** Records the per-frame action-down sets → a compact, replayable input log. */
 export declare class InputRecorder {
     private frames;
-    record(actionsDown: string[]): void;
+    private axes;
+    private anyAxes;
+    record(actionsDown: string[], axes?: AxisFrame): void;
     get length(): number;
     toLog(): InputLog;
 }
 export interface InputLog {
     frames: string[][];
+    /** Optional per-frame quantized analog axes, aligned to `frames` (absent = none). */
+    axes?: Array<AxisFrame | undefined>;
 }
 /** Replays a recorded log: returns the action set for frame index i. */
 export declare function frameActions(log: InputLog, i: number): string[];
+/** The logged analog axes for frame index i, or undefined if none were recorded. */
+export declare function frameAxes(log: InputLog, i: number): AxisFrame | undefined;
 /** A default set of common bindings games can start from. */
 export declare const DEFAULT_INPUT_MAP: InputMap;

package/dist/input/gamepad.d.ts

@@ -0,0 +1,101 @@
+import { type InputState } from './actions';
+import type { KeyboardSource } from './source';
+/** A mapping from Gamepad.buttons indices to action names. */
+export type GamepadMap = Record<number, string>;
+export interface GamepadSourceOptions {
+    /**
+     * Gamepad index (0–3). Default 0.
+     * Tip: listen for the 'gamepadconnected' event to discover the right index;
+     * the first connected controller is always index 0.
+     */
+    index?: number;
+    /**
+     * Bucket count for quantizing analog stick values (±1 range).
+     * Higher = finer precision, larger axes log. Default 128 (~0.016 resolution).
+     */
+    stickBuckets?: number;
+    /**
+     * Bucket count for quantizing trigger values (0..1 range).
+     * Default 64 (~0.016 resolution).
+     */
+    triggerBuckets?: number;
+    /**
+     * Deadzone magnitude radius (0..1) applied to each stick independently before
+     * quantization. Values below this threshold are snapped to zero; above it the
+     * range is remapped to 0..1 so the output always uses the full scale.
+     * Default 0.12 (typical hardware drift).
+     */
+    deadzone?: number;
+    /**
+     * Gamepad button index → action name. Pressed buttons call
+     * `keyboard.setHeld(action, on)` so they enter the SAME deterministic action
+     * log as keys and are covered by record/replay + netplay.
+     * Defaults to DEFAULT_GAMEPAD_MAP (face buttons + d-pad mapped to common actions).
+     */
+    buttonMap?: GamepadMap;
+    /**
+     * The KeyboardSource to drive actions through. Required for button→action
+     * routing. Typically `handle.input` from the GameHandle returned by runBrowser.
+     */
+    keyboard?: KeyboardSource;
+}
+/**
+ * Axis keys written each step:
+ *
+ *   gamepad.lx / gamepad.ly   — left stick, ±1 (after deadzone + quantize)
+ *   gamepad.rx / gamepad.ry   — right stick, ±1
+ *   gamepad.lt / gamepad.rt   — left / right trigger, 0..1
+ *   gamepad.dpad.x            — d-pad horizontal, −1 / 0 / +1
+ *   gamepad.dpad.y            — d-pad vertical,   −1 / 0 / +1 (−1 = up)
+ *
+ * Read them in the sim with `world.input.axis('gamepad.lx')`.
+ *
+ * Determinism note: axes written by sample() are live host samples and are NOT
+ * part of the string input log or world.hash() by default. Buttons routed
+ * through a KeyboardSource DO enter the log. For bit-exact analog replay, pass
+ * quantized axes as the second argument to world.step(actions, axes) — they
+ * then enter getState() → hash and InputRecorder.
+ */
+export declare class GamepadSource {
+    private index;
+    private stickBuckets;
+    private triggerBuckets;
+    private deadzone;
+    private buttonMap;
+    private keyboard;
+    /** Track which buttons were pressed last frame to detect edge transitions. */
+    private prevPressed;
+    constructor(opts?: GamepadSourceOptions);
+    /**
+     * Write the current gamepad state into InputState axes (quantized). Call once
+     * per fixed step, before world.advance() — the browser driver does this via
+     * the `sources` option in RunOptions. See also: runBrowser, GameHandle.
+     */
+    sample(input: InputState): void;
+    /**
+     * Release all held actions and clean up. Call when removing the source or
+     * switching gamepads.
+     */
+    dispose(): void;
+}
+/**
+ * Standard Gamepad API button mapping for a "Standard Gamepad" layout
+ * (Xbox / PlayStation / Switch Pro controllers).
+ *
+ *   Index  Xbox        PlayStation   Action
+ *   0      A           Cross         confirm
+ *   1      B           Circle        cancel
+ *   2      X           Square        action2
+ *   3      Y           Triangle      action
+ *   8      Select/View Share         restart (hold to restart)
+ *   9      Start/Menu  Options       confirm (pause menu OK)
+ *   12     D-pad up                  up
+ *   13     D-pad down                down
+ *   14     D-pad left                left
+ *   15     D-pad right               right
+ *
+ * Triggers (6/7) and bumpers (4/5) are intentionally omitted — their analog
+ * values are exposed as gamepad.lt / gamepad.rt axes instead, and games can
+ * add them to a custom map if they want discrete actions.
+ */
+export declare const DEFAULT_GAMEPAD_MAP: GamepadMap;

package/dist/input/source.d.ts

@@ -1,8 +1,25 @@
-import { type InputMap } from './actions';
+import { type InputMap, type InputState } from './actions';
+/**
+ * Minimal contract for a host-side input source. Implement this to feed any
+ * hardware (gamepad, MIDI, accelerometer, on-screen controls) into the sim's
+ * InputState.axes without touching the engine internals.
+ *
+ * The engine samples each registered source once per fixed step, BEFORE
+ * world.advance(). Register via RunOptions.sources or GameHandle.addSource().
+ */
+export interface InputSource {
+    /** Write quantized values into input.axes. Called before each world.advance(). */
+    sample(input: InputState): void;
+    /** Optional cleanup (remove listeners, release held actions). */
+    dispose?(): void;
+}
+import type { Vec2 } from '../core/math';
 export declare class KeyboardSource {
     private keysDown;
     /** Virtual action taps (from DOM buttons etc.) pending consumption by a step. */
     private pressed;
+    /** Sustained virtual actions (held on-screen controls) — persist until released. */
+    private held;
     private map;
     private target;
     private onDown;
@@ -11,6 +28,8 @@ export declare class KeyboardSource {
     constructor(map: InputMap, target?: Document | HTMLElement);
     /** The actions currently held down, as a stable sorted array. */
     currentActions(): string[];
+    /** The action names this source's map can produce (for InputState.declareActions). */
+    actionNames(): string[];
     /**
      * Virtually tap an action (DOM button, touch control). The tap is held until
      * at least one fixed step has sampled it — the driver calls clearPressed()
@@ -20,6 +39,119 @@ export declare class KeyboardSource {
     press(action: string): void;
     /** Consume pending virtual taps (driver-called after ≥1 step ran). */
     clearPressed(): void;
+    /**
+     * Sustain an action for as long as an on-screen control is held. Unlike
+     * `press()` (an edge-shaped tap cleared after one step), a held action models
+     * STATE: it stays in `currentActions()` every step until `setHeld(action,
+     * false)` / `releaseHeld(action)`. This is what a virtual joystick or
+     * hold-to-fire button wants — set it on drag-start, clear it on release, no
+     * re-press-per-frame. Held actions still flow through the same deterministic
+     * action set as keys.
+     */
+    setHeld(action: string, on?: boolean): void;
+    /** Release a sustained action (sugar for `setHeld(action, false)`). */
+    releaseHeld(action: string): void;
+    /** Drop all sustained actions (e.g. on blur / control teardown). */
+    clearHeld(): void;
     setMap(map: InputMap): void;
     dispose(): void;
 }
+/** A live pointer reading, in DESIGN space (already un-letterboxed). */
+export interface PointerReadout {
+    /** Design-space x. Falls outside 0..width when the pointer leaves the letterbox. */
+    x: number;
+    y: number;
+    /** Is the primary pointer/finger currently pressed? */
+    down: boolean;
+    /** Has the pointer ever produced an event (else x/y are a neutral 0,0)? */
+    active: boolean;
+    /** Stable per-touch id (from PointerEvent.pointerId). Absent on the primary hover readout. */
+    id?: number;
+}
+/** What a PointerSource needs from a renderer: the DOM node + the design mapper. */
+export interface PointerTarget {
+    readonly element?: HTMLElement | SVGElement;
+    toDesign?(clientX: number, clientY: number): Vec2;
+}
+export interface PointerSourceOptions {
+    /**
+     * Allow the browser's context menu on the attached element. Default false —
+     * the menu is suppressed (preventDefault on 'contextmenu') so right-click is
+     * usable as game input.
+     */
+    contextMenu?: boolean;
+    /**
+     * Route pointer buttons into the deterministic action pipeline: while a
+     * button is held, `sample()` calls `keyboard.setHeld('mouse.left' |
+     * 'mouse.right' | 'mouse.middle')` so buttons enter the SAME actionsDown log
+     * as keys — `justPressed('mouse.right')` works, replays stay exact, and an
+     * inputMap can bind them (`shield: ['mouse.right']`). The browser driver
+     * wires this to the GameHandle's KeyboardSource automatically.
+     */
+    keyboard?: KeyboardSource;
+}
+/** The pointer-button action names PointerSource can hold (via its keyboard). */
+export declare const MOUSE_ACTIONS: readonly ["mouse.left", "mouse.right", "mouse.middle"];
+/**
+ * Continuous pointer / touch input — the sibling of KeyboardSource for games
+ * driven by *where* the cursor is (slice, aim, drag, point-and-click, placement).
+ * It listens on the renderer's canvas, converts every event to DESIGN space via
+ * `renderer.toDesign`, and each fixed step writes the sample into InputState's
+ * analog axes: `pointer.x`, `pointer.y`, `pointer.down` (1/0), plus
+ * `pointer.right` / `pointer.middle` (1/0) for the secondary mouse buttons
+ * (the context menu is suppressed by default so right-click is usable — see
+ * PointerSourceOptions). Sim code then reads `world.input.axis('pointer.x')`
+ * — no out-of-engine letterbox glue. With `keyboard` wired, buttons also enter
+ * the action pipeline as `mouse.left/right/middle` (bindable in an inputMap,
+ * `justPressed`-able, replay-exact).
+ *
+ * Determinism note: axes are host-sampled live input and are NOT part of the
+ * string input log or the world hash. `sample()` QUANTIZES design coords to a
+ * 1/8-px grid so a recorded axes log (Studio sessions) replays bit-exactly —
+ * the sim only ever sees the quantized values, live or replayed. For lockstep
+ * netplay, still prefer discrete actions (map a tap to a key via
+ * KeyboardSource.press, or snap position to a grid cell). See docs/CONVENTIONS.md.
+ *
+ * Multitouch: `read()`/`sample()` describe the PRIMARY pointer (mouse or the
+ * most-recent finger) and are byte-identical to the single-pointer past. For
+ * dual-stick / multi-finger schemes, read every live touch via `readAll()` —
+ * each carries its stable `id` so you can tell which finger is which.
+ */
+export declare class PointerSource {
+    private clientX;
+    private clientY;
+    private isDown;
+    private rightDown;
+    private middleDown;
+    private seen;
+    /** Live touches by pointerId (a pressed finger/button); excludes hover-only mouse. */
+    private touches;
+    private target;
+    private el;
+    private keyboard;
+    private onMove;
+    private onDown;
+    private onUp;
+    private onCtx;
+    constructor(target: PointerTarget, opts?: PointerSourceOptions);
+    /** The current pointer position in design space + press state. */
+    read(): PointerReadout;
+    /**
+     * Every live (pressed) touch in DESIGN space, ordered by ascending id so the
+     * array is stable to iterate. Empty when nothing is pressed. This is the
+     * multitouch channel — a dual-stick game reads `left = touches[0]`, etc., or
+     * partitions by screen half.
+     */
+    readAll(): PointerReadout[];
+    /**
+     * Write the current sample into an InputState's axes as pointer.x / pointer.y /
+     * pointer.down, plus pointer.right / pointer.middle (0/1) for the secondary
+     * buttons. Call once per step (the browser driver does this before advance).
+     *
+     * When a keyboard is wired (PointerSourceOptions.keyboard), buttons are ALSO
+     * held as actions `mouse.left` / `mouse.right` / `mouse.middle` so they flow
+     * through the same deterministic actionsDown log as keys.
+     */
+    sample(input: InputState): void;
+    dispose(): void;
+}

package/dist/logic/coroutine.d.ts

@@ -0,0 +1,68 @@
+/** Resumes after `seconds` of accumulated sim time. */
+export declare function sleep(seconds: number): Wait;
+/** Resumes on the first step where `cond()` is true (checked once per step). */
+export declare function waitFor(cond: () => boolean): Wait;
+/** Resumes on the next step — yields one frame (e.g. to let a spawn render). */
+export declare function nextStep(): Wait;
+/**
+ * Resumes when ANY of the waits completes; the yield expression evaluates to
+ * the winning index (ties resolve to the lowest index — deterministic).
+ */
+export declare function race(...waits: Wait[]): Wait;
+/** Resumes when ALL of the waits have completed. */
+export declare function all(...waits: Wait[]): Wait;
+interface SleepWait {
+    kind: 'sleep';
+    left: number;
+}
+interface CondWait {
+    kind: 'cond';
+    cond: () => boolean;
+    /** Memo so a satisfied condition is never re-evaluated (inside all()). */
+    met?: boolean;
+}
+interface NextWait {
+    kind: 'next';
+    passed?: boolean;
+}
+interface RaceWait {
+    kind: 'race';
+    waits: Wait[];
+}
+interface AllWait {
+    kind: 'all';
+    waits: Wait[];
+}
+/** What a coroutine may yield. A `CoroutineHandle` yield joins that runner. */
+export type Wait = SleepWait | CondWait | NextWait | RaceWait | AllWait | CoroutineHandle;
+/** A started coroutine. `done` flips when it returns, throws, or is stopped. */
+export interface CoroutineHandle {
+    readonly name: string;
+    readonly done: boolean;
+    /** Kill the runner (its generator's finally blocks run via `return()`). */
+    stop(): void;
+}
+/**
+ * A deterministic scheduler for many concurrent coroutines. Owns no clock —
+ * call `step(dt)` from wherever your game advances (typically a brain node's
+ * `onUpdate`), so coroutine time IS sim time.
+ */
+export declare class Coroutines {
+    private runners;
+    /** Started since the last step boundary; adopted at the top of the next step. */
+    private pending;
+    private nextId;
+    /**
+     * Register a coroutine. Its body runs (up to the first yield) on the NEXT
+     * `step()` — never immediately, and never mid-step. Pass a `name` so a
+     * thrown generator warns something better than "co3".
+     */
+    start(gen: () => Generator<Wait, void, number>, name?: string): CoroutineHandle;
+    /** Advance every live runner by one fixed step, in insertion order. */
+    step(dt: number): void;
+    /** Stop every runner (including ones not yet adopted). */
+    stopAll(): void;
+    /** Live runner count (started-but-not-yet-stepped ones included). */
+    get active(): number;
+}
+export {};