@woosh/meep-engine 3.30.0 → 3.32.0

package/src/engine/network/state/PredictionHistory.js

@@ -0,0 +1,145 @@
+import { assert } from "../../../core/assert.js";
+
+/**
+ * One frame of one entity: its replicated components' wire bytes, by replication type id.
+ */
+class HistorySlot {
+    /** @type {number} frame this slot holds, -1 when empty */
+    frame = -1;
+    /** @type {Array<Uint8Array|null>} */
+    bytes = [];
+    /** @type {number[]} */
+    lengths = [];
+}
+
+/**
+ * What a client predicted, per entity, per frame: each replicated component's wire bytes as the
+ * client's simulation left it at the end of the frame.
+ *
+ * Reconciliation compares an authoritative state for frame S with the prediction for S — not with
+ * the present, which is further on. Kept as wire bytes, encoded by the same replication adapter as
+ * the authoritative state, so "the prediction was right" compares like for like, quantisation
+ * included.
+ *
+ * A fixed ring of frames per entity; a frame older than the ring is gone.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class PredictionHistory {
+    /**
+     * @type {Map<number, HistorySlot[]>}
+     */
+    #entities = new Map();
+
+    /**
+     * @param {number} [capacity] frames kept per entity — comfortably more than a round trip
+     */
+    constructor(capacity = 128) {
+        assert.isPositiveInteger(capacity, 'capacity');
+
+        /** @readonly @type {number} */
+        this.capacity = capacity;
+    }
+
+    /**
+     * @param {number} entity
+     * @param {number} frame
+     * @returns {HistorySlot}
+     */
+    #slot(entity, frame) {
+        let ring = this.#entities.get(entity);
+        if (ring === undefined) {
+            ring = [];
+            for (let i = 0; i < this.capacity; i++) ring.push(new HistorySlot());
+            this.#entities.set(entity, ring);
+        }
+        return ring[frame % this.capacity];
+    }
+
+    /**
+     * Store `length` bytes of `source` as `entity`'s component `type_id` at `frame`. Recording a
+     * frame the slot does not hold yet starts that frame afresh.
+     *
+     * @param {number} entity
+     * @param {number} frame
+     * @param {number} type_id
+     * @param {Uint8Array} source
+     * @param {number} length
+     */
+    record(entity, frame, type_id, source, length) {
+        assert.isNonNegativeInteger(frame, 'frame');
+
+        const slot = this.#slot(entity, frame);
+
+        if (slot.frame !== frame) {
+            slot.frame = frame;
+            for (let i = 0; i < slot.lengths.length; i++) slot.lengths[i] = -1;
+        }
+
+        while (slot.bytes.length <= type_id) {
+            slot.bytes.push(null);
+            slot.lengths.push(-1);
+        }
+
+        let target = slot.bytes[type_id];
+        if (target === null || target.length < length) {
+            target = new Uint8Array(Math.max(length, 32));
+            slot.bytes[type_id] = target;
+        }
+        target.set(source.subarray(0, length), 0);
+        slot.lengths[type_id] = length;
+    }
+
+    /**
+     * @param {number} entity
+     * @param {number} frame
+     * @param {number} type_id
+     * @returns {boolean}
+     */
+    has(entity, frame, type_id) {
+        return this.length(entity, frame, type_id) >= 0;
+    }
+
+    /**
+     * How many bytes are held for `entity`'s component `type_id` at `frame`; -1 when none are.
+     *
+     * @param {number} entity
+     * @param {number} frame
+     * @param {number} type_id
+     * @returns {number}
+     */
+    length(entity, frame, type_id) {
+        const ring = this.#entities.get(entity);
+        if (ring === undefined) return -1;
+        const slot = ring[frame % this.capacity];
+        if (slot.frame !== frame || type_id >= slot.lengths.length) return -1;
+        return slot.lengths[type_id];
+    }
+
+    /**
+     * The bytes held for `entity`'s component `type_id` at `frame` — the first
+     * {@link length} of them — or null. The array is the history's own, and a later
+     * {@link record} of the same slot writes into it: read it, do not keep it.
+     *
+     * @param {number} entity
+     * @param {number} frame
+     * @param {number} type_id
+     * @returns {Uint8Array|null}
+     */
+    bytes(entity, frame, type_id) {
+        if (this.length(entity, frame, type_id) < 0) return null;
+        return this.#entities.get(entity)[frame % this.capacity].bytes[type_id];
+    }
+
+    /**
+     * @param {number} entity
+     */
+    forget(entity) {
+        this.#entities.delete(entity);
+    }
+
+    clear() {
+        this.#entities.clear();
+    }
+}

package/src/engine/network/time/RenderPlayout.d.ts

@@ -56,7 +56,8 @@ export class RenderPlayout {
     /**
      * Advance the playhead to `now_ms` and return the frames to blend. `tick_b` may not have
      * arrived (the playhead sits on `latest_frame`): the log's `interpolate` snaps to the frame it
-     * has. Before the first arrival the window is `(0, 0, 0)`.
+     * has. Until a whole delay's worth of frames has arrived the window is `(0, 0, 0)` and the
+     * playhead has not started; it then starts the full delay behind the latest frame.
      *
      * @param {number} now_ms wall clock
      * @returns {{tick_a:number, tick_b:number, t:number}} a reused object — read it, do not keep it

package/src/engine/network/time/RenderPlayout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RenderPlayout.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/time/RenderPlayout.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;GAeG;AACH;IAsBI;;;;;;OAMG;IACH,oDANW;QACV,cAAkB,EAAE,MAAM,CAAC;QAC3B,KAAS,CAAC,EAAE,mBAAmB,CAAC;QAChC,WAAe,CAAC,EAAE,MAAM,CAAA;KACrB,EAWH;IArCD,+BAA+B;IAC/B,yBADqB,MAAM,CACZ;IAEf,4CAA4C;IAC5C,gBADqB,mBAAmB,CAClC;IAEN,+BAA+B;IAC/B,sBADqB,MAAM,CACf;IAEZ,wEAAwE;IACxE,cADW,MAAM,CACC;IA6BlB;;;;;;;OAOG;IACH,uBAJW,MAAM,gBACN,MAAM,GACJ,OAAO,CAWnB;IAED;;OAEG;IACH,0BAEC;IAED;;;OAGG;IACH,uBAEC;IAED;;;;;;;OAOG;IACH,eAHW,MAAM,GACJ;QAAC,MAAM,EAAC,MAAM,CAAC;QAAC,MAAM,EAAC,MAAM,CAAC;QAAC,CAAC,EAAC,MAAM,CAAA;KAAC,CA4CpD;IAED;;OAEG;IACH,cAKC;;CACJ;oCAjKmC,0BAA0B"}
+{"version":3,"file":"RenderPlayout.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/time/RenderPlayout.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;GAeG;AACH;IAsBI;;;;;;OAMG;IACH,oDANW;QACV,cAAkB,EAAE,MAAM,CAAC;QAC3B,KAAS,CAAC,EAAE,mBAAmB,CAAC;QAChC,WAAe,CAAC,EAAE,MAAM,CAAA;KACrB,EAWH;IArCD,+BAA+B;IAC/B,yBADqB,MAAM,CACZ;IAEf,4CAA4C;IAC5C,gBADqB,mBAAmB,CAClC;IAEN,+BAA+B;IAC/B,sBADqB,MAAM,CACf;IAEZ,wEAAwE;IACxE,cADW,MAAM,CACC;IA6BlB;;;;;;;OAOG;IACH,uBAJW,MAAM,gBACN,MAAM,GACJ,OAAO,CAWnB;IAED;;OAEG;IACH,0BAEC;IAED;;;OAGG;IACH,uBAEC;IAED;;;;;;;;OAQG;IACH,eAHW,MAAM,GACJ;QAAC,MAAM,EAAC,MAAM,CAAC;QAAC,MAAM,EAAC,MAAM,CAAC;QAAC,CAAC,EAAC,MAAM,CAAA;KAAC,CAsDpD;IAED;;OAEG;IACH,cAKC;;CACJ;oCA5KmC,0BAA0B"}

package/src/engine/network/time/RenderPlayout.js

@@ -1,163 +1,174 @@
-import { assert } from "../../../core/assert.js";
-import { AdaptiveRenderDelay } from "./AdaptiveRenderDelay.js";
-
-/**
- * Wall-clock low-pass on the render frame state machine: how hard the smoothed playhead is
- * pulled toward its target per millisecond. Small, so a jump in the target (the delay widening
- * after a jitter spike, a burst of late frames) is absorbed over ~2 s instead of a visible skip.
- * @type {number}
- */
-const PULL_PER_MS = 0.0005;
-
-/**
- * The render-delayed playhead over a sender's fixed-period frame stream — the piece of snapshot
- * interpolation that decides *which two frames to blend and by how much* on each render.
- *
- * Owns an {@link AdaptiveRenderDelay} (or is given one). Feed it every arriving frame with
- * {@link record_arrival}; ask it for the {@link window} once per render. The playhead advances
- * with wall time, is pulled toward `latest_frame - delay` by a low-pass so changes in the delay
- * never skip, and is clamped to `[0, latest_frame]` so the blend never extrapolates past what has
- * arrived. Extracted from `NetworkSession` so any fixed-period stream — a peer's netcode frames, a
- * remote editor's presence samples — plays out the same way.
- *
- * No allocation per call: {@link window} fills and returns one reused object.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class RenderPlayout {
-    /** @readonly @type {number} */
-    tick_period_ms;
-
-    /** @readonly @type {AdaptiveRenderDelay} */
-    delay;
-
-    /** @readonly @type {number} */
-    pull_per_ms;
-
-    /** @type {number} highest frame number recorded; -1 before the first */
-    latest_frame = -1;
-
-    /** @private @type {number} smoothed playhead in frames; -1 until the first window */
-    #smooth_frame = -1;
-
-    /** @private @type {number} */
-    #last_wall_ms = -1;
-
-    /** @private @type {{tick_a:number, tick_b:number, t:number}} */
-    #window = { tick_a: 0, tick_b: 0, t: 0 };
-
-    /**
-     * @param {{
-     *   tick_period_ms: number,
-     *   delay?: AdaptiveRenderDelay,
-     *   pull_per_ms?: number
-     * }} options `tick_period_ms` MUST be the sender's real period (see {@link AdaptiveRenderDelay})
-     */
-    constructor({ tick_period_ms, delay = undefined, pull_per_ms = PULL_PER_MS }) {
-        assert.isNumber(tick_period_ms, 'tick_period_ms');
-        assert.ok(tick_period_ms > 0, 'tick_period_ms must be > 0');
-        assert.isNumber(pull_per_ms, 'pull_per_ms');
-        assert.ok(pull_per_ms >= 0, 'pull_per_ms must be >= 0');
-
-        this.tick_period_ms = tick_period_ms;
-        this.delay = delay === undefined ? new AdaptiveRenderDelay({ tick_period_ms }) : delay;
-        this.pull_per_ms = pull_per_ms;
-    }
-
-    /**
-     * A frame from the sender has been applied locally. Frames at or below the latest are
-     * accepted data (a reordered or retransmitted frame) but do not move the head.
-     *
-     * @param {number} now_ms wall clock
-     * @param {number} frame_number the sender's frame index
-     * @returns {boolean} true when this frame advanced the head
-     */
-    record_arrival(now_ms, frame_number) {
-        if (frame_number <= this.latest_frame) {
-            return false;
-        }
-
-        this.delay.record_arrival(now_ms, frame_number);
-        this.latest_frame = frame_number;
-
-        return true;
-    }
-
-    /**
-     * @returns {boolean} whether anything has arrived yet
-     */
-    get has_frames() {
-        return this.latest_frame >= 0;
-    }
-
-    /**
-     * The smoothed playhead in frames after the last {@link window} call (or -1).
-     * @returns {number}
-     */
-    get playhead() {
-        return this.#smooth_frame;
-    }
-
-    /**
-     * Advance the playhead to `now_ms` and return the frames to blend. `tick_b` may not have
-     * arrived (the playhead sits on `latest_frame`): the log's `interpolate` snaps to the frame it
-     * has. Before the first arrival the window is `(0, 0, 0)`.
-     *
-     * @param {number} now_ms wall clock
-     * @returns {{tick_a:number, tick_b:number, t:number}} a reused object — read it, do not keep it
-     */
-    window(now_ms) {
-        const w = this.#window;
-        const latest = this.latest_frame;
-
-        if (latest < 0) {
-            w.tick_a = 0;
-            w.tick_b = 0;
-            w.t = 0;
-            return w;
-        }
-
-        const period = this.tick_period_ms;
-        const target = latest - this.delay.delay_ms() / period;
-        let frame = this.#smooth_frame;
-
-        if (frame < 0) {
-            frame = target < 0 ? 0 : target;
-        } else {
-            const dt_ms = now_ms - this.#last_wall_ms;
-            frame += dt_ms / period;
-            const alpha = 1 - Math.exp(-this.pull_per_ms * dt_ms);
-            frame += (target - frame) * alpha;
-        }
-
-        this.#last_wall_ms = now_ms;
-
-        if (frame > latest) {
-            frame = latest;
-        }
-
-        if (frame < 0) {
-            frame = 0;
-        }
-
-        this.#smooth_frame = frame;
-
-        const tick_a = Math.floor(frame);
-        w.tick_a = tick_a;
-        w.tick_b = tick_a + 1;
-        w.t = frame - tick_a;
-
-        return w;
-    }
-
-    /**
-     * Forget the stream (a reconnect, a new sender).
-     */
-    reset() {
-        this.latest_frame = -1;
-        this.#smooth_frame = -1;
-        this.#last_wall_ms = -1;
-        this.delay.reset();
-    }
-}
+import { assert } from "../../../core/assert.js";
+import { AdaptiveRenderDelay } from "./AdaptiveRenderDelay.js";
+
+/**
+ * Wall-clock low-pass on the render frame state machine: how hard the smoothed playhead is
+ * pulled toward its target per millisecond. Small, so a jump in the target (the delay widening
+ * after a jitter spike, a burst of late frames) is absorbed over ~2 s instead of a visible skip.
+ * @type {number}
+ */
+const PULL_PER_MS = 0.0005;
+
+/**
+ * The render-delayed playhead over a sender's fixed-period frame stream — the piece of snapshot
+ * interpolation that decides *which two frames to blend and by how much* on each render.
+ *
+ * Owns an {@link AdaptiveRenderDelay} (or is given one). Feed it every arriving frame with
+ * {@link record_arrival}; ask it for the {@link window} once per render. The playhead advances
+ * with wall time, is pulled toward `latest_frame - delay` by a low-pass so changes in the delay
+ * never skip, and is clamped to `[0, latest_frame]` so the blend never extrapolates past what has
+ * arrived. Extracted from `NetworkSession` so any fixed-period stream — a peer's netcode frames, a
+ * remote editor's presence samples — plays out the same way.
+ *
+ * No allocation per call: {@link window} fills and returns one reused object.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class RenderPlayout {
+    /** @readonly @type {number} */
+    tick_period_ms;
+
+    /** @readonly @type {AdaptiveRenderDelay} */
+    delay;
+
+    /** @readonly @type {number} */
+    pull_per_ms;
+
+    /** @type {number} highest frame number recorded; -1 before the first */
+    latest_frame = -1;
+
+    /** @private @type {number} smoothed playhead in frames; -1 until the first window */
+    #smooth_frame = -1;
+
+    /** @private @type {number} */
+    #last_wall_ms = -1;
+
+    /** @private @type {{tick_a:number, tick_b:number, t:number}} */
+    #window = { tick_a: 0, tick_b: 0, t: 0 };
+
+    /**
+     * @param {{
+     *   tick_period_ms: number,
+     *   delay?: AdaptiveRenderDelay,
+     *   pull_per_ms?: number
+     * }} options `tick_period_ms` MUST be the sender's real period (see {@link AdaptiveRenderDelay})
+     */
+    constructor({ tick_period_ms, delay = undefined, pull_per_ms = PULL_PER_MS }) {
+        assert.isNumber(tick_period_ms, 'tick_period_ms');
+        assert.ok(tick_period_ms > 0, 'tick_period_ms must be > 0');
+        assert.isNumber(pull_per_ms, 'pull_per_ms');
+        assert.ok(pull_per_ms >= 0, 'pull_per_ms must be >= 0');
+
+        this.tick_period_ms = tick_period_ms;
+        this.delay = delay === undefined ? new AdaptiveRenderDelay({ tick_period_ms }) : delay;
+        this.pull_per_ms = pull_per_ms;
+    }
+
+    /**
+     * A frame from the sender has been applied locally. Frames at or below the latest are
+     * accepted data (a reordered or retransmitted frame) but do not move the head.
+     *
+     * @param {number} now_ms wall clock
+     * @param {number} frame_number the sender's frame index
+     * @returns {boolean} true when this frame advanced the head
+     */
+    record_arrival(now_ms, frame_number) {
+        if (frame_number <= this.latest_frame) {
+            return false;
+        }
+
+        this.delay.record_arrival(now_ms, frame_number);
+        this.latest_frame = frame_number;
+
+        return true;
+    }
+
+    /**
+     * @returns {boolean} whether anything has arrived yet
+     */
+    get has_frames() {
+        return this.latest_frame >= 0;
+    }
+
+    /**
+     * The smoothed playhead in frames after the last {@link window} call (or -1).
+     * @returns {number}
+     */
+    get playhead() {
+        return this.#smooth_frame;
+    }
+
+    /**
+     * Advance the playhead to `now_ms` and return the frames to blend. `tick_b` may not have
+     * arrived (the playhead sits on `latest_frame`): the log's `interpolate` snaps to the frame it
+     * has. Until a whole delay's worth of frames has arrived the window is `(0, 0, 0)` and the
+     * playhead has not started; it then starts the full delay behind the latest frame.
+     *
+     * @param {number} now_ms wall clock
+     * @returns {{tick_a:number, tick_b:number, t:number}} a reused object — read it, do not keep it
+     */
+    window(now_ms) {
+        const w = this.#window;
+        const latest = this.latest_frame;
+
+        if (latest < 0) {
+            w.tick_a = 0;
+            w.tick_b = 0;
+            w.t = 0;
+            return w;
+        }
+
+        const period = this.tick_period_ms;
+        const target = latest - this.delay.delay_ms() / period;
+        let frame = this.#smooth_frame;
+
+        if (frame < 0) {
+            if (target < 0) {
+                // Less has arrived than one whole delay. Wait at the start rather than set off
+                // with a shorter lag than the delay asks for: the pull toward the target is slow on
+                // purpose, so a head started one frame behind the stream stays nearly that close
+                // for seconds, and every frame that arrives late in that time is a stall.
+                w.tick_a = 0;
+                w.tick_b = 0;
+                w.t = 0;
+                return w;
+            }
+            frame = target;
+        } else {
+            const dt_ms = now_ms - this.#last_wall_ms;
+            frame += dt_ms / period;
+            const alpha = 1 - Math.exp(-this.pull_per_ms * dt_ms);
+            frame += (target - frame) * alpha;
+        }
+
+        this.#last_wall_ms = now_ms;
+
+        if (frame > latest) {
+            frame = latest;
+        }
+
+        if (frame < 0) {
+            frame = 0;
+        }
+
+        this.#smooth_frame = frame;
+
+        const tick_a = Math.floor(frame);
+        w.tick_a = tick_a;
+        w.tick_b = tick_a + 1;
+        w.t = frame - tick_a;
+
+        return w;
+    }
+
+    /**
+     * Forget the stream (a reconnect, a new sender).
+     */
+    reset() {
+        this.latest_frame = -1;
+        this.#smooth_frame = -1;
+        this.#last_wall_ms = -1;
+        this.delay.reset();
+    }
+}

package/src/engine/network/transport/DeferredTransport.d.ts

@@ -0,0 +1,57 @@
+/**
+ * A transport that holds what its underlying transport raises — packets, and a lost connection —
+ * until {@link flush}, instead of passing it on the moment it happens.
+ *
+ * A browser transport raises a packet from its own event callback, whenever the event loop gets
+ * to it. In a running game that is usually after the engine has blended a frame's poses into the
+ * live components and before that frame is drawn, and whatever the packet writes there is written
+ * over what is about to be drawn, and over what the next step will simulate from. Holding packets
+ * until a point the simulation chooses — the start of a fixed step — makes every network write
+ * land where simulation writes land.
+ *
+ * Order is kept: packets are delivered in the order they arrived, and a lost connection is
+ * reported after the packets that arrived before it (a host's parting DISCONNECT is read before
+ * its socket closes). Nothing that arrives after a lost connection is delivered.
+ *
+ * Sending, connecting, disconnecting and stats are the underlying transport's.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class DeferredTransport extends Transport {
+    /**
+     * @param {Transport} inner
+     */
+    constructor(inner: Transport);
+    /**
+     * Packets the underlying transport has raised, delivered or not: how much the other end has
+     * sent, for telling a live connection from a silent one.
+     * @type {number}
+     */
+    received_count: number;
+    /**
+     * @returns {Transport}
+     */
+    get inner(): Transport;
+    /**
+     * Deliver everything held: each packet on {@link onReceive}, oldest first, then a lost
+     * connection on {@link onDisconnect}. A packet that arrives while delivering is delivered in
+     * the same call.
+     *
+     * A handler may flush again: `NetworkSession.connect()` does, when an application calls it
+     * from inside the delivery of the very peer it rebinds. Each packet leaves the queue before it
+     * is delivered, so the inner call goes on from the next one and returns with the rest
+     * delivered, lost connection included, and the outer call finds nothing left: nothing is
+     * delivered twice or out of order.
+     */
+    flush(): void;
+    /**
+     * Stop listening to the underlying transport and drop whatever is held. The underlying
+     * transport itself is left as it is.
+     */
+    release(): void;
+    send(bytes: any, length: any): void;
+    #private;
+}
+import { Transport } from "./Transport.js";
+//# sourceMappingURL=DeferredTransport.d.ts.map

package/src/engine/network/transport/DeferredTransport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeferredTransport.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/transport/DeferredTransport.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IA6BI;;OAEG;IACH,mBAFW,SAAS,EA4BnB;IApCD;;;;OAIG;IACH,gBAFU,MAAM,CAEG;IAiCnB;;OAEG;IACH,uBAEC;IAED;;;;;;;;;;OAUG;IACH,cAWC;IAED;;;OAGG;IACH,gBAIC;IAED,oCAEC;;CAgBJ;0BA7IyB,gBAAgB"}