rollback-netcode 0.0.4

package/dist/rollback/engine.d.ts

@@ -0,0 +1,261 @@
+/**
+ * Core rollback netcode engine.
+ *
+ * Handles the rollback algorithm: detecting mispredictions,
+ * restoring state, and resimulating forward.
+ */
+import type { Game, InputPredictor, PlayerId, PlayerTimeline, Tick, TickResult } from "../types.js";
+/**
+ * Callback for player lifecycle events during resimulation.
+ */
+export type PlayerLifecycleCallback = (playerId: PlayerId, tick: Tick) => void;
+/**
+ * Configuration for the rollback engine.
+ */
+export interface RollbackEngineConfig {
+    /** The game instance to control */
+    game: Game;
+    /** The local player's ID */
+    localPlayerId: PlayerId;
+    /** Number of snapshots to keep in history */
+    snapshotHistorySize?: number;
+    /** Maximum ticks to speculate ahead without confirmed inputs */
+    maxSpeculationTicks?: number;
+    /** Input predictor for remote players */
+    inputPredictor?: InputPredictor<Uint8Array>;
+    /**
+     * Number of ticks to keep before the confirmed tick when pruning.
+     * Higher values use more memory but allow rollback further into the past.
+     * @default 10
+     */
+    pruneBufferTicks?: number;
+    /**
+     * Callback invoked when a player should be added during resimulation.
+     * Called when resimulating past a player's joinTick.
+     */
+    onPlayerAddDuringResimulation?: PlayerLifecycleCallback;
+    /**
+     * Callback invoked when a player should be removed during resimulation.
+     * Called when resimulating past a player's leaveTick.
+     */
+    onPlayerRemoveDuringResimulation?: PlayerLifecycleCallback;
+    /**
+     * Callback invoked when a rollback occurs, before resimulation.
+     * Receives the tick that we're rolling back to (the restore tick).
+     * Use this to clear state that needs to be re-applied during resimulation.
+     */
+    onRollback?: (restoreTick: Tick) => void;
+}
+/**
+ * Core rollback engine that handles prediction, rollback, and resimulation.
+ */
+export declare class RollbackEngine {
+    private readonly game;
+    private readonly localPlayerId;
+    private readonly snapshotBuffer;
+    private readonly inputBuffer;
+    private readonly inputPredictor;
+    private readonly maxSpeculationTicks;
+    private readonly pruneBufferTicks;
+    private readonly onPlayerAddDuringResimulation;
+    private readonly onPlayerRemoveDuringResimulation;
+    private readonly onRollback;
+    private _currentTick;
+    private _confirmedTick;
+    private localInputs;
+    /**
+     * Create a new rollback engine.
+     */
+    constructor(config: RollbackEngineConfig);
+    /**
+     * The current simulation tick.
+     */
+    get currentTick(): Tick;
+    /**
+     * The lowest confirmed tick across all active players.
+     * All inputs up to and including this tick are confirmed.
+     */
+    get confirmedTick(): Tick;
+    /**
+     * Add a player to the simulation.
+     *
+     * @param playerId - The player's ID
+     * @param joinTick - The tick at which they join
+     */
+    addPlayer(playerId: PlayerId, joinTick: Tick): void;
+    /**
+     * Remove a player from the simulation.
+     *
+     * @param playerId - The player's ID
+     * @param leaveTick - The tick at which they leave
+     */
+    removePlayer(playerId: PlayerId, leaveTick: Tick): void;
+    /**
+     * Get the confirmed tick for a specific player.
+     * Returns the highest tick for which we have received confirmed input from this player.
+     *
+     * @param playerId - The player's ID
+     * @returns The confirmed tick, or undefined if the player is not tracked
+     */
+    getConfirmedTickForPlayer(playerId: PlayerId): Tick | undefined;
+    /**
+     * Set the local player's input for the current tick.
+     * Call this before tick() to set what input the local player uses.
+     *
+     * @param tick - The tick the input is for
+     * @param input - The input data
+     */
+    setLocalInput(tick: Tick, input: Uint8Array): void;
+    /**
+     * Receive a remote player's input.
+     *
+     * @param playerId - The player's ID
+     * @param tick - The tick the input is for
+     * @param input - The input data
+     */
+    receiveRemoteInput(playerId: PlayerId, tick: Tick, input: Uint8Array): void;
+    /**
+     * Get the local player's input for a tick.
+     *
+     * @param tick - The tick to get input for
+     * @returns The input, or undefined if not set
+     */
+    getLocalInput(tick: Tick): Uint8Array | undefined;
+    /**
+     * Save the initial snapshot at tick -1.
+     * This allows rollback of tick 0 if there's a misprediction.
+     * Call this before the first tick() if the engine wasn't initialized via setState().
+     */
+    saveInitialSnapshot(): void;
+    /**
+     * Advance the simulation by one tick.
+     *
+     * This is the core rollback algorithm:
+     * 1. Check for mispredictions among remote players
+     * 2. If misprediction found, rollback and resimulate
+     * 3. Gather inputs (real or predicted) for all players
+     * 4. Step the simulation
+     * 5. Save snapshot
+     *
+     * @returns Result containing tick number and rollback info
+     */
+    tick(): TickResult;
+    /**
+     * Check for mispredictions and rollback if found.
+     */
+    private checkAndRollback;
+    /**
+     * Handle player add/remove lifecycle events at a specific tick during resimulation.
+     * This ensures the game layer knows about player joins/leaves when replaying history.
+     * Uses O(1) tick-indexed lookups instead of iterating all players.
+     */
+    private handlePlayerLifecycleAtTick;
+    /**
+     * Gather inputs for all active players at a given tick.
+     * Uses real inputs when available, predicts otherwise.
+     */
+    private gatherInputs;
+    /**
+     * Update the confirmed tick based on all players' confirmed ticks.
+     */
+    private updateConfirmedTick;
+    /**
+     * Get the hash at a specific tick.
+     *
+     * @param tick - The tick to get hash for
+     * @returns The hash, or undefined if not available
+     */
+    getHash(tick: Tick): number | undefined;
+    /**
+     * Get the current game hash.
+     */
+    getCurrentHash(): number;
+    /**
+     * Get the current game state and player timeline for sync.
+     */
+    getState(): {
+        tick: Tick;
+        state: Uint8Array;
+        playerTimeline: PlayerTimeline;
+    };
+    /**
+     * Set the game state from a sync message.
+     * Used for late join or desync recovery.
+     *
+     * @param tick - The tick the state is from
+     * @param state - The serialized game state
+     * @param playerTimeline - Timeline of player join/leave events
+     */
+    setState(tick: Tick, state: Uint8Array, playerTimeline: PlayerTimeline): void;
+    /**
+     * Reset buffers and tick counters for sync without changing game state.
+     *
+     * Used by the host when broadcasting sync to all players. The host's game
+     * state is already correct, but it needs to reset buffers and tick counters
+     * to match the synced state being sent to clients.
+     *
+     * This is more efficient than setState() when the game state doesn't need
+     * to be restored (avoids unnecessary serialize/deserialize round-trip).
+     *
+     * @param tick - The tick to reset to
+     * @param playerTimeline - Timeline of player join/leave events
+     */
+    resetForSync(tick: Tick, playerTimeline: PlayerTimeline): void;
+    /**
+     * Check if we have all inputs for a given tick.
+     *
+     * @param tick - The tick to check
+     * @returns true if all inputs are available
+     */
+    hasAllInputsForTick(tick: Tick): boolean;
+    /**
+     * Check if a tick is "settled" - meaning we've simulated past it
+     * and have all confirmed inputs for it.
+     *
+     * A settled tick's state is stable and won't change from future rollbacks,
+     * making it safe to compare hashes for desync detection.
+     *
+     * @param tick - The tick to check
+     * @param currentTick - The current simulation tick
+     * @returns true if the tick is settled
+     */
+    isTickSettled(tick: Tick, currentTick: Tick): boolean;
+    /**
+     * Get the number of ticks we're speculating ahead.
+     */
+    getSpeculationDistance(): number;
+    /**
+     * Get all active player IDs at the current tick.
+     */
+    getActivePlayers(): PlayerId[];
+    /**
+     * Get all player IDs.
+     */
+    getAllPlayers(): PlayerId[];
+    /**
+     * Reset the engine to initial state.
+     */
+    reset(): void;
+    /**
+     * Wrap a game operation with error handling.
+     * Catches any error and re-throws it wrapped in a GameError with context.
+     */
+    private wrapGameOperation;
+    /**
+     * Call game.step() with error wrapping.
+     */
+    private gameStep;
+    /**
+     * Call game.serialize() with error wrapping.
+     */
+    private gameSerialize;
+    /**
+     * Call game.deserialize() with error wrapping.
+     */
+    private gameDeserialize;
+    /**
+     * Call game.hash() with error wrapping.
+     */
+    private gameHash;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/rollback/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/rollback/engine.ts"],"names":[],"mappings":"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"}