@phalanx-engine/server 0.1.0

package/dist/config/defaults.js

@@ -0,0 +1,51 @@
+/**
+ * Game mode presets configuration
+ */
+export const GAME_MODES = {
+    '1v1': { playersPerMatch: 2, teamsCount: 2 },
+    '2v2': { playersPerMatch: 4, teamsCount: 2 },
+    '3v3': { playersPerMatch: 6, teamsCount: 2 },
+    '4v4': { playersPerMatch: 8, teamsCount: 2 },
+    FFA4: { playersPerMatch: 4, teamsCount: 4 },
+};
+/**
+ * Default configuration values
+ */
+export const DEFAULT_CONFIG = {
+    // Server
+    port: 3000,
+    cors: { origin: '*' },
+    // Tick System
+    tickRate: 20,
+    tickDeadlineMs: 50,
+    tickMode: 'continuous',
+    // Only applies to tickMode: 'event' — ignored in continuous mode
+    turnTimeoutMs: 60000,
+    gameTypes: [],
+    // Matchmaking
+    gameMode: '1v1',
+    matchmakingIntervalMs: 1000,
+    countdownSeconds: 5,
+    // Timeouts
+    timeoutTicks: 40,
+    disconnectTicks: 100,
+    reconnectGracePeriodMs: 30000,
+    // Command Validation
+    maxTickBehind: 10,
+    maxTickAhead: 5,
+    // Command History (for reconnection)
+    commandHistoryTicks: 200, // 10 seconds at 20 TPS
+    // Determinism Features (Phase 2.1) - disabled by default for backward compatibility
+    validateInputSequence: false,
+    enableStateHashing: false,
+    stateHashInterval: 60, // 3 seconds at 20 TPS
+    // Ready Handshake
+    readyTimeoutMs: 30000,
+    // Desync Detection Behavior
+    desync: {
+        enabled: true,
+        action: 'end-match', // 'log-only' | 'end-match'
+        gracePeriodTicks: 1, // Consecutive desyncs before action
+    },
+};
+//# sourceMappingURL=defaults.js.map

package/dist/config/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/config/defaults.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAA2C;IAChE,KAAK,EAAE,EAAE,eAAe,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE;IAC5C,KAAK,EAAE,EAAE,eAAe,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE;IAC5C,KAAK,EAAE,EAAE,eAAe,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE;IAC5C,KAAK,EAAE,EAAE,eAAe,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE;IAC5C,IAAI,EAAE,EAAE,eAAe,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE;CAC5C,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAkB;IAC3C,SAAS;IACT,IAAI,EAAE,IAAI;IACV,IAAI,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE;IAErB,cAAc;IACd,QAAQ,EAAE,EAAE;IACZ,cAAc,EAAE,EAAE;IAClB,QAAQ,EAAE,YAAY;IACtB,iEAAiE;IACjE,aAAa,EAAE,KAAK;IACpB,SAAS,EAAE,EAAE;IAEb,cAAc;IACd,QAAQ,EAAE,KAAK;IACf,qBAAqB,EAAE,IAAI;IAC3B,gBAAgB,EAAE,CAAC;IAEnB,WAAW;IACX,YAAY,EAAE,EAAE;IAChB,eAAe,EAAE,GAAG;IACpB,sBAAsB,EAAE,KAAK;IAE7B,qBAAqB;IACrB,aAAa,EAAE,EAAE;IACjB,YAAY,EAAE,CAAC;IAEf,qCAAqC;IACrC,mBAAmB,EAAE,GAAG,EAAE,uBAAuB;IAEjD,oFAAoF;IACpF,qBAAqB,EAAE,KAAK;IAC5B,kBAAkB,EAAE,KAAK;IACzB,iBAAiB,EAAE,EAAE,EAAE,sBAAsB;IAE7C,kBAAkB;IAClB,cAAc,EAAE,KAAK;IAErB,4BAA4B;IAC5B,MAAM,EAAE;QACN,OAAO,EAAE,IAAI;QACb,MAAM,EAAE,WAAW,EAAE,2BAA2B;QAChD,gBAAgB,EAAE,CAAC,EAAE,oCAAoC;KAC1D;CACF,CAAC"}

package/dist/config/validation.d.ts

@@ -0,0 +1,15 @@
+import type { PhalanxConfig } from '../types/index.js';
+/**
+ * Validates and merges user configuration with defaults
+ * @param userConfig - Partial user configuration
+ * @returns Complete validated configuration
+ */
+export declare function validateConfig(userConfig?: Partial<PhalanxConfig>): PhalanxConfig;
+/**
+ * Gets the resolved game mode (players per match and teams count)
+ */
+export declare function resolveGameMode(gameMode: PhalanxConfig['gameMode']): {
+    playersPerMatch: number;
+    teamsCount: number;
+};
+//# sourceMappingURL=validation.d.ts.map

package/dist/config/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/config/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGvD;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,UAAU,GAAE,OAAO,CAAC,aAAa,CAAM,GACtC,aAAa,CAuEf;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG;IACpE,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB,CAKA"}

package/dist/config/validation.js

@@ -0,0 +1,74 @@
+import { DEFAULT_CONFIG, GAME_MODES } from './defaults.js';
+/**
+ * Validates and merges user configuration with defaults
+ * @param userConfig - Partial user configuration
+ * @returns Complete validated configuration
+ */
+export function validateConfig(userConfig = {}) {
+    const config = {
+        ...DEFAULT_CONFIG,
+        ...userConfig,
+        cors: {
+            ...DEFAULT_CONFIG.cors,
+            ...(userConfig.cors || {}),
+        },
+        desync: {
+            ...DEFAULT_CONFIG.desync,
+            ...(userConfig.desync || {}),
+        },
+    };
+    // Validate port
+    if (config.port < 1 || config.port > 65535) {
+        throw new Error(`Invalid port: ${config.port}. Must be between 1 and 65535.`);
+    }
+    // Validate tickRate
+    if (config.tickRate < 1 || config.tickRate > 128) {
+        throw new Error(`Invalid tickRate: ${config.tickRate}. Must be between 1 and 128.`);
+    }
+    // Validate tickDeadlineMs
+    if (config.tickDeadlineMs < 1) {
+        throw new Error(`Invalid tickDeadlineMs: ${config.tickDeadlineMs}. Must be positive.`);
+    }
+    // Validate gameMode
+    if (typeof config.gameMode === 'string') {
+        if (!GAME_MODES[config.gameMode]) {
+            throw new Error(`Invalid gameMode: ${config.gameMode}. Valid presets: ${Object.keys(GAME_MODES).join(', ')}`);
+        }
+    }
+    else if (typeof config.gameMode === 'object') {
+        if (config.gameMode.playersPerMatch < 2) {
+            throw new Error('playersPerMatch must be at least 2');
+        }
+        if (config.gameMode.teamsCount < 1) {
+            throw new Error('teamsCount must be at least 1');
+        }
+        if (config.gameMode.teamsCount > config.gameMode.playersPerMatch) {
+            throw new Error('teamsCount cannot exceed playersPerMatch');
+        }
+    }
+    // Validate timeout values
+    if (config.timeoutTicks < 1) {
+        throw new Error('timeoutTicks must be positive');
+    }
+    if (config.disconnectTicks < config.timeoutTicks) {
+        throw new Error('disconnectTicks must be >= timeoutTicks');
+    }
+    // Validate tick range limits
+    if (config.maxTickBehind < 1) {
+        throw new Error('maxTickBehind must be positive');
+    }
+    if (config.maxTickAhead < 1) {
+        throw new Error('maxTickAhead must be positive');
+    }
+    return config;
+}
+/**
+ * Gets the resolved game mode (players per match and teams count)
+ */
+export function resolveGameMode(gameMode) {
+    if (typeof gameMode === 'string') {
+        return GAME_MODES[gameMode];
+    }
+    return gameMode;
+}
+//# sourceMappingURL=validation.js.map

package/dist/config/validation.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Phalanx Engine
+ * A game-agnostic deterministic lockstep multiplayer engine
+ */
+export { Phalanx } from './Phalanx.js';
+export { TokenValidatorService, createDevValidator, createEndpointValidator, } from './services/TokenValidator.js';
+export { DeterministicRandom } from './utils/index.js';
+export { FP, FPVector2, FPVector3, FixedPoint } from './utils/index.js';
+export type { FPVector2Interface, FPVector3Interface } from './utils/index.js';
+export type { PhalanxConfig, PlayerCommand, MatchFoundEvent, GameStartEvent, TickSyncEvent, CommandsBatchEvent, TickCommands, SubmitCommandsEvent, PlayerInfo, MatchInfo, GameMode, GameModePreset, CustomGameMode, CorsConfig, TlsConfig, QueuedPlayer, QueueStatusEvent, StateHashEvent, DesyncDetectedEvent, PhalanxEventType, PhalanxEventHandlers, AuthConfig, TokenValidator, TokenValidationResult, DesyncConfig, DesyncAction, PauseConfig, TickMode, GameTypeConfig, RoomCreatedEvent, RoomRecoveredEvent, RoomErrorEvent, } from './types/index.js';
+export { GAME_MODES } from './config/defaults.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACxE,YAAY,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAG/E,YAAY,EACV,aAAa,EACb,aAAa,EACb,eAAe,EACf,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,mBAAmB,EACnB,UAAU,EACV,SAAS,EACT,QAAQ,EACR,cAAc,EACd,cAAc,EACd,UAAU,EACV,SAAS,EACT,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EAEpB,UAAU,EACV,cAAc,EACd,qBAAqB,EAErB,YAAY,EACZ,YAAY,EAEZ,WAAW,EAEX,QAAQ,EACR,cAAc,EAEd,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * Phalanx Engine
+ * A game-agnostic deterministic lockstep multiplayer engine
+ */
+// Main class
+export { Phalanx } from './Phalanx.js';
+// Authentication
+export { TokenValidatorService, createDevValidator, createEndpointValidator, } from './services/TokenValidator.js';
+// Utilities
+export { DeterministicRandom } from './utils/index.js';
+export { FP, FPVector2, FPVector3, FixedPoint } from './utils/index.js';
+// Constants
+export { GAME_MODES } from './config/defaults.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,aAAa;AACb,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,iBAAiB;AACjB,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,8BAA8B,CAAC;AAEtC,YAAY;AACZ,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AA4CxE,YAAY;AACZ,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/services/GameRoom.d.ts

@@ -0,0 +1,359 @@
+import type { Server as SocketIOServer } from 'socket.io';
+import type { PhalanxConfig, QueuedPlayer, MatchInfo, PlayerCommand, TickCommands } from '../types/index.js';
+/**
+ * Game Room
+ * Handles a single match with tick synchronization and command broadcasting
+ */
+export declare class GameRoom {
+    private readonly id;
+    private readonly roomId;
+    private readonly io;
+    private readonly config;
+    private readonly players;
+    private readonly socketToPlayer;
+    private readonly teams;
+    private readonly eventEmitter;
+    private currentTick;
+    private state;
+    private createdAt;
+    private tickInterval;
+    private countdownTimer;
+    private countdownInterval;
+    /**
+     * Set when the match enters `'waiting-for-players'` (i.e. start()
+     * was called but at least one participant's socket was offline).
+     * Fires after `playersConnectTimeoutMs` and ends the match with
+     * `match-end: 'players-not-connected'` so the connected players
+     * aren't stranded indefinitely waiting for someone who's never
+     * coming back.
+     *
+     * Cleared in `transitionFromWaitingForPlayers` when everyone's
+     * online and we proceed to the countdown, or in `stop()` on shutdown.
+     */
+    private playersConnectTimeout;
+    /**
+     * How long we'll hold the deferred-start state before giving up on
+     * absent participants. Long enough to cover a typical mobile
+     * "switched to messenger" round-trip, short enough that the
+     * connected player isn't staring at a frozen lobby. Pulled from
+     * config when available so games can tune it.
+     */
+    private readonly playersConnectTimeoutMs;
+    /**
+     * Absolute epoch-ms deadline for the countdown, set when the countdown
+     * starts and cleared when `game-start` is emitted. Used to compute the
+     * remaining seconds for a late-joining socket (e.g. a private-room host
+     * whose mobile browser killed the WebSocket while they were sharing the
+     * invite link) so the client can render the correct number instead of
+     * staying stuck on the last value it saw before disconnecting.
+     */
+    private countdownDeadline;
+    /**
+     * Set to true once `game-start` has been broadcast. A host who recovers
+     * after this point needs to synthesize the event locally — we signal
+     * that via this flag in the `reconnect-state` payload so the client can
+     * transition out of the countdown UI without waiting for a second
+     * `game-start` it will never receive.
+     */
+    private gameStartEmitted;
+    private pendingCommands;
+    private readyPlayers;
+    private readyTimeout;
+    private readonly readyTimeoutMs;
+    private commandBuffer;
+    private tickSubmissions;
+    private lastMessageTime;
+    private commandHistory;
+    private laggingPlayers;
+    private readonly randomSeed;
+    private lastSequence;
+    private stateHashes;
+    private consecutiveDesyncs;
+    private readonly desyncConfig;
+    private readonly pauseConfig;
+    private pauseCount;
+    private pausedByPlayerId;
+    private readonly gameType;
+    private readonly tickMode;
+    private turnTimeout;
+    constructor(id: string, io: SocketIOServer, config: PhalanxConfig, teams: QueuedPlayer[][], eventEmitter: (event: string, ...args: unknown[]) => boolean | void, gameType?: string);
+    /**
+     * Start the game room.
+     *
+     * If every participant's socket is currently live we proceed straight
+     * to the countdown. Otherwise the room enters
+     * `'waiting-for-players'` — `match-found` and
+     * `match-waiting-for-players` are emitted to whoever is online, and
+     * the countdown is held back until either:
+     *
+     *   - every player has reconnected (via `GameRoom.handleReconnect`,
+     *     typically driven by the engine's room/match-recover handlers
+     *     for the private-room case), at which point we transition to
+     *     the countdown; OR
+     *
+     *   - `playersConnectTimeoutMs` elapses and we end the match with
+     *     `match-end: 'players-not-connected'`, freeing the participants
+     *     who DID show up.
+     *
+     * Putting this gate inside `GameRoom` (rather than at the
+     * matchmaking / private-room layer) means every flow that builds a
+     * match — public matchmaking, private invites, future custom
+     * lobbies — gets the same "don't drop a single player into a
+     * countdown alone" guarantee for free.
+     */
+    start(): void;
+    /**
+     * Drive the deferred-start state machine forward: invoked from
+     * `handleReconnect` once a previously-missing player has rebound
+     * their socket. If everyone is now present, cancels the players-
+     * connect timeout and transitions into the countdown; otherwise
+     * just re-broadcasts the updated waiting-for-players list.
+     */
+    private maybeBeginCountdownAfterReconnect;
+    /** True iff every participant's `connected` flag is set. */
+    private areAllPlayersConnected;
+    /** PlayerIds whose `connected` flag is currently false. */
+    private getDisconnectedPlayerIds;
+    /**
+     * Broadcast `match-waiting-for-players` to every currently-connected
+     * socket in the room, listing which playerIds we're still waiting on.
+     * Uses `this.io.to(this.roomId).emit(...)` so socket.io handles room
+     * routing to currently connected sockets while we include the canonical
+     * `matchId` in the payload, consistent with `notifyMatchFound`.
+     */
+    private notifyWaitingForPlayers;
+    /**
+     * Emit a lifecycle event directly to every currently-connected player.
+     *
+     * `match-found` is already sent as a direct socket event, while the
+     * countdown used to depend on Socket.IO room membership established a
+     * few lines earlier in `start()`. Mobile transports can race around
+     * polling/websocket upgrade or a brief reconnect: the host still sees
+     * `match-found` and switches to the countdown screen, but misses the
+     * room broadcast that should advance it. Direct delivery keeps the
+     * pre-game lifecycle level with the personalized match-found path.
+     */
+    private emitLifecycleToConnectedPlayers;
+    /**
+     * Start the game countdown
+     * Emits countdown events (5, 4, 3, 2, 1, 0) every second, then game-start
+     */
+    private startGameCountdown;
+    /**
+     * Transition to waiting-for-ready state.
+     * The tick loop will not begin until all clients send 'client-ready'.
+     */
+    private enterWaitingForReady;
+    private armReadyTimeout;
+    private clearReadyTimeout;
+    private armPlayersReconnectTimeout;
+    private clearPlayersReconnectTimeout;
+    /**
+     * Notify all players that a match has been found
+     * Each player receives personalized data about their teammates and opponents
+     */
+    private notifyMatchFound;
+    /**
+     * Build the personalized `match-found` payload for `playerId`.
+     *
+     * Used by the initial broadcast in {@link notifyMatchFound} and by
+     * retroactive delivery when a host who was offline at `joinRoom`
+     * time finally reconnects via `room-recover`. Returns `null` if
+     * the player is not in this match.
+     */
+    buildMatchFoundPayload(playerId: string): {
+        matchId: string;
+        playerId: string;
+        teamId: number;
+        teammates: {
+            playerId: string;
+            username: string;
+        }[];
+        opponents: {
+            playerId: string;
+            username: string;
+        }[];
+    } | null;
+    private buildMatchFoundPayloadForTeam;
+    /**
+     * Handle a player reporting ready after asset loading.
+     *
+     * The match only starts once *every* player in the room is both
+     * connected and has explicitly reported `client-ready`
+     * (see `areAllPlayersConnectedAndReady`). If any player is
+     * disconnected (e.g. mid-reconnect during `waiting-for-ready`),
+     * the gate stays closed even if all currently-connected players
+     * are ready.
+     *
+     * Once the gate opens:
+     *  - In `continuous` tick mode the tick loop is started.
+     *  - In `event` tick mode no tick loop is created; the turn
+     *    timeout is armed via `resetTurnTimeout()` instead.
+     *
+     * @param playerId - The player reporting ready
+     */
+    handlePlayerReady(playerId: string): void;
+    /**
+     * End the match because not all clients reported ready within the timeout.
+     */
+    private endMatchDueToReadyTimeout;
+    /**
+     * Start the actual game (after countdown)
+     */
+    private startGame;
+    /**
+     * Process a single tick
+     */
+    private processTick;
+    /**
+     * Handle a player command
+     */
+    handleCommand(playerId: string, command: PlayerCommand): boolean;
+    /**
+     * Validate command sequence number (2.1.4)
+     * Returns true if sequence is valid, false otherwise
+     */
+    private validateCommandSequence;
+    /**
+     * Receive commands from a player for a specific tick (LOCKSTEP-2)
+     * Commands can be empty if player has no actions for this tick.
+     * This is normal - units may be moving/idle and player doesn't need to input anything.
+     */
+    receivePlayerCommands(playerId: string, tick: number, commands: PlayerCommand[]): {
+        accepted: boolean;
+        invalidCommands?: PlayerCommand[];
+    };
+    /**
+     * Get all commands for a specific tick
+     */
+    getCommandsForTick(tick: number): TickCommands | null;
+    /**
+     * Check if all players have submitted for a specific tick
+     */
+    allPlayersSubmittedForTick(tick: number): boolean;
+    /**
+     * Get which players have submitted for a specific tick
+     */
+    getSubmissionsForTick(tick: number): Set<string>;
+    /**
+     * Clean up old ticks after they've been processed
+     */
+    clearOldTicks(beforeTick: number): void;
+    /**
+     * Update player activity timestamp (called on any message from player)
+     * Uses real time instead of ticks - more reliable with Socket.IO ping/pong
+     */
+    updatePlayerActivity(playerId: string): void;
+    /**
+     * Check for lagging/disconnected players (LOCKSTEP-5)
+     * Uses real time (ms) instead of ticks for more reliable detection.
+     * Skipped entirely in event mode (turn timeout handles inactivity).
+     */
+    private checkPlayerTimeouts;
+    /**
+     * Reset (or start) the turn timeout for event mode.
+     * If no commands arrive within turnTimeoutMs the match ends.
+     */
+    private resetTurnTimeout;
+    /**
+     * End the match because the turn timeout expired (event mode only).
+     */
+    private endMatchDueToTurnTimeout;
+    /**
+     * Store command history for reconnection support (NET-2)
+     */
+    private storeCommandHistory;
+    /**
+     * Get recent command history for reconnecting player (NET-2)
+     */
+    getRecentCommandHistory(fromTick: number): {
+        tick: number;
+        commands: PlayerCommand[];
+    }[];
+    /**
+     * Pause the game.
+     * Stops the tick loop and broadcasts 'game-paused' to all clients.
+     * All clients freeze deterministically because the pause only takes effect
+     * when they receive this broadcast (after the last completed tick).
+     *
+     * @param requestedBy - Player ID who requested the pause
+     * @returns true if the game was paused, false if not in a pauseable state or player exceeded pause limit
+     */
+    pause(requestedBy: string): boolean;
+    /**
+     * Resume the game after a pause.
+     * Restarts the tick loop and broadcasts 'game-resumed' to all clients.
+     *
+     * @param requestedBy - Player ID who requested the resume
+     * @returns true if the game was resumed, false if not currently paused or player not allowed to resume
+     */
+    resume(requestedBy: string): boolean;
+    /**
+     * Get current tick number
+     */
+    getCurrentTick(): number;
+    /**
+     * Stop the game room
+     * @param skipNotify - If true, skip emitting match-ended events (used when already handled)
+     */
+    stop(skipNotify?: boolean): void;
+    /**
+     * Handle player disconnection (NET-2)
+     */
+    handleDisconnect(socketId: string): void;
+    /**
+     * Handle player reconnection (NET-2)
+     */
+    handleReconnect(playerId: string, socketId: string): boolean;
+    /**
+     * Returns true only when every player in the room is currently
+     * connected *and* has reported `client-ready`. This is the
+     * authoritative gate for leaving the `waiting-for-ready` state
+     * and starting the match (continuous or event tick mode).
+     *
+     * A disconnected player keeps the gate closed even if all other
+     * players are ready, which is required for correct reconnect
+     * behavior during `waiting-for-ready`.
+     */
+    private areAllPlayersConnectedAndReady;
+    /**
+     * Whether the given playerId is a participant of this match.
+     * Used by `PrivateRoomService.recoverRoom` to authenticate a
+     * `room-recover` against a deferred / running match without
+     * exposing the players map.
+     */
+    hasPlayer(playerId: string): boolean;
+    /**
+     * Get match information
+     */
+    getMatchInfo(): MatchInfo;
+    /**
+     * Get the room ID
+     */
+    getId(): string;
+    /**
+     * Get the random seed for this match
+     * Clients use this to initialize their deterministic RNG
+     */
+    getRandomSeed(): number;
+    /**
+     * Receive state hash from a player for a specific tick
+     * @param playerId - The player sending the hash
+     * @param tick - The tick this hash is for
+     * @param hash - The state hash string
+     */
+    receiveStateHash(playerId: string, tick: number, hash: string): void;
+    /**
+     * Check if there's a desync at a given tick
+     */
+    private checkForDesync;
+    /**
+     * End the match due to confirmed desync
+     */
+    private endMatchDueToDesync;
+    /**
+     * Clean up state hashes older than the specified tick
+     */
+    private cleanupOldStateHashes;
+}
+//# sourceMappingURL=GameRoom.d.ts.map

package/dist/services/GameRoom.d.ts.map

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