@kikorin/netcode 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,375 @@
+type PeerId = string;
+type GroupId = string;
+type EntityId = number;
+type ComponentId = number;
+type FieldId = number;
+type SequenceNumber = number;
+type NetTypedArray = Float32Array | Float64Array | Int32Array | Uint32Array | Uint16Array | Uint8Array | Int8Array | Int16Array;
+declare const HEADER_SIZE = 8;
+declare const enum MessageType {
+    Handshake = 1,
+    Subscribe = 2,
+    Unsubscribe = 3,
+    DeltaUpdate = 4,
+    FullSync = 5,
+    Ack = 6,
+    Ping = 7,
+    Pong = 8,
+    LeadClaim = 9,
+    LeadYield = 10,
+    PeerList = 11,
+    GameEvent = 12
+}
+declare const enum MessageFlag {
+    None = 0,
+    Reliable = 1,
+    Compressed = 2,
+    Fragmented = 4
+}
+interface NetMessage {
+    type: MessageType;
+    flags: MessageFlag;
+    seq: SequenceNumber;
+    ack: SequenceNumber;
+    payload: ArrayBuffer;
+}
+interface FieldSchema {
+    id: FieldId;
+    name: string;
+    /** Direct reference to the bitecs component TypedArray (e.g. Position.x) */
+    array: NetTypedArray;
+}
+interface ComponentSchema {
+    id: ComponentId;
+    name: string;
+    fields: FieldSchema[];
+}
+interface InterestGroupConfig {
+    id: GroupId;
+    /** Max entities tracked by this group. Default 4096. */
+    maxEntities?: number;
+    /** Flush interval in ms. Default 50 (20hz). */
+    tickRateMs?: number;
+    /** Lead election strategy. Default 'min-id'. */
+    electionStrategy?: ElectionStrategy;
+}
+interface PeerNetConfig {
+    peerId: PeerId;
+    /** Exponential moving average alpha for RTT. Default 0.125. */
+    rttAlpha?: number;
+}
+interface DeltaEntry {
+    entityId: EntityId;
+    componentId: ComponentId;
+    fieldId: FieldId;
+    value: number;
+}
+type DeltaSet = DeltaEntry[];
+type DeltaHandler = (deltas: DeltaSet, groupId: GroupId, fromPeer: PeerId) => void;
+type ElectionStrategy = 'min-id' | 'hash-ring' | 'load-balanced';
+interface LoadInfo {
+    peerId: PeerId;
+    connectionCount: number;
+    leadGroupCount: number;
+}
+
+interface PeerJSDataConnection {
+    readonly peer: string;
+    readonly open: boolean;
+    send(data: ArrayBuffer | Uint8Array): void;
+    close(): void;
+    on(event: 'data', cb: (data: unknown) => void): void;
+    on(event: 'open', cb: () => void): void;
+    on(event: 'close', cb: () => void): void;
+    on(event: 'error', cb: (err: Error) => void): void;
+}
+interface PeerJSPeer {
+    readonly id: string;
+    connect(peerId: string, options?: {
+        reliable?: boolean;
+        serialization?: string;
+    }): PeerJSDataConnection;
+    on(event: 'connection', cb: (conn: PeerJSDataConnection) => void): void;
+    on(event: 'open', cb: (id: string) => void): void;
+    on(event: 'error', cb: (err: Error) => void): void;
+    on(event: 'close', cb: () => void): void;
+    destroy(): void;
+}
+type DataHandler = (data: ArrayBuffer, from: PeerId) => void;
+type DisconnectHandler = (peerId: PeerId) => void;
+/**
+ * Manages the lifecycle of PeerJS data connections.
+ * Provides:
+ *   - Lazy connection (auto-connects on first send)
+ *   - Per-connection message queue drained on open
+ *   - Exponential-backoff reconnect on close/error
+ *   - Deduplication of inbound vs outbound connections to the same peer
+ */
+declare class ConnectionPool {
+    private _peer;
+    private _conns;
+    private _handlers;
+    private _disconnectHandlers;
+    private _reconnectDelay;
+    private _reconnectHandles;
+    private static readonly BASE_DELAY;
+    private static readonly MAX_DELAY;
+    setPeer(peer: PeerJSPeer): void;
+    connect(peerId: PeerId): Promise<void>;
+    send(peerId: PeerId, data: ArrayBuffer): void;
+    isOpen(peerId: PeerId): boolean;
+    disconnect(peerId: PeerId): void;
+    onData(handler: DataHandler): () => void;
+    /** Fires when a connection closes unexpectedly (not from a local disconnect() call). */
+    onDisconnect(handler: DisconnectHandler): () => void;
+    dispose(): void;
+    private _registerConn;
+    private _scheduleReconnect;
+}
+
+interface PeerState {
+    readonly peerId: PeerId;
+    isLead: boolean;
+    joinedAt: number;
+    lastSeenAt: number;
+    rttMs: number;
+}
+type SendFn = (to: PeerId, msg: NetMessage) => void;
+/**
+ * Manages one interest group: membership, lead election, and message routing.
+ *
+ * Routing rules:
+ *   - Non-lead peers send outbound deltas → lead only
+ *   - Lead receives deltas → re-broadcasts to all other group peers + notifies local handlers
+ *   - Local delta handlers always fire regardless of lead status
+ *
+ * Lead election is deterministic (all peers run the same algorithm) and
+ * re-runs on every membership change. No election messages are needed for
+ * convergence; LeadClaim messages just inform remote peers of the local result.
+ */
+declare class InterestGroup {
+    readonly id: GroupId;
+    private _config;
+    private _localPeerId;
+    private _peers;
+    private _leadId;
+    private _elector;
+    private _sendFn;
+    private _deltaHandlers;
+    private _pending;
+    private _tickHandle;
+    private _seq;
+    private _ack;
+    constructor(config: InterestGroupConfig, localPeerId: PeerId);
+    get leadId(): PeerId | null;
+    get isLead(): boolean;
+    get peerCount(): number;
+    getPeer(peerId: PeerId): Readonly<PeerState> | undefined;
+    get peerIds(): ReadonlySet<PeerId>;
+    setSendFn(fn: SendFn): void;
+    addPeer(peerId: PeerId): void;
+    removePeer(peerId: PeerId): void;
+    /** Queue deltas to be sent on the next tick flush */
+    publishDeltas(deltas: DeltaSet): void;
+    /** Send all pending deltas immediately (called by the tick interval) */
+    flush(): void;
+    handleMessage(msg: NetMessage, fromPeer: PeerId): void;
+    onDelta(handler: DeltaHandler): () => void;
+    startTick(): void;
+    stopTick(): void;
+    dispose(): void;
+    private _reelect;
+    private _broadcastLeadClaim;
+    private _onDeltaUpdate;
+    private _onFullSync;
+    private _onLeadClaim;
+    private _nextSeq;
+}
+
+/**
+ * PeerNet — top-level peer-to-peer netcode facade.
+ *
+ * Responsibilities:
+ *   - Owns the ConnectionPool (PeerJS connections)
+ *   - Owns all InterestGroups (pub/sub routing)
+ *   - Owns the ChangeTracker (minimal delta generation)
+ *   - Routes raw inbound buffers to the correct group
+ *   - RTT estimation via Ping/Pong
+ *
+ * Typical usage per game tick:
+ *   1. ECS systems run; call net.markEntityDirty(eid) for any changed entity
+ *   2. Call net.flushGroupDeltas(groupId, entityList) to compute+queue deltas
+ *   3. InterestGroup tick fires automatically (setInterval) and sends queued data
+ *
+ * Incoming deltas from remote peers surface via net.onGroupDelta(groupId, handler).
+ * Apply them to your ECS TypedArrays inside that handler.
+ */
+declare class PeerNet {
+    readonly localPeerId: PeerId;
+    private _config;
+    private _pool;
+    private _groups;
+    private _tracker;
+    private _seq;
+    private _ack;
+    private _rttMs;
+    private _gameEventHandlers;
+    constructor(config: PeerNetConfig);
+    /** Attach the live PeerJS Peer instance after it opens. */
+    attachPeer(peer: PeerJSPeer): void;
+    registerComponent(schema: ComponentSchema): void;
+    unregisterComponent(componentId: number): void;
+    createGroup(config: InterestGroupConfig): InterestGroup;
+    destroyGroup(groupId: GroupId): void;
+    getGroup(groupId: GroupId): InterestGroup | undefined;
+    connectPeer(peerId: PeerId): Promise<void>;
+    disconnectPeer(peerId: PeerId): void;
+    onPeerDisconnect(handler: (peerId: PeerId) => void): () => void;
+    sendGameEvent(peerId: PeerId, payload: ArrayBuffer): void;
+    onGameEvent(handler: (payload: ArrayBuffer, from: PeerId) => void): () => void;
+    /**
+     * Subscribe the local peer to a group and introduce remote peers.
+     * Sends a Subscribe control message to each remote peer.
+     */
+    joinGroup(groupId: GroupId, remotePeers: PeerId[]): void;
+    /**
+     * Leave a group: notify remote peers and remove local state.
+     */
+    leaveGroup(groupId: GroupId): void;
+    markEntityDirty(entityId: EntityId): void;
+    markEntitiesDirty(entities: EntityId[]): void;
+    invalidateEntity(entityId: EntityId): void;
+    /**
+     * Compute deltas for dirty entities and push them into the group's send queue.
+     * The group's tick interval handles the actual sending.
+     *
+     * Call once per game tick, after ECS systems run.
+     */
+    flushGroupDeltas(groupId: GroupId, entities: EntityId[]): void;
+    /**
+     * Send a full-state sync to a newly joined peer for a given group.
+     * Generates a snapshot of all registered component fields for all provided entities.
+     */
+    sendFullSync(groupId: GroupId, toPeer: PeerId, entities: EntityId[]): void;
+    onGroupDelta(groupId: GroupId, handler: DeltaHandler): () => void;
+    get rttMs(): number;
+    get dirtyEntityCount(): number;
+    ping(peerId: PeerId): void;
+    dispose(): void;
+    private _onRawData;
+    private _onSubscribe;
+    private _onUnsubscribe;
+    private _sendSubscribe;
+    private _sendUnsubscribe;
+    private _send;
+    private _nextSeq;
+    private _requireGroup;
+}
+
+/**
+ * Tracks the last-flushed values of registered ECS components and produces
+ * minimal delta sets by comparing current TypedArray state to the snapshot.
+ *
+ * Thread of ownership: single-threaded (JS). Call markDirty() whenever an
+ * ECS system modifies a component, then flush() once per network tick to
+ * collect only what changed.
+ */
+declare class ChangeTracker {
+    private _schemas;
+    private _snapshots;
+    private _dirtySet;
+    registerComponent(schema: ComponentSchema): void;
+    unregisterComponent(componentId: ComponentId): void;
+    markDirty(entityId: EntityId): void;
+    markDirtyBatch(entities: EntityId[]): void;
+    get dirtyCount(): number;
+    /**
+     * Compute deltas for a subset of entities and update the snapshot.
+     * Only entities that were marked dirty are compared; clean entities are skipped.
+     * Clears dirty flags for all entities in the provided list.
+     */
+    flush(entities: EntityId[]): DeltaSet;
+    /**
+     * Force-flush all registered fields for the given entities, ignoring dirty state.
+     * Use when a new peer joins and needs a full state sync.
+     */
+    fullSnapshot(entities: EntityId[]): DeltaSet;
+    /**
+     * Invalidate the snapshot for an entity (e.g. after it is destroyed and respawned).
+     * Next flush will treat all fields as changed.
+     */
+    invalidateEntity(entityId: EntityId): void;
+    clearDirtyAll(): void;
+}
+
+/**
+ * Deterministic lead election for an interest group.
+ *
+ * All peers in a group run the same algorithm over the same candidate list,
+ * so they converge on the same lead without coordination messages. When the
+ * candidate set changes (peer joins/leaves), every peer re-elects locally.
+ *
+ * Strategies:
+ *   min-id        — lexicographically smallest peer ID wins. Zero coordination
+ *                   overhead, deterministic, but always assigns load to the
+ *                   same peer. Best for low-churn groups.
+ *
+ *   hash-ring     — consistent hashing with 20 virtual nodes per peer.
+ *                   Spreads lead responsibility across peers as groups multiply.
+ *                   A single peer join/leave only re-assigns ~1/N groups.
+ *
+ *   load-balanced — weighted score from live load metrics sent by peers.
+ *                   Falls back to min-id for peers without reported metrics.
+ *                   Best when peers have heterogeneous capacity.
+ */
+declare class LeadElector {
+    private _strategy;
+    private _loadInfo;
+    constructor(strategy?: ElectionStrategy);
+    updateLoadInfo(info: LoadInfo): void;
+    removeLoadInfo(peerId: PeerId): void;
+    electLead(groupId: GroupId, candidates: PeerId[]): PeerId;
+    wouldReelect(groupId: GroupId, currentLead: PeerId, candidates: PeerId[]): boolean;
+    private _minId;
+    private _hashRing;
+    private _loadBalanced;
+}
+
+declare function encodeHeader(view: DataView, type: MessageType, flags: MessageFlag, seq: number, ack: number, payloadLen: number): void;
+declare function decodeHeader(view: DataView): {
+    type: MessageType;
+    flags: MessageFlag;
+    seq: number;
+    ack: number;
+    payloadLen: number;
+};
+declare function encodeMessage(msg: NetMessage): ArrayBuffer;
+declare function decodeMessage(buf: ArrayBuffer): NetMessage;
+declare function encodeDeltaPayload(groupId: string, deltas: DeltaSet): ArrayBuffer;
+declare function decodeDeltaPayload(buf: ArrayBuffer): {
+    groupId: string;
+    deltas: DeltaSet;
+};
+declare function encodeJson(obj: Record<string, unknown>): ArrayBuffer;
+declare function decodeJson(buf: ArrayBuffer): Record<string, unknown>;
+
+interface PQEntry<T> {
+    readonly priority: number;
+    readonly seq: number;
+    readonly value: T;
+}
+declare class PriorityQueue<T> {
+    private _heap;
+    private _seq;
+    get size(): number;
+    get isEmpty(): boolean;
+    push(value: T, priority: number): void;
+    pop(): T | undefined;
+    peek(): T | undefined;
+    clear(): void;
+    private _lt;
+    private _bubbleUp;
+    private _siftDown;
+}
+
+export { ChangeTracker, type ComponentId, type ComponentSchema, ConnectionPool, type DeltaEntry, type DeltaHandler, type DeltaSet, type ElectionStrategy, type EntityId, type FieldId, type FieldSchema, type GroupId, HEADER_SIZE, InterestGroup, type InterestGroupConfig, LeadElector, type LoadInfo, MessageFlag, MessageType, type NetMessage, type NetTypedArray, type PQEntry, type PeerId, type PeerJSDataConnection, type PeerJSPeer, PeerNet, type PeerNetConfig, type PeerState, PriorityQueue, type SendFn, type SequenceNumber, decodeDeltaPayload, decodeHeader, decodeJson, decodeMessage, encodeDeltaPayload, encodeHeader, encodeJson, encodeMessage };