openrtc-netcode 3.0.1 → 3.0.2

package/dist/codec.d.ts

@@ -0,0 +1,74 @@
+import type { NetcodeObjectState } from './types.js';
+/** Lossless moving fields only; immutable identity, scale and metadata stay in the reliable view. */
+export declare function jsonMotionRecord(object: NetcodeObjectState, index: number): {
+    index: number;
+    revision: number;
+    tick: number;
+    updatedAt: number;
+    transform: {
+        position: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        rotation: {
+            x: number;
+            y: number;
+            z: number;
+            w: number;
+        } | undefined;
+    };
+    physics: {
+        linearVelocity: {
+            x: number;
+            y: number;
+            z: number;
+        } | undefined;
+        angularVelocity: {
+            x: number;
+            y: number;
+            z: number;
+        } | undefined;
+        sleeping: boolean | undefined;
+    } | undefined;
+    teleport: boolean | undefined;
+};
+export declare function encodeJsonMotion(objects: readonly NetcodeObjectState[], ids: readonly string[]): {
+    index: number;
+    revision: number;
+    tick: number;
+    updatedAt: number;
+    transform: {
+        position: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        rotation: {
+            x: number;
+            y: number;
+            z: number;
+            w: number;
+        } | undefined;
+    };
+    physics: {
+        linearVelocity: {
+            x: number;
+            y: number;
+            z: number;
+        } | undefined;
+        angularVelocity: {
+            x: number;
+            y: number;
+            z: number;
+        } | undefined;
+        sleeping: boolean | undefined;
+    } | undefined;
+    teleport: boolean | undefined;
+}[];
+export declare function decodeJsonMotion(records: unknown[], definitions: readonly NetcodeObjectState[]): NetcodeObjectState[];
+/** V2 full-motion records; static definitions are bound to the enclosing view revision. */
+export declare function encodeMotion(objects: readonly NetcodeObjectState[], ids: readonly string[]): Uint8Array;
+export declare function decodeMotion(bytes: Uint8Array, definitions: readonly NetcodeObjectState[]): NetcodeObjectState[];
+export declare function motionToBase64(bytes: Uint8Array): string;
+export declare function motionFromBase64(value: string): Uint8Array;

package/dist/codec.js

@@ -0,0 +1,167 @@
+import { isNetcodeObjectState } from './objects.js';
+import { isCounter } from './validation.js';
+/** Lossless moving fields only; immutable identity, scale and metadata stay in the reliable view. */
+export function jsonMotionRecord(object, index) {
+    const vector = (value) => value && ({ x: value.x, y: value.y, z: value.z });
+    const rotation = object.transform.rotation;
+    return { index, revision: object.revision, tick: object.tick, updatedAt: object.updatedAt,
+        transform: { position: vector(object.transform.position), rotation: rotation && { x: rotation.x, y: rotation.y, z: rotation.z, w: rotation.w } },
+        physics: object.physics && { linearVelocity: vector(object.physics.linearVelocity),
+            angularVelocity: vector(object.physics.angularVelocity), sleeping: object.physics.sleeping },
+        teleport: object.teleport };
+}
+export function encodeJsonMotion(objects, ids) {
+    if (objects.length > 1024 || ids.length > 10000)
+        throw new Error('Motion record capacity exceeded.');
+    const indexes = new Map(ids.map((id, index) => [id, index]));
+    return objects.map((object) => {
+        const index = indexes.get(object.id);
+        if (index === undefined)
+            throw new Error('Motion baseline rejected.');
+        return jsonMotionRecord(object, index);
+    });
+}
+export function decodeJsonMotion(records, definitions) {
+    if (records.length > 1024)
+        throw new Error('Motion record capacity exceeded.');
+    const seen = new Set();
+    return records.map((value) => {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw new Error('Motion record rejected.');
+        const record = value, index = record.index;
+        if (typeof index !== 'number' || !Number.isSafeInteger(index) || index < 0 || !definitions[index] || seen.has(index))
+            throw new Error('Motion baseline rejected.');
+        seen.add(index);
+        const definition = definitions[index];
+        const transform = record.transform;
+        const object = { ...definition, revision: record.revision, tick: record.tick, updatedAt: record.updatedAt,
+            transform: { ...definition.transform, position: transform?.position, rotation: transform?.rotation },
+            physics: record.physics, teleport: record.teleport };
+        if (!isNetcodeObjectState(object))
+            throw new Error('Motion state rejected.');
+        return object;
+    });
+}
+const HEADER = 5, RECORD = 59;
+const vectorAxes = ['x', 'y', 'z'];
+/** V2 full-motion records; static definitions are bound to the enclosing view revision. */
+export function encodeMotion(objects, ids) {
+    if (objects.length > 1024 || ids.length > 10000)
+        throw new Error('Motion record capacity exceeded.');
+    const indexes = new Map(ids.map((id, index) => [id, index]));
+    const bytes = new Uint8Array(HEADER + objects.length * RECORD), view = new DataView(bytes.buffer);
+    view.setUint16(0, 0x4e43);
+    view.setUint8(2, 2);
+    view.setUint16(3, objects.length);
+    let offset = HEADER;
+    for (const object of objects) {
+        const index = indexes.get(object.id);
+        if (index === undefined || !isCounter(object.revision) || object.revision === 0 || !isCounter(object.tick))
+            throw new Error('Motion identity rejected.');
+        view.setUint16(offset, index);
+        offset += 2;
+        view.setFloat64(offset, object.revision);
+        offset += 8;
+        view.setFloat64(offset, object.tick);
+        offset += 8;
+        if (!Number.isFinite(object.updatedAt))
+            throw new Error('Motion timestamp rejected.');
+        view.setFloat64(offset, object.updatedAt);
+        offset += 8;
+        for (const axis of vectorAxes) {
+            const value = Math.round(object.transform.position[axis] * 1000);
+            if (!Number.isFinite(value) || value < -2147483648 || value > 2147483647)
+                throw new Error('Position exceeds quantized range.');
+            view.setInt32(offset, value);
+            offset += 4;
+        }
+        const quaternion = object.transform.rotation ?? { x: 0, y: 0, z: 0, w: 1 };
+        const norm = Math.hypot(quaternion.x, quaternion.y, quaternion.z, quaternion.w);
+        if (!Number.isFinite(norm) || norm < 1e-8)
+            throw new Error('Rotation rejected.');
+        for (const axis of ['x', 'y', 'z', 'w']) {
+            view.setInt16(offset, Math.round(quaternion[axis] / norm * 32767));
+            offset += 2;
+        }
+        for (const velocity of [object.physics?.linearVelocity, object.physics?.angularVelocity]) {
+            for (const axis of vectorAxes) {
+                const value = Math.round((velocity?.[axis] ?? 0) * 100);
+                if (!Number.isFinite(value) || value < -32768 || value > 32767)
+                    throw new Error('Velocity exceeds quantized range.');
+                view.setInt16(offset, value);
+                offset += 2;
+            }
+        }
+        view.setUint8(offset++, Number(!!object.physics?.sleeping) | (Number(!!object.teleport) << 1));
+    }
+    return bytes;
+}
+export function decodeMotion(bytes, definitions) {
+    if (bytes.byteLength < HEADER)
+        throw new Error('Truncated motion packet.');
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const count = view.getUint16(3);
+    if (view.getUint16(0) !== 0x4e43 || view.getUint8(2) !== 2 || count > 1024 || bytes.byteLength !== HEADER + count * RECORD)
+        throw new Error('Motion wire format rejected.');
+    const objects = [], seen = new Set();
+    let offset = HEADER;
+    for (let i = 0; i < count; i++) {
+        const index = view.getUint16(offset);
+        offset += 2;
+        const definition = definitions[index];
+        if (!definition || seen.has(index))
+            throw new Error('Motion baseline rejected.');
+        seen.add(index);
+        const revision = view.getFloat64(offset);
+        offset += 8;
+        const tick = view.getFloat64(offset);
+        offset += 8;
+        const updatedAt = view.getFloat64(offset);
+        offset += 8;
+        if (!isCounter(revision) || revision === 0 || !isCounter(tick) || !Number.isFinite(updatedAt))
+            throw new Error('Motion version rejected.');
+        const position = { x: 0, y: 0, z: 0 };
+        for (const axis of vectorAxes) {
+            position[axis] = view.getInt32(offset) / 1000;
+            offset += 4;
+        }
+        const rotation = { x: 0, y: 0, z: 0, w: 1 };
+        for (const axis of ['x', 'y', 'z', 'w']) {
+            rotation[axis] = view.getInt16(offset) / 32767;
+            offset += 2;
+        }
+        const norm = Math.hypot(rotation.x, rotation.y, rotation.z, rotation.w);
+        if (norm < 1e-8)
+            throw new Error('Motion quaternion rejected.');
+        for (const axis of ['x', 'y', 'z', 'w'])
+            rotation[axis] /= norm;
+        const velocities = [];
+        for (let j = 0; j < 2; j++) {
+            const velocity = { x: 0, y: 0, z: 0 };
+            for (const axis of vectorAxes) {
+                velocity[axis] = view.getInt16(offset) / 100;
+                offset += 2;
+            }
+            velocities.push(velocity);
+        }
+        const flags = view.getUint8(offset++);
+        if (flags > 3)
+            throw new Error('Motion flags rejected.');
+        objects.push({ ...definition, revision, tick, updatedAt, teleport: !!(flags & 2),
+            transform: { ...definition.transform, position, rotation },
+            physics: { linearVelocity: velocities[0], angularVelocity: velocities[1], sleeping: !!(flags & 1) },
+        });
+    }
+    return objects;
+}
+export function motionToBase64(bytes) {
+    let value = '';
+    for (let i = 0; i < bytes.length; i += 4096)
+        value += String.fromCharCode(...bytes.subarray(i, i + 4096));
+    return btoa(value);
+}
+export function motionFromBase64(value) {
+    if (value.length > 128 * 1024 || !/^[A-Za-z0-9+/]*={0,2}$/.test(value))
+        throw new Error('Motion encoding rejected.');
+    return Uint8Array.from(atob(value), (character) => character.charCodeAt(0));
+}

package/dist/framing.d.ts

@@ -0,0 +1,9 @@
+/** Incremental bounded u32be decoder; each payload byte is copied once. */
+export declare class FrameDecoder {
+    private readonly header;
+    private headerBytes;
+    private frame;
+    private frameBytes;
+    feed(chunk: Uint8Array, receive: (frame: Uint8Array) => void): void;
+    get incomplete(): boolean;
+}

package/dist/framing.js

@@ -0,0 +1,39 @@
+import { MAX_FRAME_BYTES } from './validation.js';
+/** Incremental bounded u32be decoder; each payload byte is copied once. */
+export class FrameDecoder {
+    constructor() {
+        this.header = new Uint8Array(4);
+        this.headerBytes = 0;
+        this.frame = null;
+        this.frameBytes = 0;
+    }
+    feed(chunk, receive) {
+        let offset = 0;
+        while (offset < chunk.byteLength) {
+            if (!this.frame) {
+                const count = Math.min(4 - this.headerBytes, chunk.byteLength - offset);
+                this.header.set(chunk.subarray(offset, offset + count), this.headerBytes);
+                this.headerBytes += count;
+                offset += count;
+                if (this.headerBytes !== 4)
+                    continue;
+                const length = new DataView(this.header.buffer).getUint32(0);
+                if (length === 0 || length > MAX_FRAME_BYTES)
+                    throw new Error('Netcode frame size rejected.');
+                this.frame = new Uint8Array(length);
+                this.frameBytes = 0;
+                this.headerBytes = 0;
+            }
+            const count = Math.min(this.frame.byteLength - this.frameBytes, chunk.byteLength - offset);
+            this.frame.set(chunk.subarray(offset, offset + count), this.frameBytes);
+            this.frameBytes += count;
+            offset += count;
+            if (this.frameBytes === this.frame.byteLength) {
+                const frame = this.frame;
+                this.frame = null;
+                receive(frame);
+            }
+        }
+    }
+    get incomplete() { return this.headerBytes > 0 || this.frame !== null; }
+}

package/dist/index.d.ts

@@ -4,3 +4,10 @@ export { ObjectStore } from './objects.js';
 export { NETCODE_PROTOCOL, PROTOCOL_VERSION, decodeEnvelope, encodeEnvelope, isEnvelopeKind, } from './protocol.js';
 export type { HelloBody, MetadataBody, NetcodeEnvelope, NetcodeEnvelopeKind, ObjectRemoveBody, ObjectSnapshotBody, ObjectUpsertBody, StatePatchBody, StateSnapshotBody, UserMessageBody, } from './protocol.js';
 export type { CreateLobbyOptions, JoinLobbyOptions, NetVar, NetVarOptions, NetcodeClient, NetcodeEventHandler, NetcodeEventName, NetcodeEvents, NetcodeLobby, NetcodeMessage, MessageHandler, NetcodeObjectChange, NetcodeObjectState, NetcodeObjectStore, NetcodeObjectUpsert, NetcodeOptions, NetcodePeer, NetcodePeerStats, NetcodePhysicsState, NetcodeQuaternion, NetcodeReliability, NetcodeRuntime, NetcodeState, NetcodeTransform, NetcodeVector3, NetcodeVoice, NetcodeVoiceEvents, NetcodeVoiceOptions, NetcodeVoicePeer, SendOptions, } from './types.js';
+export { SimulationClock, SnapshotBuffer, InputPrediction, LagHistory } from './simulation.js';
+export type { TransformSnapshot, SnapshotBufferOptions } from './simulation.js';
+export { ReplicationScheduler } from './replication.js';
+export type { ReplicationOptions, ReplicationStats } from './replication.js';
+export type { ActionHandler, ActionContext } from './actions.js';
+export { encodeMotion, decodeMotion } from './codec.js';
+export type { MotionThresholds } from './motion.js';

package/dist/index.js

@@ -2,3 +2,6 @@ export { createNetcode, } from './client.js';
 export { runtimeFromRoom } from './roomRuntime.js';
 export { ObjectStore } from './objects.js';
 export { NETCODE_PROTOCOL, PROTOCOL_VERSION, decodeEnvelope, encodeEnvelope, isEnvelopeKind, } from './protocol.js';
+export { SimulationClock, SnapshotBuffer, InputPrediction, LagHistory } from './simulation.js';
+export { ReplicationScheduler } from './replication.js';
+export { encodeMotion, decodeMotion } from './codec.js';

package/dist/latestState.d.ts

@@ -1,9 +1,12 @@
-/** Coalesces only queued values; the in-flight state is allowed to finish. */
+/** One in-flight write and one replaceable pending value, with bounded promises. */
 export declare class LatestStateQueue<T> {
     private readonly transmit;
     private pending;
     private running;
+    private current;
+    private closed;
     constructor(transmit: (value: T) => Promise<void>);
     push(value: T): Promise<void>;
+    close(error?: Error): void;
     private pump;
 }

package/dist/latestState.js

@@ -1,44 +1,48 @@
-/** Coalesces only queued values; the in-flight state is allowed to finish. */
+/** One in-flight write and one replaceable pending value, with bounded promises. */
 export class LatestStateQueue {
     constructor(transmit) {
         this.transmit = transmit;
         this.pending = null;
         this.running = false;
+        this.current = null;
+        this.closed = null;
     }
     push(value) {
+        if (this.closed)
+            return Promise.reject(this.closed);
         return new Promise((resolve, reject) => {
-            if (this.pending) {
-                this.pending.value = value;
-                this.pending.waiters.push({ resolve, reject });
-            }
-            else {
-                this.pending = { value, waiters: [{ resolve, reject }] };
-            }
+            this.pending?.resolve();
+            this.pending = { value, resolve, reject };
             this.pump();
         });
     }
+    close(error = new Error('Netcode match retired.')) {
+        this.closed = error;
+        this.current?.reject(error);
+        this.pending?.reject(error);
+        this.pending = null;
+    }
     pump() {
-        if (this.running)
+        if (this.running || this.closed)
             return;
         this.running = true;
         void (async () => {
-            while (this.pending) {
+            while (this.pending && !this.closed) {
                 const current = this.pending;
                 this.pending = null;
+                this.current = current;
                 try {
                     await this.transmit(current.value);
-                    for (const waiter of current.waiters)
-                        waiter.resolve();
+                    current.resolve();
                 }
                 catch (error) {
-                    for (const waiter of current.waiters)
-                        waiter.reject(error);
+                    current.reject(error);
+                }
+                finally {
+                    this.current = null;
                 }
             }
-        })().finally(() => {
-            this.running = false;
-            if (this.pending)
-                this.pump();
-        });
+        })().finally(() => { this.running = false; if (this.pending && !this.closed)
+            this.pump(); });
     }
 }

package/dist/motion.d.ts

@@ -0,0 +1,9 @@
+import type { NetcodeObjectState } from './types.js';
+export interface MotionThresholds {
+    position?: number;
+    rotationRadians?: number;
+    linearVelocity?: number;
+    angularVelocity?: number;
+    maxSilenceMs?: number;
+}
+export declare function motionChanged(a: NetcodeObjectState, b: NetcodeObjectState, ageMs: number, options: MotionThresholds): boolean;

package/dist/motion.js

@@ -0,0 +1,12 @@
+export function motionChanged(a, b, ageMs, options) {
+    if (b.teleport || ageMs >= (options.maxSilenceMs ?? 1000) || a.physics?.sleeping !== b.physics?.sleeping)
+        return true;
+    const distance = (left, right) => Math.hypot((left?.x ?? 0) - (right?.x ?? 0), (left?.y ?? 0) - (right?.y ?? 0), (left?.z ?? 0) - (right?.z ?? 0));
+    if (distance(a.transform.position, b.transform.position) > (options.position ?? 0.001)
+        || distance(a.physics?.linearVelocity, b.physics?.linearVelocity) > (options.linearVelocity ?? 0.01)
+        || distance(a.physics?.angularVelocity, b.physics?.angularVelocity) > (options.angularVelocity ?? 0.01))
+        return true;
+    const qa = a.transform.rotation ?? { x: 0, y: 0, z: 0, w: 1 }, qb = b.transform.rotation ?? { x: 0, y: 0, z: 0, w: 1 };
+    const dot = Math.abs(qa.x * qb.x + qa.y * qb.y + qa.z * qb.z + qa.w * qb.w) / (Math.hypot(qa.x, qa.y, qa.z, qa.w) * Math.hypot(qb.x, qb.y, qb.z, qb.w));
+    return 2 * Math.acos(Math.min(1, dot)) > (options.rotationRadians ?? 0.001);
+}

package/dist/objects.d.ts

@@ -1,28 +1,57 @@
 import type { NetcodeObjectChange, NetcodeObjectStore, NetcodeObjectState, NetcodeObjectUpsert } from './types.js';
+import type { ObjectRemoveBody } from './protocol.js';
 type ObjectListener = (change: NetcodeObjectChange) => void;
 export declare class ObjectStore implements NetcodeObjectStore {
     private readonly localPeerId;
     private readonly publishUpsert;
     private readonly publishRemove;
+    private readonly capacity;
+    private readonly incarnation;
+    private readonly tick;
+    private readonly canWrite;
     private readonly objectsById;
+    private readonly removedById;
     private readonly listeners;
     private nextObjectId;
-    constructor(localPeerId: () => string | null, publishUpsert: (object: NetcodeObjectState) => Promise<void>, publishRemove: (id: string) => Promise<void>);
+    private readonly instanceId;
+    private readonly structureListeners;
+    private readonly idSnapshots;
+    private readonly entryBytes;
+    private bytes;
+    private snapshotBatch;
+    private structurePending;
+    constructor(localPeerId: () => string | null, publishUpsert: (object: NetcodeObjectState) => Promise<void>, publishRemove: (removal: ObjectRemoveBody) => Promise<void>, capacity?: number, incarnation?: (kind?: string) => string, tick?: () => number, canWrite?: (kind?: string) => boolean);
     list(): NetcodeObjectState[];
     get(id: string): NetcodeObjectState | undefined;
+    /** Immutable, allocation-free read for render loops. */
+    read(id: string): Readonly<NetcodeObjectState> | undefined;
+    ids(kind?: string): readonly string[];
+    onStructureChange(listener: () => void): () => void;
+    removeOwner(ownerId: string, kinds?: ReadonlySet<string>): void;
+    pruneOwner(ownerId: string, visible: ReadonlySet<string>): void;
     snapshot(): Record<string, NetcodeObjectState>;
     spawn(input: NetcodeObjectUpsert): Promise<NetcodeObjectState>;
     upsert(input: NetcodeObjectUpsert): Promise<NetcodeObjectState>;
-    update(id: string, patch: Partial<Omit<NetcodeObjectState, 'id'>>): Promise<NetcodeObjectState>;
+    update(id: string, patch: Partial<Omit<NetcodeObjectState, 'id' | 'revision'>>): Promise<NetcodeObjectState>;
     remove(id: string): Promise<void>;
     onChange(listener: ObjectListener): () => void;
     clear(): void;
-    applySnapshot(objects: Record<string, NetcodeObjectState>, from: string): void;
-    applyUpsert(object: NetcodeObjectState, from: string): void;
-    applyRemove(id: string, from: string): void;
+    removalSnapshot(): Record<string, ObjectRemoveBody>;
+    applySnapshot(objects: Record<string, NetcodeObjectState>, from: string, removed?: Record<string, ObjectRemoveBody>): {
+        objects: Record<string, NetcodeObjectState>;
+        removed: Record<string, ObjectRemoveBody>;
+    };
+    applyUpsert(object: NetcodeObjectState, from: string): boolean;
+    applyRemove(id: string, sender: string, removal: ObjectRemoveBody, from?: string): boolean;
     private applyObject;
+    private assertOwner;
     private createObjectId;
+    private structureChanged;
     private emit;
+    private fitsBytes;
+    private setBytes;
+    private releaseBytes;
 }
 export declare function isNetcodeObjectState(value: unknown): value is NetcodeObjectState;
+export declare function isObjectRemoval(value: unknown): value is ObjectRemoveBody;
 export {};