@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/input/record.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Input recording and replay (ws/input-replay). A recorder sits beside an `Input` through its
+ * feed hook (`Input.onFeed`) and writes down, tick by tick, every feed call and the gamepad
+ * snapshot `update()` read. A playback feeds the same calls back into an `Input` before each
+ * `update()` and hands it the recorded pads, so an identical game sees identical `pressed`,
+ * `held`, `released` and `value` per tick. Neither changes how `Input` evaluates bindings.
+ *
+ * The recording is plain JSON: `{ version: 3, ticks: [...] }`, deltas only. A tick with events
+ * is `{ t, k?, b?, p?, w?, r?, d?, g?, ptr?, cx?, cs?, ui? }`; a run of ticks with none is
+ * `{ t, n }`.
+ * Version 2 (ws/input-5) adds the `ptr` lane (every pointer the dispatcher saw, so touch zones,
+ * gestures and a second thumb replay) and the observational `cx` and `cs`. Version 3
+ * (ws/input-7) stamps each `ptr` entry with its time, so a replayed tap, long-press or
+ * double-tap classifies as it did live. Versions 1 and 2 still parse and play. A recording may
+ * carry `tickMs`, its tick spacing (ws/input-9), which a playback given a tick `clock` advances
+ * it by per fed tick, so a replay at any `speed` keeps game time. The `ui` lane (ws/input-12)
+ * holds the overlay controls that fired on a tick, by stable id (`Input.control`); a playback
+ * replays them through `Input.replayControl` and an older reader skips them.
+ */
+import { type TickClock } from './clock.js';
+import type { Input } from './input.js';
+import type { PointerState } from './types.js';
+/** One gamepad as recorded: button values (1 when `pressed`) and axes. `null` for an empty slot. */
+export type PadSnapshot = {
+    buttons: number[];
+    axes: number[];
+} | null;
+/** A tick on which something was fed. Fields are present only when that kind of event happened. */
+export interface InputTickEvents {
+    /** Tick index, counted from the recorder's start. */
+    t: number;
+    /** Keys, in call order: `[code, 1]` down, `[code, 0]` up. */
+    k?: [string, 0 | 1][];
+    /** Mouse buttons, in call order: `[button, 1]` down, `[button, 0]` up. */
+    b?: [number, 0 | 1][];
+    /** The last pointer position fed this tick, client CSS px; the type when not `mouse`. */
+    p?: [number, number, PointerState['type']?];
+    /** Wheel delta summed over the tick. */
+    w?: [number, number];
+    /** `releaseAll` was called (replayed first on the tick). */
+    r?: 1;
+    /**
+     * A key went down after the tick's last pointer position was fed, so the keyboard is the
+     * `lastDevice`; the playback then feeds `p` before `k`. Absent, `p` is fed after `k`.
+     */
+    d?: 1;
+    /** The pads `update()` read, when they differ from the previous snapshot. */
+    g?: PadSnapshot[];
+    /**
+     * `Input.rumble` calls this tick, in call order: `[strong, weak, ms]` or `[strong, weak, ms,
+     * pad]`. Playback does not re-issue them (the game does, from the same inputs); they are kept
+     * so a replay can assert the game rumbled when it should.
+     */
+    rumble?: [number, number, number, number?][];
+    /**
+     * Every pointer event the attached dispatcher delivered this tick, in order (version 2): see
+     * `InputPointerEntry`. Consecutive moves of one pointer keep only the last. Playback dispatches
+     * them on the attached pointer target after the other lanes; without one they are skipped.
+     */
+    ptr?: InputPointerEntry[];
+    /**
+     * Context pushes (`[name, 1]`) and removals (`[name, 0]`) this tick, in order (version 2).
+     * Observational, like `rumble`: the game pushes them again from the same inputs.
+     */
+    cx?: [string, 0 | 1][];
+    /** Actions `consume`d this tick, in order (version 2). Observational. */
+    cs?: string[];
+    /**
+     * Overlay controls that fired this tick, by stable id, in order (`Input.control`, ws/input-12).
+     * Playback replays them after the other lanes, before the tick's `update()`
+     * (`Input.replayControl`), so a control's handler runs on its recorded tick.
+     */
+    ui?: string[];
+}
+/**
+ * One recorded pointer event: `[phase, id, device, clientX, clientY, button, primary, time]`,
+ * phase 0 down, 1 move, 2 up, 3 cancel, 4 leave; `primary` 1 or 0. `time` (version 3) is when
+ * the event happened, ms since the recorder started, on the recorder's clock (the linked
+ * gestures' `now`), rounded to 0.01 ms; version 2 entries have no `time`. A window blur is
+ * recorded as a cancel of every pointer still down.
+ */
+export type InputPointerEntry = [
+    0 | 1 | 2 | 3 | 4,
+    number,
+    'mouse' | 'touch' | 'pen',
+    number,
+    number,
+    number,
+    0 | 1,
+    number?
+];
+/** A run of `n` ticks starting at `t` on which nothing was fed. */
+export interface InputTickRun {
+    t: number;
+    n: number;
+}
+export type InputTick = InputTickEvents | InputTickRun;
+/** What `createInputRecorder` builds and `createInputPlayback` reads. Plain JSON. */
+export interface InputRecording {
+    /** 3 from ws/input-7 (`ptr` entries carry `time`); 2 (ws/input-5: `ptr`, `cx`, `cs`) and 1 still read. */
+    version: 1 | 2 | 3;
+    ticks: InputTick[];
+    /**
+     * Ms between ticks while recording (ws/input-9): the mean spacing on the recorder's clock
+     * (exactly the fixed step on a `createTickClock()`), or `Input.tickMs` when the recorder ran on
+     * the wall clock. A playback given a `clock` advances it by this per fed tick. Absent in
+     * recordings made before ws/input-9 and in a recording of no ticks.
+     */
+    tickMs?: number;
+}
+export interface InputRecorderOptions {
+    /** Capture the pads `update()` reads. Default true. */
+    pads?: boolean;
+    /**
+     * The clock pointer `time`s are stamped on (ws/input-7). Default: the clock of the gestures
+     * linked to the input when the recorder is made (`Gestures.now`), else the linked look's
+     * (`Look.clock`, ws/input-8), else `performance.now()`. With a `createTickClock()` shared by
+     * gestures and look, times are game time.
+     */
+    now?: () => number;
+}
+export interface InputRecorder {
+    /**
+     * Close the current tick. Called for you from `input.update()` (through the feed hook), so a
+     * game never calls it; it is public for driving a recorder by hand in tests.
+     */
+    tick(): void;
+    /** Uninstall the hook and return the recording (the same object as `recording`). */
+    stop(): InputRecording;
+    /** The recording so far, live. */
+    readonly recording: InputRecording;
+    /** Ticks recorded so far. */
+    readonly ticks: number;
+}
+export interface InputPlaybackOptions {
+    /** Ticks fed per `step()`. Default 1. See `InputPlayback.speed`. */
+    speed?: number;
+    /**
+     * The clock recorded pointer `time`s replay on (ws/input-7). Default: `clock` when given, else
+     * the clock of the gestures linked to the input when the playback is made (`Gestures.now`),
+     * else the linked look's (`Look.clock`, ws/input-8), else `performance.now()`. On a
+     * `createTickClock()` the replay is the same on every tick index whatever the wall time
+     * between `step()`s.
+     */
+    now?: () => number;
+    /**
+     * A tick clock the playback drives (ws/input-9): every fed tick advances it by `tickMs`, after
+     * the tick's events are fed and before its `update()`, as a fixed step does live. So
+     * `speed: 4` advances it 4 × `tickMs` per `step()`, and a long-press fires on the same recorded
+     * tick at any speed. Pass the clock the input's gestures and look run on, and stop advancing it
+     * from the game's own step while the playback is installed (`InputPlayback.clock` says which
+     * clock it drives). Omitted, the playback advances nothing (the default, as before).
+     */
+    clock?: TickClock;
+    /**
+     * Ms a fed tick advances `clock` by. Default: the recording's `tickMs`, else the input's
+     * `Input.tickMs` (for recordings made before ws/input-9).
+     */
+    tickMs?: number;
+}
+export interface InputPlayback {
+    /**
+     * Feed the next tick's events into the input (then the caller runs `input.update()`). With
+     * `speed` above 1, the extra ticks are fed and updated inside the call, so the input
+     * fast-forwards; the caller's game logic only sees the last one. Returns false when the
+     * recording is finished and nothing was fed.
+     */
+    step(): boolean;
+    /** True once every recorded tick has been fed. */
+    readonly done: boolean;
+    /** The next tick to feed. */
+    readonly tick: number;
+    /** Total ticks in the recording. */
+    readonly length: number;
+    /** Jump to a tick. The input gets `releaseAll()` first; skipped ticks are not fed. */
+    seek(tick: number): void;
+    /** Ticks per `step()` (an integer of at least 1). */
+    speed: number;
+    /** The tick clock this playback advances per fed tick (`InputPlaybackOptions.clock`), or null. */
+    readonly clock: TickClock | null;
+    /** Ms each fed tick advances `clock` by (`InputPlaybackOptions.tickMs`, resolved). */
+    readonly tickMs: number;
+    /** Uninstall the hook; `input.playback` is null again. */
+    detach(): void;
+}
+/** Called when a recording does not have the expected shape. */
+export declare class InputRecordingError extends Error {
+    constructor(message: string);
+}
+/** Total ticks a recording covers. */
+export declare function recordingLength(rec: InputRecording): number;
+/**
+ * Record everything `input` is fed. The recorder installs a feed hook and closes one tick per
+ * `input.update()`; `stop()` removes it. `input.recorder` points at it meanwhile.
+ */
+export declare function createInputRecorder<A extends string>(input: Input<A>, opts?: InputRecorderOptions): InputRecorder;
+/**
+ * Replay `recording` into `input`. Call `step()` before each `input.update()`; the input's
+ * `getGamepads` result is replaced by the recorded snapshot while the playback is installed.
+ * `input.playback` points at it until `detach()`.
+ */
+export declare function createInputPlayback<A extends string>(input: Input<A>, recording: InputRecording, opts?: InputPlaybackOptions): InputPlayback;
+/** The recording as a JSON string. */
+export declare function serializeRecording(rec: InputRecording): string;
+/**
+ * Parse and validate a recording (a JSON string or an already parsed value). Throws
+ * `InputRecordingError` on a wrong version or a malformed tick.
+ */
+export declare function parseRecording(source: string | unknown): InputRecording;