@woosh/meep-engine 3.30.0 → 3.31.0

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

@@ -15,10 +15,10 @@ import { ChangedEntitySet } from "../state/ChangedEntitySet.js";
 import { MutationLedger } from "../state/MutationLedger.js";
 import { ReplicationSlotTable } from "../state/ReplicationSlotTable.js";
 import { Channel } from "../transport/Channel.js";
-import { resend_fragment_chunk, send_fragmented } from "../transport/fragments/fragment_send.js";
+import { fragment_chunk_count, resend_fragment_chunk, send_fragmented } from "../transport/fragments/fragment_send.js";
 import { FragmentAssembler } from "../transport/fragments/FragmentAssembler.js";
 import { FragmentRetention } from "../transport/fragments/FragmentRetention.js";
-import { MAX_CHANNEL_PAYLOAD_BYTES } from "../transport/fragments/packet_size.js";
+import { MAX_CHANNEL_PAYLOAD_BYTES, MAX_CHUNKS_PER_MESSAGE } from "../transport/fragments/packet_size.js";
 import { ReliableCommandPipeline } from "../transport/ReliableCommandPipeline.js";
 
 // DISCONNECT packets carry a short UTF-8 reason label. The encoder/decoder
@@ -100,7 +100,9 @@ export const NetworkPacketType = {
      *
      * The sender's {@link FragmentRetention} looks up the retained
      * source bytes and re-emits the listed chunks via
-     * {@link resend_fragment_chunk}. Receiver drives NACK timing
+     * {@link resend_fragment_chunk} — each chunk of the message once,
+     * however many times the list names it, and nothing for an index the
+     * message does not have. Receiver drives NACK timing
      * via {@link FragmentAssembler#service}.
      */
     NACK_FRAGMENT: 6,
@@ -120,7 +122,9 @@ export const NetworkPacketType = {
      *   varint    frame_number   (server sim_frame this snapshot represents)
      *   bytes     payload        (Snapshotter wire format)
      *
-     * Typically exceeds MTU; fragment-send handles chunking.
+     * Typically exceeds MTU; fragment-send handles chunking. Sent more than
+     * once, against loss: a client applies the first to reach it on a
+     * connection, and takes the rest for the copies they are.
      */
     INITIAL_SYNC: 8,
     /**
@@ -150,7 +154,10 @@ export const NetworkPacketType = {
      *   uint8 reason_code  (see {@link ResumeRejectReason})
      *
      * A fresh INITIAL_SYNC typically follows on the next host tick;
-     * the client drops unconfirmed predictions and accepts the resync.
+     * the client drops unconfirmed predictions and accepts the resync. It can
+     * also trail that sync: a host that readmitted the connection as a fresh
+     * peer before reading its RESUME_HELLO has already sent one, and a client
+     * that has applied it takes the reject as stale.
      */
     RESUME_REJECT: 11,
     /**
@@ -165,6 +172,15 @@ export const NetworkPacketType = {
      * does NOT attempt reconnect.
      */
     DISCONNECT: 12,
+    /**
+     * Client → server: the frame the sender has just finished simulating. Wire layout:
+     *   varint  frame_number
+     *
+     * Sent every tick in place of an empty keep-alive, so the server's input-buffer depth for the
+     * peer — and so time dilation — follows the peer's clock even on ticks that carry no input. An
+     * input-less or idle client used to read as depth 0, and be told to run fast, indefinitely.
+     */
+    FRAME_MARKER: 13,
 };
 
 /**
@@ -294,6 +310,14 @@ export class NetworkPeer {
      */
     #slice = { frame_start: 0, frame_end: 0, head: false };
 
+    /**
+     * Scratch for the NACK_FRAGMENT being dispatched: 1 at a chunk index the
+     * NACK has already had re-sent. Only valid for the duration of that case.
+     * @type {Uint8Array}
+     * @private
+     */
+    #nack_requested = new Uint8Array(MAX_CHUNKS_PER_MESSAGE);
+
     /**
      * @param {{
      *   world: EntityComponentDataset,
@@ -304,6 +328,7 @@ export class NetworkPeer {
      *   frame_capacity?: number,
      *   initial_buffer_size?: number,
      *   mutation_ledger?: MutationLedger|null,
+     *   mutation_ledger_retention_frames?: number,
      *   changed_set_capacity?: number,
      *   max_packets_per_tick?: number,
      * }} options
@@ -317,6 +342,7 @@ export class NetworkPeer {
         frame_capacity = 32,
         initial_buffer_size = 1024,
         mutation_ledger = null,
+        mutation_ledger_retention_frames = 600,
         changed_set_capacity = 256,
         max_packets_per_tick = 8,
     }) {
@@ -385,6 +411,18 @@ export class NetworkPeer {
          */
         this.mutation_ledger = mutation_ledger;
 
+        /**
+         * How many frames of mutation history to keep.
+         *
+         * Ten seconds at 60 Hz: far beyond any recovery request worth answering with a delta
+         * rather than a full re-init, and bounded - which the ledger was not, because nothing
+         * ever called `drop_through` and it grew one varint-list entry per mutating tick for the
+         * life of the session.
+         *
+         * @type {number}
+         */
+        this.mutation_ledger_retention_frames = mutation_ledger_retention_frames;
+
         /**
          * Per-tick "what mutated this tick" sink, used only when
          * {@link mutation_ledger} is set. Cleared at the start of each tick;
@@ -495,6 +533,12 @@ export class NetworkPeer {
          */
         this.onTimeDilationFeedback = new Signal();
 
+        /**
+         * Fires on FRAME_MARKER packet arrival. Args: `(peer_id, frame_number)`.
+         * @type {Signal}
+         */
+        this.onFrameMarker = new Signal();
+
         /**
          * Fires on INITIAL_SYNC packet arrival.
          * Args: `(peer_id, session_token, frame_number, buffer, payload_end)`.
@@ -572,7 +616,7 @@ export class NetworkPeer {
         // first rollback replay of its frame, so refuse the connection rather
         // than lose its input later. Real runtime check — asserts strip in prod.
         if (peer_id > MAX_PEER_ID) {
-            throw new Error(`NetworkPeer.connect_peer: peer id ${peer_id} is out of range; must be in [0, ${MAX_PEER_ID}] — 254 and 255 are reserved provenance markers in the action log`);
+            throw new Error(`NetworkPeer.connect_peer: peer id ${peer_id} is out of range; must be in [0, ${MAX_PEER_ID}] — 253, 254 and 255 are reserved provenance markers in the action log`);
         }
         if (this.#peers.has(peer_id)) {
             throw new Error(`NetworkPeer.connect_peer: peer ${peer_id} already connected`);
@@ -709,8 +753,19 @@ export class NetworkPeer {
                         // Either way: nothing to retransmit. Drop silently.
                         break;
                     }
+                    // The list is the peer's word. A NACK re-sends each chunk
+                    // of the message at most once, and nothing for an index
+                    // the message does not have: what one costs is bounded by
+                    // the message we chose to send, not by what is asked. It
+                    // used to re-send a chunk as often as it was named — 255
+                    // times in one NACK, three NACKs for each INITIAL_SYNC.
+                    const total_chunks = fragment_chunk_count(entry.length);
+                    const requested = this.#nack_requested;
+                    requested.fill(0, 0, total_chunks);
                     for (let i = 0; i < missing_count; i++) {
                         const chunk_index = this.#recv_buffer.readUint8();
+                        if (chunk_index >= total_chunks || requested[chunk_index] !== 0) continue;
+                        requested[chunk_index] = 1;
                         resend_fragment_chunk(
                             entry.payload, entry.length, message_id, chunk_index,
                             NetworkPacketType.FRAGMENT, this.#fragment_scratch,
@@ -774,6 +829,11 @@ export class NetworkPeer {
                     this.onDisconnectPacket.send2(peer_id, label);
                     break;
                 }
+                case NetworkPacketType.FRAME_MARKER: {
+                    const frame_number = this.#recv_buffer.readUintVar();
+                    this.onFrameMarker.send2(peer_id, frame_number);
+                    break;
+                }
                 default:
                     // Unknown type — drop. Forward-compat for newer peers.
                     break;
@@ -855,6 +915,8 @@ export class NetworkPeer {
             fragment_assembler, fragment_retention,
             reliable_pipeline,
             inbound_count: 0,
+            // the first frame the action stream may carry to this peer; see hold_outbound
+            outbound_floor: 0,
         });
     }
 
@@ -951,6 +1013,42 @@ export class NetworkPeer {
         return conn === undefined ? undefined : conn.channel;
     }
 
+    /**
+     * Send `peer_id` nothing on the action stream until {@link release_outbound}. What the log
+     * records meanwhile stays owed, and goes out on release unless the release starts past it.
+     * Nothing else is held: the `send_*` packets go out as ever.
+     *
+     * For a peer that has yet to say which world it holds. A client bound to its host afresh does
+     * not know whether the host will resume the world the client has been predicting on, or replace
+     * it with a snapshot; in the second case what it predicted on the old one is input for a world
+     * that is gone, and must never be applied.
+     *
+     * @param {number} peer_id
+     */
+    hold_outbound(peer_id) {
+        assert.isNonNegativeInteger(peer_id, 'peer_id');
+        const conn = this.#peers.get(peer_id);
+        if (conn === undefined) throw new Error(`NetworkPeer.hold_outbound: peer ${peer_id} not connected`);
+
+        conn.outbound_floor = Infinity;
+    }
+
+    /**
+     * Stop holding `peer_id`'s action stream. From the next {@link flush_outbound} it is sent what
+     * it is owed from `from_frame` on; frames before `from_frame` are never sent to it.
+     *
+     * @param {number} peer_id
+     * @param {number} [from_frame=0]
+     */
+    release_outbound(peer_id, from_frame = 0) {
+        assert.isNonNegativeInteger(peer_id, 'peer_id');
+        assert.isNonNegativeInteger(from_frame, 'from_frame');
+        const conn = this.#peers.get(peer_id);
+        if (conn === undefined) throw new Error(`NetworkPeer.release_outbound: peer ${peer_id} not connected`);
+
+        conn.outbound_floor = from_frame;
+    }
+
     /**
      * Open the action log for `frame_number`. Call before running game logic
      * for the tick. The user's code (or the engine's `EntityManager.simulate`)
@@ -1018,6 +1116,16 @@ export class NetworkPeer {
         // recovery requests that arrive immediately after.)
         if (this.mutation_ledger !== null && this.#changed_entities !== null) {
             this.mutation_ledger.record_tick(current_frame, this.#changed_entities);
+
+            // ...and trim. The ledger documents that "caller invokes drop_through periodically",
+            // and nothing did: it grew one varint-list entry per mutating tick for the life of
+            // the session, and every inbound recovery request linear-scanned all of it. Unbounded
+            // memory plus a per-request cost that grows with session length, on the recovery path
+            // that exists to handle bad links - degrading exactly when it is needed.
+            //
+            // The retention window is the same one the recovery answer is bounded by: anything
+            // older than the log's oldest frame is already answered with a full re-init.
+            this.mutation_ledger.drop_through(current_frame - this.mutation_ledger_retention_frames);
         }
 
         for (const [peer_id, conn] of this.#peers) {
@@ -1064,10 +1172,14 @@ export class NetworkPeer {
             // return` guard). For first-connect scenarios the app is still
             // expected to send a state-burst seed; this just makes the
             // action-stream bootstrap work in addition to that.
+            //
+            // Last, the peer's outbound floor: nothing before it is ever sent,
+            // and a held peer's floor is past every frame (see hold_outbound).
             const start = Math.max(
                 last_acked + 1,
                 current_frame - this.action_log.frame_capacity + 1,
                 0,
+                conn.outbound_floor,
             );
             if (start > current_frame) continue;
 
@@ -1193,10 +1305,11 @@ export class NetworkPeer {
      * still owed, and crediting them would retire them from the back-fill
      * unsent. So a slice is credited only once the baseline has reached the
      * frame before it. The exception is the head of a tick's burst. Its start
-     * IS the pack start — `last_acked + 1` or the ring floor, whichever is
-     * newer — so nothing sendable lies before it and its confirmation credits
-     * outright. That is also how the baseline gets past frames the ring has
-     * already retired, which no ack could ever confirm.
+     * IS the pack start — `last_acked + 1`, the ring floor or the peer's
+     * outbound floor, whichever is newest — so nothing sendable lies before it
+     * and its confirmation credits outright. That is also how the baseline
+     * gets past frames the ring has already retired, and frames below the
+     * outbound floor, which no ack could ever confirm.
      *
      * `confirmed` is a ring indexed by frame modulo capacity that stores the
      * frame number, so a slot whose frame has since been overwritten reads as
@@ -1531,6 +1644,26 @@ export class NetworkPeer {
         this.#send_to_peer(conn, this.#send_buffer.raw_bytes, this.#send_buffer.position);
     }
 
+    /**
+     * Tell a peer which frame this one has just finished simulating. See
+     * {@link NetworkPacketType.FRAME_MARKER}. Also serves as the tick's keep-alive: it advances the
+     * channel's seq/ack like any packet.
+     *
+     * @param {number} peer_id
+     * @param {number} frame_number
+     */
+    send_frame_marker(peer_id, frame_number) {
+        assert.isNonNegativeInteger(peer_id, 'peer_id');
+        assert.isNonNegativeInteger(frame_number, 'frame_number');
+        const conn = this.#peers.get(peer_id);
+        if (conn === undefined) throw new Error(`NetworkPeer.send_frame_marker: peer ${peer_id} not connected`);
+
+        this.#send_buffer.position = 0;
+        this.#send_buffer.writeUint8(NetworkPacketType.FRAME_MARKER);
+        this.#send_buffer.writeUintVar(frame_number);
+        this.#send_to_peer(conn, this.#send_buffer.raw_bytes, this.#send_buffer.position);
+    }
+
     /**
      * Send a reliable command to a connected peer. Delivered at-least-once
      * with sender-side retransmit on Channel-detected loss and receiver-

package/src/engine/network/orchestrator/ServerAuthoritativeClient.d.ts

@@ -59,6 +59,7 @@ export class ServerAuthoritativeClient {
      *   reconcile_epsilon?: number,
      *   time_dilation?: TimeDilation,
      *   max_packets_per_tick?: number,
+     *   auto_reconcile?: boolean,
      * }} options
      *
      * `time_dilation`: optional pre-configured {@link TimeDilation}.
@@ -69,8 +70,14 @@ export class ServerAuthoritativeClient {
      *
      * `max_packets_per_tick`: forwarded to {@link NetworkPeer}; how many
      * action-stream packets a tick may send the server.
+     *
+     * `auto_reconcile` (default true): run the rewind + apply + replay
+     * reconciliation below the moment AUTH_STATE arrives. A caller with its
+     * own reconciliation — `NetworkSession` corrects by comparison instead —
+     * turns it off and listens to `peer.onAuthState` itself; {@link reconcile}
+     * remains available to it.
      */
-    constructor({ world, binary_registry, replicated_components, action_classes, scope_filter, frame_capacity, initial_buffer_size, input_ring_capacity, input_byte_size, reconcile_epsilon, time_dilation, max_packets_per_tick, }: {
+    constructor({ world, binary_registry, replicated_components, action_classes, scope_filter, frame_capacity, initial_buffer_size, input_ring_capacity, input_byte_size, reconcile_epsilon, time_dilation, max_packets_per_tick, auto_reconcile, }: {
         world: EntityComponentDataset;
         binary_registry: BinarySerializationRegistry;
         replicated_components: Function[];
@@ -83,6 +90,7 @@ export class ServerAuthoritativeClient {
         reconcile_epsilon?: number;
         time_dilation?: TimeDilation;
         max_packets_per_tick?: number;
+        auto_reconcile?: boolean;
     });
     /** @type {number} */
     reconcile_count: number;
@@ -261,7 +269,8 @@ export class ServerAuthoritativeClient {
      * @param {number} peer_id */
     channel_for(peer_id: number): import("../transport/Channel.js").Channel;
     /**
-     * Run one client-side prediction tick.
+     * Run one client-side prediction tick: {@link begin_tick} followed immediately by
+     * {@link end_tick}.
      *
      * 1. Open action_log frame.
      * 2. Fire {@link onPredict} so the user samples input, records it in the
@@ -272,6 +281,23 @@ export class ServerAuthoritativeClient {
      * @param {number} current_frame
      */
     tick(current_frame: number): void;
+    /**
+     * First half of a tick: open frame `current_frame` and fire {@link onPredict}. The frame stays
+     * open until {@link end_tick}, so whatever runs in between — the engine's fixed-step systems —
+     * executes inside it.
+     *
+     * @param {number} current_frame
+     */
+    begin_tick(current_frame: number): void;
+    /**
+     * Second half of a tick: close the frame and flush the action stream to the server.
+     */
+    end_tick(): void;
+    /**
+     * The most recent frame this client has begun predicting, or -1 before the first.
+     * @returns {number}
+     */
+    get current_frame(): number;
     /**
      * Whether the InputRing has stored input bytes for the given frame.
      * Useful in {@link onReplay} handlers that need to short-circuit
@@ -289,6 +315,16 @@ export class ServerAuthoritativeClient {
      * @returns {BinaryBuffer}
      */
     input_for(frame: number): BinaryBuffer;
+    /**
+     * Reconcile to an authoritative state by rewind + apply + replay, as an AUTH_STATE arrival
+     * does when {@link auto_reconcile} is on. For a caller that queues AUTH_STATE and reconciles
+     * at a moment of its choosing.
+     *
+     * @param {number} server_frame
+     * @param {number} network_id
+     * @param {BinaryBuffer} buffer positioned at the authoritative payload
+     */
+    reconcile(server_frame: number, network_id: number, buffer: BinaryBuffer): void;
     /**
      * Helper for the {@link onComputeExpected} handler: stash the
      * computed scalar so the orchestrator can read it. Called inside the

package/src/engine/network/orchestrator/ServerAuthoritativeClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ServerAuthoritativeClient.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/orchestrator/ServerAuthoritativeClient.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH;IA8DI;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,iOAxBW;QACV,KAAS,yBAAyB;QAClC,eAAmB,8BAA8B;QACjD,qBAAyB,EAAE,UAAU,CAAC;QACtC,cAAkB,EAAE,UAAU,CAAC;QAC/B,YAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,cAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,mBAAuB,CAAC,EAAE,MAAM,CAAC;QACjC,mBAAuB,CAAC,EAAE,MAAM,CAAC;QACjC,eAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,iBAAqB,CAAC,EAAE,MAAM,CAAC;QAC/B,aAAiB,CAAC,EAAE,YAAY,CAAC;QACjC,oBAAwB,CAAC,EAAE,MAAM,CAAC;KAC/B,EAqNH;IAzPD,qBAAqB;IACrB,iBADW,MAAM,CACG;IAEpB,qBAAqB;IACrB,oBADW,MAAM,CACM;IAEvB;;;;;;OAMG;IACH,wBAFU,MAAM,CAEW;IAE3B;;;;OAIG;IACH,2BAFU,MAAM,CAEc;IAyC1B,0BAA0B;IAC1B,MADW,WAAW,CAUpB;IAEF,qCAAqC;IACrC,8BAAkB;IAClB,gCAAgC;IAChC,4BAAkC;IAClC,mCAAmC;IACnC,iCAAsC;IACtC,wBAAwB;IACxB,sBAAsC;IACtC,gCAAgC;IAChC,mCAAgD;IAEhD;;;;OAIG;IACH,YAFU,SAAS,CAKjB;IAEF,2BAA2B;IAC3B,eADW,YAAY,CAKrB;IAEF;;;;;OAKG;IACH,mBAFU,MAAM,CAE0B;IAE1C;;;;;OAKG;IACH,eAFU,YAAY,CAEY;IAElC;;;;OAIG;IACH,mBAFU,MAAM,CAEW;IAE3B;;;;;;;;OAQG;IACH,iBAFU,MAAM,CAEU;IAO1B;;;;;;;;;OASG;IACH,WAFU,MAAM,CAEa;IAE7B;;;;;;;;;OASG;IACH,UAFU,MAAM,CAEY;IAE5B;;;;;;;;;;;;;;;;;;OAkBG;IACH,mBAFU,MAAM,CAEqB;IAErC;;;;;OAKG;IACH,kBAFU,MAAM,CAEoB;IAEpC;;;;;;;OAOG;IACH,mBAFU,MAAM,CAEqB;IAErC;;;;;;;;OAQG;IACH,kBAFU,MAAM,CAEoB;IAEpC;;;;OAIG;IACH,qBAFU,MAAM,CAEuB;IAEvC;;;;;;;;;;;;;;;;;;OAkBG;IACH,sBAFU,MAAM,CAEwB;IAW5C;;;;OAIG;IACH,2BAHW,MAAM,aACN,MAAM,QAIhB;IAED;;;OAGG;IACH,gCAFW,MAAM,QAIhB;IAED;iCAC6B;IAC7B,qBADW,MAAM,6CAGhB;IAED;;;;;;;;;;OAUG;IACH,oBAFW,MAAM,QAahB;IAED;;;;;;;OAOG;IACH,qBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;OAMG;IACH,iBAHW,MAAM,GACJ,YAAY,CAIxB;IA6OD;;;;;OAKG;IACH,oBAFW,MAAM,QAIhB;IAED;;;;OAIG;IACH,oBAFW,MAAM,QAIhB;;CACJ;4BA9pB2B,kBAAkB;0BAFpB,uBAAuB;6BADpB,wBAAwB;6BAExB,yBAAyB;mBALnC,uCAAuC;6BAF7B,sCAAsC"}
+{"version":3,"file":"ServerAuthoritativeClient.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/orchestrator/ServerAuthoritativeClient.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH;IA8DI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,iPA/BW;QACV,KAAS,yBAAyB;QAClC,eAAmB,8BAA8B;QACjD,qBAAyB,EAAE,UAAU,CAAC;QACtC,cAAkB,EAAE,UAAU,CAAC;QAC/B,YAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,cAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,mBAAuB,CAAC,EAAE,MAAM,CAAC;QACjC,mBAAuB,CAAC,EAAE,MAAM,CAAC;QACjC,eAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,iBAAqB,CAAC,EAAE,MAAM,CAAC;QAC/B,aAAiB,CAAC,EAAE,YAAY,CAAC;QACjC,oBAAwB,CAAC,EAAE,MAAM,CAAC;QAClC,cAAkB,CAAC,EAAE,OAAO,CAAC;KAC1B,EA8NH;IAnQD,qBAAqB;IACrB,iBADW,MAAM,CACG;IAEpB,qBAAqB;IACrB,oBADW,MAAM,CACM;IAEvB;;;;;;OAMG;IACH,wBAFU,MAAM,CAEW;IAE3B;;;;OAIG;IACH,2BAFU,MAAM,CAEc;IAiD1B,0BAA0B;IAC1B,MADW,WAAW,CAUpB;IAEF,qCAAqC;IACrC,8BAAkB;IAClB,gCAAgC;IAChC,4BAAkC;IAClC,mCAAmC;IACnC,iCAAsC;IACtC,wBAAwB;IACxB,sBAAsC;IACtC,gCAAgC;IAChC,mCAAgD;IAEhD;;;;OAIG;IACH,YAFU,SAAS,CAKjB;IAEF,2BAA2B;IAC3B,eADW,YAAY,CAKrB;IAEF;;;;;OAKG;IACH,mBAFU,MAAM,CAE0B;IAE1C;;;;;OAKG;IACH,eAFU,YAAY,CAEY;IAElC;;;;OAIG;IACH,mBAFU,MAAM,CAEW;IAE3B;;;;;;;;OAQG;IACH,iBAFU,MAAM,CAEU;IAO1B;;;;;;;;;OASG;IACH,WAFU,MAAM,CAEa;IAE7B;;;;;;;;;OASG;IACH,UAFU,MAAM,CAEY;IAE5B;;;;;;;;;;;;;;;;;;OAkBG;IACH,mBAFU,MAAM,CAEqB;IAErC;;;;;OAKG;IACH,kBAFU,MAAM,CAEoB;IAEpC;;;;;;;OAOG;IACH,mBAFU,MAAM,CAEqB;IAErC;;;;;;;;OAQG;IACH,kBAFU,MAAM,CAEoB;IAEpC;;;;OAIG;IACH,qBAFU,MAAM,CAEuB;IAEvC;;;;;;;;;;;;;;;;;;OAkBG;IACH,sBAFU,MAAM,CAEwB;IAa5C;;;;OAIG;IACH,2BAHW,MAAM,aACN,MAAM,QAIhB;IAED;;;OAGG;IACH,gCAFW,MAAM,QAIhB;IAED;iCAC6B;IAC7B,qBADW,MAAM,6CAGhB;IAED;;;;;;;;;;;OAWG;IACH,oBAFW,MAAM,QAKhB;IAED;;;;;;OAMG;IACH,0BAFW,MAAM,QAUhB;IAED;;OAEG;IACH,iBAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;;;;;OAOG;IACH,qBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;OAMG;IACH,iBAHW,MAAM,GACJ,YAAY,CAIxB;IAED;;;;;;;;OAQG;IACH,wBAJW,MAAM,cACN,MAAM,UACN,YAAY,QAItB;IA6OD;;;;;OAKG;IACH,oBAFW,MAAM,QAIhB;IAED;;;;OAIG;IACH,oBAFW,MAAM,QAIhB;;CACJ;4BA9sB2B,kBAAkB;0BAFpB,uBAAuB;6BADpB,wBAAwB;6BAExB,yBAAyB;mBALnC,uCAAuC;6BAF7B,sCAAsC"}

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

@@ -139,6 +139,7 @@ export class ServerAuthoritativeClient {
      *   reconcile_epsilon?: number,
      *   time_dilation?: TimeDilation,
      *   max_packets_per_tick?: number,
+     *   auto_reconcile?: boolean,
      * }} options
      *
      * `time_dilation`: optional pre-configured {@link TimeDilation}.
@@ -149,6 +150,12 @@ export class ServerAuthoritativeClient {
      *
      * `max_packets_per_tick`: forwarded to {@link NetworkPeer}; how many
      * action-stream packets a tick may send the server.
+     *
+     * `auto_reconcile` (default true): run the rewind + apply + replay
+     * reconciliation below the moment AUTH_STATE arrives. A caller with its
+     * own reconciliation — `NetworkSession` corrects by comparison instead —
+     * turns it off and listens to `peer.onAuthState` itself; {@link reconcile}
+     * remains available to it.
      */
     constructor({
         world,
@@ -163,6 +170,7 @@ export class ServerAuthoritativeClient {
         reconcile_epsilon = 1e-4,
         time_dilation = new TimeDilation(),
         max_packets_per_tick,
+        auto_reconcile = true,
     }) {
         /** @type {NetworkPeer} */
         this.peer = new NetworkPeer({
@@ -349,9 +357,11 @@ export class ServerAuthoritativeClient {
         this.#harvest_payloads.setCapacity(1024);
 
         // Wire the AUTH_STATE handler to the algorithm above.
-        this.peer.onAuthState.add((_peer_id, server_frame, network_id, buffer) => {
-            this.#handle_auth_state(server_frame, network_id, buffer);
-        });
+        if (auto_reconcile) {
+            this.peer.onAuthState.add((_peer_id, server_frame, network_id, buffer) => {
+                this.#handle_auth_state(server_frame, network_id, buffer);
+            });
+        }
     }
 
     /**
@@ -378,7 +388,8 @@ export class ServerAuthoritativeClient {
     }
 
     /**
-     * Run one client-side prediction tick.
+     * Run one client-side prediction tick: {@link begin_tick} followed immediately by
+     * {@link end_tick}.
      *
      * 1. Open action_log frame.
      * 2. Fire {@link onPredict} so the user samples input, records it in the
@@ -389,16 +400,40 @@ export class ServerAuthoritativeClient {
      * @param {number} current_frame
      */
     tick(current_frame) {
+        this.begin_tick(current_frame);
+        this.end_tick();
+    }
+
+    /**
+     * First half of a tick: open frame `current_frame` and fire {@link onPredict}. The frame stays
+     * open until {@link end_tick}, so whatever runs in between — the engine's fixed-step systems —
+     * executes inside it.
+     *
+     * @param {number} current_frame
+     */
+    begin_tick(current_frame) {
         assert.isNonNegativeInteger(current_frame, 'current_frame');
         this.#current_frame = current_frame;
 
         this.peer.begin_tick(current_frame);
-        try {
-            const input_writer = (cb) => this.input_ring.write(current_frame, cb);
-            this.onPredict.send2(current_frame, input_writer);
-        } finally {
-            this.peer.end_tick();
-        }
+
+        const input_writer = (cb) => this.input_ring.write(current_frame, cb);
+        this.onPredict.send2(current_frame, input_writer);
+    }
+
+    /**
+     * Second half of a tick: close the frame and flush the action stream to the server.
+     */
+    end_tick() {
+        this.peer.end_tick();
+    }
+
+    /**
+     * The most recent frame this client has begun predicting, or -1 before the first.
+     * @returns {number}
+     */
+    get current_frame() {
+        return this.#current_frame;
     }
 
     /**
@@ -424,6 +459,19 @@ export class ServerAuthoritativeClient {
         return this.input_ring.buffer_for(frame);
     }
 
+    /**
+     * Reconcile to an authoritative state by rewind + apply + replay, as an AUTH_STATE arrival
+     * does when {@link auto_reconcile} is on. For a caller that queues AUTH_STATE and reconciles
+     * at a moment of its choosing.
+     *
+     * @param {number} server_frame
+     * @param {number} network_id
+     * @param {BinaryBuffer} buffer positioned at the authoritative payload
+     */
+    reconcile(server_frame, network_id, buffer) {
+        this.#handle_auth_state(server_frame, network_id, buffer);
+    }
+
     /** @private */
     #handle_auth_state(server_frame, network_id, buffer) {
         // Out-of-order safety: never reconcile to an older frame than the

package/src/engine/network/orchestrator/ServerAuthoritativeServer.d.ts

@@ -1,3 +1,27 @@
+/**
+ * What the server does with input that arrives for a frame it has already simulated.
+ */
+export type LateInput = string;
+/**
+ * What the server does with input that arrives for a frame it has already simulated.
+ *
+ * @readonly
+ * @enum {string}
+ */
+export const LateInput: Readonly<{
+    /**
+     * Rewind to the input's frame and replay forward, so it lands exactly where it was tagged.
+     * Exact for a simulation made entirely of actions; a replay re-executes actions only, never the
+     * engine's fixed-step systems, so for physics-driven state it buys nothing.
+     */
+    Rollback: "rollback";
+    /**
+     * Apply it in the frame being simulated now. What input buffering (`simulation_delay_ticks`)
+     * and time dilation exist to make rare, handled the way a physics game handles it: late, not
+     * rewound.
+     */
+    Apply: "apply";
+}>;
 /**
  * Server-authoritative orchestrator with deterministic per-tick rollback.
  *
@@ -77,11 +101,14 @@ export class ServerAuthoritativeServer {
      *   initial_buffer_size?: number,
      *   simulation_delay_ticks?: number,
      *   max_packets_per_tick?: number,
+     *   late_input?: LateInput|string,
      * }} options
      *
      * `max_packets_per_tick`: forwarded to {@link NetworkPeer}; how many
      * action-stream packets a tick may send one peer.
      *
+     * `late_input`: see {@link LateInput}. Default {@link LateInput.Rollback}.
+     *
      * `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
@@ -91,7 +118,7 @@ export class ServerAuthoritativeServer {
      * input-to-feedback latency (client prediction hides it). Default 0
      * reproduces pre-feature behavior.
      */
-    constructor({ world, binary_registry, replicated_components, action_classes, scope_filter, frame_capacity, initial_buffer_size, simulation_delay_ticks, max_pending_future_lead, max_pending_total, identity_class, server_peer_id, max_packets_per_tick, }: {
+    constructor({ world, binary_registry, replicated_components, action_classes, scope_filter, frame_capacity, initial_buffer_size, simulation_delay_ticks, max_pending_future_lead, max_pending_total, identity_class, server_peer_id, max_packets_per_tick, late_input, }: {
         world: EntityComponentDataset;
         binary_registry: BinarySerializationRegistry;
         replicated_components: Function[];
@@ -101,6 +128,7 @@ export class ServerAuthoritativeServer {
         initial_buffer_size?: number;
         simulation_delay_ticks?: number;
         max_packets_per_tick?: number;
+        late_input?: LateInput | string;
     });
     /**
      * Most recently simulated frame. `-1` during warmup
@@ -109,6 +137,12 @@ export class ServerAuthoritativeServer {
      * @type {number}
      */
     current_sim_frame: number;
+    /**
+     * What happens to input that arrives for an already-simulated frame. See {@link LateInput}.
+     * @readonly
+     * @type {LateInput|string}
+     */
+    readonly late_input: LateInput | string;
     /** @type {NetworkPeer} */
     peer: NetworkPeer;
     /** @type {EntityComponentDataset} */
@@ -214,6 +248,15 @@ export class ServerAuthoritativeServer {
      * @type {Signal}
      */
     onTickComplete: Signal;
+    /**
+     * Fires once per tick, for the frame being simulated for the first time, after
+     * {@link onLocalSim} and before the frame closes — the last chance to record into it. Never
+     * fires for a replayed frame. Args: `(sim_frame)`.
+     *
+     * `NetworkSession` records the state its simulation changed here.
+     * @type {Signal}
+     */
+    onBeforeTickClose: Signal;
     /**
      * Fired when a tick triggers an actual rewind (i.e. the replay
      * window includes already-committed frames). Args:
@@ -308,7 +351,8 @@ export class ServerAuthoritativeServer {
      */
     queued_local_action_count(): number;
     /**
-     * Drive the rollback flow for one tick.
+     * Drive the rollback flow for one tick: {@link begin_tick} followed immediately by
+     * {@link end_tick}, for a caller whose simulation happens entirely inside {@link onLocalSim}.
      *
      * With `simulation_delay_ticks = 0` (default), simulates the caller's
      * `wall_frame` and drains pending. With `> 0`, simulates
@@ -321,6 +365,28 @@ export class ServerAuthoritativeServer {
      * @param {number} current_frame the caller's wall frame
      */
     tick(current_frame: number): void;
+    /**
+     * First half of a tick: resolve late input (rewinding and replaying older frames, or folding it
+     * into this frame — see {@link late_input}), then open the frame being simulated and apply its
+     * input. The frame stays open until {@link end_tick}, so whatever runs in between — the engine's
+     * fixed-step systems — executes inside it: actions it executes are recorded into the frame.
+     *
+     * Warmup (`sim_frame < 0`) opens nothing, and the matching {@link end_tick} does nothing.
+     *
+     * @param {number} current_frame the caller's wall frame
+     */
+    begin_tick(current_frame: number): void;
+    /**
+     * Second half of a tick: run {@link onLocalSim} for the open frame, close it, publish the new
+     * {@link current_sim_frame}, flush the action stream and fire {@link onTickComplete}. A no-op
+     * after a warmup {@link begin_tick}.
+     */
+    end_tick(): void;
+    /**
+     * The frame opened by {@link begin_tick} and not yet closed by {@link end_tick}, or -1.
+     * @returns {number}
+     */
+    get open_frame(): number;
     /**
      * Current input-buffer depth for a peer: `max_received_frame - current_sim_frame`.
      * Positive ⇒ peer is sending ahead of sim (good); zero/negative ⇒

package/src/engine/network/orchestrator/ServerAuthoritativeServer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ServerAuthoritativeServer.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/orchestrator/ServerAuthoritativeServer.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH;IAsCI;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,6PAxBW;QACV,KAAS,yBAAyB;QAClC,eAAmB,8BAA8B;QACjD,qBAAyB,EAAE,UAAU,CAAC;QACtC,cAAkB,EAAE,UAAU,CAAC;QAC/B,YAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,cAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,mBAAuB,CAAC,EAAE,MAAM,CAAC;QACjC,sBAA0B,CAAC,EAAE,MAAM,CAAC;QACpC,oBAAwB,CAAC,EAAE,MAAM,CAAC;KAC/B,EAiOH;IApPD;;;;;OAKG;IACH,mBAFU,MAAM,CAEO;IA6CnB,0BAA0B;IAC1B,MADW,WAAW,CAUpB;IAEF,qCAAqC;IACrC,8BAAkB;IAClB,gCAAgC;IAChC,4BAAkC;IAclC,mCAAmC;IACnC,iCAAsC;IACtC,wBAAwB;IACxB,sBAAsC;IACtC,gCAAgC;IAChC,mCAAgD;IAChD,0CAA0C;IAC1C,gDAAsD;IAEtD,2BAA2B;IAC3B,eADW,YAAY,CAKrB;IAEF;;;;;;OAMG;IACH,6BAFU,MAAM,CAEqB;IAErC;;;;OAIG;IACH,wBAFU,MAAM,CAEoC;IAEpD;;;;;;;OAOG;IACH,gBAFU,MAAM,CAEoB;IAEpC;;;;;;;;;OASG;IACH,yBAFU,MAAM,CAEsC;IAEtD;;;;;;;;;OASG;IACH,mBAFU,MAAM,CAE0B;IA+B1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,YAFU,MAAM,CAEc;IAE9B;;;;;;;OAOG;IACH,gBAFU,MAAM,CAEkB;IAElC;;;;;;;;;;;OAWG;IACH,UAFU,MAAM,CAEY;IAE5B;;;;;;;OAOG;IACH,wBAFU,MAAM,CAE0B;IAG9C;;;;;;;OAOG;IACH,sBAHW,MAAM,aACN,MAAM,QAIhB;IAED;;;OAGG;IACH,yBAFW,MAAM,QAIhB;IAED;;;;;;;;OAQG;IACH,yBALW,MAAM,gBACN,MAAM,cACN,MAAM,YACN,CAAC,GAAG,EAAE,YAAY,KAAK,IAAI,QAIrC;IAED;;;;OAIG;IACH,qBAFW,MAAM,6CAIhB;IAED;;;;;;;;OAQG;IACH,qCAFW,MAAM,QAIhB;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,wCA8BC;IAED;;;OAGG;IACH,6BAFa,MAAM,CAIlB;IAED;;;;;;;;;;;;OAYG;IACH,oBAFW,MAAM,QAkDhB;IAED;;;;;;;;OAQG;IACH,+BAHW,MAAM,GACJ,MAAM,CAOlB;IAyLD;;;;OAIG;IACH,yBAFa,MAAM,CAIlB;;CA8IJ;4BA52B2B,kBAAkB;6BAFjB,wBAAwB;mBAPlC,uCAAuC;6BAH7B,sCAAsC"}
+{"version":3,"file":"ServerAuthoritativeServer.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/orchestrator/ServerAuthoritativeServer.js"],"names":[],"mappings":";;;wBAmBU,MAAM;AAJhB;;;;;GAKG;AACH;IACI;;;;OAIG;;IAEH;;;;OAIG;;GAEJ;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH;IA2DI;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,yQA3BW;QACV,KAAS,yBAAyB;QAClC,eAAmB,8BAA8B;QACjD,qBAAyB,EAAE,UAAU,CAAC;QACtC,cAAkB,EAAE,UAAU,CAAC;QAC/B,YAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,cAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,mBAAuB,CAAC,EAAE,MAAM,CAAC;QACjC,sBAA0B,CAAC,EAAE,MAAM,CAAC;QACpC,oBAAwB,CAAC,EAAE,MAAM,CAAC;QAClC,UAAc,CAAC,EAAE,SAAS,GAAC,MAAM,CAAC;KAC/B,EAkQH;IAtRD;;;;;OAKG;IACH,mBAFU,MAAM,CAEO;IAqDnB;;;;OAIG;IACH,qBAFU,SAAS,GAAC,MAAM,CAEE;IAC5B,0BAA0B;IAC1B,MADW,WAAW,CAUpB;IAEF,qCAAqC;IACrC,8BAAkB;IAClB,gCAAgC;IAChC,4BAAkC;IAclC,mCAAmC;IACnC,iCAAsC;IACtC,wBAAwB;IACxB,sBAAsC;IACtC,gCAAgC;IAChC,mCAAgD;IAChD,0CAA0C;IAC1C,gDAAsD;IAEtD,2BAA2B;IAC3B,eADW,YAAY,CAKrB;IAEF;;;;;;OAMG;IACH,6BAFU,MAAM,CAEqB;IAErC;;;;OAIG;IACH,wBAFU,MAAM,CAEoC;IAEpD;;;;;;;OAOG;IACH,gBAFU,MAAM,CAEoB;IAEpC;;;;;;;;;OASG;IACH,yBAFU,MAAM,CAEsC;IAEtD;;;;;;;;;OASG;IACH,mBAFU,MAAM,CAE0B;IAyC1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,YAFU,MAAM,CAEc;IAE9B;;;;;;;OAOG;IACH,gBAFU,MAAM,CAEkB;IAElC;;;;;;;OAOG;IACH,mBAFU,MAAM,CAEqB;IAErC;;;;;;;;;;;OAWG;IACH,UAFU,MAAM,CAEY;IAE5B;;;;;;;OAOG;IACH,wBAFU,MAAM,CAE0B;IAG9C;;;;;;;OAOG;IACH,sBAHW,MAAM,aACN,MAAM,QAIhB;IAED;;;OAGG;IACH,yBAFW,MAAM,QAIhB;IAED;;;;;;;;OAQG;IACH,yBALW,MAAM,gBACN,MAAM,cACN,MAAM,YACN,CAAC,GAAG,EAAE,YAAY,KAAK,IAAI,QAIrC;IAED;;;;OAIG;IACH,qBAFW,MAAM,6CAIhB;IAED;;;;;;;;OAQG;IACH,qCAFW,MAAM,QAIhB;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,wCA8BC;IAED;;;OAGG;IACH,6BAFa,MAAM,CAIlB;IAED;;;;;;;;;;;;;OAaG;IACH,oBAFW,MAAM,QAKhB;IAED;;;;;;;;;OASG;IACH,0BAFW,MAAM,QAqEhB;IAED;;;;OAIG;IACH,iBAiBC;IAED;;;OAGG;IACH,yBAEC;IAED;;;;;;;;OAQG;IACH,+BAHW,MAAM,GACJ,MAAM,CAOlB;IAoQD;;;;OAIG;IACH,yBAFa,MAAM,CAIlB;;CA6MJ;4BAroC2B,kBAAkB;6BAFjB,wBAAwB;mBAPlC,uCAAuC;6BAH7B,sCAAsC"}