rollback-netcode 0.0.4

package/dist/rollback/snapshot-buffer.js

@@ -0,0 +1,256 @@
+/**
+ * Ring buffer for storing game state snapshots.
+ *
+ * Used for rollback: when a misprediction is detected, the game state
+ * is restored from a snapshot and resimulated forward.
+ */
+/**
+ * A ring buffer that stores game state snapshots for rollback.
+ *
+ * Snapshots are stored at specific ticks and can be retrieved by tick.
+ * When the buffer is full, the oldest snapshot is evicted.
+ * Uses a tick-to-index map for O(1) lookup performance.
+ *
+ * INVARIANT: Snapshots must be saved in ascending tick order. This is required
+ * for O(log n) binary search in getAtOrBefore(). The invariant is maintained by:
+ * - Normal simulation: ticks advance sequentially (0, 1, 2, ...)
+ * - Resimulation: existing ticks are updated in-place, preserving order
+ *
+ * Saving a non-existing tick out of order will corrupt the sort order and
+ * cause getAtOrBefore() to return incorrect results.
+ */
+export class SnapshotBuffer {
+    capacity;
+    buffer;
+    tickToIndex = new Map();
+    head = 0; // Next write position
+    count = 0;
+    _oldestTick;
+    _newestTick;
+    /**
+     * Create a new snapshot buffer.
+     *
+     * @param capacity - Maximum number of snapshots to store
+     */
+    constructor(capacity) {
+        this.capacity = capacity;
+        if (capacity <= 0) {
+            throw new Error("Capacity must be positive");
+        }
+        this.buffer = new Array(capacity);
+    }
+    /**
+     * Number of snapshots currently stored.
+     */
+    get size() {
+        return this.count;
+    }
+    /**
+     * The oldest tick in the buffer, or undefined if empty.
+     */
+    get oldestTick() {
+        return this._oldestTick;
+    }
+    /**
+     * The newest tick in the buffer, or undefined if empty.
+     */
+    get newestTick() {
+        return this._newestTick;
+    }
+    /**
+     * Save a snapshot at a specific tick.
+     *
+     * If the tick already exists, updates in-place to maintain sort order.
+     * If the buffer is full, the oldest snapshot is evicted.
+     * The state is copied to prevent external mutation.
+     *
+     * PRECONDITION: New ticks (not already in buffer) must be >= all existing ticks.
+     * Saving an out-of-order new tick corrupts sort order. See class invariant.
+     *
+     * @param tick - The tick this snapshot was taken at
+     * @param state - The serialized game state
+     * @param hash - The hash of the game state
+     */
+    save(tick, state, hash) {
+        // Copy the state to prevent external mutation
+        const stateCopy = new Uint8Array(state.length);
+        stateCopy.set(state);
+        const snapshot = {
+            tick,
+            state: stateCopy,
+            hash,
+        };
+        // Check if this tick already exists - update in-place to maintain order
+        const existingIdx = this.tickToIndex.get(tick);
+        if (existingIdx !== undefined) {
+            this.buffer[existingIdx] = snapshot;
+            return;
+        }
+        // Warn on invariant violation: new ticks must be >= newest for binary search
+        if (this._newestTick !== undefined && tick < this._newestTick) {
+            console.error(`SnapshotBuffer: tick ${tick} is out of order (newest: ${this._newestTick}). This will corrupt binary search in getAtOrBefore().`);
+        }
+        // New tick - append or evict oldest
+        if (this.count === this.capacity) {
+            // Remove old tick from index map
+            const oldSnapshot = this.buffer[this.head];
+            if (oldSnapshot) {
+                this.tickToIndex.delete(oldSnapshot.tick);
+            }
+            // The slot at head contains the oldest snapshot
+            this.buffer[this.head] = snapshot;
+            this.tickToIndex.set(tick, this.head);
+            this.head = (this.head + 1) % this.capacity;
+            // Update oldest tick to the new oldest
+            const oldestSnapshot = this.buffer[this.head];
+            this._oldestTick = oldestSnapshot?.tick;
+        }
+        else {
+            // Buffer not full, just append
+            const writePos = (this.head + this.count) % this.capacity;
+            this.buffer[writePos] = snapshot;
+            this.tickToIndex.set(tick, writePos);
+            this.count++;
+            if (this.count === 1) {
+                this._oldestTick = tick;
+            }
+        }
+        this._newestTick = tick;
+    }
+    /**
+     * Get a snapshot at a specific tick.
+     * Uses O(1) map lookup for performance.
+     *
+     * @param tick - The tick to retrieve
+     * @returns The snapshot at that tick, or undefined if not found
+     */
+    get(tick) {
+        const idx = this.tickToIndex.get(tick);
+        if (idx === undefined) {
+            return undefined;
+        }
+        return this.buffer[idx];
+    }
+    /**
+     * Get the oldest snapshot in the buffer.
+     *
+     * @returns The oldest snapshot, or undefined if empty
+     */
+    getOldest() {
+        if (this.count === 0) {
+            return undefined;
+        }
+        return this.buffer[this.head];
+    }
+    /**
+     * Get the newest snapshot in the buffer.
+     *
+     * @returns The newest snapshot, or undefined if empty
+     */
+    getNewest() {
+        if (this.count === 0) {
+            return undefined;
+        }
+        const newestIdx = (this.head + this.count - 1) % this.capacity;
+        return this.buffer[newestIdx];
+    }
+    /**
+     * Clear all snapshots from the buffer.
+     */
+    clear() {
+        this.buffer.fill(undefined);
+        this.tickToIndex.clear();
+        this.head = 0;
+        this.count = 0;
+        this._oldestTick = undefined;
+        this._newestTick = undefined;
+    }
+    /**
+     * Get the snapshot at or before a given tick.
+     * Useful for finding the closest snapshot for rollback.
+     *
+     * O(log n) binary search. Snapshots are stored in ascending tick order.
+     *
+     * @param tick - The target tick
+     * @returns The snapshot at or before that tick, or undefined if none exists
+     */
+    getAtOrBefore(tick) {
+        if (this.count === 0) {
+            return undefined;
+        }
+        // Binary search to find the rightmost snapshot with tick <= target
+        // Logical indices: 0 to count-1, physical: (head + logical) % capacity
+        let lo = 0;
+        let hi = this.count - 1;
+        let result;
+        while (lo <= hi) {
+            const mid = (lo + hi) >>> 1;
+            const idx = (this.head + mid) % this.capacity;
+            const snapshot = this.buffer[idx];
+            if (snapshot && snapshot.tick <= tick) {
+                // This snapshot is valid, but there might be a better one to the right
+                result = snapshot;
+                lo = mid + 1;
+            }
+            else {
+                // Snapshot tick is too high, search left
+                hi = mid - 1;
+            }
+        }
+        return result;
+    }
+    /**
+     * Remove all snapshots before a given tick.
+     * Used to clean up old snapshots that are no longer needed.
+     *
+     * @param tick - Remove all snapshots with tick < this value
+     */
+    pruneBeforeTick(tick) {
+        while (this.count > 0) {
+            const oldest = this.buffer[this.head];
+            if (oldest && oldest.tick < tick) {
+                // Remove from index map
+                this.tickToIndex.delete(oldest.tick);
+                this.buffer[this.head] = undefined;
+                this.head = (this.head + 1) % this.capacity;
+                this.count--;
+                if (this.count === 0) {
+                    this._oldestTick = undefined;
+                    this._newestTick = undefined;
+                }
+                else {
+                    this._oldestTick = this.buffer[this.head]?.tick;
+                }
+            }
+            else {
+                break;
+            }
+        }
+    }
+    /**
+     * Check if a snapshot exists at a given tick.
+     *
+     * @param tick - The tick to check
+     * @returns true if a snapshot exists at that tick
+     */
+    has(tick) {
+        return this.get(tick) !== undefined;
+    }
+    /**
+     * Get all ticks that have snapshots, in order from oldest to newest.
+     *
+     * @returns Array of ticks with snapshots
+     */
+    getTicks() {
+        const ticks = [];
+        for (let i = 0; i < this.count; i++) {
+            const idx = (this.head + i) % this.capacity;
+            const snapshot = this.buffer[idx];
+            if (snapshot) {
+                ticks.push(snapshot.tick);
+            }
+        }
+        return ticks;
+    }
+}
+//# sourceMappingURL=snapshot-buffer.js.map

package/dist/rollback/snapshot-buffer.js.map

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

package/dist/session/desync-manager.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Desync detection and management.
+ *
+ * Supports both host-authority mode (host collects and compares all hashes)
+ * and peer mode (each peer compares independently).
+ */
+import { DesyncAuthority, type PlayerId, type Tick, Topology } from "../types.js";
+/**
+ * Configuration for the desync manager.
+ */
+export interface DesyncManagerConfig {
+    /** Network topology */
+    topology: Topology;
+    /** Desync authority mode */
+    desyncAuthority: DesyncAuthority;
+    /** Hash interval for pruning calculations */
+    hashInterval: number;
+}
+/**
+ * Result when a desync is detected.
+ */
+export interface DesyncResult {
+    /** The tick where desync was detected */
+    tick: Tick;
+    /** The player who desynced (in host-authority mode) */
+    desyncedPlayerId: PlayerId;
+    /** The host/reference hash */
+    referenceHash: number;
+    /** The player's actual hash */
+    playerHash: number;
+}
+/**
+ * Result of checking a hash in peer mode.
+ * Returned only when a desync is detected (non-null means desync).
+ */
+export interface PeerDesyncResult {
+    /** The tick where desync was detected */
+    tick: Tick;
+    /** Local hash */
+    localHash: number;
+    /** Remote hash */
+    remoteHash: number;
+    /** Remote player ID */
+    remotePlayerId: PlayerId;
+}
+/**
+ * Manages desync detection for both host-authority and peer modes.
+ */
+export declare class DesyncManager {
+    private readonly topology;
+    private readonly desyncAuthority;
+    private readonly hashInterval;
+    /** Host-authority mode: hashes received from players, keyed by tick then playerId */
+    private readonly receivedHashes;
+    constructor(config: DesyncManagerConfig);
+    /**
+     * Whether this is host-authority mode.
+     */
+    get isHostAuthority(): boolean;
+    /**
+     * Record a hash from a player (host-authority mode).
+     *
+     * @param tick - The tick the hash is for
+     * @param playerId - The player who sent the hash
+     * @param hash - The hash value
+     */
+    recordHash(tick: Tick, playerId: PlayerId, hash: number): void;
+    /**
+     * Check if we have all hashes for a tick (host-authority mode).
+     *
+     * @param tick - The tick to check
+     * @param expectedPlayerCount - Number of players expected to submit hashes
+     * @returns true if all hashes have been received
+     */
+    hasAllHashes(tick: Tick, expectedPlayerCount: number): boolean;
+    /**
+     * Check for desyncs at a tick (host-authority mode).
+     * Compares all player hashes against the reference (host) hash.
+     *
+     * @param tick - The tick to check
+     * @param hostPlayerId - The host's player ID
+     * @returns Array of desync results for any desynced players
+     */
+    checkDesyncs(tick: Tick, hostPlayerId: PlayerId): DesyncResult[];
+    /**
+     * Check for desync in peer mode (comparing local vs remote hash).
+     *
+     * @param tick - The tick to check
+     * @param localHash - Local hash value (or undefined if not available)
+     * @param remoteHash - Remote hash value
+     * @param remotePlayerId - Remote player's ID
+     * @returns Desync result if a desync is detected, null otherwise
+     */
+    checkPeerDesync(tick: Tick, localHash: number | undefined, remoteHash: number, remotePlayerId: PlayerId): PeerDesyncResult | null;
+    /**
+     * Remove old hash entries to prevent memory growth.
+     *
+     * @param currentTick - Current simulation tick
+     */
+    pruneOldHashes(currentTick: Tick): void;
+    /**
+     * Clear all stored hashes.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=desync-manager.d.ts.map

package/dist/session/desync-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"desync-manager.d.ts","sourceRoot":"","sources":["../../src/session/desync-manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACN,eAAe,EACf,KAAK,QAAQ,EACb,KAAK,IAAI,EACT,QAAQ,EAER,MAAM,aAAa,CAAC;AAErB;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,uBAAuB;IACvB,QAAQ,EAAE,QAAQ,CAAC;IACnB,4BAA4B;IAC5B,eAAe,EAAE,eAAe,CAAC;IACjC,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,yCAAyC;IACzC,IAAI,EAAE,IAAI,CAAC;IACX,uDAAuD;IACvD,gBAAgB,EAAE,QAAQ,CAAC;IAC3B,8BAA8B;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAChC,yCAAyC;IACzC,IAAI,EAAE,IAAI,CAAC;IACX,iBAAiB;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,uBAAuB;IACvB,cAAc,EAAE,QAAQ,CAAC;CACzB;AAED;;GAEG;AACH,qBAAa,aAAa;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;IACpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC,qFAAqF;IACrF,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA+C;gBAElE,MAAM,EAAE,mBAAmB;IAMvC;;OAEG;IACH,IAAI,eAAe,IAAI,OAAO,CAO7B;IAED;;;;;;OAMG;IACH,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAS9D;;;;;;OAMG;IACH,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,GAAG,OAAO;IAQ9D;;;;;;;OAOG;IACH,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,YAAY,EAAE,QAAQ,GAAG,YAAY,EAAE;IA6BhE;;;;;;;;OAQG;IACH,eAAe,CACd,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,QAAQ,GACtB,gBAAgB,GAAG,IAAI;IAiB1B;;;;OAIG;IACH,cAAc,CAAC,WAAW,EAAE,IAAI,GAAG,IAAI;IASvC;;OAEG;IACH,KAAK,IAAI,IAAI;CAGb"}

package/dist/session/desync-manager.js

@@ -0,0 +1,136 @@
+/**
+ * Desync detection and management.
+ *
+ * Supports both host-authority mode (host collects and compares all hashes)
+ * and peer mode (each peer compares independently).
+ */
+import { DesyncAuthority, Topology, asTick, } from "../types.js";
+/**
+ * Manages desync detection for both host-authority and peer modes.
+ */
+export class DesyncManager {
+    topology;
+    desyncAuthority;
+    hashInterval;
+    /** Host-authority mode: hashes received from players, keyed by tick then playerId */
+    receivedHashes = new Map();
+    constructor(config) {
+        this.topology = config.topology;
+        this.desyncAuthority = config.desyncAuthority;
+        this.hashInterval = config.hashInterval;
+    }
+    /**
+     * Whether this is host-authority mode.
+     */
+    get isHostAuthority() {
+        // Only Mesh + Host authority uses host-authority mode
+        // Star topology and Mesh + Peer use peer-based detection
+        return (this.topology === Topology.Mesh &&
+            this.desyncAuthority === DesyncAuthority.Host);
+    }
+    /**
+     * Record a hash from a player (host-authority mode).
+     *
+     * @param tick - The tick the hash is for
+     * @param playerId - The player who sent the hash
+     * @param hash - The hash value
+     */
+    recordHash(tick, playerId, hash) {
+        let tickHashes = this.receivedHashes.get(tick);
+        if (!tickHashes) {
+            tickHashes = new Map();
+            this.receivedHashes.set(tick, tickHashes);
+        }
+        tickHashes.set(playerId, hash);
+    }
+    /**
+     * Check if we have all hashes for a tick (host-authority mode).
+     *
+     * @param tick - The tick to check
+     * @param expectedPlayerCount - Number of players expected to submit hashes
+     * @returns true if all hashes have been received
+     */
+    hasAllHashes(tick, expectedPlayerCount) {
+        const tickHashes = this.receivedHashes.get(tick);
+        if (!tickHashes) {
+            return false;
+        }
+        return tickHashes.size >= expectedPlayerCount;
+    }
+    /**
+     * Check for desyncs at a tick (host-authority mode).
+     * Compares all player hashes against the reference (host) hash.
+     *
+     * @param tick - The tick to check
+     * @param hostPlayerId - The host's player ID
+     * @returns Array of desync results for any desynced players
+     */
+    checkDesyncs(tick, hostPlayerId) {
+        const tickHashes = this.receivedHashes.get(tick);
+        if (!tickHashes) {
+            return [];
+        }
+        const hostHash = tickHashes.get(hostPlayerId);
+        if (hostHash === undefined) {
+            return [];
+        }
+        const desyncs = [];
+        for (const [playerId, playerHash] of tickHashes) {
+            if (playerId === hostPlayerId) {
+                continue;
+            }
+            if (playerHash !== hostHash) {
+                desyncs.push({
+                    tick,
+                    desyncedPlayerId: playerId,
+                    referenceHash: hostHash,
+                    playerHash,
+                });
+            }
+        }
+        return desyncs;
+    }
+    /**
+     * Check for desync in peer mode (comparing local vs remote hash).
+     *
+     * @param tick - The tick to check
+     * @param localHash - Local hash value (or undefined if not available)
+     * @param remoteHash - Remote hash value
+     * @param remotePlayerId - Remote player's ID
+     * @returns Desync result if a desync is detected, null otherwise
+     */
+    checkPeerDesync(tick, localHash, remoteHash, remotePlayerId) {
+        if (localHash === undefined) {
+            return null;
+        }
+        if (localHash !== remoteHash) {
+            return {
+                tick,
+                localHash,
+                remoteHash,
+                remotePlayerId,
+            };
+        }
+        return null;
+    }
+    /**
+     * Remove old hash entries to prevent memory growth.
+     *
+     * @param currentTick - Current simulation tick
+     */
+    pruneOldHashes(currentTick) {
+        const pruneBelow = asTick(currentTick - this.hashInterval * 2);
+        for (const tick of this.receivedHashes.keys()) {
+            if (tick < pruneBelow) {
+                this.receivedHashes.delete(tick);
+            }
+        }
+    }
+    /**
+     * Clear all stored hashes.
+     */
+    clear() {
+        this.receivedHashes.clear();
+    }
+}
+//# sourceMappingURL=desync-manager.js.map

package/dist/session/desync-manager.js.map

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

package/dist/session/lag-monitor.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Lag monitoring for detecting and reporting players that fall behind.
+ */
+import type { PlayerId, Tick } from "../types.js";
+/**
+ * Configuration for the lag monitor.
+ */
+export interface LagMonitorConfig {
+    /**
+     * Number of ticks behind before a player is considered lagging.
+     * Set to 0 to disable lag monitoring.
+     */
+    threshold: number;
+    /**
+     * Minimum ticks between lag reports for the same player.
+     * Prevents spam when a player is consistently lagging.
+     */
+    cooldownTicks: number;
+}
+/**
+ * Result when a player is detected as lagging.
+ */
+export interface LagReport {
+    /** The player who is lagging */
+    laggyPlayerId: PlayerId;
+    /** How many ticks behind they are */
+    ticksBehind: number;
+}
+/**
+ * Default cooldown between lag reports for the same player.
+ */
+export declare const DEFAULT_LAG_REPORT_COOLDOWN_TICKS = 60;
+/**
+ * Monitors player lag and generates reports when players fall too far behind.
+ *
+ * Uses a cooldown system to prevent flooding the host with lag reports
+ * for persistently lagging players.
+ */
+export declare class LagMonitor {
+    private readonly threshold;
+    private readonly cooldownTicks;
+    private readonly lastReportTick;
+    constructor(config: LagMonitorConfig);
+    /**
+     * Check if a player is lagging and should be reported.
+     *
+     * @param playerId - The player to check
+     * @param ticksBehind - How many ticks behind the player is
+     * @param currentTick - The current simulation tick
+     * @returns A LagReport if the player is lagging and cooldown has passed, null otherwise
+     */
+    checkPlayer(playerId: PlayerId, ticksBehind: number, currentTick: Tick): LagReport | null;
+    /**
+     * Reset the cooldown for a player.
+     * Use this when a player recovers from lag.
+     *
+     * @param playerId - The player to reset
+     */
+    reset(playerId: PlayerId): void;
+    /**
+     * Clear all lag tracking state.
+     */
+    clear(): void;
+    /**
+     * Whether lag monitoring is enabled.
+     */
+    get isEnabled(): boolean;
+}
+//# sourceMappingURL=lag-monitor.d.ts.map

package/dist/session/lag-monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lag-monitor.d.ts","sourceRoot":"","sources":["../../src/session/lag-monitor.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACzB,gCAAgC;IAChC,aAAa,EAAE,QAAQ,CAAC;IACxB,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,eAAO,MAAM,iCAAiC,KAAK,CAAC;AAEpD;;;;;GAKG;AACH,qBAAa,UAAU;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAkC;gBAErD,MAAM,EAAE,gBAAgB;IAKpC;;;;;;;OAOG;IACH,WAAW,CACV,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,IAAI,GACf,SAAS,GAAG,IAAI;IA4BnB;;;;;OAKG;IACH,KAAK,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAI/B;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;CACD"}

package/dist/session/lag-monitor.js

@@ -0,0 +1,74 @@
+/**
+ * Lag monitoring for detecting and reporting players that fall behind.
+ */
+/**
+ * Default cooldown between lag reports for the same player.
+ */
+export const DEFAULT_LAG_REPORT_COOLDOWN_TICKS = 60;
+/**
+ * Monitors player lag and generates reports when players fall too far behind.
+ *
+ * Uses a cooldown system to prevent flooding the host with lag reports
+ * for persistently lagging players.
+ */
+export class LagMonitor {
+    threshold;
+    cooldownTicks;
+    lastReportTick = new Map();
+    constructor(config) {
+        this.threshold = config.threshold;
+        this.cooldownTicks = config.cooldownTicks;
+    }
+    /**
+     * Check if a player is lagging and should be reported.
+     *
+     * @param playerId - The player to check
+     * @param ticksBehind - How many ticks behind the player is
+     * @param currentTick - The current simulation tick
+     * @returns A LagReport if the player is lagging and cooldown has passed, null otherwise
+     */
+    checkPlayer(playerId, ticksBehind, currentTick) {
+        // Disabled if threshold is 0 or negative
+        if (this.threshold <= 0) {
+            return null;
+        }
+        // Not lagging enough
+        if (ticksBehind < this.threshold) {
+            return null;
+        }
+        // Check cooldown
+        const lastReport = this.lastReportTick.get(playerId);
+        if (lastReport !== undefined &&
+            currentTick - lastReport < this.cooldownTicks) {
+            return null;
+        }
+        // Record this report and return
+        this.lastReportTick.set(playerId, currentTick);
+        return {
+            laggyPlayerId: playerId,
+            ticksBehind,
+        };
+    }
+    /**
+     * Reset the cooldown for a player.
+     * Use this when a player recovers from lag.
+     *
+     * @param playerId - The player to reset
+     */
+    reset(playerId) {
+        this.lastReportTick.delete(playerId);
+    }
+    /**
+     * Clear all lag tracking state.
+     */
+    clear() {
+        this.lastReportTick.clear();
+    }
+    /**
+     * Whether lag monitoring is enabled.
+     */
+    get isEnabled() {
+        return this.threshold > 0;
+    }
+}
+//# sourceMappingURL=lag-monitor.js.map

package/dist/session/lag-monitor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lag-monitor.js","sourceRoot":"","sources":["../../src/session/lag-monitor.ts"],"names":[],"mappings":"AAAA;;GAEG;AA+BH;;GAEG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,EAAE,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,OAAO,UAAU;IACL,SAAS,CAAS;IAClB,aAAa,CAAS;IACtB,cAAc,GAAwB,IAAI,GAAG,EAAE,CAAC;IAEjE,YAAY,MAAwB;QACnC,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;QAClC,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC,aAAa,CAAC;IAC3C,CAAC;IAED;;;;;;;OAOG;IACH,WAAW,CACV,QAAkB,EAClB,WAAmB,EACnB,WAAiB;QAEjB,yCAAyC;QACzC,IAAI,IAAI,CAAC,SAAS,IAAI,CAAC,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC;QACb,CAAC;QAED,qBAAqB;QACrB,IAAI,WAAW,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;YAClC,OAAO,IAAI,CAAC;QACb,CAAC;QAED,iBAAiB;QACjB,MAAM,UAAU,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACrD,IACC,UAAU,KAAK,SAAS;YACxB,WAAW,GAAG,UAAU,GAAG,IAAI,CAAC,aAAa,EAC5C,CAAC;YACF,OAAO,IAAI,CAAC;QACb,CAAC;QAED,gCAAgC;QAChC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;QAC/C,OAAO;YACN,aAAa,EAAE,QAAQ;YACvB,WAAW;SACX,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,QAAkB;QACvB,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACtC,CAAC;IAED;;OAEG;IACH,KAAK;QACJ,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,IAAI,SAAS;QACZ,OAAO,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;IAC3B,CAAC;CACD"}