@driftengine/network 3.61.0

package/dist/inputLog.d.ts

@@ -0,0 +1,117 @@
+/**
+ * What every participant did on every retained tick, and what was guessed for them.
+ *
+ * **An input is a fixed number of bytes a consumer declares.** That is a constraint and it buys the
+ * whole allocation story: one `Uint8Array` for the session, indexed by participant and tick, so
+ * neither recording an input nor reading one back during a replay allocates anything. It costs a
+ * consumer having to fit an input into a known size, which for a simulation input is what they
+ * already are — a bitfield of buttons and a couple of axes — and it refuses the one shape that
+ * would break it, which is an input carrying a variable-length payload like a chat message. Those
+ * are not simulation inputs and do not belong on this path.
+ *
+ * **A predicted input is stored, not computed on read.** A replay has to see the same guess the
+ * first run saw, or the ticks it re-runs differ from the ticks it is replaying for a reason that has
+ * nothing to do with the correction being applied. So a missing input is guessed *once*, written
+ * into its slot and marked unconfirmed; a later real input overwrites it and says whether it
+ * differed.
+ *
+ * ---
+ *
+ * ## The window is explicit, because a ring that evicts silently is the bug here
+ *
+ * The obvious shape is a ring indexed by `tick % depth`, and it is wrong in a way that only shows
+ * up on a real link. Inputs arrive **ahead** of the local simulation — a peer three ticks in front
+ * sends tick 45 while this one is simulating 42 — and with a depth of eight, tick 45 lands in the
+ * slot tick 37 occupies. Tick 37 is inside the rewind window and its confirmed input has just been
+ * thrown away, so a rewind to 37 re-predicts an input it already knew, and the world quietly
+ * changes under a correction that was supposed to be about something else.
+ *
+ * So the window is a range this log is told about. `retain(oldest)` moves it, dropping what falls
+ * off the back; a tick outside it is **refused** rather than stored somewhere convenient. A depth
+ * therefore has to cover the rewind distance behind the current tick *and* the lookahead in front
+ * of it, which is why the session that owns one sizes it as the sum and not as the rewind depth.
+ *
+ * ## Repeat-the-last, and why the default is stated rather than hidden
+ *
+ * A missing input is guessed by repeating that participant's last known one. That is right for a
+ * held control and wrong for a tap, and nothing in an engine can know which a given game has: a
+ * racing game's throttle is held, a fighting game's punch is not. So the default is documented and
+ * `predict` is replaceable.
+ */
+/** How a missing input is guessed. `previous` is that participant's last confirmed input. */
+export type InputPredictor = (participant: number, tick: number, previous: Uint8Array, out: Uint8Array) => void;
+/** Repeat the last input seen from that participant. See the header for when this is wrong. */
+export declare const repeatLastInput: InputPredictor;
+export interface InputLogOptions {
+    readonly participants: number;
+    /**
+     * Retained ticks, covering the rewind window behind the current tick **and** the inputs that
+     * arrive ahead of it. See the header: this is not the rewind depth.
+     */
+    readonly depth: number;
+    readonly inputBytes: number;
+    readonly predict?: InputPredictor;
+}
+export declare class InputLog {
+    readonly participants: number;
+    readonly depth: number;
+    readonly inputBytes: number;
+    private readonly bytes;
+    /** Which tick each (participant, slot) holds, or -1. */
+    private readonly slotTick;
+    /** 1 when the value in the slot came from that participant, 0 when it was guessed. */
+    private readonly confirmed;
+    /** The last confirmed input per participant, for the predictor. */
+    private readonly previous;
+    private readonly scratch;
+    private readonly predict;
+    /** The oldest tick this log will accept. The window is `[oldest, oldest + depth)`. */
+    private oldest;
+    constructor(options: InputLogOptions);
+    /** The oldest tick this log holds. Everything below it has been dropped. */
+    get windowStart(): number;
+    /** One past the newest tick this log will accept. */
+    get windowEnd(): number;
+    /** Whether a tick is inside the window at all. */
+    holds(tick: number): boolean;
+    /**
+     * Move the window so `oldest` is the earliest tick kept, forgetting what falls off.
+     *
+     * The slots that leave are cleared rather than left, because their `slotTick` would otherwise
+     * match a tick a whole window later and answer a stale input as a confirmed one.
+     */
+    retain(oldest: number): void;
+    /**
+     * Record a real input. **`true` when this changed what the slot held**, which is what tells a
+     * rewind whether it has anything to do. `false` also means refused, for a tick outside the
+     * window — see `holds` to tell the two apart when it matters.
+     *
+     * A confirmed input matching the guess is the common case on a held control, and replaying for
+     * it would burn a rewind to produce the identical world.
+     */
+    set(participant: number, tick: number, payload: Uint8Array): boolean;
+    /**
+     * The input to simulate with, guessing and storing one if none has arrived.
+     *
+     * **`false` means it was guessed**, or that the tick is outside the window, in which case `out` is
+     * zeroed. A caller deciding whether a tick can be confirmed reads that; a caller simulating does
+     * not care, because either way `out` holds the bytes this tick ran with, now and on every replay.
+     */
+    into(participant: number, tick: number, out: Uint8Array): boolean;
+    /** Whether a real input for this participant and tick has arrived. */
+    isConfirmed(participant: number, tick: number): boolean;
+    /** Whether every participant's input for this tick has arrived. What lockstep advances on. */
+    isComplete(tick: number): boolean;
+    /**
+     * The highest tick at or below `upTo` such that **every** tick from the window's start up to it is
+     * complete, or -1.
+     *
+     * Walked upward from the start of the window and stopped at the first gap, which is the property
+     * that matters: ticks 40 and 42 confirmed with 41 missing is not a session confirmed to 42, and
+     * answering 42 would let a peer discard the snapshot it still needs to correct 41.
+     */
+    confirmedThrough(upTo: number): number;
+    /** The newest tick this participant has a confirmed input for, or -1. */
+    private newestConfirmed;
+    private slotOf;
+}

package/dist/inputLog.js

@@ -0,0 +1,232 @@
+/**
+ * What every participant did on every retained tick, and what was guessed for them.
+ *
+ * **An input is a fixed number of bytes a consumer declares.** That is a constraint and it buys the
+ * whole allocation story: one `Uint8Array` for the session, indexed by participant and tick, so
+ * neither recording an input nor reading one back during a replay allocates anything. It costs a
+ * consumer having to fit an input into a known size, which for a simulation input is what they
+ * already are — a bitfield of buttons and a couple of axes — and it refuses the one shape that
+ * would break it, which is an input carrying a variable-length payload like a chat message. Those
+ * are not simulation inputs and do not belong on this path.
+ *
+ * **A predicted input is stored, not computed on read.** A replay has to see the same guess the
+ * first run saw, or the ticks it re-runs differ from the ticks it is replaying for a reason that has
+ * nothing to do with the correction being applied. So a missing input is guessed *once*, written
+ * into its slot and marked unconfirmed; a later real input overwrites it and says whether it
+ * differed.
+ *
+ * ---
+ *
+ * ## The window is explicit, because a ring that evicts silently is the bug here
+ *
+ * The obvious shape is a ring indexed by `tick % depth`, and it is wrong in a way that only shows
+ * up on a real link. Inputs arrive **ahead** of the local simulation — a peer three ticks in front
+ * sends tick 45 while this one is simulating 42 — and with a depth of eight, tick 45 lands in the
+ * slot tick 37 occupies. Tick 37 is inside the rewind window and its confirmed input has just been
+ * thrown away, so a rewind to 37 re-predicts an input it already knew, and the world quietly
+ * changes under a correction that was supposed to be about something else.
+ *
+ * So the window is a range this log is told about. `retain(oldest)` moves it, dropping what falls
+ * off the back; a tick outside it is **refused** rather than stored somewhere convenient. A depth
+ * therefore has to cover the rewind distance behind the current tick *and* the lookahead in front
+ * of it, which is why the session that owns one sizes it as the sum and not as the rewind depth.
+ *
+ * ## Repeat-the-last, and why the default is stated rather than hidden
+ *
+ * A missing input is guessed by repeating that participant's last known one. That is right for a
+ * held control and wrong for a tap, and nothing in an engine can know which a given game has: a
+ * racing game's throttle is held, a fighting game's punch is not. So the default is documented and
+ * `predict` is replaceable.
+ */
+/** Repeat the last input seen from that participant. See the header for when this is wrong. */
+export const repeatLastInput = (_participant, _tick, previous, out) => {
+    out.set(previous);
+};
+export class InputLog {
+    participants;
+    depth;
+    inputBytes;
+    bytes;
+    /** Which tick each (participant, slot) holds, or -1. */
+    slotTick;
+    /** 1 when the value in the slot came from that participant, 0 when it was guessed. */
+    confirmed;
+    /** The last confirmed input per participant, for the predictor. */
+    previous;
+    scratch;
+    predict;
+    /** The oldest tick this log will accept. The window is `[oldest, oldest + depth)`. */
+    oldest = 0;
+    constructor(options) {
+        this.participants = Math.max(1, Math.trunc(options.participants));
+        this.depth = Math.max(1, Math.trunc(options.depth));
+        this.inputBytes = Math.max(1, Math.trunc(options.inputBytes));
+        this.predict = options.predict ?? repeatLastInput;
+        const slots = this.participants * this.depth;
+        this.bytes = new Uint8Array(slots * this.inputBytes);
+        this.slotTick = new Int32Array(slots).fill(-1);
+        this.confirmed = new Uint8Array(slots);
+        this.previous = new Uint8Array(this.participants * this.inputBytes);
+        this.scratch = new Uint8Array(this.inputBytes);
+    }
+    /** The oldest tick this log holds. Everything below it has been dropped. */
+    get windowStart() {
+        return this.oldest;
+    }
+    /** One past the newest tick this log will accept. */
+    get windowEnd() {
+        return this.oldest + this.depth;
+    }
+    /** Whether a tick is inside the window at all. */
+    holds(tick) {
+        return tick >= this.oldest && tick < this.oldest + this.depth;
+    }
+    /**
+     * Move the window so `oldest` is the earliest tick kept, forgetting what falls off.
+     *
+     * The slots that leave are cleared rather than left, because their `slotTick` would otherwise
+     * match a tick a whole window later and answer a stale input as a confirmed one.
+     */
+    retain(oldest) {
+        const next = Math.max(0, Math.trunc(oldest));
+        if (next <= this.oldest)
+            return;
+        for (let p = 0; p < this.participants; p++) {
+            for (let slot = 0; slot < this.depth; slot++) {
+                const index = p * this.depth + slot;
+                const at = this.slotTick[index];
+                if (at >= 0 && at < next) {
+                    this.slotTick[index] = -1;
+                    this.confirmed[index] = 0;
+                }
+            }
+        }
+        this.oldest = next;
+    }
+    /**
+     * Record a real input. **`true` when this changed what the slot held**, which is what tells a
+     * rewind whether it has anything to do. `false` also means refused, for a tick outside the
+     * window — see `holds` to tell the two apart when it matters.
+     *
+     * A confirmed input matching the guess is the common case on a held control, and replaying for
+     * it would burn a rewind to produce the identical world.
+     */
+    set(participant, tick, payload) {
+        const slot = this.slotOf(participant, tick);
+        if (slot < 0)
+            return false;
+        const at = slot * this.inputBytes;
+        /*
+         * **Changed means the bytes changed, and deliberately not "was unconfirmed and now is".**
+         * A guess that turns out byte-identical to the real input costs a replay nothing, because the
+         * replay would re-run the same ticks with the same values and arrive at the same world. On any
+         * held control that is the common case, so treating confirmation as a change would burn a
+         * rewind per packet to reproduce what is already on screen. What confirmation changes is
+         * `confirmedThrough`, which is a different question from whether the world is wrong.
+         */
+        const held = this.slotTick[slot] === tick;
+        let changed = !held;
+        if (held) {
+            for (let i = 0; i < this.inputBytes; i++) {
+                if (this.bytes[at + i] !== (payload[i] ?? 0)) {
+                    changed = true;
+                    break;
+                }
+            }
+        }
+        for (let i = 0; i < this.inputBytes; i++)
+            this.bytes[at + i] = payload[i] ?? 0;
+        this.slotTick[slot] = tick;
+        this.confirmed[slot] = 1;
+        /* The newest confirmed input is what the predictor repeats, so an input arriving out of order
+           must not overwrite a newer one. */
+        if (this.newestConfirmed(participant) <= tick) {
+            const previousAt = participant * this.inputBytes;
+            for (let i = 0; i < this.inputBytes; i++)
+                this.previous[previousAt + i] = payload[i] ?? 0;
+        }
+        return changed;
+    }
+    /**
+     * The input to simulate with, guessing and storing one if none has arrived.
+     *
+     * **`false` means it was guessed**, or that the tick is outside the window, in which case `out` is
+     * zeroed. A caller deciding whether a tick can be confirmed reads that; a caller simulating does
+     * not care, because either way `out` holds the bytes this tick ran with, now and on every replay.
+     */
+    into(participant, tick, out) {
+        const slot = this.slotOf(participant, tick);
+        if (slot < 0) {
+            out.fill(0);
+            return false;
+        }
+        const at = slot * this.inputBytes;
+        if (this.slotTick[slot] !== tick) {
+            const previousAt = participant * this.inputBytes;
+            for (let i = 0; i < this.inputBytes; i++) {
+                this.scratch[i] = this.previous[previousAt + i];
+            }
+            this.predict(participant, tick, this.scratch, out);
+            for (let i = 0; i < this.inputBytes; i++)
+                this.bytes[at + i] = out[i] ?? 0;
+            this.slotTick[slot] = tick;
+            this.confirmed[slot] = 0;
+            return false;
+        }
+        for (let i = 0; i < this.inputBytes; i++)
+            out[i] = this.bytes[at + i];
+        return this.confirmed[slot] === 1;
+    }
+    /** Whether a real input for this participant and tick has arrived. */
+    isConfirmed(participant, tick) {
+        const slot = this.slotOf(participant, tick);
+        if (slot < 0)
+            return false;
+        return this.slotTick[slot] === tick && this.confirmed[slot] === 1;
+    }
+    /** Whether every participant's input for this tick has arrived. What lockstep advances on. */
+    isComplete(tick) {
+        for (let p = 0; p < this.participants; p++) {
+            if (!this.isConfirmed(p, tick))
+                return false;
+        }
+        return true;
+    }
+    /**
+     * The highest tick at or below `upTo` such that **every** tick from the window's start up to it is
+     * complete, or -1.
+     *
+     * Walked upward from the start of the window and stopped at the first gap, which is the property
+     * that matters: ticks 40 and 42 confirmed with 41 missing is not a session confirmed to 42, and
+     * answering 42 would let a peer discard the snapshot it still needs to correct 41.
+     */
+    confirmedThrough(upTo) {
+        let answer = -1;
+        for (let at = this.oldest; at <= upTo && at < this.oldest + this.depth; at++) {
+            if (!this.isComplete(at))
+                break;
+            answer = at;
+        }
+        return answer;
+    }
+    /** The newest tick this participant has a confirmed input for, or -1. */
+    newestConfirmed(participant) {
+        let newest = -1;
+        for (let slot = 0; slot < this.depth; slot++) {
+            const index = participant * this.depth + slot;
+            if (this.confirmed[index] !== 1)
+                continue;
+            const at = this.slotTick[index];
+            if (at > newest)
+                newest = at;
+        }
+        return newest;
+    }
+    slotOf(participant, tick) {
+        if (participant < 0 || participant >= this.participants)
+            return -1;
+        if (!this.holds(tick))
+            return -1;
+        return participant * this.depth + (tick % this.depth);
+    }
+}

package/dist/lockstep.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Every peer simulates every tick, and a wrong guess is unwound.
+ *
+ * **Classic lockstep stalls; this predicts.** The original design waits until every participant's
+ * input for a tick has arrived and only then advances, which makes the whole session run at the
+ * latency of its worst link and turns a single dropped packet into a visible freeze for everyone.
+ * With a rewind loop underneath, a missing input can be guessed and corrected — so the session runs
+ * at local speed and pays for a wrong guess only when the guess was wrong.
+ *
+ * ---
+ *
+ * ## The input delay, and why it is not just latency tolerance
+ *
+ * A local input for tick *T* is published for tick *T + delay*. That buys `delay` ticks for it to
+ * reach everyone before anybody needs it, so on a link inside that budget **nobody predicts and
+ * nobody rewinds** — the session is exact, not merely convergent.
+ *
+ * What it costs is that a player's own control is `delay` ticks late on their own screen. That is a
+ * real cost and it is a game's to choose: two ticks is 33 ms and unnoticeable in a racing game,
+ * and unacceptable in a fighting game where it is the whole argument for rollback.
+ *
+ * ## Halting is a feature
+ *
+ * Two things stop the session rather than degrade it, because both mean the local world can no
+ * longer be made correct:
+ *
+ * - **An input arrives for a tick outside the rewind window.** It cannot be applied, so this peer's
+ *   world is permanently different from the one that input describes.
+ * - **A fingerprint disagrees at a confirmed tick.** Two peers computed different worlds from the
+ *   same inputs, which is a determinism bug rather than a networking one, and continuing produces
+ *   two games that both believe they are right.
+ *
+ * A session that carried on would be showing each player a plausible world with no relationship to
+ * anyone else's. Halting names the tick, which is where the debugging starts.
+ */
+import { Fingerprint } from './fingerprint.ts';
+import type { InputLog } from './inputLog.ts';
+import type { RewindLoop } from './rewind.ts';
+import { type PeerId, type Transport } from './transport.ts';
+export type LockstepStatus = 'running' | 'halted';
+export interface LockstepOptions<S> {
+    readonly transport: Transport;
+    readonly loop: RewindLoop<S>;
+    readonly inputs: InputLog;
+    /** This peer's id, and the index its inputs occupy in the log. */
+    readonly self: PeerId;
+    readonly participants: number;
+    /**
+     * How many ticks ahead a local input is published. Two is 33 ms at 60 Hz.
+     *
+     * See the header: inside this budget the session is exact rather than convergent.
+     */
+    readonly inputDelay?: number;
+    /**
+     * How often a fingerprint is published, in ticks. Every tick is wasteful and every hundred is
+     * slow to notice; the default is every eight, which at 60 Hz is seven a second.
+     */
+    readonly fingerprintEvery?: number;
+    /** Publish fingerprints at all. Off needs no digest from the snapshotter. */
+    readonly compareStates?: boolean;
+    /**
+     * How many recent inputs ride along in every packet. Four by default.
+     *
+     * **This is what makes lockstep survive loss, and one is not enough.** An input is only useful
+     * for the tick it names, so asking for a lost one and waiting a round trip delivers it after that
+     * tick has gone — the peer's world is then permanently different and nothing local repairs it.
+     * Sending the last few in every packet covers a run of drops before anybody notices, for a
+     * handful of bytes on a message that already has a header.
+     *
+     * Four covers three consecutive losses. A link losing four in a row at 60 Hz has stopped being a
+     * link.
+     *
+     * **It may reach further back than the rewind window without any arrangement between the two.**
+     * The session forgets inputs below the oldest tick a rewind can reach, so past that depth every
+     * packet's oldest words name ticks the log can no longer say anything about. Those are skipped on
+     * the strength of what this world already applied, not on what the log still holds — see the
+     * watermark in `receive`. Choose this number for the link and the rewind depth for the game.
+     */
+    readonly redundancy?: number;
+}
+export interface Desync {
+    readonly tick: number;
+    readonly peer: PeerId;
+    readonly ours: string;
+    readonly theirs: string;
+}
+export declare class LockstepSession<S> {
+    readonly self: PeerId;
+    readonly participants: number;
+    readonly inputDelay: number;
+    private readonly transport;
+    private readonly loop;
+    private readonly inputs;
+    private readonly fingerprintEvery;
+    private readonly compareStates;
+    /** One buffer for the process. Sized for the largest message this session sends. */
+    private readonly outgoing;
+    /** The last `redundancy` inputs this peer submitted, oldest first, flat. */
+    private readonly recent;
+    private readonly redundancy;
+    /** The tick the first payload in `recent` belongs to, or -1 before anything is submitted. */
+    private recentFrom;
+    private recentCount;
+    private readonly decoded;
+    private readonly scratchDigest;
+    /** Digests we published, by tick, so a peer's claim has something to be compared against. */
+    private readonly ourDigests;
+    private statusValue;
+    private desyncValue;
+    private haltReason;
+    private confirmedValue;
+    /**
+     * The highest tick this world has ever had every participant's real input for.
+     *
+     * **Separate from `confirmedValue`, and monotonic where that one is not.** `confirmedThrough`
+     * answers for the window the log currently holds, and the session moves that window forward every
+     * tick — so the moment retention passes a tick, the log stops being able to say anything about it
+     * and the live watermark can drop. What was applied stays applied, which is the fact a redundant
+     * copy has to be judged against, so it is kept here rather than asked of the log.
+     */
+    private appliedThrough;
+    constructor(options: LockstepOptions<S>);
+    get status(): LockstepStatus;
+    /** Why the session halted, or an empty string. */
+    get reason(): string;
+    /** The disagreement that halted it, naming the tick it began at. */
+    get desync(): Desync | null;
+    /** The highest tick every participant's real input has arrived for. */
+    get confirmed(): number;
+    /**
+     * Publish this peer's input for `tick + inputDelay`, and record it locally at the same tick.
+     *
+     * **Recorded locally as well as sent, and that is not redundancy.** A peer's own input is not
+     * echoed back to it, so without this the local simulation would predict its own controls — and a
+     * player would feel their own input arrive late and get corrected, which is the one thing
+     * prediction is supposed to prevent.
+     */
+    submit(tick: number, payload: Uint8Array): void;
+    /**
+     * Keep this input, and the few before it, for the next packet to carry.
+     *
+     * Shifted rather than kept in a ring, because the run has to be **contiguous and in order** on
+     * the wire: a receiver reads it as "these are the inputs for ticks `firstTick` onward", and a ring
+     * would have to be unwrapped before sending anyway. `redundancy` is four, so the shift is three
+     * copies of a handful of bytes.
+     */
+    private remember;
+    /**
+     * Take everything the transport has and apply it.
+     *
+     * Called once per tick, before advancing. Never from a transport callback — see `transport.ts`
+     * for why a message must not arrive in the middle of a step.
+     */
+    poll(): void;
+    /**
+     * Advance one tick, then publish a fingerprint if this is a tick to publish one at.
+     *
+     * The rewind loop performs any pending correction first, so a late input that arrived during
+     * `poll` is applied before this tick runs rather than after it.
+     */
+    advance(dt: number, tick: number): void;
+    /**
+     * Publish a hash of the state at a **confirmed** tick, which is the only state worth comparing.
+     *
+     * **Not the live world, and this cost a healthy session at tick 32 during development.** The
+     * newest tick is speculative: each peer has predicted inputs the other already knows, so their
+     * live worlds differ constantly and correctly. A snapshot at a tick every participant's input has
+     * arrived for was computed from the same inputs on both ends, and a disagreement there is a real
+     * one.
+     *
+     * The slot for tick *T* holds the state as *T* began, so it is final once every input below *T*
+     * is confirmed — which is what `confirmedThrough` answers.
+     */
+    private publishDigest;
+    /** Stop the session with a reason. Public so a consumer can halt on their own condition. */
+    halt(reason: string): void;
+    private receive;
+    private forgetDigestsBefore;
+    /** The shared digest builder, for a consumer whose `digestAt` wants one without allocating. */
+    get digestBuilder(): Fingerprint;
+}