@net-mesh/browser 0.42.0 → 0.44.0

package/dist/netcode/client.js

@@ -16,7 +16,28 @@
  */
 import { ClockEstimator } from './clock.js';
 import { lerpNumbers, SnapshotBuffer } from './interpolate.js';
-import { MAX_NETCODE_INTEREST_KEYS, MAX_NETCODE_INTEREST_KEY_LENGTH, chunkOf, defaultNow, decodeFrame, encodeFrame, eventPeer, peerHex, } from './wire.js';
+import { MAX_NETCODE_INTEREST_KEYS, MAX_NETCODE_INTEREST_KEY_LENGTH, MAX_NAME_REQUESTS, NAME_FORGET_MS, chunkOf, defaultNow, decodeFrame, encodeFrame, eventPeer, peerHex, } from './wire.js';
+import { decodeBinarySnapshot, isBinaryFrame } from './codec.js';
+/** A typed join failure from {@link NetcodeClient.ready}. */
+export class NetcodeError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+        this.name = 'NetcodeError';
+    }
+}
+/**
+ * Unacknowledged inputs one frame may carry when there is a backlog — the
+ * inputs held across a change of owner while the new epoch propagated. One
+ * frame, so they arrive together: inputs split over frames can land in two
+ * ticks, and a host skips the gap the earlier frame would have filled.
+ */
+const MAX_INPUT_BACKLOG = 64;
+/** A fresh {@link InputSequencer}: `seq` 0, nothing pending. */
+export function createInputSequencer() {
+    return { seq: 0, pending: [] };
+}
 /** Join a host's netcode. */
 export function joinNetcode(options) {
     const now = options.now ?? defaultNow;
@@ -25,14 +46,22 @@ export function joinNetcode(options) {
         throw new TypeError(`host is not a node id: ${JSON.stringify(options.host)}`);
     const label = options.label;
     const delay = options.interpolationDelayMs ?? 100;
-    const blend = options.interpolate ?? lerpNumbers;
+    const blend = options.interpolate ?? options.codec?.interpolate ?? lerpNumbers;
     const redundancy = Math.max(1, options.inputRedundancy ?? 8);
     const clock = new ClockEstimator();
-    const snapshots = new SnapshotBuffer();
+    // Replaced, not cleared, when a binary snapshot shows a re-created host.
+    let snapshots = new SnapshotBuffer();
     let stream = null;
     let closed = false;
-    let seq = 0;
-    let pending = [];
+    // Shared with the other shards' clients when `sequencer` is given, so the
+    // sequence and the unacknowledged inputs survive a change of owner.
+    const inputs = options.sequencer ?? createInputSequencer();
+    // Whether this client speaks for the inputs: sends them, and trims them
+    // on its host's acks. With a shared sequencer (`joinShards`) only the
+    // client predicting the local entity does; the other shards' clients hold
+    // the same list and must neither send it to their hosts nor trim it on
+    // acks for inputs those hosts never received.
+    const speaks = options.sequencer === undefined || options.local !== undefined;
     let predicted = null;
     // A correction being blended in: the stale prediction (still advanced
     // by every input, so it keeps pace with the controls) and when it began.
@@ -50,6 +79,10 @@ export function joinNetcode(options) {
         return blend(correcting.from, predicted, Math.max(0, alpha));
     };
     let snapshotsSeen = 0;
+    // With a codec the host's state arrives quantized, and a prediction is
+    // never exactly a quantized value: compare within the codec's quanta, or
+    // every snapshot would read as a correction.
+    const sameState = (a, b) => options.codec !== undefined ? options.codec.near(a, b) : JSON.stringify(a) === JSON.stringify(b);
     // The interest set: what was asked, its version, and the newest version a
     // snapshot has echoed (the `w` frame repeats until they meet).
     let interest = null;
@@ -82,23 +115,73 @@ export function joinNetcode(options) {
     let partialSnapshots = 0;
     let corrections = 0;
     let joined = false;
+    // The epoch of the newest-tick snapshot that carried one.
+    let snapshotEpoch = null;
+    let epochTick = -1;
+    let lastSnapshotAt = null;
+    const inputEpoch = () => (options.epoch === undefined ? {} : { ep: options.epoch() });
+    // The newest `redundancy` inputs — or, past that, the whole backlog up to
+    // MAX_INPUT_BACKLOG, in one frame.
+    const sendInputs = () => {
+        const count = inputs.pending.length > redundancy ? MAX_INPUT_BACKLOG : redundancy;
+        send({ n: label, k: 'i', i: inputs.pending.slice(-count), ...inputEpoch() });
+    };
     const offset = () => clock.estimate()?.offsetMs ?? null;
     const hostNow = () => {
         const o = offset();
         return o === null ? null : now() + o;
     };
+    // What the last attempt to reach the host said, for `stats()` and for
+    // `ready()`'s typed failure: a join that never connects must say why.
+    let connectOutcome = null;
+    let lastError = null;
+    const message = (error) => String(error?.message ?? error);
+    // Whether a reopen should offer again. Found by the S0b topology run: a
+    // pair whose direct attempt ended relayed was re-offered on EVERY stream
+    // reopen. `connectPeer` is a no-op only on a healthy direct pair, so each
+    // reopen began a fresh ICE attempt, a late one bumped the session, the
+    // stream went stale, the next send failed and reopened — 44 attempts in
+    // five minutes and no snapshot. A relayed pair is a supported outcome:
+    // reopen the stream on it, and try direct again only after
+    // `directRetryMs`. `noAnnouncement` is retried at once (it is cheap and
+    // discovery needs it); a direct pair's call is the idempotent check.
+    //
+    // A `connectPeer` that rejects (the peer answered `Reject`, say) is
+    // throttled the same way: it leaves no outcome, and without this every
+    // reopen would offer again.
+    const directRetryMs = Math.max(0, options.directRetryMs ?? 30_000);
+    let lastOfferAt = -Infinity;
+    let offerRejected = false;
+    const shouldOffer = () => now() - lastOfferAt >= directRetryMs ||
+        (!offerRejected &&
+            (connectOutcome === null || connectOutcome === 'noAnnouncement' || connectOutcome === 'direct'));
     let opening = null;
     const open = () => {
         opening ??= (async () => {
-            await options.transport.connectPeer?.(host).catch(() => { });
+            if (options.transport.connectPeer !== undefined && shouldOffer()) {
+                lastOfferAt = now();
+                try {
+                    const outcome = (await options.transport.connectPeer(host));
+                    offerRejected = false;
+                    if (outcome !== null && typeof outcome === 'object' && typeof outcome.type === 'string')
+                        connectOutcome = outcome.type;
+                }
+                catch (error) {
+                    offerRejected = true;
+                    lastError = message(error);
+                }
+            }
             const opened = await options.transport.openStream({ reliability: 'fireAndForget', peer: host, label, lossy: true });
             if (closed) {
                 opened.close();
                 return;
             }
             stream = opened;
+            lastError = null;
         })()
-            .catch(() => { })
+            .catch(error => {
+            lastError = message(error);
+        })
             .finally(() => {
             opening = null;
         });
@@ -114,7 +197,9 @@ export function joinNetcode(options) {
             void open();
             return;
         }
-        const retire = () => {
+        const retire = (error) => {
+            if (error !== undefined)
+                lastError = message(error);
             if (stream === current) {
                 stream = null;
                 try {
@@ -128,8 +213,8 @@ export function joinNetcode(options) {
         try {
             void Promise.resolve(current.send(encodeFrame(frame))).catch(retire);
         }
-        catch {
-            retire();
+        catch (error) {
+            retire(error);
         }
     };
     const stopEvents = options.transport.onEvent(event => {
@@ -137,6 +222,10 @@ export function joinNetcode(options) {
             return;
         if (eventPeer(event.peerNode) !== host)
             return;
+        if (isBinaryFrame(event.payload)) {
+            onBinary(event.payload);
+            return;
+        }
         const frame = decodeFrame(event.payload, label);
         if (frame === null)
             return;
@@ -146,7 +235,47 @@ export function joinNetcode(options) {
         }
         if (frame.k !== 's')
             return;
-        joined = true;
+        onSnapshot(frame);
+    });
+    /** One snapshot frame, JSON or decoded binary: whole, or a chunk. */
+    // `ready()`: settled once, at the first snapshot, the deadline, or close.
+    let readySettle = null;
+    let readyPromise = null;
+    let readyTimer = null;
+    let readyFailure = null;
+    const settleReady = (failure) => {
+        if (readyTimer !== null)
+            clearTimeout(readyTimer);
+        readyTimer = null;
+        const settle = readySettle;
+        readySettle = null;
+        if (failure === null)
+            settle?.resolve();
+        else {
+            readyFailure = failure;
+            settle?.reject(failure);
+        }
+    };
+    const joinFailure = () => {
+        const why = lastError === null ? '' : ` (${lastError})`;
+        if (connectOutcome === 'noAnnouncement') {
+            return new NetcodeError('no-announcement', `no announcement from host ${host}: the host must announce, and this node must have heard it before it can connect${why}`);
+        }
+        if (stream === null)
+            return new NetcodeError('unreachable', `could not open a stream to host ${host}${why}`);
+        return new NetcodeError('timeout', `no snapshot from host ${host} within ${String(joinTimeoutMs)} ms`);
+    };
+    const joinTimeoutMs = Math.max(0, options.joinTimeoutMs ?? 15_000);
+    function onSnapshot(frame) {
+        lastSnapshotAt = now();
+        if (frame.ep !== undefined && frame.tick >= epochTick) {
+            snapshotEpoch = frame.ep;
+            epochTick = frame.tick;
+        }
+        if (!joined) {
+            joined = true;
+            settleReady(null);
+        }
         if (frame.iv !== undefined && frame.iv > interestAcked)
             interestAcked = frame.iv;
         if (frame.of === undefined || frame.c === undefined) {
@@ -172,7 +301,100 @@ export function joinNetcode(options) {
         assembly.ack = Math.max(assembly.ack, frame.ack);
         if (assembly.parts.size === assembly.of)
             finish(frame.tick, assembly);
-    });
+    }
+    // Binary snapshots: index → id, learnt from the frames that name them,
+    // and when a frame last carried the index. One host instance never
+    // reuses an index, so a name, once known, stays right for that instance.
+    const idOf = new Map();
+    let binaryFrames = 0;
+    let unnamedEntities = 0;
+    // The host instance the names belong to, and instances replaced since
+    // (a late frame from one is not a new host).
+    let hostInstance = null;
+    const retiredInstances = new Set();
+    /**
+     * A new host instance: the host was re-created under this label. Its
+     * indexes start over, and so do its ticks — drop every name, assembly
+     * and snapshot the old one left, rather than read the new one through
+     * them.
+     */
+    const newHostInstance = (instance) => {
+        if (hostInstance !== null) {
+            retiredInstances.add(hostInstance);
+            if (retiredInstances.size > 8)
+                retiredInstances.delete(retiredInstances.values().next().value);
+            idOf.clear();
+            assemblies.clear();
+            newestTick = null;
+            snapshots = new SnapshotBuffer();
+            snapshotEpoch = null;
+            epochTick = -1;
+        }
+        hostInstance = instance;
+    };
+    // Names not carried by a frame for three times the host's forget time
+    // are forgotten (see NAME_FORGET_MS), checked about once a second.
+    let lastForget = now();
+    const forgetNames = (at) => {
+        if (at - lastForget < 1000)
+            return;
+        lastForget = at;
+        for (const [index, known] of idOf)
+            if (at - known.seen > 3 * NAME_FORGET_MS)
+                idOf.delete(index);
+    };
+    function onBinary(payload) {
+        const codec = options.codec;
+        if (codec === undefined)
+            return;
+        const decoded = decodeBinarySnapshot(payload, label, codec);
+        if (decoded === null)
+            return;
+        if (decoded.instance !== undefined && decoded.instance !== hostInstance) {
+            if (retiredInstances.has(decoded.instance))
+                return;
+            newHostInstance(decoded.instance);
+        }
+        const at = now();
+        for (const [index, id] of decoded.names) {
+            const known = idOf.get(index);
+            if (known !== undefined && known.id !== id) {
+                // A different name for a known index is another host's numbering
+                // (one from before instances were stamped): start over from this
+                // frame's names, and ask for the rest below.
+                idOf.clear();
+                break;
+            }
+        }
+        for (const [index, id] of decoded.names)
+            idOf.set(index, { id, seen: at });
+        binaryFrames += 1;
+        const entities = {};
+        const unknown = [];
+        for (const [index, entity] of decoded.entities) {
+            const known = idOf.get(index);
+            if (known === undefined) {
+                unknown.push(index);
+                continue;
+            }
+            known.seen = at;
+            Object.defineProperty(entities, known.id, { value: entity, enumerable: true, writable: true, configurable: true });
+        }
+        forgetNames(at);
+        if (unknown.length > 0) {
+            unnamedEntities += unknown.length;
+            send({ n: label, k: 'u', u: unknown.slice(0, MAX_NAME_REQUESTS) });
+        }
+        onSnapshot({
+            tick: decoded.tick,
+            t: decoded.t,
+            ack: decoded.ack,
+            e: entities,
+            ...(decoded.iv === undefined ? {} : { iv: decoded.iv }),
+            ...(decoded.ep === undefined ? {} : { ep: decoded.ep }),
+            ...(decoded.of === undefined ? {} : { c: decoded.c, of: decoded.of }),
+        });
+    }
     /**
      * A chunked snapshot, done: every chunk, or the chunks that came, with
      * each missing chunk's entities carried over from the previous snapshot
@@ -207,18 +429,22 @@ export function joinNetcode(options) {
         snapshots.add({ time, tick, entities });
         if (newestTick === null || tick > newestTick)
             newestTick = tick;
+        // Acknowledged inputs are done with, predicting or not: a client that
+        // never trimmed would send its whole backlog in every input frame. An
+        // ack only grows, so an older snapshot's trims nothing.
+        if (speaks)
+            inputs.pending = inputs.pending.filter(input => input.seq > ack);
         // Reconcile only on a snapshot newer than any seen: an older one
         // (reordered by the carrier) must not roll the local entity back.
         if (options.local && (newest === null || tick > newest.tick)) {
-            pending = pending.filter(input => input.seq > ack);
             const authoritative = Object.prototype.hasOwnProperty.call(sent, options.local.id)
                 ? sent[options.local.id]
                 : undefined;
             if (authoritative !== undefined) {
                 let replayed = authoritative;
-                for (const input of pending)
+                for (const input of inputs.pending)
                     replayed = options.local.predict(replayed, input.data);
-                if (predicted !== null && JSON.stringify(replayed) !== JSON.stringify(predicted)) {
+                if (predicted !== null && !sameState(replayed, predicted)) {
                     corrections += 1;
                     // Blend from what is on screen now, so a correction that lands
                     // mid-blend continues from there rather than jumping back.
@@ -229,36 +455,49 @@ export function joinNetcode(options) {
             }
         }
     }
-    // Join, and keep the clock honest.
-    const pingEvery = 1000 / Math.max(0.5, options.pingRate ?? 4);
+    // Join, and keep the clock honest. The codec fingerprint rides both.
+    const fingerprint = options.codec === undefined ? {} : { f: options.codec.fingerprint };
+    const pingRate = Math.max(0.5, options.pingRate ?? 4);
+    const pingEvery = 1000 / pingRate;
+    // Once the clock has settled, ping on every Nth beat of the timer only.
+    const settledEvery = Math.max(1, Math.round(pingRate / Math.max(0.1, Math.min(pingRate, options.settledPingRate ?? 1))));
+    const SETTLED_SAMPLES = 8;
+    let beat = 0;
     const timer = setInterval(() => {
         if (!joined)
-            send({ n: label, k: 'h' });
-        send({ n: label, k: 'p', t0: now() });
+            send({ n: label, k: 'h', ...fingerprint });
+        const settled = (clock.estimate()?.samples ?? 0) >= SETTLED_SAMPLES;
+        beat += 1;
+        if (!settled || beat % settledEvery === 0)
+            send({ n: label, k: 'p', t0: now(), ...fingerprint });
         sendInterest();
         // Unacknowledged inputs are repeated even with nothing new to send, so
         // a lost input frame is repaired without waiting for the next input.
-        if (pending.length > 0)
-            send({ n: label, k: 'i', i: pending.slice(-redundancy) });
+        // With a shared sequencer, only the client predicting the local entity
+        // speaks for the inputs (`speaks`, above).
+        if (speaks && inputs.pending.length > 0) {
+            sendInputs();
+        }
     }, pingEvery);
     void open().then(() => {
-        send({ n: label, k: 'h' });
-        send({ n: label, k: 'p', t0: now() });
+        send({ n: label, k: 'h', ...fingerprint });
+        send({ n: label, k: 'p', t0: now(), ...fingerprint });
         sendInterest();
     });
     return {
         input(data) {
             if (closed)
                 return;
-            seq += 1;
+            inputs.seq += 1;
+            const seq = inputs.seq;
             const seen = (hostNow() ?? now()) - delay;
-            pending.push({ seq, seen, data });
+            inputs.pending.push({ seq, seen, data });
             if (options.local && predicted !== null) {
                 predicted = options.local.predict(predicted, data);
                 if (correcting !== null)
                     correcting = { ...correcting, from: options.local.predict(correcting.from, data) };
             }
-            send({ n: label, k: 'i', i: pending.slice(-redundancy) });
+            sendInputs();
         },
         view() {
             const at = hostNow();
@@ -275,20 +514,45 @@ export function joinNetcode(options) {
             if (!closed)
                 sendInterest();
         },
+        ready() {
+            if (joined)
+                return Promise.resolve();
+            if (readyFailure !== null && closed)
+                return Promise.reject(readyFailure);
+            readyPromise ??= new Promise((resolve, reject) => {
+                readySettle = { resolve, reject };
+                readyTimer = setTimeout(() => {
+                    // Failed for THIS wait; a later call waits afresh, since the
+                    // client keeps trying.
+                    settleReady(joinFailure());
+                    readyPromise = null;
+                }, joinTimeoutMs);
+            });
+            return readyPromise;
+        },
         hostNow,
+        sampleAt: hostTime => snapshots.sample(hostTime, blend),
+        latest: () => snapshots.latest(),
         stats: () => ({
             clock: clock.estimate(),
             snapshots: snapshotsSeen,
             lateSnapshots: snapshots.late,
-            pendingInputs: pending.length,
+            pendingInputs: inputs.pending.length,
             corrections,
             partialSnapshots,
+            binaryFrames,
+            unnamedEntities,
+            connectOutcome,
+            lastError,
+            epoch: snapshotEpoch,
+            lastSnapshotAt,
         }),
         close() {
             if (closed)
                 return;
             closed = true;
             clearInterval(timer);
+            settleReady(new NetcodeError('closed', 'the netcode client was closed before it joined'));
             stopEvents();
             stream?.close();
         },

package/dist/netcode/codec.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Compact snapshots: a game-supplied entity schema, and the binary snapshot
+ * frame it makes possible (sharded-match plan, slice S0c).
+ *
+ * ```ts
+ * const shipCodec = entityCodec({
+ *   x: quantized(0, 512),          // 16 bits over the arena: ~8 mm
+ *   z: quantized(0, 512),
+ *   yaw: angle(),                  // 8 bits: ~1.4°
+ *   hp: uint(8),
+ * });
+ * hostNetcode({ …, codec: shipCodec });
+ * joinNetcode({ …, codec: shipCodec });
+ * ```
+ *
+ * JSON stays the default and the fallback. A player announces its codec's
+ * fingerprint in its join and ping frames; the host sends binary snapshots
+ * only to a player whose fingerprint matches its own, and JSON to everyone
+ * else — so a mismatched or older peer degrades to JSON, never to garbage.
+ *
+ * **Ids.** On the binary wire an entity is named by a varint index, not its
+ * id string. The host assigns indexes in order of first appearance and
+ * **never reuses one** within its lifetime, so a late or reordered
+ * snapshot cannot name the wrong entity. A snapshot carries an entity's
+ * name the first time it shows that entity to a player; a player that sees
+ * an index it has no name for does not draw that entity and asks again
+ * (`u` frame) — the lossy carrier's repair, with no acknowledgements.
+ *
+ * Every binary snapshot also carries the host's **instance**, a random
+ * 32-bit number drawn when `hostNetcode` starts. A host re-created under
+ * the same label starts its indexes over; a player that sees a new instance
+ * drops every name (and every snapshot) it learnt from the old one, so the
+ * new host's indexes are never read through the old host's names.
+ *
+ * Names are also forgotten: an id no player has been shown for
+ * `NAME_FORGET_MS` (10 s) loses its index, and comes back, if it does,
+ * under a fresh one, named again. Transient ids (projectiles) do not grow
+ * the tables for the whole match.
+ *
+ * **Versions.** The fingerprint covers the binary wire's version as well as
+ * the schema. Frames carrying an instance are version 2; a peer from before
+ * it has another fingerprint for the same schema, so the pair falls back
+ * to JSON instead of refusing each other's frames.
+ *
+ * **Interpolation.** `entityCodec` also supplies an `interpolate` blend
+ * that knows its fields: an `angle()` turns the short way round across
+ * 0 / 2π. `joinNetcode` uses it when it has a codec and no `interpolate`
+ * of its own.
+ *
+ * **What the schema promises.** An entity is a flat object of the schema's
+ * fields and nothing else. Writing an entity with a field the schema does
+ * not have, or a value that is not a finite number (or boolean, for
+ * `bool()`), throws: the host then sends that player JSON for that tick
+ * (counted in `dropped`) rather than silently losing a field.
+ */
+/** One field of an entity schema: its bytes, and how it is written and read. */
+export interface FieldCodec {
+    /** Bytes it takes. */
+    readonly size: number;
+    /** A stable description, part of the codec's fingerprint. */
+    readonly spec: string;
+    write(view: DataView, at: number, value: unknown): void;
+    read(view: DataView, at: number): number | boolean;
+    /** The largest error a written value may come back with (0: exact). */
+    readonly quantum: number;
+    /** Two values this field cannot tell apart once quantized (within two quantization steps). */
+    near(a: unknown, b: unknown): boolean;
+    /**
+     * Blend two values of this field for interpolation (`alpha` in `[0, 1]`,
+     * above 1 when extrapolating). Omitted: linear. `angle()` turns the short
+     * way round.
+     */
+    blend?(from: number, to: number, alpha: number): number;
+}
+/** A whole-entity codec: fixed size, and a fingerprint both ends compare. */
+export interface EntityCodec<E> {
+    readonly size: number;
+    /** Equal on host and player iff they encode entities the same way. */
+    readonly fingerprint: string;
+    write(entity: E, view: DataView, at: number): void;
+    read(view: DataView, at: number): E;
+    /**
+     * Two states equal within what the codec can carry — how a player tells a
+     * real correction from quantization. A prediction is never exactly a
+     * quantized value, and comparing exactly would read every snapshot as a
+     * correction.
+     */
+    near(a: E, b: E): boolean;
+    /**
+     * Blend two states of an entity for interpolation, field by field:
+     * linear, except where a field blends its own way (an `angle()` turns the
+     * short way). `joinNetcode` uses it when given this codec and no
+     * `interpolate`. Optional: a hand-written codec may leave it out.
+     */
+    readonly interpolate?: Interpolator<E>;
+}
+import { type Interpolator } from './interpolate.js';
+type Bits = 8 | 16 | 32;
+/**
+ * A number in `[min, max]`, quantized to `bits` (8 or 16; default 16).
+ * Values outside the range are clamped — including one a hair past an edge
+ * after rounding, which must not wrap around.
+ */
+export declare function quantized(min: number, max: number, bits?: 8 | 16): FieldCodec;
+/** An angle in radians, any value, stored as a fraction of a turn in `bits` (default 8). Reads in `[0, 2π)`. */
+export declare function angle(bits?: 8 | 16): FieldCodec;
+/** A whole number in `[0, 2^bits)`, exact (default 8 bits). Out of range throws. */
+export declare function uint(bits?: Bits): FieldCodec;
+/** A whole number in `[-2^(bits-1), 2^(bits-1))`, exact (default 16 bits). Out of range throws. */
+export declare function int(bits?: Bits): FieldCodec;
+/** A 32-bit float: ~7 significant digits, no range to choose. A NaN or an infinity read off the wire refuses the frame. */
+export declare function float32(): FieldCodec;
+/** A boolean, one byte. */
+export declare function bool(): FieldCodec;
+/**
+ * An entity codec from a schema: one field codec per property, written in
+ * the schema's key order. The fingerprint covers names, order and specs,
+ * and the binary wire's version.
+ */
+export declare function entityCodec<E extends object>(fields: {
+    readonly [K in keyof E]: FieldCodec;
+}): EntityCodec<E>;
+/** First byte of a binary netcode frame. Never `{` (0x7b), so it cannot be JSON. */
+export declare const BINARY_FRAME_MAGIC = 177;
+/** The label's 32-bit FNV-1a: a binary frame's stand-in for the JSON `n`. */
+export declare function labelHash(label: string): number;
+/** What a binary snapshot carries; the same fields as the JSON `s` frame, plus names. */
+export interface BinarySnapshot<E> {
+    readonly tick: number;
+    readonly t: number;
+    readonly ack: number;
+    readonly iv?: number;
+    readonly c?: number;
+    readonly of?: number;
+    /** The assignment epoch the host sent it under, if it stamps one. */
+    readonly ep?: number;
+    /** The sending host's instance (wire version 2), if the frame carries one. */
+    readonly instance?: number;
+    /** Index → id, for the indexes this frame names. */
+    readonly names: ReadonlyMap<number, string>;
+    /** Index → entity. */
+    readonly entities: ReadonlyMap<number, E>;
+}
+/** The binary size of one snapshot frame, without building it. */
+export declare function binarySnapshotSize(frame: {
+    readonly tick: number;
+    readonly ack: number;
+    readonly iv?: number;
+    readonly c?: number;
+    readonly of?: number;
+    readonly ep?: number;
+    readonly instance?: number;
+}, names: Iterable<readonly [number, Uint8Array]>, indexes: Iterable<number>, entitySize: number): number;
+/**
+ * Build one binary snapshot frame. `names` are UTF-8 ids by index;
+ * `entities` are by index. Throws if the codec refuses an entity.
+ */
+export declare function encodeBinarySnapshot<E>(label: string, frame: {
+    readonly tick: number;
+    readonly t: number;
+    readonly ack: number;
+    readonly iv?: number;
+    readonly c?: number;
+    readonly of?: number;
+    readonly ep?: number;
+    /** The host's instance, a 32-bit unsigned integer: written as wire version 2. */
+    readonly instance?: number;
+}, names: ReadonlyMap<number, Uint8Array>, entities: ReadonlyMap<number, E>, codec: EntityCodec<E>): Uint8Array;
+/** True if `payload` is a binary netcode frame (of any label). */
+export declare function isBinaryFrame(payload: Uint8Array | undefined): payload is Uint8Array;
+/**
+ * Read a binary snapshot for `label`, or `null` for another label, another
+ * kind, or anything malformed (truncated, trailing bytes, bad chunk fields,
+ * a duplicate index, a name that is not UTF-8, an entity the codec will not
+ * read, such as a NaN `float32()`).
+ */
+export declare function decodeBinarySnapshot<E>(payload: Uint8Array, label: string, codec: EntityCodec<E>): BinarySnapshot<E> | null;
+/** UTF-8 of an id, for {@link encodeBinarySnapshot}'s names. */
+export declare function nameBytes(id: string): Uint8Array;
+export {};