@phalanx-engine/client 0.1.0

package/dist/PhalanxClient.d.ts

@@ -0,0 +1,335 @@
+/**
+ * Phalanx Client
+ * Client library for connecting to Phalanx Engine servers
+ */
+import { EventEmitter } from './EventEmitter.js';
+import { type DesyncConfig } from './DesyncDetector.js';
+import { RoomRecoveryController } from './recovery/index.js';
+import type { PhalanxClientConfig, PhalanxClientEvents, PhalanxAuthState, PhalanxAuthUser, PlayerCommand, MatchFoundEvent, CountdownEvent, GameStartEvent, QueueStatusEvent, ReconnectStateEvent, SubmitCommandsAck, ConnectionState, ClientState, TickHandler, FrameHandler, Unsubscribe, PauseHandler, RoomCreatedEvent, RoomRecoveredEvent } from './types.js';
+/**
+ * PhalanxClient - Main client class for connecting to Phalanx Engine servers
+ *
+ * @example
+ * ```typescript
+ * const client = await PhalanxClient.create({
+ *   serverUrl: 'http://localhost:3000',
+ *   playerId: 'player-123',
+ *   username: 'MyPlayer',
+ * });
+ *
+ * client.on('matchFound', (data) => console.log('Match found!'));
+ * client.on('gameStart', () => console.log('Game started!'));
+ *
+ * await client.joinQueue();
+ *
+ * client.onTick((tick, commands) => {
+ *   // Process commands and run simulation
+ * });
+ *
+ * client.onFrame((alpha, dt) => {
+ *   // Interpolate and render
+ * });
+ * ```
+ */
+export declare class PhalanxClient extends EventEmitter<PhalanxClientEvents> {
+    private config;
+    private socketManager;
+    private renderLoop;
+    private desyncDetector;
+    private authManager;
+    private _roomRecovery;
+    private clientState;
+    private currentMatchId;
+    private currentTick;
+    private authState;
+    private pendingCommands;
+    private pauseHandlers;
+    private resumeHandlers;
+    constructor(config: PhalanxClientConfig);
+    private createRoomRecoveryController;
+    /**
+     * Mobile-friendly room recovery controller. `null` unless
+     * `roomRecovery.enabled` was set in the config. See
+     * `RoomRecoveryController` for the surface — typically you only
+     * need `startTrackingHost(code)` after creating a private room and
+     * `loadColdStartCode()` on app startup.
+     */
+    get roomRecovery(): RoomRecoveryController | null;
+    /**
+     * Initialize authentication manager
+     */
+    private initializeAuth;
+    /**
+     * Handle auth state changes from AuthManager
+     */
+    private handleAuthStateChange;
+    /**
+     * Handle OAuth callback from redirect
+     */
+    private handleAuthCallback;
+    /**
+     * Start login flow (redirects to OAuth provider)
+     */
+    login(): void;
+    /**
+     * Log out the current user
+     */
+    logout(): Promise<void>;
+    /**
+     * Get current authentication state
+     */
+    getAuthState(): PhalanxAuthState;
+    /**
+     * Check if user is authenticated
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Get current user info
+     */
+    getUser(): PhalanxAuthUser | null;
+    /**
+     * Create and connect a new PhalanxClient
+     * @param config Client configuration
+     * @returns Connected PhalanxClient instance
+     */
+    static create(config: PhalanxClientConfig): Promise<PhalanxClient>;
+    /**
+     * Connect to the Phalanx server
+     * @returns Promise that resolves when connected
+     * @throws Error if connection fails or times out
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the server
+     */
+    disconnect(): void;
+    /**
+     * Destroy the client and clean up all resources
+     */
+    destroy(): void;
+    /**
+     * Check if client is connected to the server
+     */
+    isConnected(): boolean;
+    /**
+     * Get current connection state
+     */
+    getConnectionState(): ConnectionState;
+    /**
+     * Get current client state
+     */
+    getClientState(): ClientState;
+    /**
+     * Join the matchmaking queue
+     * @returns Promise that resolves with queue status
+     */
+    joinQueue(): Promise<QueueStatusEvent>;
+    /**
+     * Leave the matchmaking queue
+     */
+    leaveQueue(): void;
+    /**
+     * Create a private room and wait for the room code.
+     * After creation, the host should wait for match-found (when another player joins).
+     */
+    createRoom(gameType?: string): Promise<RoomCreatedEvent>;
+    /**
+     * Join a private room by code.
+     * The server will create a match and emit match-found to both players.
+     */
+    joinRoom(code: string): void;
+    /**
+     * Cancel a previously created private room.
+     */
+    cancelRoom(): void;
+    /**
+     * Reclaim a private room after a transient socket disconnect.
+     *
+     * Call this after `connect()` has re-established the underlying socket
+     * (typically inside a `visibilitychange` listener, or the first thing
+     * on `pageshow` from bfcache) to tell the server to re-bind the still-
+     * living room / in-flight match to this new socket.
+     *
+     * On success the server emits `match-found` (if a guest had already
+     * joined) followed by `reconnect-state` carrying a countdown snapshot,
+     * which `SocketManager`'s global `reconnect-state` handler fans out
+     * through the local `countdown` and `game-start` listeners so any
+     * `waitForCountdown` / `waitForGameStart` promises pending since the
+     * original flow resume naturally.
+     *
+     * Rejects with the server's `room-error` message (e.g. `'Room expired'`)
+     * or `'Recover timeout'` if the server doesn't answer before the configured
+     * recovery timeout.
+     */
+    recoverRoom(code: string, timeoutMs?: number): Promise<RoomRecoveredEvent>;
+    /**
+     * Request the server to pause the game.
+     * The game will not freeze immediately — it freezes only when the server
+     * broadcasts the 'game-paused' event back to all clients, ensuring
+     * every client pauses at the same deterministic point.
+     */
+    pauseGame(): void;
+    /**
+     * Request the server to resume the game.
+     * Same as pause — the actual resume occurs when the server broadcasts
+     * 'game-resumed' to all clients.
+     */
+    resumeGame(): void;
+    /**
+     * Notify the server that this client has finished loading and is ready to receive ticks.
+     * Must be called after assets are loaded and game systems are initialized.
+     * The server will not start the tick loop until all clients report ready.
+     */
+    sendReady(): void;
+    /**
+     * Wait for a match to be found
+     * @returns Promise that resolves with match found event
+     */
+    waitForMatch(): Promise<MatchFoundEvent>;
+    /**
+     * Join queue and wait for match in one call
+     * @returns Promise that resolves with match found event
+     */
+    joinQueueAndWaitForMatch(): Promise<MatchFoundEvent>;
+    /**
+     * Wait for countdown to complete (listening to countdown events)
+     * @param onCountdown Optional callback for each countdown tick
+     * @returns Promise that resolves when countdown reaches 0
+     */
+    waitForCountdown(onCountdown?: (event: CountdownEvent) => void): Promise<void>;
+    /**
+     * Wait for the game to start
+     * @returns Promise that resolves with game start event
+     */
+    waitForGameStart(): Promise<GameStartEvent>;
+    /**
+     * Submit commands for a specific tick
+     * @param tick The tick number these commands are for
+     * @param commands Array of commands to submit
+     * @returns Promise that resolves with acknowledgment
+     */
+    submitCommands(tick: number, commands: PlayerCommand[]): Promise<SubmitCommandsAck>;
+    /**
+     * Submit commands without waiting for acknowledgment (fire and forget)
+     * @param tick The tick number these commands are for
+     * @param commands Array of commands to submit
+     */
+    submitCommandsAsync(tick: number, commands: PlayerCommand[]): void;
+    /**
+     * Send a command to the server
+     * Commands are buffered and sent automatically each frame
+     *
+     * @param type Command type (e.g., 'move', 'attack')
+     * @param data Command payload
+     */
+    sendCommand(type: string, data: unknown): void;
+    /**
+     * Register a callback for simulation ticks
+     * Called when the server sends a tick with commands from all players
+     *
+     * @param handler Callback receiving tick number and commands grouped by player
+     * @returns Unsubscribe function
+     */
+    onTick(handler: TickHandler): Unsubscribe;
+    /**
+     * Register a callback for render frames
+     * Called every animation frame (~60fps) with interpolation alpha
+     * Automatically starts the render loop when first handler is added
+     *
+     * @param handler Callback receiving alpha (0-1) and delta time in seconds
+     * @returns Unsubscribe function
+     */
+    onFrame(handler: FrameHandler): Unsubscribe;
+    /**
+     * Request the server to pause the game (ITickFrameProvider contract).
+     * The actual pause is signalled asynchronously via onPause when the
+     * server broadcasts 'game-paused' to all clients.
+     */
+    requestPause(): void;
+    /**
+     * Request the server to resume the game (ITickFrameProvider contract).
+     * The actual resume is signalled asynchronously via onResume when the
+     * server broadcasts 'game-resumed' to all clients.
+     */
+    requestResume(): void;
+    /**
+     * Subscribe to the "paused" signal (ITickFrameProvider contract).
+     * Fired when the server confirms the pause and broadcasts it.
+     */
+    onPause(handler: PauseHandler): Unsubscribe;
+    /**
+     * Subscribe to the "resumed" signal (ITickFrameProvider contract).
+     * Fired when the server confirms the resume and broadcasts it.
+     */
+    onResume(handler: PauseHandler): Unsubscribe;
+    /**
+     * Attempt to reconnect to a match after disconnection
+     * @param matchId The match ID to reconnect to
+     * @returns Promise that resolves with reconnection state
+     */
+    reconnectToMatch(matchId: string): Promise<ReconnectStateEvent>;
+    /**
+     * Attempt automatic reconnection with retries
+     * @returns Promise that resolves when reconnected, rejects if all attempts fail
+     */
+    attemptReconnection(): Promise<void>;
+    /**
+     * Submit state hash for desync detection
+     * Call this after each simulation tick (or every N ticks based on your preference)
+     *
+     * The game is responsible for computing the hash using StateHasher or
+     * a custom implementation. The SDK just handles transport and comparison.
+     *
+     * @param tick - The tick this hash is for
+     * @param hash - Hash computed by game (any string)
+     *
+     * @example
+     * ```typescript
+     * client.onTick((tick, commands) => {
+     *   simulation.processTick(tick, commands);
+     *
+     *   // Submit hash every 20 ticks (once per second at 20 TPS)
+     *   if (tick % 20 === 0) {
+     *     const hash = computeGameStateHash(tick);
+     *     client.submitStateHash(tick, hash);
+     *   }
+     * });
+     * ```
+     */
+    submitStateHash(tick: number, hash: string): void;
+    /**
+     * Configure desync detection
+     * @param config - Configuration options for desync detection
+     *
+     * @example
+     * ```typescript
+     * // Disable desync detection
+     * client.configureDesyncDetection({ enabled: false });
+     *
+     * // Limit stored hashes
+     * client.configureDesyncDetection({ maxStoredHashes: 50 });
+     * ```
+     */
+    configureDesyncDetection(config: Partial<DesyncConfig>): void;
+    /**
+     * Get current tick number
+     */
+    getCurrentTick(): number;
+    /**
+     * Get current match ID
+     */
+    getMatchId(): string | null;
+    /**
+     * Get player ID configured for this client
+     */
+    getPlayerId(): string;
+    /**
+     * Get username configured for this client
+     */
+    getUsername(): string;
+    private flushPendingCommands;
+    private ensureConnected;
+    private ensurePlaying;
+    private log;
+}
+//# sourceMappingURL=PhalanxClient.d.ts.map

package/dist/PhalanxClient.d.ts.map

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