@nice2dev/game-engine 1.1.5 → 1.1.6

package/dist/types/systems/NiceNetwork.d.ts

@@ -0,0 +1,568 @@
+/**
+ * NiceNetwork - Comprehensive Multiplayer Network System
+ *
+ * Professional networking system for real-time multiplayer games.
+ * Supports WebSocket, WebRTC, lobbies, matchmaking, and state sync.
+ *
+ * Features:
+ * - WebSocket / WebRTC connections
+ * - Lobby system with matchmaking
+ * - Room management
+ * - State synchronization
+ * - Client prediction & reconciliation
+ * - Lag compensation
+ * - Message serialization
+ * - RPC system
+ * - Peer-to-peer support
+ * - Host migration
+ *
+ * @packageDocumentation
+ */
+import { EventEmitter } from 'eventemitter3';
+/** Unique identifier for clients */
+export type ClientId = string;
+/** Unique identifier for rooms */
+export type RoomId = string;
+/** Unique identifier for lobbies */
+export type LobbyId = string;
+/** Unique identifier for entities */
+export type EntityId = string;
+/** Connection state */
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error';
+/** Network role */
+export type NetworkRole = 'server' | 'client' | 'host' | 'peer';
+/** Message priority */
+export type MessagePriority = 'low' | 'normal' | 'high' | 'critical';
+/** Delivery mode */
+export type DeliveryMode = 'unreliable' | 'reliable' | 'ordered';
+/** Serializable types */
+export type Serializable = string | number | boolean | null | undefined | Serializable[] | {
+    [key: string]: Serializable;
+};
+/** Network message */
+export interface NetworkMessage {
+    id: string;
+    type: string;
+    payload: Serializable;
+    senderId: ClientId;
+    timestamp: number;
+    sequence: number;
+    priority: MessagePriority;
+    delivery: DeliveryMode;
+}
+/** Client info */
+export interface ClientInfo {
+    id: ClientId;
+    name: string;
+    role: NetworkRole;
+    roomId?: RoomId;
+    lobbyId?: LobbyId;
+    ping: number;
+    lastSeen: number;
+    metadata: Record<string, Serializable>;
+    isReady: boolean;
+    isHost: boolean;
+}
+/** Room configuration */
+export interface RoomConfig {
+    id?: RoomId;
+    name: string;
+    maxPlayers: number;
+    minPlayers: number;
+    isPrivate: boolean;
+    password?: string;
+    gameMode?: string;
+    metadata?: Record<string, Serializable>;
+    tickRate: number;
+    allowLateJoin: boolean;
+    autoStart: boolean;
+}
+/** Room instance */
+export interface Room {
+    id: RoomId;
+    config: RoomConfig;
+    hostId: ClientId;
+    clients: Map<ClientId, ClientInfo>;
+    state: RoomState;
+    createdAt: number;
+    startedAt?: number;
+    gameState: Serializable;
+}
+/** Room state */
+export type RoomState = 'waiting' | 'countdown' | 'playing' | 'paused' | 'finished' | 'closed';
+/** Lobby configuration */
+export interface LobbyConfig {
+    id?: LobbyId;
+    name: string;
+    maxRooms: number;
+    region: string;
+    metadata?: Record<string, Serializable>;
+}
+/** Lobby instance */
+export interface Lobby {
+    id: LobbyId;
+    config: LobbyConfig;
+    rooms: Map<RoomId, RoomListing>;
+    clients: Set<ClientId>;
+    createdAt: number;
+}
+/** Room listing for lobby */
+export interface RoomListing {
+    id: RoomId;
+    name: string;
+    hostName: string;
+    playerCount: number;
+    maxPlayers: number;
+    isPrivate: boolean;
+    state: RoomState;
+    gameMode?: string;
+    ping?: number;
+    metadata?: Record<string, Serializable>;
+}
+/** Matchmaking request */
+export interface MatchmakingRequest {
+    clientId: ClientId;
+    gameMode: string;
+    rating?: number;
+    region?: string;
+    partyIds?: ClientId[];
+    preferences?: Record<string, Serializable>;
+    createdAt: number;
+}
+/** Matchmaking match */
+export interface MatchmakingMatch {
+    roomId: RoomId;
+    clients: ClientId[];
+    averageRating?: number;
+    region: string;
+}
+/** Network entity */
+export interface NetworkEntity {
+    id: EntityId;
+    ownerId: ClientId;
+    type: string;
+    state: Serializable;
+    lastUpdate: number;
+    version: number;
+    interpolation: {
+        previous: Serializable;
+        current: Serializable;
+        timestamp: number;
+    };
+}
+/** State snapshot */
+export interface StateSnapshot {
+    sequence: number;
+    timestamp: number;
+    entities: Map<EntityId, Serializable>;
+    gameState: Serializable;
+}
+/** Input frame */
+export interface InputFrame {
+    sequence: number;
+    timestamp: number;
+    inputs: Serializable;
+    clientId: ClientId;
+}
+/** RPC definition */
+export interface RPCDefinition {
+    name: string;
+    target: 'server' | 'client' | 'all' | 'others';
+    validate?: (args: Serializable[], sender: ClientId) => boolean;
+}
+/** RPC call */
+export interface RPCCall {
+    id: string;
+    method: string;
+    args: Serializable[];
+    senderId: ClientId;
+    targetId?: ClientId;
+    timestamp: number;
+}
+/** Network event types */
+export type NetworkEventType = 'connected' | 'disconnected' | 'reconnected' | 'error' | 'message' | 'client:joined' | 'client:left' | 'client:ready' | 'client:notReady' | 'room:created' | 'room:joined' | 'room:left' | 'room:closed' | 'room:stateChanged' | 'room:hostChanged' | 'lobby:joined' | 'lobby:left' | 'lobby:updated' | 'matchmaking:started' | 'matchmaking:found' | 'matchmaking:cancelled' | 'matchmaking:failed' | 'state:sync' | 'state:snapshot' | 'entity:spawned' | 'entity:destroyed' | 'entity:updated' | 'rpc:called' | 'ping:updated';
+/** Network event */
+export interface NetworkEvent {
+    type: NetworkEventType;
+    clientId?: ClientId;
+    roomId?: RoomId;
+    lobbyId?: LobbyId;
+    entityId?: EntityId;
+    message?: NetworkMessage;
+    client?: ClientInfo;
+    room?: Room;
+    lobby?: Lobby;
+    state?: Serializable;
+    error?: Error;
+    ping?: number;
+    timestamp: number;
+}
+/** Event callback */
+export type NetworkEventCallback = (event: NetworkEvent) => void;
+/** Network configuration */
+export interface NetworkConfig {
+    /** Server URL */
+    serverUrl: string;
+    /** Use WebSocket */
+    useWebSocket: boolean;
+    /** Use WebRTC */
+    useWebRTC: boolean;
+    /** Auto reconnect */
+    autoReconnect: boolean;
+    /** Reconnect attempts */
+    reconnectAttempts: number;
+    /** Reconnect delay (ms) */
+    reconnectDelay: number;
+    /** Heartbeat interval (ms) */
+    heartbeatInterval: number;
+    /** Connection timeout (ms) */
+    connectionTimeout: number;
+    /** Message buffer size */
+    messageBufferSize: number;
+    /** Enable compression */
+    compression: boolean;
+    /** Client prediction */
+    clientPrediction: boolean;
+    /** Server reconciliation */
+    serverReconciliation: boolean;
+    /** Interpolation delay (ms) */
+    interpolationDelay: number;
+    /** Tick rate (Hz) */
+    tickRate: number;
+    /** Send rate (Hz) */
+    sendRate: number;
+    /** Enable debug logging */
+    debug: boolean;
+}
+/** Default configuration */
+export declare const DEFAULT_NETWORK_CONFIG: NetworkConfig;
+export declare class NiceNetwork extends EventEmitter<Record<NetworkEventType, [NetworkEvent]>> {
+    private config;
+    private connectionState;
+    private localClientId;
+    private role;
+    private ws;
+    private reconnectTimer?;
+    private reconnectCount;
+    private heartbeatTimer?;
+    private rooms;
+    private lobbies;
+    private clients;
+    private entities;
+    private localEntities;
+    private messageCounter;
+    private pendingMessages;
+    private messageHandlers;
+    private rpcDefinitions;
+    private rpcHandlers;
+    private rpcCallbacks;
+    private inputBuffer;
+    private stateSnapshots;
+    private lastAckedInput;
+    private localSequence;
+    private remoteSequence;
+    private matchmakingRequest;
+    private matchmakingTimer?;
+    private lastTickTime;
+    private lastSendTime;
+    private serverTimeOffset;
+    private pingHistory;
+    private currentPing;
+    constructor(config?: Partial<NetworkConfig>);
+    /**
+     * Connect to server
+     */
+    connect(serverUrl?: string): Promise<boolean>;
+    /**
+     * Connect via WebSocket
+     */
+    private connectWebSocket;
+    /**
+     * Handle successful connection
+     */
+    private handleConnected;
+    /**
+     * Handle disconnection
+     */
+    private handleDisconnected;
+    /**
+     * Schedule reconnection
+     */
+    private scheduleReconnect;
+    /**
+     * Handle connection error
+     */
+    private handleConnectionError;
+    /**
+     * Disconnect from server
+     */
+    disconnect(): void;
+    /**
+     * Check if connected
+     */
+    isConnected(): boolean;
+    /**
+     * Get connection state
+     */
+    getConnectionState(): ConnectionState;
+    /**
+     * Get local client ID
+     */
+    getLocalClientId(): ClientId | null;
+    /**
+     * Start heartbeat
+     */
+    private startHeartbeat;
+    /**
+     * Stop heartbeat
+     */
+    private stopHeartbeat;
+    /**
+     * Send ping
+     */
+    private sendPing;
+    /**
+     * Handle pong
+     */
+    private handlePong;
+    /**
+     * Get current ping
+     */
+    getPing(): number;
+    /**
+     * Get average ping
+     */
+    getAveragePing(): number;
+    /**
+     * Send handshake
+     */
+    private sendHandshake;
+    /**
+     * Handle incoming message
+     */
+    private handleMessage;
+    /**
+     * Handle handshake acknowledgment
+     */
+    private handleHandshakeAck;
+    /**
+     * Send message
+     */
+    sendMessage(type: string, payload: Serializable, priority?: MessagePriority, delivery?: DeliveryMode): void;
+    /**
+     * Send raw message
+     */
+    private sendRaw;
+    /**
+     * Serialize message
+     */
+    private serializeMessage;
+    /**
+     * Deserialize message
+     */
+    private deserializeMessage;
+    /**
+     * Register message handler
+     */
+    onMessage(type: string, handler: (msg: NetworkMessage) => void): () => void;
+    /**
+     * Flush pending messages
+     */
+    private flushPendingMessages;
+    /**
+     * Create room
+     */
+    createRoom(config: Partial<RoomConfig>): Promise<Room | null>;
+    /**
+     * Join room
+     */
+    joinRoom(roomId: RoomId, password?: string): Promise<boolean>;
+    /**
+     * Leave room
+     */
+    leaveRoom(roomId: RoomId): void;
+    /**
+     * Get room
+     */
+    getRoom(roomId: RoomId): Room | undefined;
+    /**
+     * Set ready state
+     */
+    setReady(roomId: RoomId, ready: boolean): void;
+    /**
+     * Start game (host only)
+     */
+    startGame(roomId: RoomId): void;
+    /**
+     * Join lobby
+     */
+    joinLobby(lobbyId: LobbyId): Promise<boolean>;
+    /**
+     * Leave lobby
+     */
+    leaveLobby(lobbyId: LobbyId): void;
+    /**
+     * Get room listings
+     */
+    getRoomListings(lobbyId: LobbyId): RoomListing[];
+    /**
+     * Refresh room listings
+     */
+    refreshRoomListings(lobbyId: LobbyId): void;
+    /**
+     * Start matchmaking
+     */
+    startMatchmaking(gameMode: string, options?: {
+        rating?: number;
+        region?: string;
+        partyIds?: ClientId[];
+        preferences?: Record<string, Serializable>;
+    }): void;
+    /**
+     * Cancel matchmaking
+     */
+    cancelMatchmaking(): void;
+    private cancelMatchmakingTimer;
+    /**
+     * Handle state sync
+     */
+    private handleStateSync;
+    /**
+     * Reconcile local state with server
+     */
+    private reconcileState;
+    /**
+     * Handle input acknowledgment
+     */
+    private handleInputAck;
+    /**
+     * Send input
+     */
+    sendInput(inputs: Serializable): void;
+    /**
+     * Get interpolated entity state
+     */
+    getInterpolatedState(entityId: EntityId): Serializable | undefined;
+    /**
+     * Interpolate between states
+     */
+    private interpolateStates;
+    /**
+     * Spawn entity
+     */
+    spawnEntity(type: string, state: Serializable, local?: boolean): EntityId;
+    /**
+     * Handle entity spawn from server
+     */
+    private handleEntitySpawn;
+    /**
+     * Destroy entity
+     */
+    destroyEntity(entityId: EntityId): void;
+    /**
+     * Handle entity destroy from server
+     */
+    private handleEntityDestroy;
+    /**
+     * Update entity state
+     */
+    updateEntity(entityId: EntityId, state: Serializable): void;
+    /**
+     * Handle entity update from server
+     */
+    private handleEntityUpdate;
+    /**
+     * Get entity
+     */
+    getEntity(entityId: EntityId): NetworkEntity | undefined;
+    /**
+     * Get all entities
+     */
+    getAllEntities(): NetworkEntity[];
+    /**
+     * Get local entities
+     */
+    getLocalEntities(): NetworkEntity[];
+    /**
+     * Register RPC
+     */
+    registerRPC(name: string, handler: (args: Serializable[], sender: ClientId) => Serializable | void, definition?: Partial<RPCDefinition>): void;
+    /**
+     * Call RPC
+     */
+    callRPC(method: string, args: Serializable[], target?: ClientId | 'all' | 'others'): void;
+    /**
+     * Call RPC with response
+     */
+    callRPCWithResponse<T extends Serializable>(method: string, args: Serializable[], timeout?: number): Promise<T>;
+    /**
+     * Handle RPC message
+     */
+    private handleRPCMessage;
+    /**
+     * Update network (call each frame)
+     */
+    update(_deltaTime: number): void;
+    /**
+     * Tick
+     */
+    private tick;
+    /**
+     * Flush queued messages
+     */
+    private flush;
+    /**
+     * Get server time
+     */
+    getServerTime(): number;
+    /**
+     * Get client info
+     */
+    getClient(id: ClientId): ClientInfo | undefined;
+    /**
+     * Get all clients
+     */
+    getAllClients(): ClientInfo[];
+    /**
+     * Get statistics
+     */
+    getStats(): {
+        connectionState: ConnectionState;
+        ping: number;
+        avgPing: number;
+        entityCount: number;
+        localEntityCount: number;
+        roomCount: number;
+        inputBufferSize: number;
+        messagesSent: number;
+    };
+    /**
+     * Destroy the network system
+     */
+    destroy(): void;
+    private agents;
+}
+/**
+ * Create a network system
+ */
+export declare function createNetworkSystem(config?: Partial<NetworkConfig>): NiceNetwork;
+/**
+ * Create room config
+ */
+export declare function roomConfig(options: Partial<RoomConfig> & {
+    name: string;
+}): RoomConfig;
+/**
+ * Create lobby config
+ */
+export declare function lobbyConfig(options: Partial<LobbyConfig> & {
+    name: string;
+}): LobbyConfig;
+/**
+ * Estimate packet size
+ */
+export declare function estimatePacketSize(data: Serializable): number;
+/**
+ * Validate serializable
+ */
+export declare function isSerializable(value: unknown): value is Serializable;