Documentation
    Preparing search index...

    Class ReplayRecorder

    Records a live session into a §34 replay document.

    A recorder is a small state machine — idle → recording → idle — and is reusable: ReplayRecorder.end returns it to idle, ready for another ReplayRecorder.begin.

    const recorder = new ReplayRecorder();
    recorder.begin(world, { fixedDeltaTime: 1 / 60, seed: 1337 });

    app.on("fixedUpdate", () => {
      recorder.recordInput(recorder.stepsRecorded, { thrust: input.thrust });
    });
    app.on("update", (time) => {
      recorder.recordFrame(time.fixedStepsThisFrame, time.droppedTime);
    });

    const recording = recorder.end();
    Index
    constructor
    framesRecorded inputsRecorded isRecording snapshotsRecorded stepsRecorded
    abort begin end recordFrame recordInput
    • get framesRecorded(): number

      Frames recorded so far.

      Returns number

    • get inputsRecorded(): number

      Inputs recorded so far.

      Returns number

    • get isRecording(): boolean

      Whether a session is open (between begin and end).

      Returns boolean

    • get snapshotsRecorded(): number

      Periodic snapshots captured so far (excluding the initial one).

      Returns number

    • get stepsRecorded(): number

      Simulation steps recorded so far — the sum of every ReplayRecorder.recordFrame's stepCount.

      Also the index of the next step to run, which is the step index an input recorded "now, for the step about to happen" belongs to.

      Returns number

    • Abandons an open session without producing a document, returning the recorder to its idle state.

      Idempotent, and safe to call from a finally: it never touches the target. ReplayRecorder.end finishes with the same reset, so the counters above describe the open session and read zero between sessions.

      Returns void

    • Opens a session and captures the initial snapshot — §34's "initial scene state", plus the adapter name and version the whole document is keyed on and, since 2026-08-06 (PH-6), the world configuration it was captured under, taken from ReplaySnapshot.configuration.

      Parameters

      Returns void

      FourError INVALID_APPLICATION_STATE if a session is already open

      TypeError if fixedDeltaTime or snapshotIntervalSteps is out of range, or metadata or the target's snapshot configuration is not representable JSON

    • Closes the session and returns the §34 document.

      The final checksum is read from the target here, at the end of the last recorded frame: a replay that reproduces the run must land on this exact uint32 (§33, §92).

      Returns ReplayRecording

      the canonical, deep-frozen recording

      FourError INVALID_APPLICATION_STATE if no session is open

    • Records one frame of the §10 fixed-step loop, and captures a periodic snapshot if one is due.

      Call this after the frame's fixed steps have run, with the numbers TimeState reports: how many fixed steps executed and how much time the maximumSubSteps clamp dropped.

      The recorder only ever sees the target between frames, so it cannot capture state at an exact multiple of snapshotIntervalSteps in the middle of a frame that ran several steps. It therefore captures at most one snapshot per frame, at the first frame boundary at or after each due multiple, and records the step index the snapshot actually corresponds to. The recorded step is always exact — the state after that many steps — while the cadence is approximate whenever frames run more than one step. Missed multiples are skipped rather than queued, so a long frame produces one snapshot, not five.

      Parameters

      • stepCount: number

        fixed steps executed this frame; a non-negative integer

      • droppedTime: number

        dropped simulation time this frame, in seconds; >= 0

      Returns void

      FourError INVALID_APPLICATION_STATE if no session is open

      RangeError if either argument is out of range

    • Records one external input against the simulation step it applies to (§34).

      The payload is validated as JSON and deep-copied, so a caller may hand over the same mutable object every frame without the recording collapsing to N copies of its final state. Inputs are kept in insertion order (plan §1, §33) — several inputs may share a step, and they replay in the order they were recorded.

      Parameters

      • step: number

        the simulation step the input applies to; a non-negative integer, not before the previously recorded input's step

      • payload: JsonValue

        any JSON value

      Returns void

      FourError INVALID_APPLICATION_STATE if no session is open

      RangeError if step is not a non-negative integer, or goes backwards

      TypeError if payload is not representable JSON

    Settings
    Member Visibility

    On This Page
    Constructors
    Accessors
    Methods