openrtc-netcode 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,258 @@
+import type { OpenRTC } from 'openrtc';
+import type { RuntimeClient } from 'openrtc/runtime';
+import type { MetadataBody, NetcodeEnvelope, ObjectRemoveBody, ObjectSnapshotBody, ObjectUpsertBody, StatePatchBody, StateSnapshotBody, UserMessageBody, VoiceSignalBody } from './protocol.js';
+type OpenrtcClientOptions = Parameters<typeof OpenRTC>[0];
+export type NetcodeRuntime = RuntimeClient;
+export type NetcodeReliability = 'reliable';
+export interface NetcodeOptions {
+    runtime?: NetcodeRuntime;
+    apiKey?: OpenrtcClientOptions['apiKey'];
+    projectId?: OpenrtcClientOptions['projectId'];
+    authMode?: OpenrtcClientOptions['authMode'];
+    discoveryMode?: OpenrtcClientOptions['discoveryMode'];
+    allowAnonymousHostedDefaults?: OpenrtcClientOptions['allowAnonymousHostedDefaults'];
+    space?: OpenrtcClientOptions['space'];
+    spaceKey?: OpenrtcClientOptions['spaceKey'];
+    spaceTokenProvider?: NonNullable<OpenrtcClientOptions>['spaceTokenProvider'];
+    storagePrefix?: OpenrtcClientOptions['storagePrefix'];
+    nodeIdPersistence?: OpenrtcClientOptions['nodeIdPersistence'];
+    transports?: OpenrtcClientOptions['transports'];
+    transportPriority?: OpenrtcClientOptions['transportPriority'];
+    preferredPayloadTransports?: RuntimeApplicationPayloadReadinessOptions['preferredTransports'];
+    strictMode?: OpenrtcClientOptions['strictMode'];
+    turnCredentialsProvider?: NonNullable<OpenrtcClientOptions>['turnCredentialsProvider'];
+    displayName?: string;
+    maxPeers?: number;
+    localFallback?: boolean;
+}
+export interface CreateLobbyOptions {
+    id?: string;
+    metadata?: Record<string, string>;
+}
+export interface JoinLobbyOptions {
+    metadata?: Record<string, string>;
+}
+export interface NetcodeLobby {
+    id: string;
+    localPeerId: string;
+    ownerId: string | null;
+    members: NetcodePeer[];
+    metadata: Record<string, string>;
+}
+export interface NetcodePeer {
+    id: string;
+    userId?: string;
+    ticket?: string;
+    joinedAt?: number;
+    connected: boolean;
+    metadata: Record<string, string>;
+    stats?: NetcodePeerStats;
+}
+export interface NetcodePeerStats {
+    peerId: string;
+    transport: string;
+    latencyMs: number | null;
+    connected: boolean;
+    updatedAt: number;
+}
+export interface SendOptions {
+    reliability?: NetcodeReliability;
+}
+export interface NetVarOptions {
+    owner?: 'local' | 'lobby-owner' | string;
+}
+export interface NetVar<T = unknown> {
+    readonly key: string;
+    readonly owner: string;
+    readonly value: T;
+    set(value: T): Promise<void>;
+    onChange(callback: (value: T, previous: T | undefined) => void): () => void;
+}
+export interface NetcodeState {
+    define<T>(key: string, initial: T, options?: NetVarOptions): NetVar<T>;
+    get<T = unknown>(key: string): T | undefined;
+    snapshot(): Record<string, unknown>;
+}
+export interface NetcodeVector3 {
+    x: number;
+    y: number;
+    z: number;
+}
+export interface NetcodeQuaternion {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+}
+export interface NetcodeTransform {
+    position: NetcodeVector3;
+    rotation?: NetcodeQuaternion;
+    scale?: NetcodeVector3;
+}
+export interface NetcodePhysicsState {
+    linearVelocity?: NetcodeVector3;
+    angularVelocity?: NetcodeVector3;
+    sleeping?: boolean;
+}
+export interface NetcodeObjectState<TMetadata extends Record<string, unknown> = Record<string, unknown>> {
+    id: string;
+    kind: string;
+    ownerId: string;
+    transform: NetcodeTransform;
+    physics?: NetcodePhysicsState;
+    metadata?: TMetadata;
+    updatedAt: number;
+}
+export type NetcodeObjectUpsert<TMetadata extends Record<string, unknown> = Record<string, unknown>> = Partial<Omit<NetcodeObjectState<TMetadata>, 'transform'>> & {
+    kind?: string;
+    transform: Partial<NetcodeTransform> & {
+        position: NetcodeVector3;
+    };
+};
+export type NetcodeObjectChange = {
+    type: 'snapshot';
+    objects: NetcodeObjectState[];
+    from: string;
+} | {
+    type: 'upsert';
+    object: NetcodeObjectState;
+    from: string;
+} | {
+    type: 'remove';
+    id: string;
+    from: string;
+};
+export interface NetcodeObjectStore {
+    list(): NetcodeObjectState[];
+    get(id: string): NetcodeObjectState | undefined;
+    snapshot(): Record<string, NetcodeObjectState>;
+    spawn(input: NetcodeObjectUpsert): Promise<NetcodeObjectState>;
+    upsert(input: NetcodeObjectUpsert): Promise<NetcodeObjectState>;
+    update(id: string, patch: Partial<Omit<NetcodeObjectState, 'id'>>): Promise<NetcodeObjectState>;
+    remove(id: string): Promise<void>;
+    onChange(listener: (change: NetcodeObjectChange) => void): () => void;
+}
+export interface NetcodeVoiceSignal {
+    description?: RTCSessionDescriptionInit;
+    candidate?: RTCIceCandidateInit;
+}
+export interface NetcodeVoiceOptions {
+    mediaStream?: MediaStream;
+    mediaDevices?: Pick<MediaDevices, 'getUserMedia'>;
+    audio?: boolean | MediaTrackConstraints;
+    rtcConfig?: RTCConfiguration;
+    createPeerConnection?: (config?: RTCConfiguration) => RTCPeerConnection;
+    stopTracksOnStop?: boolean;
+}
+export interface NetcodeVoicePeer {
+    peerId: string;
+    stream: MediaStream | null;
+    connectionState: RTCPeerConnectionState;
+    iceConnectionState: RTCIceConnectionState;
+}
+export interface NetcodeVoiceEvents {
+    'local:stream': MediaStream;
+    'peer:stream': {
+        peerId: string;
+        stream: MediaStream;
+    };
+    'peer:left': {
+        peerId: string;
+    };
+    peers: NetcodeVoicePeer[];
+    mute: boolean;
+}
+export interface NetcodeVoice {
+    readonly enabled: boolean;
+    readonly localStream: MediaStream | null;
+    readonly isMuted: boolean;
+    listPeers(): NetcodeVoicePeer[];
+    start(options?: NetcodeVoiceOptions): Promise<MediaStream>;
+    stop(): Promise<void>;
+    setMuted(muted: boolean): void;
+    on<K extends keyof NetcodeVoiceEvents>(event: K, handler: (payload: NetcodeVoiceEvents[K]) => void): () => void;
+}
+export interface NetcodeEvents {
+    lobby: NetcodeLobby | null;
+    'peer:joined': NetcodePeer;
+    'peer:left': NetcodePeer;
+    'peer:connected': NetcodePeer;
+    'peer:disconnected': NetcodePeer;
+    'peer:stats': NetcodePeerStats;
+    message: NetcodeMessage;
+    envelope: NetcodeEnvelope;
+    'state:snapshot': StateSnapshotBody;
+    'state:patch': StatePatchBody;
+    'object:snapshot': ObjectSnapshotBody;
+    'object:upsert': ObjectUpsertBody;
+    'object:remove': ObjectRemoveBody;
+    'lobby:metadata': MetadataBody;
+    'member:metadata': MetadataBody & {
+        peerId: string;
+    };
+    'voice:signal': VoiceSignalBody & {
+        peerId: string;
+    };
+}
+export type NetcodeEventName = keyof NetcodeEvents;
+export type NetcodeEventHandler<K extends NetcodeEventName> = (payload: NetcodeEvents[K]) => void;
+export type NetcodeMessageHandler<T = unknown> = (message: NetcodeMessage<T>) => void;
+export interface NetcodeMessage<T = unknown> {
+    type: string;
+    payload: T;
+    from: string;
+    target?: string;
+    sentAt: number;
+}
+export interface NetcodeClient {
+    readonly peerId: string | null;
+    readonly lobby: NetcodeLobby | null;
+    readonly peers: NetcodePeer[];
+    readonly peerStats: NetcodePeerStats[];
+    readonly state: NetcodeState;
+    readonly objects: NetcodeObjectStore;
+    readonly voice: NetcodeVoice;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    createLobby(options?: CreateLobbyOptions): Promise<NetcodeLobby>;
+    joinLobby(lobbyId: string, options?: JoinLobbyOptions): Promise<NetcodeLobby>;
+    joinOrCreateLobby(lobbyId: string, options?: JoinLobbyOptions): Promise<NetcodeLobby>;
+    leaveLobby(): Promise<void>;
+    send(peerId: string, type: string, payload: unknown, options?: SendOptions): Promise<void>;
+    broadcast(type: string, payload: unknown, options?: SendOptions): Promise<void>;
+    on<K extends NetcodeEventName>(event: K, handler: NetcodeEventHandler<K>): () => void;
+    onMessage<T = unknown>(type: string, handler: NetcodeMessageHandler<T>): () => void;
+    setLobbyData(key: string, value: string): Promise<void>;
+    setMemberData(key: string, value: string): Promise<void>;
+}
+export type RuntimeConnectionLike = {
+    id?: string;
+    deviceId?: string;
+    remoteNodeId?: string;
+    isClosed?: boolean;
+    getTransportStatus?(): {
+        activeTransport: string;
+        parallelTransport?: string | null;
+    };
+    getAvailableTransports?(): string[];
+    requestWebRTCUpgrade?(reason?: string): void;
+    send(message: unknown): Promise<void> | void;
+    onMessage(callback: (message: unknown) => void): void | (() => void);
+    onDisconnect(callback: () => void): void | (() => void);
+    disconnect?(): Promise<void> | void;
+};
+export type RuntimeApplicationPayloadReadinessOptions = {
+    preferredTransports?: string[];
+    allowFallbackAfterPreferredTransportFailure?: boolean;
+};
+export type RuntimeMemberLike = {
+    nodeId?: string;
+    userId?: string;
+    ticket?: string;
+    joinedAt?: number;
+    lastSeenAt?: number;
+    expiresAt?: number;
+    metadata?: string | Record<string, unknown> | null;
+};
+export type RuntimeEnvelopeBody = UserMessageBody | StateSnapshotBody | StatePatchBody | ObjectSnapshotBody | ObjectUpsertBody | ObjectRemoveBody | MetadataBody | VoiceSignalBody | Record<string, unknown>;
+export {};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/voice.d.ts

@@ -0,0 +1,35 @@
+import type { NetcodePeer, NetcodeVoice, NetcodeVoiceEvents, NetcodeVoiceOptions, NetcodeVoicePeer, NetcodeVoiceSignal } from './types.js';
+export declare class NetcodeVoiceController implements NetcodeVoice {
+    private readonly localPeerId;
+    private readonly peers;
+    private readonly shouldOffer;
+    private readonly sendSignal;
+    private readonly emitter;
+    private readonly sessions;
+    private readonly pendingSignals;
+    private localMediaStream;
+    private options;
+    private active;
+    private muted;
+    constructor(localPeerId: () => string | null, peers: () => NetcodePeer[], shouldOffer: (localPeerId: string, remotePeerId: string) => boolean, sendSignal: (peerId: string, signal: NetcodeVoiceSignal) => Promise<void>);
+    get enabled(): boolean;
+    get localStream(): MediaStream | null;
+    get isMuted(): boolean;
+    listPeers(): NetcodeVoicePeer[];
+    start(options?: NetcodeVoiceOptions): Promise<MediaStream>;
+    stop(): Promise<void>;
+    setMuted(muted: boolean): void;
+    on<K extends keyof NetcodeVoiceEvents>(event: K, handler: (payload: NetcodeVoiceEvents[K]) => void): () => void;
+    handlePeerConnected(peerId: string): Promise<void>;
+    handlePeerDisconnected(peerId: string): void;
+    handleSignal(peerId: string, signal: NetcodeVoiceSignal): Promise<void>;
+    private createAndSendOffer;
+    private startPeerSession;
+    private flushPendingSignals;
+    private applySignal;
+    private flushPendingCandidates;
+    private ensureSession;
+    private createPeerConnection;
+    private captureAudio;
+    private applyMuteState;
+}

package/dist/voice.js

@@ -0,0 +1,227 @@
+import { TypedEmitter } from './events.js';
+export class NetcodeVoiceController {
+    constructor(localPeerId, peers, shouldOffer, sendSignal) {
+        this.localPeerId = localPeerId;
+        this.peers = peers;
+        this.shouldOffer = shouldOffer;
+        this.sendSignal = sendSignal;
+        this.emitter = new TypedEmitter();
+        this.sessions = new Map();
+        this.pendingSignals = new Map();
+        this.localMediaStream = null;
+        this.options = {};
+        this.active = false;
+        this.muted = false;
+    }
+    get enabled() {
+        return this.active;
+    }
+    get localStream() {
+        return this.localMediaStream;
+    }
+    get isMuted() {
+        return this.muted;
+    }
+    listPeers() {
+        return Array.from(this.sessions.values()).map((session) => ({
+            peerId: session.peerId,
+            stream: session.remoteStream,
+            connectionState: session.connection.connectionState,
+            iceConnectionState: session.connection.iceConnectionState,
+        }));
+    }
+    async start(options = {}) {
+        if (this.active && this.localMediaStream) {
+            return this.localMediaStream;
+        }
+        this.options = options;
+        this.localMediaStream = options.mediaStream ?? await this.captureAudio(options);
+        this.active = true;
+        this.applyMuteState();
+        this.emitter.emit('local:stream', this.localMediaStream);
+        const localPeerId = this.localPeerId();
+        if (localPeerId) {
+            for (const peer of this.peers().filter((candidate) => candidate.connected)) {
+                void this.startPeerSession(peer.id, localPeerId);
+            }
+        }
+        return this.localMediaStream;
+    }
+    async stop() {
+        this.active = false;
+        for (const session of this.sessions.values()) {
+            session.connection.close();
+        }
+        this.sessions.clear();
+        this.pendingSignals.clear();
+        if (this.options.stopTracksOnStop !== false) {
+            for (const track of this.localMediaStream?.getTracks() ?? []) {
+                track.stop();
+            }
+        }
+        this.localMediaStream = null;
+        this.emitter.emit('peers', []);
+    }
+    setMuted(muted) {
+        this.muted = muted;
+        this.applyMuteState();
+        this.emitter.emit('mute', muted);
+    }
+    on(event, handler) {
+        return this.emitter.on(event, handler);
+    }
+    async handlePeerConnected(peerId) {
+        if (!this.active) {
+            return;
+        }
+        const localPeerId = this.localPeerId();
+        if (!localPeerId) {
+            return;
+        }
+        await this.startPeerSession(peerId, localPeerId);
+    }
+    handlePeerDisconnected(peerId) {
+        const session = this.sessions.get(peerId);
+        if (!session) {
+            return;
+        }
+        session.connection.close();
+        this.sessions.delete(peerId);
+        this.emitter.emit('peer:left', { peerId });
+        this.emitter.emit('peers', this.listPeers());
+    }
+    async handleSignal(peerId, signal) {
+        if (!this.active) {
+            const pending = this.pendingSignals.get(peerId) ?? [];
+            pending.push(signal);
+            this.pendingSignals.set(peerId, pending);
+            return;
+        }
+        const session = this.ensureSession(peerId);
+        await this.applySignal(session, signal);
+    }
+    async createAndSendOffer(session) {
+        const offer = await session.connection.createOffer();
+        await session.connection.setLocalDescription(offer);
+        if (session.connection.localDescription) {
+            await this.sendSignal(session.peerId, { description: session.connection.localDescription.toJSON() });
+        }
+    }
+    async startPeerSession(peerId, localPeerId) {
+        try {
+            const session = this.ensureSession(peerId);
+            await this.flushPendingSignals(peerId);
+            if (this.shouldOffer(localPeerId, peerId)) {
+                await this.createAndSendOffer(session);
+            }
+        }
+        catch (error) {
+            console.warn('[openrtc-netcode] voice peer setup failed', error);
+        }
+    }
+    async flushPendingSignals(peerId) {
+        const pending = this.pendingSignals.get(peerId);
+        if (!pending?.length) {
+            return;
+        }
+        this.pendingSignals.delete(peerId);
+        const session = this.ensureSession(peerId);
+        for (const signal of pending) {
+            await this.applySignal(session, signal);
+        }
+    }
+    async applySignal(session, signal) {
+        if (signal.description) {
+            await session.connection.setRemoteDescription(signal.description);
+            await this.flushPendingCandidates(session);
+            if (signal.description.type === 'offer') {
+                const answer = await session.connection.createAnswer();
+                await session.connection.setLocalDescription(answer);
+                if (session.connection.localDescription) {
+                    await this.sendSignal(session.peerId, { description: session.connection.localDescription.toJSON() });
+                }
+            }
+        }
+        if (signal.candidate) {
+            if (!session.connection.remoteDescription) {
+                session.pendingCandidates.push(signal.candidate);
+                return;
+            }
+            await session.connection.addIceCandidate(signal.candidate);
+        }
+    }
+    async flushPendingCandidates(session) {
+        if (!session.connection.remoteDescription || !session.pendingCandidates.length) {
+            return;
+        }
+        const pending = session.pendingCandidates.splice(0);
+        for (const candidate of pending) {
+            await session.connection.addIceCandidate(candidate);
+        }
+    }
+    ensureSession(peerId) {
+        const existing = this.sessions.get(peerId);
+        if (existing) {
+            return existing;
+        }
+        const connection = this.createPeerConnection();
+        const session = {
+            peerId,
+            connection,
+            remoteStream: null,
+            pendingCandidates: [],
+        };
+        const localStream = this.localMediaStream;
+        if (localStream) {
+            for (const track of localStream.getAudioTracks()) {
+                connection.addTrack(track, localStream);
+            }
+        }
+        connection.onicecandidate = (event) => {
+            if (event.candidate) {
+                void this.sendSignal(peerId, { candidate: event.candidate.toJSON() });
+            }
+        };
+        connection.ontrack = (event) => {
+            session.remoteStream = event.streams[0] ?? null;
+            if (session.remoteStream) {
+                this.emitter.emit('peer:stream', { peerId, stream: session.remoteStream });
+            }
+            this.emitter.emit('peers', this.listPeers());
+        };
+        connection.onconnectionstatechange = () => {
+            this.emitter.emit('peers', this.listPeers());
+        };
+        this.sessions.set(peerId, session);
+        this.emitter.emit('peers', this.listPeers());
+        return session;
+    }
+    createPeerConnection() {
+        if (this.options.createPeerConnection) {
+            return this.options.createPeerConnection(this.options.rtcConfig);
+        }
+        if (typeof RTCPeerConnection === 'undefined') {
+            throw new Error('Voice chat requires RTCPeerConnection support in this environment.');
+        }
+        return new RTCPeerConnection(this.options.rtcConfig);
+    }
+    async captureAudio(options) {
+        const mediaDevices = options.mediaDevices ?? globalThis.navigator?.mediaDevices;
+        if (!mediaDevices?.getUserMedia) {
+            throw new Error('Voice chat requires navigator.mediaDevices.getUserMedia.');
+        }
+        return mediaDevices.getUserMedia({
+            audio: options.audio ?? {
+                echoCancellation: true,
+                noiseSuppression: true,
+                autoGainControl: true,
+            },
+            video: false,
+        });
+    }
+    applyMuteState() {
+        for (const track of this.localMediaStream?.getAudioTracks() ?? []) {
+            track.enabled = !this.muted;
+        }
+    }
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "openrtc-netcode",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "sideEffects": false,
+  "description": "A small lobby, mesh, message, and replicated-state netcode layer built on OpenRTC.",
+  "keywords": [
+    "openrtc",
+    "netcode",
+    "p2p",
+    "multiplayer",
+    "lobby",
+    "mesh"
+  ],
+  "author": "Bryant Hargreaves",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://openrtc.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bluestarburst/openrtc.git",
+    "directory": "packages/openrtc-netcode"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "prepublishOnly": "pnpm run build",
+    "test": "vitest run tests",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "openrtc": "^0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "happy-dom": "^20.5.0",
+    "typescript": "^5.8.3",
+    "vitest": "^4.0.18"
+  }
+}