@series-inc/rundot-syncplay 5.23.0-beta.7

package/dist/networked-client.d.ts

@@ -0,0 +1,124 @@
+import type { EncodedInput } from './input-authority.js';
+import { type DeterministicSessionRole } from './session-wire.js';
+import type { OfflineSession, ReplayFile } from './types.js';
+/**
+ * Reusable client transport for game-agnostic deterministic multiplayer (§6 M4).
+ *
+ * A game (or the H5 host bridge) hands this a socket-like transport and a factory for the game's
+ * deterministic session. The client speaks the frozen `rdm-local-authority/v1` session protocol:
+ * it consumes `session-start` (slot + server-owned seed), predicts locally (repeating opponents'
+ * last confirmed input), submits `input`, and reconciles `confirmed-input` via rollback/resim.
+ * Only inputs cross the wire; the simulation runs entirely here. This is the same predict/rollback
+ * contract the M0 spike proved, packaged for real transports.
+ */
+export interface NetworkedClientTransport {
+    send(text: string): void;
+    onMessage(handler: (text: string) => void): void;
+}
+export interface NetworkedSyncplayClientOptions<State, Input> {
+    readonly transport: NetworkedClientTransport;
+    /** Build the game session once the server issues the seed and player count. */
+    readonly createSession: (params: {
+        seed: number;
+        playerCount: number;
+    }) => OfflineSession<State, Input>;
+    /** This client's own input for a tick (game-defined). */
+    readonly localInputForTick: (slot: number, tick: number) => Input;
+    readonly encodeInput: (input: Input) => EncodedInput;
+    /** Decode a wire input to a game input; MUST map the neutral substitute (canonical null) to the default. */
+    readonly decodeInput: (encoded: EncodedInput) => Input;
+    readonly maxPredictionTicks?: number;
+    /** Host wire envelope msgType carrying session messages. Default 'rdm'. */
+    readonly sessionMsgType?: string;
+    /**
+     * Auto-send a checksum-report whenever `appliedThrough` crosses a multiple
+     * of this cadence (M5.5). Aligned reports across clients are what let the
+     * authority quorum-validate donated snapshots; they also feed desync
+     * telemetry. Reports are read from the rolling snapshot buffer — never via
+     * `restoreToFrame`, which would rewind the live session. Default 120.
+     */
+    readonly checksumCadenceTicks?: number;
+    /**
+     * Wall-clock pacing + clock-drift correction (G1), consumed by
+     * {@link NetworkedSyncplayClient.pumpPaced}. The step-counted `pump()` path
+     * ignores all of this, so step-driven tests and existing callers are
+     * unaffected. Rates are per-tick error corrections in the Quantum
+     * TimeCorrectionRate / GGPO frames-behind family: the client measures RTT via
+     * `time-sync-ping/pong`, estimates the authority frontier, and nudges its
+     * local timescale inside [minTimescale, maxTimescale] so it neither stalls at
+     * the prediction cap (fast clock / short path) nor starves into permanent
+     * substitution (slow clock / long path).
+     */
+    readonly pacing?: NetworkedSyncplayClientPacingOptions;
+    /**
+     * Own-input scheduling delay in ticks (G2): input sampled while predicting
+     * tick T is bound and sent for tick T+delay, trading a fixed sliver of local
+     * latency for inputs that arrive before the authority's deadline (fewer
+     * substitutions of THIS client's input, shallower rollbacks for peers).
+     * With `maxTicks > minTicks` the delay auto-tunes from measured RTT
+     * (ping-adaptive, Quantum InputDelayMin/Max analog) — RTT measurement
+     * requires driving `pumpPaced`. Defaults to a static 0 (today's behavior).
+     */
+    readonly inputDelay?: NetworkedSyncplayClientInputDelayOptions;
+    /** Monotonic-enough clock for RTT measurement. Default Date.now. NEVER used by the sim. */
+    readonly now?: () => number;
+}
+export interface NetworkedSyncplayClientPacingOptions {
+    /** Interval between time-sync pings while pumpPaced is driven. Default 1000. */
+    readonly pingIntervalMs?: number;
+    /** Safety lead (ticks) kept over the input-arrival deadline. Default 2. */
+    readonly targetLeadTicks?: number;
+    /** Timescale clamp. Defaults 0.9 / 1.1 (±10%, imperceptible per Quantum/GGPO practice). */
+    readonly minTimescale?: number;
+    readonly maxTimescale?: number;
+    /** Timescale correction gain per tick of frame-advantage error. Default 0.02. */
+    readonly correctionPerTick?: number;
+    /** Catch-up cap: max frames stepped per pumpPaced call. Default 4. */
+    readonly maxStepsPerPump?: number;
+}
+export interface NetworkedSyncplayClientInputDelayOptions {
+    /** Minimum (and initial) own-input delay in ticks. Default 0. */
+    readonly minTicks?: number;
+    /** Maximum delay for ping-adaptive tuning. Default = minTicks (static). */
+    readonly maxTicks?: number;
+}
+/** Live netcode telemetry for the local client (G8). */
+export interface NetworkedSyncplayClientNetStats {
+    /** Smoothed RTT in ms; -1 until the first time-sync pong arrives. */
+    readonly rttMs: number;
+    /** Current pacing timescale in permille (1000 = realtime). */
+    readonly timescalePermille: number;
+    readonly inputDelayTicks: number;
+    readonly rollbacks: number;
+    readonly maxRollbackDepth: number;
+}
+export interface NetworkedSyncplayClient {
+    readonly slot: number;
+    /** 'player' (holds a slot) or 'spectator' (read-only follower, slot -1). From session-start. */
+    readonly role: DeterministicSessionRole;
+    readonly ready: boolean;
+    readonly predictedThrough: number;
+    readonly appliedThrough: number;
+    readonly rollbacks: number;
+    /** Live local netcode telemetry (RTT, timescale, delay, rollback depth). */
+    readonly netStats: NetworkedSyncplayClientNetStats;
+    /** Resolves once `session-start` has been received. */
+    whenReady(): Promise<void>;
+    /** Predict and submit local input up to the prediction budget. */
+    pump(): void;
+    /**
+     * Wall-clock-paced pump (G1): steps as many fixed frames as elapsed time ×
+     * the drift-corrected timescale allows (bounded by the prediction budget and
+     * the catch-up cap), and drives RTT pings. Call once per host frame (rAF /
+     * host tick) with a monotonic-enough `nowMs`. Prefer this over raw `pump()`
+     * on real networks — raw pump() slams into the prediction cap and
+     * rubber-bands under asymmetric latency.
+     */
+    pumpPaced(nowMs: number): void;
+    /** Report this client's confirmed-state checksum for desync telemetry. */
+    reportChecksum(): void;
+    /** Confirmed-state checksum at `frame` (must be <= appliedThrough + 1). */
+    confirmedStateChecksum(frame: number): string;
+    exportReplay(): ReplayFile;
+}
+export declare function createNetworkedSyncplayClient<State, Input>(options: NetworkedSyncplayClientOptions<State, Input>): NetworkedSyncplayClient;