@carverjs/multiplayer 0.0.1

package/dist/NetworkManager-DrKM2tEx.d.mts

@@ -0,0 +1,369 @@
+import { S as SignalingStrategy } from './types-5LHBOW08.mjs';
+
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'migrating' | 'reconnecting';
+type RoomState = 'lobby' | 'playing' | 'ended';
+interface Room {
+    id: string;
+    name: string;
+    hostId: string;
+    playerCount: number;
+    maxPlayers: number;
+    gameMode?: string;
+    isPrivate: boolean;
+    metadata: Record<string, unknown>;
+    createdAt: number;
+    state: RoomState;
+}
+interface RoomConfig {
+    name: string;
+    maxPlayers?: number;
+    gameMode?: string;
+    password?: string;
+    isPrivate?: boolean;
+    metadata?: Record<string, unknown>;
+}
+interface Player {
+    peerId: string;
+    displayName: string;
+    isHost: boolean;
+    isSelf: boolean;
+    isReady: boolean;
+    isConnected: boolean;
+    metadata: Record<string, unknown>;
+    latencyMs: number;
+    joinedAt: number;
+}
+interface CarverTransport {
+    readonly peerId: string;
+    readonly peers: ReadonlySet<string>;
+    readonly hostId: string;
+    readonly isHost: boolean;
+    readonly room?: Room;
+    readonly initialPlayers?: Player[];
+    onPeerJoin(cb: (peerId: string) => void): void;
+    onPeerLeave(cb: (peerId: string) => void): void;
+    onPeerUpdated(cb: (player: Player) => void): void;
+    onHostChanged(cb: (newHostId: string) => void): void;
+    createChannel<T = unknown>(name: string, options?: ChannelOptions): CarverChannel<T>;
+    connect(roomId: string, config?: TransportConfig): Promise<void>;
+    disconnect(): void;
+    setReady?(ready: boolean): void;
+    setMetadata?(metadata: Record<string, unknown>): void;
+    setRoomMetadata?(metadata: Record<string, unknown>): void;
+    kick?(peerId: string, reason?: string): void;
+    transferHost?(peerId: string): void;
+    setRoomState?(state: RoomState): void;
+    setMaxPlayers?(n: number): void;
+    lockRoom?(): void;
+    unlockRoom?(): void;
+    requestRoomList?(): void;
+}
+interface CarverChannel<T = unknown> {
+    send(data: T, target?: string | string[]): void;
+    onReceive(cb: (data: T, peerId: string) => void): void;
+    close(): void;
+}
+interface ChannelOptions {
+    reliable?: boolean;
+    ordered?: boolean;
+    maxRetransmits?: number;
+}
+interface TransportConfig {
+    displayName?: string;
+    playerMetadata?: Record<string, unknown>;
+    password?: string;
+    iceServers?: RTCIceServer[];
+    iceTransportPolicy?: RTCIceTransportPolicy;
+    maxPlayers?: number;
+    roomConfig?: RoomConfig;
+}
+
+type SyncMode = 'events' | 'snapshot' | 'prediction';
+type NetworkQuality = 'good' | 'degraded' | 'poor';
+interface EntityState2D {
+    id: string;
+    x: number;
+    y: number;
+    a: number;
+    vx: number;
+    vy: number;
+    va: number;
+    c?: Record<string, unknown>;
+}
+interface EntityState3D {
+    id: string;
+    x: number;
+    y: number;
+    z: number;
+    qx: number;
+    qy: number;
+    qz: number;
+    qw: number;
+    vx: number;
+    vy: number;
+    vz: number;
+    wx: number;
+    wy: number;
+    wz: number;
+    c?: Record<string, unknown>;
+}
+type EntityState = EntityState2D | EntityState3D;
+interface SnapshotPacket {
+    t: number;
+    b: number;
+    s: Uint8Array;
+    hi?: unknown;
+}
+interface InputPacket {
+    t: number;
+    i: unknown;
+    p: string;
+}
+interface EventPacket {
+    type: string;
+    payload: unknown;
+    sender: string;
+    target?: string;
+}
+type CarverErrorCode = 'ROOM_NOT_FOUND' | 'ROOM_FULL' | 'ROOM_LOCKED' | 'INVALID_PASSWORD' | 'CONNECTION_FAILED' | 'HOST_UNREACHABLE' | 'KICKED' | 'SIGNALING_ERROR' | 'TURN_CREDENTIAL_ERROR' | 'TRANSPORT_ERROR' | 'MIGRATION_FAILED';
+interface CarverMultiplayerError {
+    code: CarverErrorCode;
+    message: string;
+    recoverable: boolean;
+}
+interface UseRoomOptions {
+    /** Supply a custom CarverTransport instance to bypass the built-in WebRTCTransport. */
+    transport?: CarverTransport;
+    password?: string;
+    displayName?: string;
+    playerMetadata?: Record<string, unknown>;
+    /** Override ICE servers for this room (overrides provider-level config). */
+    iceServers?: RTCIceServer[];
+    hostMigration?: boolean;
+    reconnectAttempts?: number;
+    reconnectIntervalMs?: number;
+    /** ICE transport policy: 'all' (default) or 'relay' (force TURN only). */
+    privacy?: 'all' | 'relay';
+    onConnected?: () => void;
+    onDisconnected?: (reason: string) => void;
+    onHostMigration?: (newHostId: string) => void;
+    onError?: (error: CarverMultiplayerError) => void;
+}
+interface UseLobbyOptions {
+    autoRefresh?: boolean;
+    filter?: {
+        maxPlayers?: number;
+        gameMode?: string;
+        hasPassword?: boolean;
+    };
+}
+interface UseMultiplayerOptions {
+    mode?: SyncMode;
+    tickRate?: number;
+    broadcastRate?: number;
+    keyframeInterval?: number;
+    quantize?: {
+        position?: number;
+        rotation?: number;
+        velocity?: number;
+    };
+    deltaThresholds?: {
+        position?: number;
+        rotation?: number;
+        velocity?: number;
+        custom?: 'strict' | number;
+    };
+    prediction?: {
+        maxRewindTicks?: number;
+        errorSmoothingDecay?: number;
+        maxErrorPerFrame?: number;
+        snapThreshold?: number;
+        lagCompensation?: boolean;
+    };
+    interpolation?: {
+        bufferSize?: number;
+        method?: 'hermite' | 'linear';
+        extrapolateMs?: number;
+    };
+    interestManagement?: {
+        enabled?: boolean;
+        cellSize?: number;
+        defaultRadius?: number;
+        alwaysRelevant?: string[];
+    };
+    debug?: {
+        overlay?: boolean;
+        simulatedLatencyMs?: number;
+        simulatedPacketLoss?: number;
+        logLevel?: 'none' | 'error' | 'warn' | 'verbose';
+    };
+    onPhysicsStep?: (inputs: Map<string, unknown>, tick: number, isRollback: boolean) => void;
+}
+interface MultiplayerContextValue {
+    appId: string;
+    strategy: SignalingStrategy;
+    iceServers?: RTCIceServer[];
+    networkManager: NetworkManager;
+}
+interface JoinOptions {
+    password?: string;
+    displayName?: string;
+    playerMetadata?: Record<string, unknown>;
+}
+
+/**
+ * Accumulator-based fixed timestep with drift-aware time dilation.
+ * Adapted from lumbernet's LumberTickKeeper.
+ */
+declare class TickKeeper {
+    private _tickRate;
+    private _tickDelta;
+    private _accumulator;
+    private _tick;
+    private _serverTick;
+    private _alpha;
+    private _timeScale;
+    private static readonly DRIFT_BEHIND_THRESHOLD;
+    private static readonly DRIFT_AHEAD_THRESHOLD;
+    private static readonly SPEED_UP_SCALE;
+    private static readonly SLOW_DOWN_SCALE;
+    private static readonly NORMAL_SCALE;
+    constructor(tickRate?: number);
+    get tick(): number;
+    get serverTick(): number;
+    get tickDelta(): number;
+    get tickRate(): number;
+    /** Interpolation alpha for rendering between ticks (0-1) */
+    get alpha(): number;
+    /** Current time scale (affected by drift correction) */
+    get timeScale(): number;
+    /** Ticks ahead of server (positive = ahead, negative = behind) */
+    get drift(): number;
+    /** Update server tick from received snapshot */
+    setServerTick(serverTick: number): void;
+    /**
+     * Accumulate time and return the number of fixed ticks to process.
+     * Call this once per render frame with the raw frame delta.
+     */
+    update(rawDelta: number): number;
+    /** Reset to initial state */
+    reset(): void;
+    /** Set tick rate (updates tickDelta accordingly) */
+    setTickRate(rate: number): void;
+    private _updateDriftCorrection;
+}
+
+/** Configuration for delta thresholds */
+interface DeltaThresholds {
+    position: number;
+    rotation: number;
+    velocity: number;
+    custom: 'strict' | number;
+}
+/** Quantization config: number of decimal places to keep */
+interface QuantizeConfig {
+    position?: number;
+    rotation?: number;
+    velocity?: number;
+}
+/**
+ * Snapshot ring buffer: stores recent snapshots for delta computation.
+ */
+declare class SnapshotBuffer {
+    private _buffer;
+    private _capacity;
+    constructor(capacity?: number);
+    /** Store a snapshot at the given tick */
+    store(tick: number, entities: Map<string, EntityState>): void;
+    /** Get a snapshot at the given tick */
+    get(tick: number): Map<string, EntityState> | undefined;
+    /** Clear all stored snapshots */
+    clear(): void;
+}
+/**
+ * Codec handles serialization and delta compression for network state.
+ */
+declare class Codec {
+    private _thresholds;
+    private _quantize;
+    private _is2D;
+    constructor(options?: {
+        thresholds?: Partial<DeltaThresholds>;
+        quantize?: QuantizeConfig;
+        is2D?: boolean;
+    });
+    /** Serialize entity states to binary (msgpackr) */
+    serialize(entities: EntityState[]): Uint8Array;
+    /** Deserialize binary to entity states */
+    deserialize(data: Uint8Array): EntityState[];
+    /**
+     * Compute delta: only include entities that changed beyond thresholds
+     * since the baseline snapshot.
+     * Returns null if nothing changed.
+     */
+    computeDelta(current: Map<string, EntityState>, baseline: Map<string, EntityState> | undefined): EntityState[] | null;
+    /** Serialize a delta snapshot packet */
+    serializeDelta(tick: number, baseTick: number, current: Map<string, EntityState>, baseline: Map<string, EntityState> | undefined): Uint8Array | null;
+    /** Deserialize a snapshot packet */
+    deserializePacket(data: Uint8Array): {
+        tick: number;
+        baseTick: number;
+        entities: EntityState[];
+    };
+    private _hasChanged;
+    private _quantizeEntity;
+}
+
+/**
+ * Central orchestrator for the multiplayer system.
+ * Holds references to the active transport, sync engine, room state, and codec.
+ * One instance per MultiplayerProvider.
+ */
+declare class NetworkManager {
+    private _transport;
+    private _connectionState;
+    private _room;
+    private _players;
+    private _syncMode;
+    private _tickKeeper;
+    private _codec;
+    private _snapshotBuffer;
+    private _networkQuality;
+    private _options;
+    private _connectionListeners;
+    private _playerListeners;
+    private _roomListeners;
+    private _errorListeners;
+    constructor(options?: UseMultiplayerOptions);
+    get transport(): CarverTransport | null;
+    get connectionState(): ConnectionState;
+    get room(): Room | null;
+    get players(): Map<string, Player>;
+    get selfId(): string | null;
+    get isHost(): boolean;
+    get hostId(): string | null;
+    get syncMode(): SyncMode;
+    get tickKeeper(): TickKeeper;
+    get codec(): Codec;
+    get snapshotBuffer(): SnapshotBuffer;
+    get networkQuality(): NetworkQuality;
+    get options(): UseMultiplayerOptions;
+    setTransport(transport: CarverTransport): void;
+    setConnectionState(state: ConnectionState): void;
+    onConnectionStateChange(cb: (state: ConnectionState) => void): () => void;
+    setRoom(room: Room): void;
+    onRoomChange(cb: () => void): () => void;
+    setPlayers(players: Player[]): void;
+    updatePlayer(player: Player): void;
+    removePlayer(peerId: string): void;
+    onPlayersChange(cb: () => void): () => void;
+    emitError(error: CarverMultiplayerError): void;
+    onError(cb: (error: CarverMultiplayerError) => void): () => void;
+    setNetworkQuality(quality: NetworkQuality): void;
+    updateOptions(options: UseMultiplayerOptions): void;
+    destroy(): void;
+    private _notifyPlayerListeners;
+    private _notifyRoomListeners;
+}
+
+export { type CarverTransport as C, type EntityState as E, type InputPacket as I, type JoinOptions as J, type MultiplayerContextValue as M, type NetworkQuality as N, type Player as P, type Room as R, SnapshotBuffer as S, type TransportConfig as T, type UseRoomOptions as U, type ChannelOptions as a, type CarverChannel as b, type RoomState as c, Codec as d, TickKeeper as e, type EntityState2D as f, type EntityState3D as g, type EventPacket as h, type SnapshotPacket as i, type SyncMode as j, NetworkManager as k, type ConnectionState as l, type CarverMultiplayerError as m, type UseLobbyOptions as n, type RoomConfig as o, type UseMultiplayerOptions as p, type CarverErrorCode as q };