Lockstep (Rollback Netcode)

Configurable lockstep rules (defaults here, never inline).

• int HistoryLimitFrames { get; set; }

  Input history kept per player (reconnect replay window; 0 = unbounded).

• byte InputDelayFrames { get; set; }

  Input delay frames every client applies (shipped to clients in the join reply).

• LockstepInputSubstitution InputSubstitution { get; set; }

  What a substituted frame contains.

• int InputSubstitutionGraceFrames { get; set; }

  0 = off (byte-for-byte legacy: a stalled player's peers wait at their prediction cap until it speaks again). When > 0, once the session clock is this many frames past frame F and a player's input for F still has not arrived, the server writes a substitute into that player's history (see InputSubstitution), relays it to everyone INCLUDING that player, and ignores the late original. The match keeps moving; the stalled player is the one who rolls back. Size it above the input delay plus one network trip, or healthy players get substituted. While on, input acks travel on the reliable-ordered channel behind the relay, so a client never learns a frame is "delivered" before it has seen the server's version of it. The paired client option is RollbackOptions.ServerAuthoritativeLocalInput.

• int MaxBatchFrames { get; set; }

  Maximum frames in one input batch (bounds a hostile packet).

• int MaxInputBytes { get; set; }

  Maximum bytes per single input frame.

• int MaxKeyLength { get; set; }

  Maximum session-key length.

• int MaxSnapshotBytes { get; set; }

  Total bytes one snapshot may carry before the request is abandoned (hostile donor guard).

• int MaxSpectatorsPerSession { get; set; }

  Maximum spectators per session (bounds the relay fan-out).

• int MaxSubstitutionsPerTick { get; set; }

  Per player per tick cap on substituted frames (bounds the work a long-dead player causes). 0 = substitute nothing (ADR-0006); the documented off switch for the feature as a whole remains InputSubstitutionGraceFrames.

• int PlayersPerSession { get; set; }

  Players required before a session starts.

• ushort SimRateHz { get; set; }

  Shared simulation rate every client runs at.

• int SnapshotChunkBytes { get; set; }

  Snapshot chunk size the donor is asked for (keep under the transport's message cap).

• bool SnapshotLateJoin { get; set; }

  Off by default (a late spectator or reconnecting player replays the whole input history from frame 0). On, the server asks a connected player for its latest CONFIRMED state snapshot, forwards it to the joiner in chunks, and then replays only the inputs from that frame on — a joiner at minute twenty no longer re-simulates twenty minutes. Falls back to the full replay when no donor answers within SnapshotTimeoutMs or the donor disconnects.

• int SnapshotTimeoutMs { get; set; }

  How long to wait for a donor before falling back to the full history replay.

• int StartDelayMs { get; set; }

  Countdown between the last join and frame 0 (clients arm against the shared clock).

Engine tuning (defaults here, never inline).

• bool AdaptiveInputDelay { get; set; }

  Off by default — the delay stays at InputDelayFrames for the whole match, exactly as before. On, the engine re-targets its own input delay from the round-trip samples the transport feeds it through ReportRoundTrip: the desired delay is ceil(rtt in frames) + InputDelayMarginFrames, clamped to [MinInputDelayFrames, MaxInputDelayFrames], approached one frame per InputDelayAdjustIntervalFrames. The stamped local-input timeline stays contiguous across every change (a raise duplicates the current input into the gap, a lowering absorbs inputs until the frontier is reached), so peers never see a hole. Assumes peers sit at a similar ping — a client-only heuristic that needs no protocol change; a server-driven per-player offset is a follow-up seam.

• int ChecksumIntervalFrames { get; set; }

  A checksum is captured every this many CONFIRMED frames.

• int InputDelayAdjustIntervalFrames { get; set; }

  The adaptive controller moves the delay by at most one frame per this many simulated frames.

• int InputDelayFrames { get; set; }

  Local inputs apply this many frames ahead (softens rollback depth; 0 = pure rollback). With AdaptiveInputDelay on this is only the STARTING delay.

• int InputDelayMarginFrames { get; set; }

  Frames added on top of the round-trip-derived delay (jitter headroom).

• int MaxInputDelayFrames { get; set; }

  Adaptive ceiling (frames).

• int MaxPredictionFrames { get; set; }

  Refuse to simulate further than this many frames past the last confirmed frame — beyond it the engine stalls instead of speculating into the void (peer died / vast lag).

• int MinInputDelayFrames { get; set; }

  Adaptive floor (frames).

• bool ServerAuthoritativeLocalInput { get; set; }

  Off by default: a local stamp is truth the moment it is made (the original contract — nothing the server sends can change your own input). Turn it ON when the server runs input substitution for stalled players: your stamps then count as confirmed only once the server has ACKED them, so a frame the server filled in for you is still inside the rollback window when its override arrives (AddServerInput) and can be replayed. Costs a little prediction depth (the ack trails by half a round trip) — raise MaxPredictionFrames accordingly. The paired server option is LockstepOptions.InputSubstitutionGraceFrames.

• int SimRateHz { get; set; }

  Simulation rate; converts a measured round-trip into frames for the adaptive input delay. Only read when AdaptiveInputDelay is on.

The Lockstep piece, client side: join an input-authority session by key, hand over your IDeterministicSim, then pump RunFrames from your fixed-rate driver with the local input each frame. The shared RollbackEngine (same code the server tests run) does prediction + rewind; this client does the wiring: redundant input windows out, relayed peer inputs in, checksums up, desync/peer events surfaced, round-trip samples into the adaptive delay, server overrides of your own frames applied, snapshots donated to and adopted from late joiners. Presentation — what a frame LOOKS like — is 100% the game's.

• void Join(string sessionKey, IDeterministicSim sim)

  Joins (or creates) the session. The sim starts when the server says everyone is in.

• void Spectate(string sessionKey, IDeterministicSim sim)

  Watches an EXISTING session: the server streams the full input history (or, when its snapshot late-join option is on, a peer's confirmed state plus the tail), then the live relay, and a confirmed-only engine replays the match (zero rollbacks, a beat behind live). Pump RunFrames with null input; render from your sim as usual.

• bool IsSpectating

  True when watching rather than playing.

• event Action<LockstepSpectateJoined> SpectateJoined

  Spectate verdict (success + session parameters, or the refusal reason).

• bool IsRunning

  True once the session started (frame 0 scheduled).

• int Slot

  Your slot in the session (-1 before joining).

• RollbackEngine Engine

  The engine (null until the session starts) — frames, rollback diagnostics.

• RollbackOptions EngineOptions

  The rollback tuning the engine is created with. Set the opt-in levers here BEFORE the session starts (adaptive input delay, server-authoritative local input, prediction window); the server-shipped parameters (input delay, sim rate) overwrite theirs on start.

• int RunFrames(byte[] localInput, int maxFrames = 4)

  Advances up to maxFrames frames toward the shared clock, using localInput for each new frame, and flushes inputs/checksums to the server. Call once per Update with your sampled input. Returns frames actually simulated.

• int MaxBacklogFrames

  Frames this client may fall behind the shared clock before FellBehind raises (the spiral-of-death guard: a machine that can't hold the sim rate should slow-mo, resync, or concede — the game decides; the engine never silently death-spirals trying to catch up).

• event Action<uint> FellBehind

  This client can't keep up (current backlog in frames). Raised once per episode.

• event Action<LockstepJoined> Joined

  Joined successfully (slot, playerCount) / refused (reason code in the message).

• event Action<uint, uint> ChecksumReported

  A confirmed-state checksum left the engine (frame, value) — the sync proof a HUD or log can display. Players raise it as each checksum is reported to the server; spectators as each is locally captured (watchers verify, they never send).

• event Action<uint> DesyncDetected

  The session desynced at a frame — the game decides (void the match, resync…).

• event Action<int> PeerLeft

  A peer's slot went dark (disconnect; it may reconnect and resume).

• event Action<uint> ResyncRequired

  The server overrode one of YOUR frames (it substituted input while you stalled) and the engine could not replay it — this machine has left the match's history. Spectate/rejoin to resync. Never fires with ServerAuthoritativeLocalInput on.

• event Action<uint> ResumedFromSnapshot

  A peer's confirmed snapshot was adopted (late join) — the sim now sits at this frame.

Narrow contract the presenter drives. UI-only, read-only: joining or spectating a lockstep session requires the game's IDeterministicSim, so this monitor raises no intents — it only watches the session the game runs.