@carverjs/multiplayer 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,316 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { S as SignalingStrategy, a as StrategyConfig } from './types-5LHBOW08.js';
+export { F as FirebaseStrategyConfig, M as MqttStrategyConfig, P as PeerMetadata, R as RoomAnnouncement } from './types-5LHBOW08.js';
+import { k as NetworkManager, U as UseRoomOptions, l as ConnectionState, R as Room, m as CarverMultiplayerError, C as CarverTransport, n as UseLobbyOptions, o as RoomConfig, P as Player, c as RoomState, p as UseMultiplayerOptions, N as NetworkQuality, j as SyncMode, E as EntityState } from './NetworkManager-nvVAOr1O.js';
+export { b as CarverChannel, q as CarverErrorCode, a as ChannelOptions, f as EntityState2D, g as EntityState3D, h as EventPacket, I as InputPacket, J as JoinOptions, M as MultiplayerContextValue, i as SnapshotPacket, T as TransportConfig } from './NetworkManager-nvVAOr1O.js';
+export { F as FirebaseStrategy, M as MqttStrategy } from './firebase-CPu87KA0.js';
+
+interface MultiplayerContextValue {
+    appId: string;
+    strategy: SignalingStrategy;
+    iceServers?: RTCIceServer[];
+    networkManager: NetworkManager;
+}
+
+interface MultiplayerProviderProps {
+    /**
+     * Unique application identifier. Used to namespace rooms across the
+     * signaling network so different games don't interfere.
+     */
+    appId: string;
+    /**
+     * Signaling strategy configuration. Defaults to MQTT (free public brokers).
+     *
+     * ```tsx
+     * // Free (MQTT, zero config)
+     * <MultiplayerProvider appId="my-game">
+     *
+     * // Firebase (your own project)
+     * <MultiplayerProvider
+     *   appId="my-game"
+     *   strategy={{ type: 'firebase', databaseURL: 'https://my-project.firebaseio.com' }}
+     * >
+     * ```
+     */
+    strategy?: StrategyConfig;
+    /**
+     * ICE servers (STUN + TURN). Defaults to public Google/Cloudflare STUN.
+     *
+     * To add your own TURN server (e.g. Cloudflare TURN):
+     * ```tsx
+     * <MultiplayerProvider
+     *   appId="my-game"
+     *   iceServers={[
+     *     { urls: 'stun:stun.cloudflare.com:3478' },
+     *     { urls: 'turn:turn.cloudflare.com:3478', username: '...', credential: '...' },
+     *   ]}
+     * >
+     * ```
+     */
+    iceServers?: RTCIceServer[];
+    children: ReactNode;
+}
+declare function MultiplayerProvider({ appId, strategy: strategyConfig, iceServers, children, }: MultiplayerProviderProps): react.FunctionComponentElement<react.ProviderProps<MultiplayerContextValue | null>>;
+
+interface MultiplayerBridgeProps {
+    children: ReactNode;
+}
+/**
+ * Bridges the MultiplayerContext from the parent React tree into an R3F Canvas.
+ *
+ * R3F's `<Canvas>` uses a separate React reconciler, so React contexts from the
+ * parent tree are not automatically available inside the Canvas. This component
+ * reads the MultiplayerContext value from the parent tree and re-provides it
+ * inside the Canvas, making all CarverJS multiplayer hooks work seamlessly.
+ *
+ * Place `<MultiplayerBridge>` as a direct child of `<Game>`, wrapping `<World>`
+ * and all scene content that uses multiplayer hooks.
+ *
+ * @example
+ * ```tsx
+ * <MultiplayerProvider appId="my-game">
+ *   <Game mode="2d">
+ *     <MultiplayerBridge>
+ *       <World>
+ *         <MyScene />
+ *       </World>
+ *     </MultiplayerBridge>
+ *   </Game>
+ * </MultiplayerProvider>
+ * ```
+ */
+declare function MultiplayerBridge({ children }: MultiplayerBridgeProps): react.FunctionComponentElement<react.ProviderProps<MultiplayerContextValue | null>> | react.DOMElement<react.DOMAttributes<Element>, Element>;
+
+interface UseRoomReturn {
+    roomId: string | null;
+    connectionState: ConnectionState;
+    isHost: boolean;
+    hostId: string | null;
+    selfId: string | null;
+    room: Room | null;
+    error: CarverMultiplayerError | null;
+    join: (roomId: string, options?: {
+        password?: string;
+    }) => Promise<void>;
+    leave: () => void;
+    setReady: (ready: boolean) => void;
+    setMetadata: (meta: Record<string, unknown>) => void;
+    setRoomMetadata: (meta: Record<string, unknown>) => void;
+    transport: CarverTransport | null;
+}
+declare function useRoom(roomId?: string, options?: UseRoomOptions): UseRoomReturn;
+
+interface UseLobbyReturn {
+    rooms: Room[];
+    isLoading: boolean;
+    error: CarverMultiplayerError | null;
+    refresh: () => void;
+    createRoom: (config: RoomConfig) => Promise<string>;
+}
+declare function useLobby(options?: UseLobbyOptions): UseLobbyReturn;
+
+interface UsePlayersReturn {
+    players: Player[];
+    self: Player | null;
+    host: Player | null;
+    count: number;
+    allReady: boolean;
+    getPlayer: (peerId: string) => Player | undefined;
+}
+declare function usePlayers(): UsePlayersReturn;
+
+interface UseHostReturn {
+    kick: (peerId: string, reason?: string) => void;
+    transferHost: (peerId: string) => void;
+    setRoomState: (state: RoomState) => void;
+    setMaxPlayers: (n: number) => void;
+    lockRoom: () => void;
+    unlockRoom: () => void;
+}
+declare function useHost(): UseHostReturn;
+
+interface UseMultiplayerReturn {
+    isActive: boolean;
+    networkQuality: NetworkQuality;
+    tick: number;
+    serverTick: number;
+    drift: number;
+    syncEngine: SyncMode;
+}
+declare function useMultiplayer(options?: UseMultiplayerOptions): UseMultiplayerReturn;
+
+interface UseNetworkEventsReturn<T extends {
+    [K in keyof T]: unknown;
+} = Record<string, unknown>> {
+    sendEvent: <K extends keyof T & string>(type: K, payload: T[K], target?: string) => void;
+    broadcast: <K extends keyof T & string>(type: K, payload: T[K]) => void;
+    onEvent: <K extends keyof T & string>(type: K, callback: (data: T[K], peerId: string) => void) => () => void;
+}
+declare function useNetworkEvents<T extends {
+    [K in keyof T]: unknown;
+} = Record<string, unknown>>(options?: {
+    hostValidation?: boolean;
+}): UseNetworkEventsReturn<T>;
+
+interface UseNetworkStateReturn {
+    /** Host only. Create a networked entity and broadcast its existence to all peers. */
+    spawn: (id: string, initialState: EntityState) => void;
+    /** Host only. Remove a networked entity and broadcast removal to all peers. */
+    despawn: (id: string) => void;
+    /** Client sends a spawn request to the host, who validates and spawns if the id is not taken. */
+    requestSpawn: (id: string, config: Record<string, unknown>) => void;
+    /** Read the current state of a networked entity by id. */
+    getState: (id: string) => EntityState | undefined;
+    /** Write a partial update to a networked entity. Host-authoritative: only the host may call this. */
+    setState: (id: string, partialState: Partial<EntityState>) => void;
+    /** Reactive map of all current networked entity states. */
+    entities: Map<string, EntityState>;
+}
+/**
+ * Phase 4.4 – Advanced escape-hatch hook for direct networked entity management.
+ *
+ * Provides host-authoritative spawn / despawn, client requestSpawn,
+ * and direct state read / write over a reliable+ordered data channel.
+ */
+declare function useNetworkState(): UseNetworkStateReturn;
+
+interface DebugOverlayOptions {
+    position?: "top-left" | "top-right" | "bottom-left" | "bottom-right";
+    /** Keyboard key used to toggle visibility (default: "F3") */
+    keyboardToggle?: string;
+}
+interface DebugStats {
+    tick: number;
+    serverTick: number;
+    drift: number;
+    /** Per-peer latency map or a single average value */
+    latencyMs: Map<string, number> | number;
+    /** Packet-loss rate in the range 0-1 */
+    packetLossRate: number;
+    /** Inbound bandwidth in bytes / second */
+    bandwidthIn: number;
+    /** Outbound bandwidth in bytes / second */
+    bandwidthOut: number;
+    networkQuality: "good" | "degraded" | "poor";
+    peerCount: number;
+    isHost: boolean;
+    syncMode: string;
+}
+declare class DebugOverlay {
+    private el;
+    private visible;
+    private lastHTML;
+    private readonly keyboardToggle;
+    private readonly handleKey;
+    constructor(options?: DebugOverlayOptions);
+    update(stats: DebugStats): void;
+    show(): void;
+    hide(): void;
+    toggle(): void;
+    destroy(): void;
+    private positionStyles;
+    private formatLatency;
+}
+
+interface NetworkSimulatorOptions {
+    /** Additional one-way latency in milliseconds (default 0) */
+    latencyMs?: number;
+    /** Packet drop rate, 0-1 (default 0) */
+    packetLoss?: number;
+    /** Random jitter +/- milliseconds (default 0) */
+    jitterMs?: number;
+}
+interface SimulatorStats {
+    sentCount: number;
+    droppedCount: number;
+    avgLatencyMs: number;
+}
+declare class NetworkSimulator {
+    private latencyMs;
+    private packetLoss;
+    private jitterMs;
+    private sentCount;
+    private droppedCount;
+    private latencySum;
+    /** Active timeout handles so we can cancel them on destroy() */
+    private pending;
+    constructor(options?: NetworkSimulatorOptions);
+    /** Update simulation parameters at runtime. */
+    setOptions(options: Partial<NetworkSimulatorOptions>): void;
+    /**
+     * Wrap an existing send function so that every call goes through the
+     * simulated network conditions (latency, jitter, packet loss).
+     */
+    wrapSend<T>(originalSend: (data: T, target?: string | string[]) => void): (data: T, target?: string | string[]) => void;
+    /** Current statistics snapshot. */
+    get stats(): SimulatorStats;
+    /** Cancel all pending delayed sends and clean up. */
+    destroy(): void;
+}
+
+interface InterestManagerOptions {
+    /** Spatial hash cell size in world units. Default: 50 */
+    cellSize?: number;
+    /** Default relevance radius around a client's position. Default: 200 */
+    defaultRadius?: number;
+    /** Entity ids/names that are always sent to every client. */
+    alwaysRelevant?: string[];
+}
+/**
+ * Spatial-hash-grid area-of-interest filter.
+ *
+ * Runs on the host side. Each tick the host feeds the full entity map via
+ * `updateEntities`, then queries per-client relevance with
+ * `getRelevantEntities` (or creates a single filter callback via
+ * `createFilter` for `HostAuthority.setInterestFilter`).
+ */
+declare class InterestManager {
+    /** cell-key -> set of entity ids occupying that cell */
+    private _cells;
+    /** entity id -> last-known 3D position */
+    private _entityPositions;
+    private _cellSize;
+    private _defaultRadius;
+    private _alwaysRelevant;
+    constructor(options?: InterestManagerOptions);
+    /**
+     * Rebuild the spatial hash from the authoritative entity map.
+     * Called once per host tick before any relevance queries.
+     */
+    updateEntities(entities: Map<string, EntityState>): void;
+    /**
+     * Return the set of entity ids relevant to a single client.
+     *
+     * Relevance is the *union* of:
+     *  1. Entities whose cell overlaps the client's bounding sphere
+     *  2. Entities in the `alwaysRelevant` set
+     *  3. Entities owned by this client
+     */
+    getRelevantEntities(clientPosition: {
+        x: number;
+        y: number;
+        z?: number;
+    }, clientId: string, owners: Map<string, string>, overrideRadius?: number): Set<string>;
+    /**
+     * Build a filter callback compatible with
+     * `HostAuthority.setInterestFilter`.
+     *
+     * The returned function closes over a single relevance pass for every
+     * known client so that per-entity filtering during broadcast is a cheap
+     * `Set.has` lookup.
+     *
+     * @param clientPositions  peerId -> position of that client's camera/player
+     * @param owners           entityId -> ownerPeerId
+     */
+    createFilter(clientPositions: Map<string, {
+        x: number;
+        y: number;
+        z?: number;
+    }>, owners: Map<string, string>): (entityId: string, peerId: string) => boolean;
+    /** Remove all data from the grid. */
+    clear(): void;
+    private _cellKey;
+}
+
+export { CarverMultiplayerError, CarverTransport, ConnectionState, DebugOverlay, type DebugOverlayOptions, type DebugStats, EntityState, InterestManager, type InterestManagerOptions, MultiplayerBridge, MultiplayerProvider, type MultiplayerProviderProps, NetworkQuality, NetworkSimulator, type NetworkSimulatorOptions, Player, Room, RoomConfig, RoomState, SignalingStrategy, StrategyConfig, SyncMode, UseLobbyOptions, UseMultiplayerOptions, UseRoomOptions, useHost, useLobby, useMultiplayer, useNetworkEvents, useNetworkState, usePlayers, useRoom };