@woosh/meep-engine 3.14.4 → 3.14.5

package/src/engine/network/orchestrator/ServerAuthoritativeServer.js

@@ -8,6 +8,7 @@ import { NetworkIdentity } from "../ecs/components/NetworkIdentity.js";
 import { make_owner_authorization } from "../ecs/owner_authorization.js";
 import { Replicator } from "../replication/Replicator.js";
 import { AlwaysRelevantScope } from "../replication/ScopeFilter.js";
+import { ActionRecordCursor } from "../sim/ActionRecordCursor.js";
 import { RewindEngine } from "../sim/RewindEngine.js";
 import { SENDER_DERIVED, SENDER_LOCAL } from "../sim/SimActionExecutor.js";
 import { NetworkPeer } from "./NetworkPeer.js";
@@ -20,14 +21,15 @@ import { NetworkPeer } from "./NetworkPeer.js";
  *
  *   1. Inbound action packets do NOT execute on arrival. Instead, a deferral
  *      hook on the {@link Replicator} drops them into a per-tick pending log
- *      tagged with `(client_frame, sender_id, type_id, payload_bytes)`.
+ *      tagged with `(client_frame, sender_id, type_id, payload_bytes)` —
+ *      unless the action log already holds that record. The action stream
+ *      re-sends every unconfirmed frame each tick, so most arrivals at any
+ *      real latency are copies of applied records; those are dropped where
+ *      they arrive, and pending holds only input the log does not.
  *   2. Once per server tick, `tick(current_frame)` consumes the pending log:
  *      - Rejects entries older than the action_log's rewindable window.
- *      - Determines `replay_start`: the oldest pending frame carrying an
- *        action the log does not already hold. The action stream re-sends
- *        every unacked frame each tick, so most of pending is copies of
- *        already-applied records; rewinding for those would replay the
- *        world into the state it was already in.
+ *      - Determines `replay_start`: the oldest pending frame, which by the
+ *        above is the oldest frame whose outcome can change.
  *      - Rewinds the server world back to end-of-(replay_start - 1) via the
  *        action_log's prior-state captures (see {@link RewindEngine}).
  *      - Replays forward `[replay_start, current_frame]`. For each frame `f`:
@@ -92,6 +94,8 @@ export class ServerAuthoritativeServer {
     #historical_scratch = /** @type {Array<{type_id:number, sender_id:number, payload:Uint8Array}>} */ ([]);
     #sort_scratch = /** @type {Array<{sender_id:number, type_id:number, payload:Uint8Array}>} */ ([]);
     #payload_buf;
+    // Walks a frame's records, for the history read and the arrival check.
+    #cursor = new ActionRecordCursor();
     // Locally-authored actions waiting for the next fresh frame. Parallel
     // arrays, serialized at enqueue time so the caller's instance is not
     // retained (and so a bad action class is rejected at the call site rather
@@ -99,10 +103,6 @@ export class ServerAuthoritativeServer {
     #local_type_ids = /** @type {number[]} */ ([]);
     #local_payloads = /** @type {Uint8Array[]} */ ([]);
     #local_buf;
-    // The frame this tick is simulating for the first time. Only it may take
-    // the locally-authored queue; every earlier frame in the replay window
-    // already holds, in its history, the actions it was given the first time.
-    #fresh_frame = -1;
     /**
      * Count of inbound pending entries dropped by the future-lead / total
      * bounds. See {@link onPendingActionDropped}.
@@ -128,8 +128,12 @@ export class ServerAuthoritativeServer {
      *   frame_capacity?: number,
      *   initial_buffer_size?: number,
      *   simulation_delay_ticks?: number,
+     *   max_packets_per_tick?: number,
      * }} options
      *
+     * `max_packets_per_tick`: forwarded to {@link NetworkPeer}; how many
+     * action-stream packets a tick may send one peer.
+     *
      * `simulation_delay_ticks`: server-side input buffer (Overwatch-style).
      * When > 0, {@link tick}(wall_frame) simulates
      * `sim_frame = wall_frame - simulation_delay_ticks`. Pending actions
@@ -152,6 +156,7 @@ export class ServerAuthoritativeServer {
         max_pending_total = 4096,
         identity_class = NetworkIdentity,
         server_peer_id = -1,
+        max_packets_per_tick,
     }) {
         assert.isNonNegativeInteger(simulation_delay_ticks, 'simulation_delay_ticks');
         assert.isPositiveInteger(max_pending_future_lead, 'max_pending_future_lead');
@@ -165,6 +170,7 @@ export class ServerAuthoritativeServer {
             scope_filter,
             frame_capacity,
             initial_buffer_size,
+            max_packets_per_tick,
         });
 
         /** @type {EntityComponentDataset} */
@@ -496,31 +502,17 @@ export class ServerAuthoritativeServer {
             this.#pending_trim_to_window(window_oldest);
         }
 
-        // 2. Pick the replay window: the OLDEST pending frame that carries
-        //    input the action log doesn't already hold.
-        //
-        //    `__pending_referenced_frames` is sorted ascending; entries
-        //    `> sim_frame` stay buffered. Most of what it holds at any real
-        //    latency is retransmission: `Replicator.pack_for_peer` packs
-        //    every frame in [last_acked + 1, current] each tick, so each
-        //    action arrives once per tick until its ack round-trips, and the
-        //    deferral hook logs every copy. Taking `refs[0]` verbatim would
-        //    therefore rewind by the ACK round trip on every tick — and
-        //    `__replay_frame`'s dedup would then discard the very entries
-        //    that caused the rewind, leaving the world exactly as it was.
-        //    So run the same comparison here, before the window is chosen:
-        //    a frame whose every pending entry is already in the log needs
-        //    no rewind. What's left is genuinely late input, which is what
-        //    the rollback exists for.
+        // 2. Pick the replay window: the OLDEST pending frame at or below
+        //    `sim_frame`. Pending holds only input the log does not already
+        //    hold — a retransmission of an applied record is dropped on
+        //    arrival, see __pending_add — so the oldest pending frame is the
+        //    oldest frame whose outcome can change, and a rewind to it is
+        //    never wasted. `__pending_referenced_frames` is sorted
+        //    ascending; entries `> sim_frame` stay buffered.
         let replay_start = sim_frame;
         const refs = this.#pending_referenced_frames;
-        for (let i = 0; i < refs.length; i++) {
-            const f = refs[i];
-            if (f > sim_frame) break;
-            if (this.#frame_has_unapplied_input(f)) {
-                replay_start = f;
-                break;
-            }
+        if (refs.length > 0 && refs[0] <= sim_frame) {
+            replay_start = refs[0];
         }
 
         // 3. Rewind only if the replay window covers committed frames.
@@ -533,9 +525,8 @@ export class ServerAuthoritativeServer {
         // 4. Replay [replay_start, sim_frame]. Only `sim_frame` is being
         //    simulated for the first time; the rest are re-executions of
         //    frames the log already holds.
-        this.#fresh_frame = sim_frame;
         for (let f = replay_start; f <= sim_frame; f++) {
-            this.#replay_frame(f);
+            this.#replay_frame(f, f === sim_frame);
         }
 
         // 5. Keep only `frame > sim_frame` pending (future buffer).
@@ -564,48 +555,20 @@ export class ServerAuthoritativeServer {
         return max - this.current_sim_frame;
     }
 
-    /**
-     * Does frame `f` carry at least one pending entry the action log does not
-     * already hold? Only such a frame can change the world when replayed, so
-     * only such a frame is worth rewinding to.
-     *
-     * Same key as {@link __replay_frame}'s dedup — `(sender_id, type_id,
-     * payload bytes)` — asked one step earlier, against the log rather than
-     * against a scratch copy of it. The two must stay in step: a frame this
-     * call reports clean is never replayed, so an entry it treats as a
-     * duplicate that `__replay_frame` would have treated as new would be
-     * dropped from pending without ever being applied.
-     *
-     * Note the key can only recognise records the log actually holds. An
-     * action the executor REJECTED (owner authorization) writes nothing, so
-     * each of its retransmissions still reads as new input and still costs a
-     * rewind — unchanged from before this check existed, and self-limiting,
-     * because the sender stops re-sending the frame once it is acked.
-     *
-     * @param {number} f
-     * @returns {boolean}
-     * @private
-     */
-    #frame_has_unapplied_input(f) {
-        const has_history = this.action_log.has_frame(f);
-        for (let i = 0; i < this.#pending_frames.length; i++) {
-            if (this.#pending_frames[i] !== f) continue;
-            // Nothing recorded for this frame yet: every entry is new.
-            if (!has_history) return true;
-            if (!this.#log_holds_record(f, this.#pending_senders[i], this.#pending_type_ids[i], this.#pending_payloads[i])) {
-                return true;
-            }
-        }
-        return false;
-    }
-
     /**
      * Walk `action_log[frame_number]` looking for a record identical to
      * `(sender_id, type_id, payload)`. Compares the payload in place against
      * the log's own bytes — no copy, unlike {@link __read_historical}, because
-     * this runs per pending entry on every tick.
+     * this runs once per arriving action.
      *
-     * Caller must have checked `action_log.has_frame(frame_number)`.
+     * The key can only recognise records the log actually holds. An action
+     * the executor REJECTED (owner authorization) writes nothing, so each of
+     * its retransmissions still reads as new input and still costs a rewind —
+     * self-limiting, because the sender stops re-sending the frame once it is
+     * acked.
+     *
+     * Caller must have checked `action_log.has_frame(frame_number)`, and that
+     * the frame is closed.
      *
      * @param {number} frame_number
      * @param {number} sender_id
@@ -615,38 +578,34 @@ export class ServerAuthoritativeServer {
      * @private
      */
     #log_holds_record(frame_number, sender_id, type_id, payload) {
-        const buf = this.action_log.buffer_for(frame_number); // sets position = 0
-        const end = this.action_log.write_end_for(frame_number);
-        const bytes = buf.raw_bytes;
-        while (buf.position < end) {
-            const prior_count = buf.readUintVar();
-            for (let i = 0; i < prior_count; i++) {
-                buf.readUintVar();             // entity_id
-                buf.readUint8();               // component_type_id
-                const plen = buf.readUint32();
-                buf.position += plen;
-            }
-            const r_type_id = buf.readUint8();
-            const r_sender_id = buf.readUint8();
-            const r_payload_len = buf.readUint32();
-            const r_payload_start = buf.position;
-            buf.position += r_payload_len;
-
-            if (r_type_id !== type_id) continue;
-            if (r_sender_id !== sender_id) continue;
-            if (r_payload_len !== payload.length) continue;
-
+        const cursor = this.#cursor;
+        cursor.open(this.action_log, frame_number);
+        const bytes = cursor.buffer.raw_bytes;
+        while (cursor.next()) {
+            if (cursor.action_type_id !== type_id) continue;
+            if (cursor.sender_id !== sender_id) continue;
+            if (cursor.payload_len !== payload.length) continue;
+
+            const payload_start = cursor.payload_start;
             let same = true;
-            for (let i = 0; i < r_payload_len; i++) {
-                if (bytes[r_payload_start + i] !== payload[i]) { same = false; break; }
+            for (let i = 0; i < payload.length; i++) {
+                if (bytes[payload_start + i] !== payload[i]) { same = false; break; }
             }
             if (same) return true;
         }
         return false;
     }
 
-    /** @private */
-    #replay_frame(f) {
+    /**
+     * Execute frame `f`: its history, its pending input and — when `fresh`,
+     * meaning this is the first time the frame is simulated — the
+     * locally-authored queue, merged and sorted, then the local sim.
+     *
+     * @param {number} f
+     * @param {boolean} fresh
+     * @private
+     */
+    #replay_frame(f, fresh) {
         this.#sort_scratch.length = 0;
 
         // Read historical actions out of action_log[f] BEFORE begin_frame(f)
@@ -659,15 +618,13 @@ export class ServerAuthoritativeServer {
             this.#sort_scratch.push({ sender_id: h.sender_id, type_id: h.type_id, payload: h.payload });
         }
 
-        // Append newly-arrived pending actions for this frame, deduplicating
-        // against historical entries. Retransmissions are routine on the
-        // wire — `Replicator.pack_for_peer` packs every frame in
-        // [last_acked + 1, current_frame] each tick, so an action lives in
-        // every outgoing packet for the round-trip duration of its ack.
-        // The server receives each retransmission as a fresh pending entry;
-        // without dedup, the rollback flow merges it with the historical
-        // record left over from the previous apply and executes the action
-        // twice (and three times, four times… until the ack arrives).
+        // Append the pending actions for this frame. Retransmissions of
+        // records the log already holds are dropped on arrival (see
+        // __pending_add), so in the supported call pattern nothing here
+        // duplicates history. The check stays as a safety net: a duplicate
+        // that reached this point would merge with the historical record and
+        // execute the action twice, diverging the world, and the cost of the
+        // check is a scan of a small frame's copied history.
         //
         // Dedup key: (sender_id, type_id, payload bytes). Two actions are
         // "the same arrival" if all three match. (Same sender_id and
@@ -696,7 +653,7 @@ export class ServerAuthoritativeServer {
         // depend on whether it is being simulated fresh or replayed: on replay
         // these come back through __read_historical and are sorted with
         // everything else, so the fresh pass has to sort them the same way.
-        if (f === this.#fresh_frame && this.#local_type_ids.length > 0) {
+        if (fresh && this.#local_type_ids.length > 0) {
             const sender = this.server_peer_id >= 0 ? this.server_peer_id : SENDER_LOCAL;
             for (let i = 0; i < this.#local_type_ids.length; i++) {
                 this.#sort_scratch.push({
@@ -764,32 +721,20 @@ export class ServerAuthoritativeServer {
     #read_historical(frame_number, out_array) {
         out_array.length = 0;
         if (!this.action_log.has_frame(frame_number)) return;
-        const buf = this.action_log.buffer_for(frame_number); // sets position = 0
-        const end = this.action_log.write_end_for(frame_number);
-        while (buf.position < end) {
-            const prior_count = buf.readUintVar();
-            for (let i = 0; i < prior_count; i++) {
-                buf.readUintVar();             // entity_id
-                buf.readUint8();               // component_type_id
-                const plen = buf.readUint32();
-                buf.position += plen;
-            }
-            const type_id = buf.readUint8();
-            const sender_id = buf.readUint8();
-            const payload_len = buf.readUint32();
-            const payload_start = buf.position;
-            buf.position += payload_len;
-
+        const cursor = this.#cursor;
+        cursor.open(this.action_log, frame_number);
+        const bytes = cursor.buffer.raw_bytes;
+        while (cursor.next()) {
             // Derived records are the previous pass's local-sim output. The
             // caller re-runs onLocalSim for this frame, which recomputes them
             // against a world that now includes the late input that forced the
             // replay; carrying the stale copy forward as well would apply the
             // effect twice, and the copies would accumulate one per replay.
-            if (sender_id === SENDER_DERIVED) continue;
+            if (cursor.sender_id === SENDER_DERIVED) continue;
 
-            const payload = new Uint8Array(payload_len);
-            payload.set(buf.raw_bytes.subarray(payload_start, payload_start + payload_len));
-            out_array.push({ type_id, sender_id, payload });
+            const payload = new Uint8Array(cursor.payload_len);
+            payload.set(bytes.subarray(cursor.payload_start, cursor.payload_start + cursor.payload_len));
+            out_array.push({ type_id: cursor.action_type_id, sender_id: cursor.sender_id, payload });
         }
     }
 
@@ -824,17 +769,17 @@ export class ServerAuthoritativeServer {
             return;
         }
 
-        // Dedup against other pending entries for the same frame. Multiple
-        // retransmission packets routinely arrive in the same c2s.tick
-        // window when ack RTT exceeds tick period; each carries the same
-        // action records for the same frames. The __replay_frame dedup
-        // catches retransmissions across server ticks (where historical
-        // already has the record), but the SAME server tick can collect
-        // multiple identical pending entries before historical exists. So
-        // also dedup here, against everything already in pending for this
-        // frame. Match on (sender_id, type_id, payload bytes) — distinct
-        // payloads from the same sender at the same frame are legitimately
-        // different actions (move + fire) and both flow through.
+        // Retransmissions are routine on the wire: `Replicator.pack_for_peer`
+        // packs every frame in [last_acked + 1, current_frame] each tick, so
+        // an action arrives once per tick until its ack round-trips, and
+        // several copies can land in the same server tick when the round trip
+        // exceeds the tick period. A copy is recognised by its whole identity,
+        // (sender_id, type_id, payload bytes) — distinct payloads from the
+        // same sender at the same frame are legitimately different actions
+        // (move + fire) and both flow through.
+        //
+        // First against everything already pending for the frame, which
+        // catches the copies that arrive before the frame is simulated.
         for (let i = 0; i < this.#pending_frames.length; i++) {
             if (this.#pending_frames[i] !== frame_number) continue;
             if (this.#pending_senders[i] !== sender_id) continue;
@@ -842,6 +787,26 @@ export class ServerAuthoritativeServer {
             if (fastArrayEquals(this.#pending_payloads[i], payload)) return; // duplicate already in pending; drop
         }
 
+        // Then against the action log, which catches the copies that arrive
+        // after it. A record the log already holds is not input — applying it
+        // again would apply the action twice, and rewinding for it would
+        // replay the world into the state it is already in — so it is dropped
+        // here, and pending holds only input the log does not. That is what
+        // lets `tick` take the oldest pending frame as its replay window
+        // without a second look.
+        //
+        // Frames are only open inside `tick`, and packets arrive between
+        // ticks, so an open frame here means a call pattern this orchestrator
+        // does not support (a packet delivered from inside a local-sim
+        // handler). The check is skipped rather than reading an open frame's
+        // stale length; the copy then costs one spurious rewind, and
+        // `__replay_frame`'s own dedup keeps it from applying twice.
+        if (this.action_log.has_frame(frame_number)
+            && !this.action_log.has_open_frame()
+            && this.#log_holds_record(frame_number, sender_id, type_id, payload)) {
+            return;
+        }
+
         this.#pending_frames.push(frame_number);
         this.#pending_senders.push(sender_id);
         this.#pending_type_ids.push(type_id);

package/src/engine/network/replication/Replicator.d.ts

@@ -25,6 +25,10 @@
  *       uint32:  action_payload_len
  *       bytes:   action_payload
  * ```
+ * {@link NetworkPeer} prefixes each packet of this with a slice header — the
+ * frame range the packet covers and whether it is the first of the sender's
+ * tick — which it parses itself and hands to {@link unpack_from_peer} as
+ * `slice`, so the receiver can apply the sender's packets in frame order.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -56,8 +60,9 @@ export class Replicator {
      * or anything else that needs to know "frame N from peer P has just
      * been applied to the local world."
      *
-     * Fires in frame-ascending order within a single packet (the order
-     * the wire format encodes them in).
+     * Fires in frame order — within a packet, which encodes its frames
+     * ascending, and across packets, because a later slice of a sender's tick
+     * is held until the slices before it have landed.
      *
      * @type {Signal}
      */
@@ -136,15 +141,32 @@ export class Replicator {
      * sender's frame number, ensuring the rewind/replay machinery sees consistent
      * frame indexing across peers.
      *
+     * `slice` is the sender's description of the packet, from the
+     * {@link NetworkPeer} slice header: the frame range it covers and whether
+     * it is the first packet of the sender's tick. Frames are applied in frame
+     * order. A slice that starts past the frames applied so far and is not a
+     * head is a later slice of a burst whose earlier slice has not landed; it
+     * is held and applied once the gap before it fills. A head is applied as
+     * soon as it arrives, because nothing the sender can still send lies
+     * before it — that is also how the receiver moves past frames lost for
+     * good. Without `slice` (callers that pack and unpack directly) the packet
+     * is taken as a head covering the frames it carries.
+     *
      * @param {number} peer_id
      * @param {BinaryBuffer} in_buffer
      * @param {number} in_buffer_end byte position to stop reading at
+     * @param {{frame_start: number, frame_end: number, head: boolean}|null} [slice]
      */
-    unpack_from_peer(peer_id: number, in_buffer: BinaryBuffer, in_buffer_end: number): void;
+    unpack_from_peer(peer_id: number, in_buffer: BinaryBuffer, in_buffer_end: number, slice?: {
+        frame_start: number;
+        frame_end: number;
+        head: boolean;
+    } | null): void;
     /**
-     * Forget the per-peer apply watermark. Call when a peer disconnects so a
-     * later peer reusing the same id (or the same peer resuming a session whose
-     * frame numbering restarts) is not wrongly deduped against stale state.
+     * Forget a peer's inbound state — its apply watermark and any slices held
+     * for it. Call when a peer disconnects so a later peer reusing the same id
+     * (or the same peer resuming a session whose frame numbering restarts) is
+     * not wrongly deduped against stale state.
      *
      * @param {number} peer_id
      */
@@ -152,4 +174,5 @@ export class Replicator {
     #private;
 }
 import Signal from "../../../core/events/signal/Signal.js";
+import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
 //# sourceMappingURL=Replicator.d.ts.map

package/src/engine/network/replication/Replicator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Replicator.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/replication/Replicator.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH;IA2DI;;;;;;;;OAQG;IACH;;;;;;wCAHiD,MAAM,cAAc,MAAM,GAAG,OAAO;;OA8BpF;IAvED;;;;;;;;;;;;OAYG;IACH,gBAFU,MAAM,CAEc;IAE9B;;;;;;;;;;;;;;;;;OAiBG;IACH,6BAFqB,MAAM,gBAAgB,MAAM,kBAAkB,MAAM,2CAA2C,MAAM,eAAe,MAAM,KAAK,IAAI,CAE/H;IAYrB;;OAEG;IACH,sBAA4B;IAE5B;;OAEG;IACH,mCAAsC;IAEtC;;OAEG;IACH,4BAAwB;IAExB;;OAEG;IACH,iCAA4B;IAE5B;;;;OAIG;IACH;oCAFwC,MAAM,cAAc,MAAM,GAAG,OAAO;MAE5C;IAGpC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,uBAVW,MAAM,eACN,MAAM,aACN,MAAM,wCAEN,MAAM,GACJ,MAAM,CAyElB;IAED;;;;;;;;;OASG;IACH,0BAJW,MAAM,0CAEN,MAAM,QA4GhB;IAED;;;;;;OAMG;IACH,qBAFW,MAAM,QAKhB;;CAuFJ;mBA5bkB,uCAAuC"}
+{"version":3,"file":"Replicator.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/replication/Replicator.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH;IAkFI;;;;;;;;OAQG;IACH;;;;;;wCAHiD,MAAM,cAAc,MAAM,GAAG,OAAO;;OA8BpF;IA/ED;;;;;;;;;;;;;OAaG;IACH,gBAFU,MAAM,CAEc;IAE9B;;;;;;;;;;;;;;;;;OAiBG;IACH,6BAFqB,MAAM,gBAAgB,MAAM,kBAAkB,MAAM,aAAa,YAAY,kBAAkB,MAAM,eAAe,MAAM,KAAK,IAAI,CAE/H;IAmBrB;;OAEG;IACH,sBAA4B;IAE5B;;OAEG;IACH,mCAAsC;IAEtC;;OAEG;IACH,4BAAwB;IAExB;;OAEG;IACH,iCAA4B;IAE5B;;;;OAIG;IACH;oCAFwC,MAAM,cAAc,MAAM,GAAG,OAAO;MAE5C;IAGpC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,uBAVW,MAAM,eACN,MAAM,aACN,MAAM,cACN,YAAY,cACZ,MAAM,GACJ,MAAM,CA4ElB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,0BALW,MAAM,aACN,YAAY,iBACZ,MAAM,UACN;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAC,GAAC,IAAI,QAmEtE;IAyLD;;;;;;;OAOG;IACH,qBAFW,MAAM,QAKhB;;CA8CJ;mBAxlBkB,uCAAuC;6BAD7B,sCAAsC"}