@series-inc/rundot-game-sdk 5.23.0-beta.5 → 5.23.0-beta.7

package/dist/SyncplayRoomTransport-D6xsCdn5.d.ts

@@ -0,0 +1,379 @@
+import { C as CanonicalValue, h as ReplayFile, O as OfflineSession } from './types-DbhOvOdx.js';
+import { M as MultiplayerApi } from './MultiplayerApi-nnrGTTcO.js';
+
+/**
+ * Game-agnostic input authority (server orders inputs, clients simulate — §2 Option 1).
+ *
+ * It orders per-slot inputs by tick and confirms each tick exactly once, in order,
+ * either when every player slot has reported or when a HardTolerance deadline elapses
+ * (substituting the slot's last confirmed input). It never runs the simulation — only
+ * inputs cross the wire and clients run the deterministic sim locally.
+ *
+ * This module is the reusable core: the M0 spike hosts it over sockets, and M2 lifts it
+ * into the mp-room-server room type unchanged.
+ */
+/** Opaque, engine-defined input payload. The authority never interprets it. */
+type EncodedInput = CanonicalValue;
+interface ConfirmedInputFrame {
+    readonly tick: number;
+    /** One entry per player slot, in slot order. */
+    readonly inputs: readonly EncodedInput[];
+    /** Slots whose input was substituted (repeated) because it never arrived in time. */
+    readonly substitutedSlots: readonly number[];
+    readonly checksum: string;
+}
+interface InputAuthorityConfig {
+    readonly playerCount: number;
+    /** Confirm a tick once `now - tick >= hardToleranceTicks`, substituting any missing input. */
+    readonly hardToleranceTicks: number;
+    /** Substitute this when a slot has no prior confirmed input to repeat. */
+    readonly neutralInput: EncodedInput;
+    /** Reject inputs whose tick is further ahead than `confirmedThrough + maxFutureTicks`. */
+    readonly maxFutureTicks?: number;
+    /** Confirmed frames retained for the redundant broadcast window. */
+    readonly retainedConfirmedFrames?: number;
+    /**
+     * Rebuild a previously-persisted authority (M6.5 crash recovery): the
+     * retained frames, frontier, and per-slot last-confirmed inputs (derived
+     * from the final frame — confirmed inputs equal the post-substitution
+     * last-confirmed values by construction). Fail-loud on gaps or a frontier
+     * mismatch.
+     */
+    readonly restoreFrom?: InputAuthorityRestoreState;
+}
+interface InputAuthorityRestoreState {
+    readonly confirmedThrough: number;
+    readonly frames: readonly ConfirmedInputFrame[];
+}
+type InputRejectionReason = 'slot-out-of-range' | 'invalid-tick' | 'tick-already-confirmed' | 'tick-too-far-ahead';
+interface InputSubmissionResult {
+    readonly accepted: boolean;
+    readonly reason?: InputRejectionReason;
+}
+interface InputAuthorityStats {
+    readonly confirmedTicks: number;
+    readonly substitutedInputs: number;
+    readonly droppedLateInputs: number;
+    readonly rejectedFutureInputs: number;
+}
+interface InputAuthority {
+    readonly playerCount: number;
+    /** Highest confirmed tick, or -1 when nothing is confirmed yet. */
+    readonly confirmedThrough: number;
+    /** Lowest confirmed tick still retained, or -1 when nothing is confirmed yet. */
+    readonly earliestRetainedTick: number;
+    receiveInput(slot: number, tick: number, input: EncodedInput): InputSubmissionResult;
+    /** Confirm every tick that can be confirmed up to and including `now`. Returns the new frames in order. */
+    advance(now: number): readonly ConfirmedInputFrame[];
+    /** A confirmed frame still inside the retained window, for redundant re-broadcast. */
+    confirmedFrame(tick: number): ConfirmedInputFrame | undefined;
+    /**
+     * The retained frames `from..to` inclusive, for persistence (M6.5). Throws
+     * if any tick in the range is no longer retained — a persisted record with
+     * a silent gap would strand every restored client.
+     */
+    confirmedFrameRange(from: number, to: number): readonly ConfirmedInputFrame[];
+    /**
+     * Drop retained frames below `tick` (M5.5: history before a validated
+     * snapshot is no longer needed for late-join catch-up). Never moves the
+     * frontier; a no-op at or below the current earliest retained tick.
+     */
+    pruneConfirmedBefore(tick: number): void;
+    stats(): InputAuthorityStats;
+}
+declare function createInputAuthority(config: InputAuthorityConfig): InputAuthority;
+
+/**
+ * Frozen v1 session-control wire protocol for game-agnostic input-authority rooms (§8, M1).
+ *
+ * Covers the server/client roles for a live match: session-start (slot assignment + the
+ * server-owned RNG seed + tick params), clock/time-sync, input, confirmed-input (the verified
+ * tick), reconnect, spectator, and close/error. Snapshot request/offer/chunk/complete for
+ * late-join reuse the existing envelopes in `local-authority-wire.ts` (wired at M5).
+ *
+ * Both families share the `rdm-local-authority/v1` version namespace. Decoding is FAIL-CLOSED:
+ * unknown protocol, unknown version, unknown kind, malformed payload, or checksum mismatch are
+ * rejected with a reason — never silently coerced. This is a public forward-compat boundary; the
+ * discriminants below are frozen and must only be extended, never repurposed.
+ */
+declare const deterministicSessionWireVersion = 1;
+type DeterministicSessionRole = 'player' | 'spectator';
+type DeterministicSessionMessage = {
+    readonly kind: 'session-start';
+    readonly slot: number;
+    readonly playerCount: number;
+    readonly seed: number;
+    readonly tickRateHz: number;
+    readonly hardToleranceTicks: number;
+    readonly role: DeterministicSessionRole;
+} | {
+    readonly kind: 'time-sync-ping';
+    readonly clientSendTick: number;
+    readonly nonce: number;
+} | {
+    readonly kind: 'time-sync-pong';
+    readonly clientSendTick: number;
+    readonly nonce: number;
+    readonly authorityTick: number;
+} | {
+    readonly kind: 'input';
+    readonly slot: number;
+    readonly tick: number;
+    readonly input: EncodedInput;
+    readonly attempt: number;
+} | {
+    readonly kind: 'confirmed-input';
+    readonly authorityTick: number;
+    readonly frames: readonly ConfirmedInputFrame[];
+} | {
+    readonly kind: 'reconnect';
+    readonly slot: number;
+    readonly resumeFromTick: number;
+} | {
+    readonly kind: 'spectator-join';
+} | {
+    readonly kind: 'checksum-report';
+    readonly slot: number;
+    readonly tick: number;
+    readonly checksum: string;
+} | {
+    /**
+     * Client → authority netcode telemetry (G8). Additive v1 extension: unknown
+     * kinds are dropped fail-closed by older decoders, so this never breaks an
+     * old authority. All fields are integers (rttMs rounded, timescale in
+     * permille) so the payload stays canonical-checksum friendly.
+     */
+    readonly kind: 'net-stats';
+    readonly slot: number;
+    readonly tick: number;
+    readonly rttMs: number;
+    readonly rollbacks: number;
+    readonly maxRollbackDepth: number;
+    readonly timescalePermille: number;
+    readonly inputDelayTicks: number;
+} | {
+    readonly kind: 'close';
+    readonly code: string;
+    readonly reason: string;
+} | {
+    readonly kind: 'error';
+    readonly code: string;
+    readonly message: string;
+};
+type DeterministicSessionMessageKind = DeterministicSessionMessage['kind'];
+type DeterministicSessionDecodeRejection = 'invalid-json' | 'not-an-envelope' | 'unknown-protocol' | 'unknown-version' | 'unknown-kind' | 'checksum-mismatch' | 'malformed-payload';
+type DeterministicSessionDecodeResult = {
+    readonly ok: true;
+    readonly message: DeterministicSessionMessage;
+} | {
+    readonly ok: false;
+    readonly reason: DeterministicSessionDecodeRejection;
+};
+declare function encodeDeterministicSessionMessage(message: DeterministicSessionMessage): string;
+declare function decodeDeterministicSessionMessage(text: string): DeterministicSessionDecodeResult;
+
+/**
+ * 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.
+ */
+interface NetworkedClientTransport {
+    send(text: string): void;
+    onMessage(handler: (text: string) => void): void;
+}
+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;
+}
+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;
+}
+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). */
+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;
+}
+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;
+}
+declare function createNetworkedSyncplayClient<State, Input>(options: NetworkedSyncplayClientOptions<State, Input>): NetworkedSyncplayClient;
+
+/**
+ * Reusable, production-shaped client surface for deterministic multiplayer.
+ *
+ * A game joins a deterministic room by code (or creates one) and gets back a
+ * {@link NetworkedClientTransport} — the exact socket-like surface the
+ * deterministic engine's `createNetworkedSyncplayClient` consumes. There is
+ * NO per-game server logic: the server-side deterministic room (built-in input
+ * authority) is generic, and this transport is a thin, opaque pass-through of the
+ * frozen `rdm-local-authority/v1` session envelope over the `rdm` room channel.
+ *
+ * The room's raw channel ({@link ServerRoom.sendRaw}/{@link ServerRoom.onRaw})
+ * carries the session envelope verbatim; the typed-message path would spread a
+ * raw string and corrupt it, which is why the raw channel exists.
+ */
+
+/** Connection-health signal surfaced by {@link SyncplayRoomTransport.onConnectionEvent}. */
+type SyncplayConnectionEvent = {
+    readonly kind: 'error';
+    readonly message: string;
+} | {
+    readonly kind: 'disconnected';
+} | {
+    readonly kind: 'reconnecting';
+};
+interface SyncplayRoomTransport extends NetworkedClientTransport {
+    /** The shareable room code (e.g. "HX9KWR"). */
+    readonly roomCode: string;
+    /** This client's player id, as assigned by the server on join. */
+    readonly playerId: string;
+    /** Leave the deterministic room and close the underlying connection. */
+    close(): void;
+    /**
+     * Connection-health signal: socket errors, disconnects, and reconnect
+     * attempts. Without observing this, a mid-match socket drop is silent — the
+     * room layer no-ops sends while dead, so the engine would predict into a
+     * dead socket forever. Games should surface these to the player and/or tear
+     * the match down.
+     */
+    onConnectionEvent(handler: (event: SyncplayConnectionEvent) => void): void;
+}
+/**
+ * Join an existing deterministic room by its 6-char code and return a transport
+ * ready to hand to `createNetworkedSyncplayClient`.
+ */
+declare function joinSyncplayRoomByCode(api: MultiplayerApi, code: string): Promise<SyncplayRoomTransport>;
+/** Options for {@link quickMatchSyncplayRoom}. */
+interface QuickMatchSyncplayOptions {
+    /**
+     * Auto-inject a coarse `region` criterion (default true). See
+     * {@link quickMatchSyncplayRoom} for the semantics and the tradeoff.
+     */
+    readonly autoRegion?: boolean;
+}
+/**
+ * Quick-match into a deterministic room (M9): the platform's joinOrCreate
+ * matchmaking pools compatible players into an open room or creates a fresh
+ * one. Optional `criteria` narrow the pool (matched exactly by the platform).
+ * With drop-in defaults the match starts immediately; unfilled slots
+ * substitute the canonical null input, which a game can treat as
+ * "bot-controlled" deterministically (see SYNCPLAY.md — Bots & quick match).
+ *
+ * Region-aware by default (G6): a coarse `region` criterion ('na' | 'sa' |
+ * 'eu' | 'africa' | 'asia' | 'oceania', derived from the device timezone) is
+ * auto-injected so cross-ocean pairings — whose RTT forces constant deep
+ * rollback — don't happen by accident. An explicit `criteria.region` wins
+ * over the derived value, and an underivable region ('unknown') is never
+ * injected: pooling globally beats fragmenting into an 'unknown' bucket.
+ *
+ * Tradeoff: strict region pools can go thin for low-traffic games. Pass
+ * `{ autoRegion: false }` (or your own `region` value) to pool globally;
+ * cross-region fallback-after-timeout is future work.
+ */
+declare function quickMatchSyncplayRoom(api: MultiplayerApi, criteria?: Record<string, string | number>, options?: QuickMatchSyncplayOptions): Promise<SyncplayRoomTransport>;
+/**
+ * Create a new deterministic room and return a transport ready to hand to
+ * `createNetworkedSyncplayClient`. The server mints the room code; read it
+ * back from {@link SyncplayRoomTransport.roomCode} to share with peers.
+ * (Caller-chosen codes are not supported on create — when the platform grows
+ * that path, this signature gains a typed parameter rather than a dead one.)
+ */
+declare function createSyncplayRoom(api: MultiplayerApi): Promise<SyncplayRoomTransport>;
+
+export { type ConfirmedInputFrame as C, type DeterministicSessionDecodeRejection as D, type EncodedInput as E, type InputAuthority as I, type NetworkedClientTransport as N, type QuickMatchSyncplayOptions as Q, type SyncplayRoomTransport as S, type DeterministicSessionDecodeResult as a, type DeterministicSessionMessage as b, type DeterministicSessionMessageKind as c, type DeterministicSessionRole as d, type InputAuthorityConfig as e, type InputAuthorityRestoreState as f, type InputAuthorityStats as g, type InputRejectionReason as h, type InputSubmissionResult as i, type NetworkedSyncplayClient as j, type NetworkedSyncplayClientInputDelayOptions as k, type NetworkedSyncplayClientNetStats as l, type NetworkedSyncplayClientOptions as m, type NetworkedSyncplayClientPacingOptions as n, createInputAuthority as o, createNetworkedSyncplayClient as p, createSyncplayRoom as q, decodeDeterministicSessionMessage as r, deterministicSessionWireVersion as s, encodeDeterministicSessionMessage as t, joinSyncplayRoomByCode as u, quickMatchSyncplayRoom as v };