@net-mesh/browser 0.43.0 → 0.44.0

package/dist/netcode/host.js

@@ -16,7 +16,18 @@
  * });
  * ```
  */
-import { MAX_SNAPSHOT_CHUNKS, chunkOf, defaultNow, decodeFrame, encodeFrame, eventPeer, } from './wire.js';
+import { MAX_SNAPSHOT_CHUNKS, NAME_FORGET_MS, chunkOf, defaultNow, decodeFrame, encodeFrame, eventPeer, } from './wire.js';
+import { encodeBinarySnapshot, nameBytes } from './codec.js';
+/** Departed players whose boundary is kept, at most (the oldest is forgotten first). */
+const MAX_PARKED = 4096;
+/**
+ * A name request (`u`) for an index named less than this long ago is not
+ * honoured: a player asks again on its next snapshot anyway, and a player
+ * spamming requests cannot make every tick carry every name.
+ */
+const NAME_RESEND_MS = 100;
+/** An input seq the host takes: a positive safe integer (seqs count from 1). */
+const isSeq = (seq) => Number.isSafeInteger(seq) && seq > 0;
 /** 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);
@@ -27,10 +38,13 @@ function historySize(tickRate, maxRewindMs) {
  * {@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) {
+export function snapshotFrames(label, tick, time, ack, entities, maxBytes, interestVersion = 0, epoch) {
     // The interest version the view was filtered by, echoed so the player
-    // stops repeating its `w` frame.
-    const iv = interestVersion > 0 ? { iv: interestVersion } : {};
+    // stops repeating its `w` frame; and the epoch, when the host has one.
+    const iv = {
+        ...(interestVersion > 0 ? { iv: interestVersion } : {}),
+        ...(epoch === undefined ? {} : { ep: epoch }),
+    };
     const whole = { n: label, k: 's', tick, t: time, ack, e: entities, ...iv };
     const size = encodeFrame(whole).length;
     if (size <= maxBytes)
@@ -59,6 +73,17 @@ export function hostNetcode(options) {
     const maxFrameBytes = Math.max(256, options.maxFrameBytes ?? 8000);
     const playerTimeoutMs = options.playerTimeoutMs ?? 5000;
     const players = new Map();
+    // Boundaries of players without a record: timed out, or adopted before
+    // `authorize` admits them. Restored when the player is next admitted.
+    const parked = new Map();
+    const park = (peer, state) => {
+        parked.delete(peer);
+        if (!(state.lastApplied > 0 || state.released || state.resuming))
+            return;
+        parked.set(peer, state);
+        if (parked.size > MAX_PARKED)
+            parked.delete(parked.keys().next().value);
+    };
     const history = [];
     const keep = historySize(tickRate, maxRewindMs);
     const dropped = {};
@@ -69,7 +94,8 @@ export function hostNetcode(options) {
     let lastError = null;
     let lastTickAt = now();
     let closed = false;
-    const send = (peer, player, frame) => {
+    const send = (peer, player, frame) => sendBytes(peer, player, encodeFrame(frame));
+    const sendBytes = (peer, player, payload) => {
         if (player.stream === null) {
             if (!player.opening) {
                 player.opening = true;
@@ -111,7 +137,7 @@ export function hostNetcode(options) {
             }
         };
         try {
-            void Promise.resolve(stream.send(encodeFrame(frame))).catch(retire);
+            void Promise.resolve(stream.send(payload)).catch(retire);
         }
         catch (error) {
             retire(error);
@@ -125,18 +151,124 @@ export function hostNetcode(options) {
             drop('unauthorized');
             return null;
         }
+        const restored = parked.get(peer);
+        parked.delete(peer);
         const player = {
             stream: null,
             opening: false,
-            lastApplied: 0,
+            lastApplied: restored?.lastApplied ?? 0,
             pending: new Map(),
             lastHeard: now(),
             interest: null,
             interestVersion: 0,
+            binary: false,
+            named: new Map(),
+            requested: new Set(),
+            released: restored?.released ?? false,
+            resuming: restored?.resuming ?? false,
         };
         players.set(peer, player);
         return player;
     };
+    // Binary ids: an index per entity id, in order of first appearance, never
+    // reused while this host runs — so a stale snapshot cannot name the wrong
+    // entity. An id no player has been shown for NAME_FORGET_MS is forgotten,
+    // and gets a fresh index if it comes back. Every frame carries this
+    // host's instance, so a player tells a re-created host's indexes from
+    // this one's.
+    const codec = options.codec;
+    const instance = Math.floor(Math.random() * 0x100000000) >>> 0;
+    const indexOf = new Map();
+    const names = new Map();
+    let nextIndex = 0;
+    const indexFor = (id, time) => {
+        let index = indexOf.get(id);
+        if (index === undefined) {
+            index = nextIndex;
+            nextIndex += 1;
+            indexOf.set(id, index);
+            names.set(index, { id, name: nameBytes(id), used: time });
+        }
+        else {
+            names.get(index).used = time;
+        }
+        return index;
+    };
+    // Forget names gone from every view for NAME_FORGET_MS, about once a second.
+    let lastForget = now();
+    const forgetNames = (time) => {
+        if (time - lastForget < 1000)
+            return;
+        lastForget = time;
+        for (const [index, entry] of names) {
+            if (time - entry.used > NAME_FORGET_MS) {
+                names.delete(index);
+                indexOf.delete(entry.id);
+            }
+        }
+        for (const player of players.values()) {
+            for (const [index, sent] of player.named) {
+                if (time - sent.shown > NAME_FORGET_MS || !names.has(index))
+                    player.named.delete(index);
+            }
+            for (const index of player.requested)
+                if (!player.named.has(index))
+                    player.requested.delete(index);
+        }
+    };
+    const noteFingerprint = (player, fingerprint) => {
+        if (codec !== undefined)
+            player.binary = fingerprint === codec.fingerprint;
+    };
+    /** One player's view as binary frames, chunked to fit; names it needs included. */
+    const binaryFrames = (player, tick, time, view, epoch) => {
+        const header = {
+            tick,
+            t: time,
+            ack: player.lastApplied,
+            instance,
+            ...(player.interestVersion > 0 ? { iv: player.interestVersion } : {}),
+            ...(epoch === undefined ? {} : { ep: epoch }),
+        };
+        const ids = Object.keys(view);
+        const named = (index) => player.named.has(index) && !player.requested.has(index);
+        const build = (of) => {
+            const parts = Array.from({ length: of }, () => ({ names: new Map(), entities: new Map() }));
+            for (const id of ids) {
+                const index = indexFor(id, time);
+                const part = parts[of === 1 ? 0 : chunkOf(id, of)];
+                part.entities.set(index, view[id]);
+                if (!named(index))
+                    part.names.set(index, names.get(index).name);
+            }
+            return parts.map((part, c) => encodeBinarySnapshot(options.label, of === 1 ? header : { ...header, c, of }, part.names, part.entities, codec));
+        };
+        let frames = build(1);
+        if (frames[0].length > maxFrameBytes) {
+            let of = Math.min(MAX_SNAPSHOT_CHUNKS, Math.max(2, Math.ceil(frames[0].length / (maxFrameBytes * 0.75))));
+            for (;;) {
+                frames = build(of);
+                if (of >= MAX_SNAPSHOT_CHUNKS || frames.every(frame => frame.length <= maxFrameBytes))
+                    break;
+                of = Math.min(MAX_SNAPSHOT_CHUNKS, of * 2);
+            }
+        }
+        // Built: their names count as sent. A lost one is asked for again.
+        for (const id of ids) {
+            const index = indexOf.get(id);
+            const sent = player.named.get(index);
+            if (sent === undefined) {
+                player.named.set(index, { shown: time, namedAt: time });
+            }
+            else {
+                if (player.requested.has(index))
+                    sent.namedAt = time;
+                sent.shown = time;
+            }
+            player.requested.delete(index);
+        }
+        return frames;
+    };
     const stopEvents = options.transport.onEvent(event => {
         if (closed || event.type !== 'stream_data')
             return;
@@ -155,10 +287,29 @@ export function hostNetcode(options) {
         player.lastHeard = t1;
         switch (frame.k) {
             case 'h':
+                noteFingerprint(player, frame.f);
                 return;
             case 'p':
+                noteFingerprint(player, frame.f);
                 send(peer, player, { n: options.label, k: 'q', t0: frame.t0, t1, t2: now() });
                 return;
+            case 'u': {
+                // Only indexes this player was shown, and not named again just
+                // now; anything else is noise or spam.
+                let throttled = false;
+                for (const index of frame.u) {
+                    const sent = player.named.get(index);
+                    if (sent === undefined)
+                        continue;
+                    if (t1 - sent.namedAt < NAME_RESEND_MS)
+                        throttled = true;
+                    else
+                        player.requested.add(index);
+                }
+                if (throttled)
+                    drop('name-request-throttled');
+                return;
+            }
             case 'w':
                 // The lossy carrier reorders and repeats: only a newer version counts.
                 if (frame.v > player.interestVersion) {
@@ -167,8 +318,26 @@ export function hostNetcode(options) {
                 }
                 return;
             case 'i':
+                if (options.epoch !== undefined && frame.ep !== undefined && frame.ep !== options.epoch()) {
+                    drop('stale-epoch');
+                    return;
+                }
+                if (player.released) {
+                    drop('released');
+                    return;
+                }
+                if (player.resuming) {
+                    player.resuming = false;
+                    let newest = player.lastApplied;
+                    for (const input of frame.i)
+                        if (isSeq(input.seq))
+                            newest = Math.max(newest, input.seq);
+                    player.lastApplied = newest;
+                    dropped['resumed'] = (dropped['resumed'] ?? 0) + frame.i.length;
+                    return;
+                }
                 for (const input of frame.i) {
-                    if (!Number.isInteger(input.seq) || input.seq <= player.lastApplied)
+                    if (!isSeq(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 });
@@ -185,12 +354,30 @@ export function hostNetcode(options) {
         const time = now();
         const dtMs = tick === 0 ? tickMs : time - lastTickAt;
         lastTickAt = time;
+        if (options.live !== undefined && !options.live()) {
+            for (const player of players.values()) {
+                if (player.pending.size > 0) {
+                    dropped['lease-lost'] = (dropped['lease-lost'] ?? 0) + player.pending.size;
+                    // Applied as if seen, so a repeat of these inputs is not applied later either.
+                    for (const seq of player.pending.keys())
+                        if (seq > player.lastApplied)
+                            player.lastApplied = seq;
+                    player.pending.clear();
+                }
+            }
+            return;
+        }
         for (const [peer, player] of players) {
             if (time - player.lastHeard > playerTimeoutMs) {
                 player.stream?.close();
                 players.delete(peer);
+                // The boundary outlives the record: a player that comes back (or an
+                // adoption still waiting for its first frame) carries on from it.
+                park(peer, { lastApplied: player.lastApplied, released: player.released, resuming: player.resuming });
             }
         }
+        if (codec !== undefined)
+            forgetNames(time);
         const inputs = new Map();
         for (const [peer, player] of players) {
             if (player.pending.size === 0)
@@ -204,6 +391,7 @@ export function hostNetcode(options) {
         }
         options.step({ tick, time, dtMs, inputs });
         const entities = options.snapshot(tick);
+        const epoch = options.epoch?.();
         history.push({ tick, time, entities });
         if (history.length > keep)
             history.shift();
@@ -230,7 +418,24 @@ export function hostNetcode(options) {
                 }
                 view = filtered;
             }
-            const frames = snapshotFrames(options.label, tick, time, player.lastApplied, view, maxFrameBytes, player.interestVersion);
+            if (codec !== undefined && player.binary) {
+                let binary = null;
+                try {
+                    binary = binaryFrames(player, tick, time, view, epoch);
+                }
+                catch (error) {
+                    // The codec refused an entity: this player gets JSON this tick,
+                    // not a snapshot missing a field.
+                    lastError = String(error?.message ?? error);
+                    drop('codec-write-failed');
+                }
+                if (binary !== null) {
+                    for (const payload of binary)
+                        sendBytes(peer, player, payload);
+                    continue;
+                }
+            }
+            const frames = snapshotFrames(options.label, tick, time, player.lastApplied, view, maxFrameBytes, player.interestVersion, epoch);
             for (const frame of frames)
                 send(peer, player, frame);
         }
@@ -239,6 +444,45 @@ export function hostNetcode(options) {
     const timer = options.autoTick === false ? null : setInterval(runTick, tickMs);
     return {
         players: () => [...players.keys()],
+        releasePlayer(peer) {
+            const player = players.get(peer);
+            if (player === undefined) {
+                // Timed out: its boundary was kept.
+                const kept = parked.get(peer);
+                if (kept === undefined)
+                    return { lastApplied: 0 };
+                kept.released = true;
+                kept.resuming = false;
+                return { lastApplied: kept.lastApplied };
+            }
+            // Received but not yet applied: not in the frozen state, so not
+            // acknowledged — the player still holds them, for the new owner.
+            player.pending.clear();
+            player.released = true;
+            return { lastApplied: player.lastApplied };
+        },
+        adoptPlayer(peer, from) {
+            const player = playerFor(peer);
+            if (player === null) {
+                // Not admitted now: keep the boundary for when it is.
+                drop('adopt-unauthorized');
+                const kept = parked.get(peer);
+                park(peer, 'resume' in from
+                    ? { lastApplied: kept?.lastApplied ?? 0, released: false, resuming: true }
+                    : { lastApplied: Math.max(kept?.lastApplied ?? 0, from.lastApplied), released: false, resuming: false });
+                return;
+            }
+            player.released = false;
+            if ('resume' in from) {
+                player.resuming = true;
+                player.pending.clear();
+                return;
+            }
+            player.lastApplied = Math.max(player.lastApplied, from.lastApplied);
+            for (const seq of [...player.pending.keys()])
+                if (seq <= player.lastApplied)
+                    player.pending.delete(seq);
+        },
         get currentTick() {
             return tick;
         },
@@ -271,6 +515,7 @@ export function hostNetcode(options) {
             for (const player of players.values())
                 player.stream?.close();
             players.clear();
+            parked.clear();
         },
     };
 }

package/dist/netcode/index.d.ts

@@ -10,13 +10,23 @@
  */
 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 { NetcodeError, createInputSequencer, joinNetcode } from './client.js';
+export type { InputSequencer, JoinNetcodeOptions, LocalEntity, NetcodeClient, NetcodeErrorKind, NetcodeStats } from './client.js';
+export { joinShards } from './shards.js';
+export { MAX_PATH_POINTS, npcModes, pathAction, pathAt, pathProblems } from './paths.js';
+export type { ModedEntity, NpcModes, NpcModesOptions, NpcPath, PathPoint } from './paths.js';
+export { assignAction, assignmentProblems, authorizeTeams, leaseWatch, mayReassign, npcShard, renewLeases, shardAssignment, teamOf, withNpcs, } from './assignment.js';
+export type { LeaseWatch, LeaseWatchOptions, MatchAssignment, ShardRecord, Squad } from './assignment.js';
+export type { JoinShardsOptions, ShardAssignment, ShardStats, ShardedMatch, ShardedMatchStats } from './shards.js';
 export { ClockEstimator, CLOCK_WINDOW } from './clock.js';
 export type { ClockEstimate, Millis } from './clock.js';
-export { SnapshotBuffer, lerpNumbers, SNAPSHOT_BUFFER } from './interpolate.js';
+export { SnapshotBuffer, lerpAngle, lerpNumbers, SNAPSHOT_BUFFER } from './interpolate.js';
 export type { Interpolator, TimedSnapshot } from './interpolate.js';
 export type { NetcodeStream, NetcodeTransport } from './wire.js';
+export { angle, bool, entityCodec, float32, int, quantized, uint } from './codec.js';
+export type { EntityCodec, FieldCodec } from './codec.js';
 export { snapshotFrames, } from './host.js';
-export { chunkOf, decodeFrame, defaultNow, encodeFrame, eventPeer, MAX_NETCODE_INTEREST_KEY_LENGTH, MAX_NETCODE_INTEREST_KEYS, MAX_SNAPSHOT_CHUNKS, peerHex, } from './wire.js';
+export { BINARY_FRAME_MAGIC, decodeBinarySnapshot, encodeBinarySnapshot, isBinaryFrame, labelHash, } from './codec.js';
+export type { BinarySnapshot } from './codec.js';
+export { MAX_NAME_REQUESTS, chunkOf, decodeFrame, defaultNow, encodeFrame, eventPeer, MAX_NETCODE_INTEREST_KEY_LENGTH, MAX_NETCODE_INTEREST_KEYS, MAX_SNAPSHOT_CHUNKS, peerHex, } from './wire.js';
 export type { Frame, Now, WireInput, } from './wire.js';

package/dist/netcode/index.js

@@ -9,10 +9,15 @@
  * transforms that are superseded many times a second.
  */
 export { hostNetcode } from './host.js';
-export { joinNetcode } from './client.js';
+export { NetcodeError, createInputSequencer, joinNetcode } from './client.js';
+export { joinShards } from './shards.js';
+export { MAX_PATH_POINTS, npcModes, pathAction, pathAt, pathProblems } from './paths.js';
+export { assignAction, assignmentProblems, authorizeTeams, leaseWatch, mayReassign, npcShard, renewLeases, shardAssignment, teamOf, withNpcs, } from './assignment.js';
 export { ClockEstimator, CLOCK_WINDOW } from './clock.js';
-export { SnapshotBuffer, lerpNumbers, SNAPSHOT_BUFFER } from './interpolate.js';
+export { SnapshotBuffer, lerpAngle, lerpNumbers, SNAPSHOT_BUFFER } from './interpolate.js';
+export { angle, bool, entityCodec, float32, int, quantized, uint } from './codec.js';
 // The netcode wire format and its helpers, exported so callers can
 // build their own transports and tooling on the same frames.
 export { snapshotFrames, } from './host.js';
-export { chunkOf, decodeFrame, defaultNow, encodeFrame, eventPeer, MAX_NETCODE_INTEREST_KEY_LENGTH, MAX_NETCODE_INTEREST_KEYS, MAX_SNAPSHOT_CHUNKS, peerHex, } from './wire.js';
+export { BINARY_FRAME_MAGIC, decodeBinarySnapshot, encodeBinarySnapshot, isBinaryFrame, labelHash, } from './codec.js';
+export { MAX_NAME_REQUESTS, chunkOf, decodeFrame, defaultNow, encodeFrame, eventPeer, MAX_NETCODE_INTEREST_KEY_LENGTH, MAX_NETCODE_INTEREST_KEYS, MAX_SNAPSHOT_CHUNKS, peerHex, } from './wire.js';

package/dist/netcode/interpolate.d.ts

@@ -20,9 +20,17 @@ 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.
+ * angles supplies its own (built on {@link lerpAngle}), or uses a codec,
+ * whose `interpolate` turns its `angle()` fields the short way.
  */
 export declare function lerpNumbers<E>(from: E, to: E, alpha: number): E;
+/**
+ * Blend two angles in radians the short way round: from 350° to 10° passes
+ * 0°, not 180°. `alpha` 1 gives `to` exactly, and above 1 carries on along
+ * the same short arc (extrapolation). The result is not normalized: it is
+ * within half a turn of `to`, on `to`'s side of any wrap.
+ */
+export declare function lerpAngle(from: number, to: number, alpha: number): number;
 /** Snapshots kept, at most. */
 export declare const SNAPSHOT_BUFFER = 64;
 /** A time-ordered buffer of snapshots with interpolated reads. */
@@ -38,6 +46,21 @@ export declare class SnapshotBuffer<E> {
     get late(): number;
     /** The newest snapshot, or `null`. */
     latest(): TimedSnapshot<E> | null;
+    /**
+     * History, not rendering: the entities as of host time `time`, from the
+     * two snapshots that bracket it, and how far apart those two were. `null`
+     * when no two held snapshots bracket `time` — before the oldest, after
+     * the newest — so a caller checking a claim against history can tell "no
+     * history" from "this is where it was". Never extrapolates.
+     *
+     * `gapMs` is the evidence's resolution: one snapshot interval normally,
+     * more where snapshots were lost. A caller sets its tolerance from it, or
+     * refuses a gap too wide to judge.
+     */
+    sample(time: number, blend: Interpolator<E>): {
+        readonly entities: Readonly<Record<string, E>>;
+        readonly gapMs: number;
+    } | null;
     /**
      * The entities as of host time `at`: interpolated between the two
      * snapshots around it. Before the oldest held, the oldest. Past the

package/dist/netcode/interpolate.js

@@ -7,7 +7,8 @@
  * 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.
+ * angles supplies its own (built on {@link lerpAngle}), or uses a codec,
+ * whose `interpolate` turns its `angle()` fields the short way.
  */
 export function lerpNumbers(from, to, alpha) {
     if (typeof from === 'number' && typeof to === 'number') {
@@ -23,6 +24,18 @@ export function lerpNumbers(from, to, alpha) {
     }
     return out;
 }
+const TURN = Math.PI * 2;
+/**
+ * Blend two angles in radians the short way round: from 350° to 10° passes
+ * 0°, not 180°. `alpha` 1 gives `to` exactly, and above 1 carries on along
+ * the same short arc (extrapolation). The result is not normalized: it is
+ * within half a turn of `to`, on `to`'s side of any wrap.
+ */
+export function lerpAngle(from, to, alpha) {
+    // The signed difference from `to` back to `from`, in [-π, π).
+    const back = ((((from - to) % TURN) + TURN + Math.PI) % TURN) - Math.PI;
+    return to + back * (1 - alpha);
+}
 /** Snapshots kept, at most. */
 export const SNAPSHOT_BUFFER = 64;
 /** A time-ordered buffer of snapshots with interpolated reads. */
@@ -55,6 +68,44 @@ export class SnapshotBuffer {
     latest() {
         return this.#snapshots.at(-1) ?? null;
     }
+    /**
+     * History, not rendering: the entities as of host time `time`, from the
+     * two snapshots that bracket it, and how far apart those two were. `null`
+     * when no two held snapshots bracket `time` — before the oldest, after
+     * the newest — so a caller checking a claim against history can tell "no
+     * history" from "this is where it was". Never extrapolates.
+     *
+     * `gapMs` is the evidence's resolution: one snapshot interval normally,
+     * more where snapshots were lost. A caller sets its tolerance from it, or
+     * refuses a gap too wide to judge.
+     */
+    sample(time, blend) {
+        const list = this.#snapshots;
+        if (list.length === 0 || time < list[0].time || time > list.at(-1).time)
+            return null;
+        if (list.length === 1)
+            return { entities: list[0].entities, gapMs: 0 };
+        let i = 1;
+        while (i < list.length - 1 && list[i].time < time)
+            i += 1;
+        const a = list[i - 1];
+        const b = list[i];
+        // Exactly at a snapshot: that snapshot is the evidence, whole, an
+        // entity that first appears in it included.
+        if (b.time === time)
+            return { entities: b.entities, gapMs: b.time - a.time };
+        if (a.time === time)
+            return { entities: a.entities, gapMs: b.time - a.time };
+        const alpha = (time - a.time) / (b.time - a.time);
+        const out = {};
+        for (const [id, to] of Object.entries(b.entities)) {
+            const from = a.entities[id];
+            // In only one of the two: known at one end of the gap, not across it.
+            if (from !== undefined)
+                out[id] = blend(from, to, alpha);
+        }
+        return { entities: out, gapMs: b.time - a.time };
+    }
     /**
      * The entities as of host time `at`: interpolated between the two
      * snapshots around it. Before the oldest held, the oldest. Past the

package/dist/netcode/paths.d.ts

@@ -0,0 +1,115 @@
+/**
+ * NPCs driven by paths in the store (sharded-match plan, slice N2): an NPC
+ * on a known route is published once as a path record, instead of in every
+ * snapshot, and every client evaluates the path itself.
+ *
+ * Two sources, then, for one NPC: snapshots (live, lossy, every tick while
+ * live) and the store's path record (reliable, written on a switch). They
+ * can arrive in either order, so each carries a **mode version** `mv` that
+ * the owner bumps on every switch between `'path'` and `'live'`:
+ *
+ * - the client draws from **whichever source shows the highest `mv`**;
+ * - if that says `'path'` and the record has not arrived yet, the last live
+ *   motion is carried forward for at most `carryMs` (500), then held;
+ * - a switch of source blends over `smoothingMs` (100), so it never jumps;
+ * - an NPC whose highest `mv` says `'live'` but that no snapshot shows any
+ *   more (dead, or out of interest) is held for `carryMs`, then no longer
+ *   drawn — which is how a retired path record (`'live'`, no points)
+ *   clears it.
+ *
+ * ```ts
+ * const modes = npcModes<Npc>();
+ * renderLoop(() => draw(modes.resolve(match.view(), lobbyReplica.getState().paths, id => match.hostNow(ownerOf(id)))));
+ * ```
+ *
+ * An NPC whose position is secret (fog) never uses a path: a record goes to
+ * every reader of the store. The shard host recipe refuses to put such an
+ * NPC on a path.
+ */
+import type { MatchAssignment } from './assignment.js';
+/** One waypoint, in the owner host's clock. */
+export interface PathPoint {
+    readonly t: number;
+    readonly x: number;
+    readonly z: number;
+}
+/** An NPC's path record, as the lobby store holds it (D8). */
+export interface NpcPath {
+    /** The mode version: bumped by the owner on every switch. */
+    readonly mv: number;
+    readonly mode: 'path' | 'live';
+    /** The interest key the record is found under (`null`: everyone). */
+    readonly key: string | null;
+    /** Waypoints by owner host time, ascending; empty while `live`. */
+    readonly points: readonly PathPoint[];
+}
+/** Waypoints one record may carry. */
+export declare const MAX_PATH_POINTS = 64;
+/** What an NPC entity carries so a client can order its two sources. */
+export interface ModedEntity {
+    readonly x: number;
+    readonly z: number;
+    readonly mv?: number;
+    readonly mode?: 'path' | 'live';
+}
+/** Where a path puts its NPC at owner host time `t`: interpolated, held before the first point and after the last. */
+export declare function pathAt(points: readonly PathPoint[], t: number): {
+    readonly x: number;
+    readonly z: number;
+} | null;
+/** What is wrong with a path record; empty when it is valid. */
+export declare function pathProblems(path: NpcPath): string[];
+/**
+ * The lobby store's `setPath` action (D8): record `path` for `npc`. Refused
+ * (the action rejects, the state is unchanged) unless the caller hosts the
+ * shard that owns `npc` in the installed assignment, the record is valid,
+ * and its `mv` is above the one held.
+ */
+export declare function pathAction<S extends object>(options: {
+    /** The installed assignment, read from the state. */
+    readonly assignment: (state: S) => MatchAssignment | null | undefined;
+    /** Where the records live in the state. Default `paths`. */
+    readonly field?: string;
+}): (input: {
+    readonly npc: string;
+    readonly path: NpcPath;
+}, context: {
+    readonly peer: string;
+    getState(): unknown;
+    setState(update: Partial<S>): void;
+}) => {
+    readonly mv: number;
+};
+/** {@link npcModes}'s argument. */
+export interface NpcModesOptions {
+    /** How long a switch of source blends, ms. Default 100. */
+    readonly smoothingMs?: number;
+    /** How long to carry the last live motion forward while a path record is late, ms. Default 500. */
+    readonly carryMs?: number;
+    /** How far behind the owner's clock paths are drawn, ms — match `interpolationDelayMs`. Default 100. */
+    readonly interpolationDelayMs?: number;
+    readonly now?: () => number;
+}
+/** The running resolver. */
+export interface NpcModes<E extends ModedEntity> {
+    /**
+     * The world to draw: `view` (from `joinShards` / `joinNetcode`) with every
+     * NPC that has a mode version resolved between its snapshot entry and its
+     * path record. `ownerNow(id)` is the owning host's clock (`hostNow`).
+     */
+    resolve(view: Readonly<Record<string, E>>, records: Readonly<Record<string, NpcPath>> | null | undefined, ownerNow: (id: string) => number | null): Readonly<Record<string, E>>;
+    /**
+     * `carried`: times a path was due but its record had not arrived (carried
+     * forward, then held). Not counted while the record is here and only the
+     * owner's clock is unknown: that is held, not carried. `tracks`: NPCs
+     * being followed (pruned once absent from both sources for longer than
+     * `carryMs + smoothingMs`).
+     */
+    readonly stats: () => {
+        readonly carried: number;
+        readonly switches: number;
+        readonly tracks: number;
+    };
+}
+/** Resolve NPCs between their snapshot entries and their path records. */
+export declare function npcModes<E extends ModedEntity>(options?: NpcModesOptions): NpcModes<E>;