@net-mesh/browser 0.37.0

package/dist/netcode/host.d.ts

@@ -0,0 +1,118 @@
+/**
+ * `hostNetcode` — the authoritative side of netcode model 2: a fixed-rate
+ * tick loop that applies each player's inputs, broadcasts snapshots on the
+ * lossy carrier, answers clock pings, and keeps a short history for lag
+ * compensation.
+ *
+ * ```ts
+ * const net = hostNetcode({
+ *   transport: node,               // or meshStoreTransport(mesh) on a dedicated host
+ *   label: 'my-game.movement',
+ *   tickRate: 30,
+ *   step: ({ inputs }) => {        // apply this tick's inputs to your world
+ *     for (const [peer, list] of inputs) for (const { data } of list) move(world, peer, data);
+ *   },
+ *   snapshot: () => world.ships,   // entity id → state, sent to every player
+ * });
+ * ```
+ */
+import { type Frame, type NetcodeTransport, type Now } from './wire.js';
+/** One input as `step` receives it. */
+export interface TickInput<I> {
+    readonly seq: number;
+    /** The host time the player was rendering when it issued the input. */
+    readonly seen: number;
+    readonly data: I;
+}
+/** What `step` gets each tick. */
+export interface TickContext<I> {
+    readonly tick: number;
+    /** Host clock, ms, at this tick. */
+    readonly time: number;
+    /** ms since the previous tick (1000 / tickRate, nominally). */
+    readonly dtMs: number;
+    /** Each player's inputs since the last tick, oldest first, each applied
+     * exactly once however many times the lossy carrier repeated it. */
+    readonly inputs: ReadonlyMap<string, readonly TickInput<I>[]>;
+}
+/** What {@link HostNetcode.rewind} returns. */
+export interface Rewound<E> {
+    /** The entities as of the returned `time`. */
+    readonly entities: Readonly<Record<string, E>>;
+    /** The host time rewound to — `seen`, unless the cap clamped it. */
+    readonly time: number;
+    /** `true` when `seen` was further back than `maxRewindMs` allows. */
+    readonly clamped: boolean;
+}
+/** {@link hostNetcode}'s argument. */
+export interface HostNetcodeOptions<E, I> {
+    readonly transport: NetcodeTransport;
+    /** Names this netcode instance; players join the same label. */
+    readonly label: string;
+    /** Ticks per second. Default 30. */
+    readonly tickRate?: number;
+    /** Advance the world one tick. */
+    step(context: TickContext<I>): void;
+    /** The world as players should see it: entity id → state. */
+    snapshot(tick: number): Readonly<Record<string, E>>;
+    /** Which entities `peer` receives. Default: all. */
+    visible?(peer: string, id: string, entity: E): boolean;
+    /**
+     * Interest management: the key an entity is found under (a grid cell, a
+     * room; `null`: always delivered). A player that states interest keys
+     * (`joinNetcode({ interest })` / `setInterest`) then receives only the
+     * entities whose key it named — after `visible`, which stays the
+     * permission; interest is only a filter. A player that states none
+     * receives everything `visible` allows.
+     */
+    interest?(id: string, entity: E): string | null;
+    /** Admit `peer` as a player. Default: everyone. */
+    authorize?(peer: string): boolean;
+    /**
+     * How far back {@link HostNetcode.rewind} may go, in ms. Default 200 —
+     * lag compensation that trusts any claimed latency lets a player buy an
+     * advantage by faking lag.
+     */
+    readonly maxRewindMs?: number;
+    /**
+     * Largest snapshot frame, bytes. Default 8000 — under one event, so a
+     * snapshot never rides as fragments (on the lossy carrier one lost
+     * fragment loses them all). A larger snapshot is sent as independent
+     * chunks; a lost chunk costs the entities it carried, for one tick.
+     */
+    readonly maxFrameBytes?: number;
+    /** Drop a player silent this long, ms. Default 5000. */
+    readonly playerTimeoutMs?: number;
+    /** `false` to drive ticks yourself with {@link HostNetcode.tick}. Default `true`. */
+    readonly autoTick?: boolean;
+    readonly now?: Now;
+}
+/** The running host. */
+export interface HostNetcode<E> {
+    /** Players currently connected, 16-hex peer ids. */
+    players(): readonly string[];
+    /** The tick about to run. */
+    readonly currentTick: number;
+    /** Run one tick now (what the auto loop calls). */
+    tick(): void;
+    /**
+     * Lag compensation: the entities as a player saw them at host time
+     * `seen` (from {@link TickInput.seen}), from this host's own history —
+     * never further back than `maxRewindMs` before now.
+     */
+    rewind(seen: number): Rewound<E>;
+    /** Frames dropped and why. */
+    readonly dropped: Readonly<Record<string, number>>;
+    /** The last error a send or stream open raised, for diagnosis; `null` if none. */
+    readonly lastSendError: string | null;
+    close(): void;
+}
+/**
+ * One snapshot as frames: one, or — over `maxBytes` — chunks by
+ * {@link chunkOf}, as many as it takes for each to fit (up to
+ * {@link MAX_SNAPSHOT_CHUNKS}; past that the chunks are sent over-size and
+ * ride as fragments).
+ */
+export declare function snapshotFrames<E>(label: string, tick: number, time: number, ack: number, entities: Readonly<Record<string, E>>, maxBytes: number, interestVersion?: number): Frame<E, never>[];
+/** Start the authoritative netcode host. */
+export declare function hostNetcode<E, I>(options: HostNetcodeOptions<E, I>): HostNetcode<E>;

package/dist/netcode/host.js

@@ -0,0 +1,276 @@
+/**
+ * `hostNetcode` — the authoritative side of netcode model 2: a fixed-rate
+ * tick loop that applies each player's inputs, broadcasts snapshots on the
+ * lossy carrier, answers clock pings, and keeps a short history for lag
+ * compensation.
+ *
+ * ```ts
+ * const net = hostNetcode({
+ *   transport: node,               // or meshStoreTransport(mesh) on a dedicated host
+ *   label: 'my-game.movement',
+ *   tickRate: 30,
+ *   step: ({ inputs }) => {        // apply this tick's inputs to your world
+ *     for (const [peer, list] of inputs) for (const { data } of list) move(world, peer, data);
+ *   },
+ *   snapshot: () => world.ships,   // entity id → state, sent to every player
+ * });
+ * ```
+ */
+import { MAX_SNAPSHOT_CHUNKS, chunkOf, defaultNow, decodeFrame, encodeFrame, eventPeer, } from './wire.js';
+/** History kept: enough ticks to cover the rewind cap with room. */
+function historySize(tickRate, maxRewindMs) {
+    return Math.max(8, Math.ceil((maxRewindMs / 1000) * tickRate) + 4);
+}
+/**
+ * One snapshot as frames: one, or — over `maxBytes` — chunks by
+ * {@link chunkOf}, as many as it takes for each to fit (up to
+ * {@link MAX_SNAPSHOT_CHUNKS}; past that the chunks are sent over-size and
+ * ride as fragments).
+ */
+export function snapshotFrames(label, tick, time, ack, entities, maxBytes, interestVersion = 0) {
+    // The interest version the view was filtered by, echoed so the player
+    // stops repeating its `w` frame.
+    const iv = interestVersion > 0 ? { iv: interestVersion } : {};
+    const whole = { n: label, k: 's', tick, t: time, ack, e: entities, ...iv };
+    const size = encodeFrame(whole).length;
+    if (size <= maxBytes)
+        return [whole];
+    const ids = Object.keys(entities);
+    let of = Math.min(MAX_SNAPSHOT_CHUNKS, Math.max(2, Math.ceil(size / (maxBytes * 0.75))));
+    for (;;) {
+        const parts = Array.from({ length: of }, () => ({}));
+        for (const id of ids)
+            parts[chunkOf(id, of)][id] = entities[id];
+        const frames = parts.map((e, c) => ({ n: label, k: 's', tick, t: time, ack, e, c, of, ...iv }));
+        if (of >= MAX_SNAPSHOT_CHUNKS || frames.every(frame => encodeFrame(frame).length <= maxBytes)) {
+            return frames;
+        }
+        of = Math.min(MAX_SNAPSHOT_CHUNKS, of * 2);
+    }
+}
+/** Start the authoritative netcode host. */
+export function hostNetcode(options) {
+    const now = options.now ?? defaultNow;
+    const tickRate = options.tickRate ?? 30;
+    if (!(tickRate > 0 && tickRate <= 240))
+        throw new RangeError('tickRate must be in (0, 240]');
+    const tickMs = 1000 / tickRate;
+    const maxRewindMs = options.maxRewindMs ?? 200;
+    const maxFrameBytes = Math.max(256, options.maxFrameBytes ?? 8000);
+    const playerTimeoutMs = options.playerTimeoutMs ?? 5000;
+    const players = new Map();
+    const history = [];
+    const keep = historySize(tickRate, maxRewindMs);
+    const dropped = {};
+    const drop = (why) => {
+        dropped[why] = (dropped[why] ?? 0) + 1;
+    };
+    let tick = 0;
+    let lastError = null;
+    let lastTickAt = now();
+    let closed = false;
+    const send = (peer, player, frame) => {
+        if (player.stream === null) {
+            if (!player.opening) {
+                player.opening = true;
+                Promise.resolve(options.transport.openStream({ reliability: 'fireAndForget', peer, label: options.label, lossy: true }))
+                    .then(stream => {
+                    if (closed || !players.has(peer)) {
+                        stream.close();
+                        return;
+                    }
+                    player.stream = stream;
+                })
+                    .catch(error => {
+                    lastError = String(error?.message ?? error);
+                    drop('stream-open-failed');
+                })
+                    .finally(() => {
+                    player.opening = false;
+                });
+            }
+            drop('stream-not-open');
+            return;
+        }
+        // A failed send retires the stream: the session under it may have
+        // been replaced (a reconnect, a relayed → direct upgrade), and a stream
+        // handle is fenced to the session it was opened on — every later send
+        // on it would fail too. The next send reopens on the current session.
+        const stream = player.stream;
+        const retire = (error) => {
+            lastError = String(error?.message ?? error);
+            drop('send-failed');
+            if (player.stream === stream) {
+                player.stream = null;
+                try {
+                    stream.close();
+                }
+                catch {
+                    // Already unusable.
+                }
+            }
+        };
+        try {
+            void Promise.resolve(stream.send(encodeFrame(frame))).catch(retire);
+        }
+        catch (error) {
+            retire(error);
+        }
+    };
+    const playerFor = (peer) => {
+        const existing = players.get(peer);
+        if (existing)
+            return existing;
+        if (options.authorize && !options.authorize(peer)) {
+            drop('unauthorized');
+            return null;
+        }
+        const player = {
+            stream: null,
+            opening: false,
+            lastApplied: 0,
+            pending: new Map(),
+            lastHeard: now(),
+            interest: null,
+            interestVersion: 0,
+        };
+        players.set(peer, player);
+        return player;
+    };
+    const stopEvents = options.transport.onEvent(event => {
+        if (closed || event.type !== 'stream_data')
+            return;
+        const frame = decodeFrame(event.payload, options.label);
+        if (frame === null)
+            return;
+        const peer = eventPeer(event.peerNode);
+        if (peer === null) {
+            drop('no-authenticated-peer');
+            return;
+        }
+        const player = playerFor(peer);
+        if (player === null)
+            return;
+        const t1 = now();
+        player.lastHeard = t1;
+        switch (frame.k) {
+            case 'h':
+                return;
+            case 'p':
+                send(peer, player, { n: options.label, k: 'q', t0: frame.t0, t1, t2: now() });
+                return;
+            case 'w':
+                // The lossy carrier reorders and repeats: only a newer version counts.
+                if (frame.v > player.interestVersion) {
+                    player.interestVersion = frame.v;
+                    player.interest = new Set(frame.w);
+                }
+                return;
+            case 'i':
+                for (const input of frame.i) {
+                    if (!Number.isInteger(input.seq) || input.seq <= player.lastApplied)
+                        continue;
+                    if (!player.pending.has(input.seq)) {
+                        player.pending.set(input.seq, { seq: input.seq, seen: Number(input.seen) || 0, data: input.data });
+                    }
+                }
+                return;
+            default:
+                drop('unexpected-frame');
+        }
+    });
+    const runTick = () => {
+        if (closed)
+            return;
+        const time = now();
+        const dtMs = tick === 0 ? tickMs : time - lastTickAt;
+        lastTickAt = time;
+        for (const [peer, player] of players) {
+            if (time - player.lastHeard > playerTimeoutMs) {
+                player.stream?.close();
+                players.delete(peer);
+            }
+        }
+        const inputs = new Map();
+        for (const [peer, player] of players) {
+            if (player.pending.size === 0)
+                continue;
+            const ordered = [...player.pending.values()].sort((a, b) => a.seq - b.seq);
+            player.pending.clear();
+            // A gap (inputs lost despite redundancy) is skipped, not waited on:
+            // a tick cannot stall for one player's packet.
+            player.lastApplied = ordered.at(-1).seq;
+            inputs.set(peer, ordered);
+        }
+        options.step({ tick, time, dtMs, inputs });
+        const entities = options.snapshot(tick);
+        history.push({ tick, time, entities });
+        if (history.length > keep)
+            history.shift();
+        for (const [peer, player] of players) {
+            let view = entities;
+            const wanted = options.interest && player.interest;
+            if (options.visible || wanted) {
+                const filtered = {};
+                for (const [id, entity] of Object.entries(entities)) {
+                    if (options.visible && !options.visible(peer, id, entity))
+                        continue;
+                    if (wanted) {
+                        let key;
+                        try {
+                            key = options.interest(id, entity);
+                        }
+                        catch {
+                            key = null;
+                        }
+                        if (typeof key === 'string' && !wanted.has(key))
+                            continue;
+                    }
+                    filtered[id] = entity;
+                }
+                view = filtered;
+            }
+            const frames = snapshotFrames(options.label, tick, time, player.lastApplied, view, maxFrameBytes, player.interestVersion);
+            for (const frame of frames)
+                send(peer, player, frame);
+        }
+        tick += 1;
+    };
+    const timer = options.autoTick === false ? null : setInterval(runTick, tickMs);
+    return {
+        players: () => [...players.keys()],
+        get currentTick() {
+            return tick;
+        },
+        tick: runTick,
+        rewind(seen) {
+            const floor = now() - maxRewindMs;
+            const clamped = seen < floor;
+            const time = clamped ? floor : seen;
+            // The newest recorded state at or before `time`.
+            let chosen = history[0];
+            for (const entry of history) {
+                if (entry.time <= time)
+                    chosen = entry;
+                else
+                    break;
+            }
+            return { entities: chosen?.entities ?? {}, time, clamped };
+        },
+        dropped,
+        get lastSendError() {
+            return lastError;
+        },
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            if (timer !== null)
+                clearInterval(timer);
+            stopEvents();
+            for (const player of players.values())
+                player.stream?.close();
+            players.clear();
+        },
+    };
+}

package/dist/netcode/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `@net-mesh/browser/netcode` — responsive movement over the lossy carrier
+ * (netcode model 2): an authoritative host tick loop with lag compensation,
+ * and on each player snapshot interpolation for others plus prediction and
+ * reconciliation for yourself.
+ *
+ * Use it beside the store, not instead of it: the store holds durable,
+ * validated state (inventory, score, doors); netcode carries high-rate
+ * transforms that are superseded many times a second.
+ */
+export { hostNetcode } from './host.js';
+export type { HostNetcode, HostNetcodeOptions, Rewound, TickContext, TickInput } from './host.js';
+export { joinNetcode } from './client.js';
+export type { JoinNetcodeOptions, LocalEntity, NetcodeClient, NetcodeStats } from './client.js';
+export { ClockEstimator, CLOCK_WINDOW } from './clock.js';
+export type { ClockEstimate, Millis } from './clock.js';
+export { SnapshotBuffer, lerpNumbers, SNAPSHOT_BUFFER } from './interpolate.js';
+export type { Interpolator, TimedSnapshot } from './interpolate.js';
+export type { NetcodeStream, NetcodeTransport } from './wire.js';

package/dist/netcode/index.js

@@ -0,0 +1,14 @@
+/**
+ * `@net-mesh/browser/netcode` — responsive movement over the lossy carrier
+ * (netcode model 2): an authoritative host tick loop with lag compensation,
+ * and on each player snapshot interpolation for others plus prediction and
+ * reconciliation for yourself.
+ *
+ * Use it beside the store, not instead of it: the store holds durable,
+ * validated state (inventory, score, doors); netcode carries high-rate
+ * transforms that are superseded many times a second.
+ */
+export { hostNetcode } from './host.js';
+export { joinNetcode } from './client.js';
+export { ClockEstimator, CLOCK_WINDOW } from './clock.js';
+export { SnapshotBuffer, lerpNumbers, SNAPSHOT_BUFFER } from './interpolate.js';

package/dist/netcode/interpolate.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Snapshot interpolation: render remote entities a little in the past,
+ * between two snapshots the host already sent, so lost and late packets
+ * do not make them stutter.
+ */
+/** A snapshot as the client keeps it. */
+export interface TimedSnapshot<E> {
+    /** Host clock, ms, when the host produced it. */
+    readonly time: number;
+    readonly tick: number;
+    readonly entities: Readonly<Record<string, E>>;
+}
+/**
+ * Blend two states of one entity; `alpha` is in `[0, 1]` — or above 1 when
+ * extrapolating past the newest snapshot (`extrapolateMs`), where `to` is
+ * carried on along the line from `from`.
+ */
+export type Interpolator<E> = (from: E, to: E, alpha: number) => E;
+/**
+ * The default blend: every numeric field is linearly interpolated, every
+ * other field is taken from `to`. Nested objects are blended the same way,
+ * one level at a time. Angles are not special-cased: a game with wrapping
+ * angles supplies its own.
+ */
+export declare function lerpNumbers<E>(from: E, to: E, alpha: number): E;
+/** Snapshots kept, at most. */
+export declare const SNAPSHOT_BUFFER = 64;
+/** A time-ordered buffer of snapshots with interpolated reads. */
+export declare class SnapshotBuffer<E> {
+    #private;
+    /**
+     * Add a snapshot. One older than the newest already held is still
+     * inserted in order (an unordered carrier reorders); one for a tick
+     * already held is ignored.
+     */
+    add(snapshot: TimedSnapshot<E>): void;
+    /** Snapshots that arrived after a newer one (reordered by the carrier). */
+    get late(): number;
+    /** The newest snapshot, or `null`. */
+    latest(): TimedSnapshot<E> | null;
+    /**
+     * The entities as of host time `at`: interpolated between the two
+     * snapshots around it. Before the oldest held, the oldest. Past the
+     * newest: held there, or — with `extrapolateMs` — carried on along the
+     * last two snapshots' line for at most that long, then held. An entity
+     * present only in the later snapshot appears as it is there; one gone
+     * from the later snapshot is gone.
+     */
+    at(time: number, blend: Interpolator<E>, extrapolateMs?: number): Readonly<Record<string, E>>;
+}

package/dist/netcode/interpolate.js

@@ -0,0 +1,100 @@
+/**
+ * Snapshot interpolation: render remote entities a little in the past,
+ * between two snapshots the host already sent, so lost and late packets
+ * do not make them stutter.
+ */
+/**
+ * The default blend: every numeric field is linearly interpolated, every
+ * other field is taken from `to`. Nested objects are blended the same way,
+ * one level at a time. Angles are not special-cased: a game with wrapping
+ * angles supplies its own.
+ */
+export function lerpNumbers(from, to, alpha) {
+    if (typeof from === 'number' && typeof to === 'number') {
+        return (from + (to - from) * alpha);
+    }
+    if (from === null || to === null || typeof from !== 'object' || typeof to !== 'object' || Array.isArray(to)) {
+        return to;
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(to)) {
+        const previous = from[key];
+        out[key] = previous === undefined ? value : lerpNumbers(previous, value, alpha);
+    }
+    return out;
+}
+/** Snapshots kept, at most. */
+export const SNAPSHOT_BUFFER = 64;
+/** A time-ordered buffer of snapshots with interpolated reads. */
+export class SnapshotBuffer {
+    #snapshots = [];
+    #late = 0;
+    /**
+     * Add a snapshot. One older than the newest already held is still
+     * inserted in order (an unordered carrier reorders); one for a tick
+     * already held is ignored.
+     */
+    add(snapshot) {
+        const list = this.#snapshots;
+        if (list.some(s => s.tick === snapshot.tick))
+            return;
+        let at = list.length;
+        while (at > 0 && list[at - 1].time > snapshot.time)
+            at -= 1;
+        if (at < list.length)
+            this.#late += 1;
+        list.splice(at, 0, snapshot);
+        if (list.length > SNAPSHOT_BUFFER)
+            list.shift();
+    }
+    /** Snapshots that arrived after a newer one (reordered by the carrier). */
+    get late() {
+        return this.#late;
+    }
+    /** The newest snapshot, or `null`. */
+    latest() {
+        return this.#snapshots.at(-1) ?? null;
+    }
+    /**
+     * The entities as of host time `at`: interpolated between the two
+     * snapshots around it. Before the oldest held, the oldest. Past the
+     * newest: held there, or — with `extrapolateMs` — carried on along the
+     * last two snapshots' line for at most that long, then held. An entity
+     * present only in the later snapshot appears as it is there; one gone
+     * from the later snapshot is gone.
+     */
+    at(time, blend, extrapolateMs = 0) {
+        const list = this.#snapshots;
+        if (list.length === 0)
+            return {};
+        if (time <= list[0].time)
+            return list[0].entities;
+        const last = list.at(-1);
+        if (time >= last.time) {
+            const before = list.at(-2);
+            if (extrapolateMs <= 0 || before === undefined || last.time === before.time || time === last.time) {
+                return last.entities;
+            }
+            const ahead = Math.min(time - last.time, extrapolateMs);
+            const alpha = 1 + ahead / (last.time - before.time);
+            const out = {};
+            for (const [id, to] of Object.entries(last.entities)) {
+                const from = before.entities[id];
+                out[id] = from === undefined ? to : blend(from, to, alpha);
+            }
+            return out;
+        }
+        let i = 1;
+        while (list[i].time < time)
+            i += 1;
+        const a = list[i - 1];
+        const b = list[i];
+        const alpha = b.time === a.time ? 1 : (time - a.time) / (b.time - a.time);
+        const out = {};
+        for (const [id, to] of Object.entries(b.entities)) {
+            const from = a.entities[id];
+            out[id] = from === undefined ? to : blend(from, to, alpha);
+        }
+        return out;
+    }
+}