@woosh/meep-engine 3.46.0 → 3.47.0

package/src/engine/network/replication/Replicator.js

@@ -3,6 +3,7 @@ import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
 import Signal from "../../../core/events/signal/Signal.js";
 import { MalformedPacketError } from "../core/MalformedPacketError.js";
 import { ActionRecordCursor } from "../sim/ActionRecordCursor.js";
+import { SENDER_CORRECTED } from "../sim/SimActionExecutor.js";
 
 // Bytes of fixed per-action framing that always precede the variable payload:
 // uint8 action_type_id + uint32 action_payload_len.
@@ -321,6 +322,9 @@ export class Replicator {
                 // back to it — harmless where ownership rejects it, and the host overwriting its own
                 // simulation with a stale copy of itself where the entity belongs to the client.
                 if (cursor.sender_id === peer_id) continue;
+                // Nor anyone a correction: it is the server's word about this peer's own world,
+                // and sent back, a host would take a client-owned entity's old state from it.
+                if (cursor.sender_id === SENDER_CORRECTED) continue;
                 if (!this.#record_in_scope(cursor, peer_id)) continue;
                 if ((in_scope_count + 1) * 3 > this.#in_scope_actions.length) {
                     this.#grow_in_scope_actions();
@@ -543,7 +547,9 @@ export class Replicator {
                 continue;
             }
 
-            this.action_log.begin_frame(frame_number);
+            // After what the frame already holds: on a client this frame is usually one it has
+            // already predicted, and its own records are what a rewind undoes.
+            this.action_log.resume_frame(frame_number);
             try {
                 for (let i = 0; i < action_count; i++) {
                     if (in_buffer.position + ACTION_HEADER_BYTES > in_buffer_end) {

package/src/engine/network/sim/ActionLog.d.ts

@@ -27,7 +27,7 @@
  * `sender_id` says where the record came from, which is what a rollback replay
  * needs in order to decide what to do with it:
  *
- *   - a peer id `[0, 252]` — arrived from that peer;
+ *   - a peer id `[0, 251]` — arrived from that peer;
  *   - `SENDER_LOCAL` (255) — authored on this peer;
  *   - `SENDER_DERIVED` (254) — computed by this peer's simulation from the
  *     frame's own state. A replay of the frame recomputes these rather than
@@ -35,7 +35,11 @@
  *     the sim's output does not accumulate a copy per replay;
  *   - `SENDER_RECORDED` (253) — recorded, not executed: what this peer's world
  *     became, for the peers (see `SimActionExecutor.record`). A replay carries
- *     these over unchanged.
+ *     these over unchanged;
+ *   - `SENDER_CORRECTED` (252) — a server's correction of one entity on a
+ *     predicting client (see `SimActionExecutor.begin_correction`): prior state
+ *     and the server's bytes, no action. A replay applies it again, last in its
+ *     frame, and it is never packed for any peer.
  *
  * It also gives the replay a stable sort key, so multi-client action order is
  * deterministic across peers. It never crosses the wire —
@@ -70,6 +74,29 @@ export class ActionLog {
      * @param {number} frame absolute frame number
      */
     begin_frame(frame: number): void;
+    /**
+     * Open a frame for writing after the records it already holds, rather than over them. A frame
+     * the ring does not hold is opened empty, as {@link begin_frame} opens it.
+     *
+     * For a writer adding to a frame someone else wrote: records arriving from a peer for a frame
+     * this peer has already simulated. Opened with {@link begin_frame} instead, they would erase
+     * this peer's own records for the frame — and with them the prior state a rewind needs to undo
+     * that input, so a replay would apply it a second time, and the outbound stream, which packs
+     * from this log, would lose it before the peer it was for had confirmed it.
+     *
+     * @param {number} frame absolute frame number
+     */
+    resume_frame(frame: number): void;
+    /**
+     * Drop every record the log holds, keeping each frame it holds present and empty.
+     *
+     * For when the world the records were written against is replaced wholesale, and the frame
+     * numbers they were written under with it: their prior state belongs to that world, so a rewind
+     * that walked them would put it back into this one. Present rather than absent, because a frame
+     * the new world never ran — skipped by the seek that came with it — is one in which nothing was
+     * done, and a rewind crossing it has nothing to undo; an absent frame would make it abandon.
+     */
+    empty_frames(): void;
     /**
      * Close the currently-open frame.
      */
@@ -100,9 +127,9 @@ export class ActionLog {
      * The buffer's `position` will be set to 0 and its valid byte length is `write_end_for(frame)`.
      *
      * **Only valid for frames that have been closed via {@link end_frame}.** While a
-     * frame is open, its slot's recorded length still holds the previous
-     * occupant's — `buffer_for`/`write_end_for` would return mismatched
-     * buffer-contents-vs-length and any reader would walk garbage.
+     * frame is open, its slot's recorded length is what was last committed — 0 for a
+     * frame opened by {@link begin_frame}, the old end for one opened by
+     * {@link resume_frame} — so a reader sees none of what is being written.
      *
      * @param {number} frame
      * @returns {BinaryBuffer}

package/src/engine/network/sim/ActionLog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ActionLog.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/ActionLog.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH;IAoBI;;OAEG;IACH,qDAFW;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;KAAE,EAIlE;IAED;;;OAGG;IACH,6BAEC;IAED;;;;OAIG;IACH,mBAFW,MAAM,QAShB;IAED;;OAEG;IACH,kBASC;IAED;;;;;;OAMG;IACH,kBAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,+BAMC;IAED;;;;;OAKG;IACH,iBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;;;OAWG;IACH,kBAHW,MAAM,gBAKhB;IAED;;;;OAIG;IACH,qBAHW,MAAM,GACJ,MAAM,CAIlB;;CACJ"}
+{"version":3,"file":"ActionLog.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/ActionLog.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH;IAoBI;;OAEG;IACH,qDAFW;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;KAAE,EAIlE;IAED;;;OAGG;IACH,6BAEC;IAED;;;;OAIG;IACH,mBAFW,MAAM,QAShB;IAED;;;;;;;;;;;OAWG;IACH,oBAFW,MAAM,QAShB;IAED;;;;;;;;OAQG;IACH,qBAMC;IAED;;OAEG;IACH,kBASC;IAED;;;;;;OAMG;IACH,kBAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,+BAMC;IAED;;;;;OAKG;IACH,iBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;;;OAWG;IACH,kBAHW,MAAM,gBAKhB;IAED;;;;OAIG;IACH,qBAHW,MAAM,GACJ,MAAM,CAIlB;;CACJ"}

package/src/engine/network/sim/ActionLog.js

@@ -29,7 +29,7 @@ import { FrameBufferRing } from "../state/FrameBufferRing.js";
  * `sender_id` says where the record came from, which is what a rollback replay
  * needs in order to decide what to do with it:
  *
- *   - a peer id `[0, 252]` — arrived from that peer;
+ *   - a peer id `[0, 251]` — arrived from that peer;
  *   - `SENDER_LOCAL` (255) — authored on this peer;
  *   - `SENDER_DERIVED` (254) — computed by this peer's simulation from the
  *     frame's own state. A replay of the frame recomputes these rather than
@@ -37,7 +37,11 @@ import { FrameBufferRing } from "../state/FrameBufferRing.js";
  *     the sim's output does not accumulate a copy per replay;
  *   - `SENDER_RECORDED` (253) — recorded, not executed: what this peer's world
  *     became, for the peers (see `SimActionExecutor.record`). A replay carries
- *     these over unchanged.
+ *     these over unchanged;
+ *   - `SENDER_CORRECTED` (252) — a server's correction of one entity on a
+ *     predicting client (see `SimActionExecutor.begin_correction`): prior state
+ *     and the server's bytes, no action. A replay applies it again, last in its
+ *     frame, and it is never packed for any peer.
  *
  * It also gives the replay a stable sort key, so multi-client action order is
  * deterministic across peers. It never crosses the wire —
@@ -102,6 +106,44 @@ export class ActionLog {
         this.#current_frame = frame;
     }
 
+    /**
+     * Open a frame for writing after the records it already holds, rather than over them. A frame
+     * the ring does not hold is opened empty, as {@link begin_frame} opens it.
+     *
+     * For a writer adding to a frame someone else wrote: records arriving from a peer for a frame
+     * this peer has already simulated. Opened with {@link begin_frame} instead, they would erase
+     * this peer's own records for the frame — and with them the prior state a rewind needs to undo
+     * that input, so a replay would apply it a second time, and the outbound stream, which packs
+     * from this log, would lose it before the peer it was for had confirmed it.
+     *
+     * @param {number} frame absolute frame number
+     */
+    resume_frame(frame) {
+        if (this.#current_frame !== -1) {
+            throw new Error(`ActionLog.resume_frame: previous frame ${this.#current_frame} still open; call end_frame first`);
+        }
+
+        this.#current_buffer = this.#ring.resume(frame);
+        this.#current_frame = frame;
+    }
+
+    /**
+     * Drop every record the log holds, keeping each frame it holds present and empty.
+     *
+     * For when the world the records were written against is replaced wholesale, and the frame
+     * numbers they were written under with it: their prior state belongs to that world, so a rewind
+     * that walked them would put it back into this one. Present rather than absent, because a frame
+     * the new world never ran — skipped by the seek that came with it — is one in which nothing was
+     * done, and a rewind crossing it has nothing to undo; an absent frame would make it abandon.
+     */
+    empty_frames() {
+        if (this.#current_frame !== -1) {
+            throw new Error(`ActionLog.empty_frames: frame ${this.#current_frame} is open; call end_frame first`);
+        }
+
+        this.#ring.empty();
+    }
+
     /**
      * Close the currently-open frame.
      */
@@ -155,9 +197,9 @@ export class ActionLog {
      * The buffer's `position` will be set to 0 and its valid byte length is `write_end_for(frame)`.
      *
      * **Only valid for frames that have been closed via {@link end_frame}.** While a
-     * frame is open, its slot's recorded length still holds the previous
-     * occupant's — `buffer_for`/`write_end_for` would return mismatched
-     * buffer-contents-vs-length and any reader would walk garbage.
+     * frame is open, its slot's recorded length is what was last committed — 0 for a
+     * frame opened by {@link begin_frame}, the old end for one opened by
+     * {@link resume_frame} — so a reader sees none of what is being written.
      *
      * @param {number} frame
      * @returns {BinaryBuffer}

package/src/engine/network/sim/SimActionExecutor.d.ts

@@ -23,7 +23,7 @@ export const SENDER_LOCAL: number;
  * Local-only, like `SENDER_LOCAL` — {@link Replicator#pack_for_peer} strips
  * the byte before send, so this never reaches the wire.
  *
- * The sentinels are reserved: valid peer ids are `[0, 252]`, enforced by
+ * The sentinels are reserved: valid peer ids are `[0, 251]`, enforced by
  * {@link SimActionExecutor#execute} and at {@link NetworkPeer#connect_peer}.
  * A peer allowed to take 254 would have its records read back as the local
  * sim's own output and dropped from every replay — its input would apply once
@@ -44,9 +44,24 @@ export const SENDER_DERIVED: number;
  * @type {number}
  */
 export const SENDER_RECORDED: number;
+/**
+ * Sentinel sender id for a server's correction written into a predicting client's log (see
+ * {@link SimActionExecutor#begin_correction}): the server's state for one entity at the end of a
+ * frame, put over this client's prediction of it.
+ *
+ * Its prior state is what makes the correction undoable, so a rewind across its frame takes the
+ * entity back to the prediction underneath. It has no action: a rollback replay applies it again,
+ * last in its frame, from the bytes it carries. It is never sent — the client's log is its outbound
+ * stream, and a host would take a client-owned entity's old state from it. Local-only, like the
+ * other sentinels.
+ *
+ * @type {number}
+ */
+export const SENDER_CORRECTED: number;
 /**
  * Largest id a remote peer may take. Above this are the local provenance sentinels,
- * {@link SENDER_RECORDED}, {@link SENDER_DERIVED} and {@link SENDER_LOCAL}.
+ * {@link SENDER_CORRECTED}, {@link SENDER_RECORDED}, {@link SENDER_DERIVED} and
+ * {@link SENDER_LOCAL}.
  *
  * @type {number}
  */
@@ -242,6 +257,31 @@ export class SimActionExecutor {
      * @param {SimAction} action
      */
     record(action: SimAction): void;
+    /**
+     * Open a {@link SENDER_CORRECTED} record in the open frame: capture the prior state of every
+     * replicated component `entity_id` has, as {@link execute} captures an action's, so a rewind
+     * across the frame puts it back. The caller then overwrites the entity with the server's state
+     * and closes the record with {@link end_correction} — also when that overwrite throws, or the
+     * frame is left holding half a record.
+     *
+     * Every replicated component, because a correction is the server's whole state for the entity
+     * and the executor cannot know which of them the caller's deserialize writes.
+     *
+     * No authorization, no {@link before_execute}, no announcement: the caller writes, not this.
+     *
+     * @param {number} entity_id
+     */
+    begin_correction(entity_id: number): void;
+    /**
+     * Close the record {@link begin_correction} opened, carrying `length` bytes of `bytes` from
+     * `offset` — what a replay needs to apply the correction again. The record has no action: its
+     * action type byte is 0 and means nothing, and readers go by its sender.
+     *
+     * @param {Uint8Array} bytes
+     * @param {number} offset
+     * @param {number} length
+     */
+    end_correction(bytes: Uint8Array, offset: number, length: number): void;
     #private;
 }
 import Signal from "../../../core/events/signal/Signal.js";

package/src/engine/network/sim/SimActionExecutor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SimActionExecutor.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/SimActionExecutor.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,2BAFU,MAAM,CAEiB;AAEjC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,6BAFU,MAAM,CAEmB;AAEnC;;;;;;;;;;GAUG;AACH,8BAFU,MAAM,CAEoB;AAEpC;;;;;GAKG;AACH,0BAFU,MAAM,CAEgB;AAEhC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAqEI;;;;;;;;;OASG;IACH,sGATW;QACV,KAAS,yBAAyB;QAClC,UAAc,YAAY;QAC1B,eAAmB,oBAAoB;QACvC,kBAAsB,8BAA8B;QACpD,UAAc,uBAAuB;QACrC,gBAAoB,CAAC,mBAAmB;KACrC,EAyFH;IAjKD;;;;;;;;;OASG;IACH,gBAFU,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAEP;IAEtB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,WAFU,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,WAAW,KAAK,OAAO,CAAC,GAAG,IAAI,CAEtE;IAEjB;;;;;;;;;;;;;;;OAeG;IACH,UAFU,OAAO,CAEA;IAEjB;;;;;;;OAOG;IACH,sBAFU,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,UAAU,KAAK,IAAI,CAAC,GAAG,IAAI,CAE7C;IAaxB;;OAEG;IACH,8BAAkB;IAElB;;OAEG;IACH,sBAA4B;IAE5B;;OAEG;IACH,mCAAsC;IAEtC;;OAEG;IACH,gDAA4C;IAE5C;;;;OAIG;IACH,iCAA4B;IAE5B;;;;;;;;;;;OAWG;IACH,kBAFU,mBAAiB,IAAI,CAES;IA4BxC;;;;;;;OAOG;IACH,mBAFU,MAAM,CAEqB;IAErC;;;;;;;OAOG;IACH,kBAFU,MAAM,CAEoB;IAGxC;;;;;;;;;;OAUG;IACH,uCAPW,MAAM,GAGJ,OAAO,CA0KnB;IAkCD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,gCAwCC;;CACJ;mBA7gBkB,uCAAuC"}
+{"version":3,"file":"SimActionExecutor.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/SimActionExecutor.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,2BAFU,MAAM,CAEiB;AAEjC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,6BAFU,MAAM,CAEmB;AAEnC;;;;;;;;;;GAUG;AACH,8BAFU,MAAM,CAEoB;AAEpC;;;;;;;;;;;;GAYG;AACH,+BAFU,MAAM,CAEqB;AAErC;;;;;;GAMG;AACH,0BAFU,MAAM,CAEgB;AAEhC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IA2EI;;;;;;;;;OASG;IACH,sGATW;QACV,KAAS,yBAAyB;QAClC,UAAc,YAAY;QAC1B,eAAmB,oBAAoB;QACvC,kBAAsB,8BAA8B;QACpD,UAAc,uBAAuB;QACrC,gBAAoB,CAAC,mBAAmB;KACrC,EAyFH;IAjKD;;;;;;;;;OASG;IACH,gBAFU,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAEP;IAEtB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,WAFU,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,WAAW,KAAK,OAAO,CAAC,GAAG,IAAI,CAEtE;IAEjB;;;;;;;;;;;;;;;OAeG;IACH,UAFU,OAAO,CAEA;IAEjB;;;;;;;OAOG;IACH,sBAFU,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,UAAU,KAAK,IAAI,CAAC,GAAG,IAAI,CAE7C;IAaxB;;OAEG;IACH,8BAAkB;IAElB;;OAEG;IACH,sBAA4B;IAE5B;;OAEG;IACH,mCAAsC;IAEtC;;OAEG;IACH,gDAA4C;IAE5C;;;;OAIG;IACH,iCAA4B;IAE5B;;;;;;;;;;;OAWG;IACH,kBAFU,mBAAiB,IAAI,CAES;IA4BxC;;;;;;;OAOG;IACH,mBAFU,MAAM,CAEqB;IAErC;;;;;;;OAOG;IACH,kBAFU,MAAM,CAEoB;IAGxC;;;;;;;;;;OAUG;IACH,uCAPW,MAAM,GAGJ,OAAO,CA0KnB;IAkCD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,gCAwCC;IAED;;;;;;;;;;;;;OAaG;IACH,4BAFW,MAAM,QAqChB;IAED;;;;;;;;OAQG;IACH,sBAJW,UAAU,UACV,MAAM,UACN,MAAM,QAchB;;CACJ;mBA7mBkB,uCAAuC"}

package/src/engine/network/sim/SimActionExecutor.js

@@ -27,7 +27,7 @@ export const SENDER_LOCAL = 0xFF;
  * Local-only, like `SENDER_LOCAL` — {@link Replicator#pack_for_peer} strips
  * the byte before send, so this never reaches the wire.
  *
- * The sentinels are reserved: valid peer ids are `[0, 252]`, enforced by
+ * The sentinels are reserved: valid peer ids are `[0, 251]`, enforced by
  * {@link SimActionExecutor#execute} and at {@link NetworkPeer#connect_peer}.
  * A peer allowed to take 254 would have its records read back as the local
  * sim's own output and dropped from every replay — its input would apply once
@@ -50,13 +50,29 @@ export const SENDER_DERIVED = 0xFE;
  */
 export const SENDER_RECORDED = 0xFD;
 
+/**
+ * Sentinel sender id for a server's correction written into a predicting client's log (see
+ * {@link SimActionExecutor#begin_correction}): the server's state for one entity at the end of a
+ * frame, put over this client's prediction of it.
+ *
+ * Its prior state is what makes the correction undoable, so a rewind across its frame takes the
+ * entity back to the prediction underneath. It has no action: a rollback replay applies it again,
+ * last in its frame, from the bytes it carries. It is never sent — the client's log is its outbound
+ * stream, and a host would take a client-owned entity's old state from it. Local-only, like the
+ * other sentinels.
+ *
+ * @type {number}
+ */
+export const SENDER_CORRECTED = 0xFC;
+
 /**
  * Largest id a remote peer may take. Above this are the local provenance sentinels,
- * {@link SENDER_RECORDED}, {@link SENDER_DERIVED} and {@link SENDER_LOCAL}.
+ * {@link SENDER_CORRECTED}, {@link SENDER_RECORDED}, {@link SENDER_DERIVED} and
+ * {@link SENDER_LOCAL}.
  *
  * @type {number}
  */
-export const MAX_PEER_ID = 0xFC;
+export const MAX_PEER_ID = 0xFB;
 
 /**
  * The single legitimate gateway for replicated state mutations.
@@ -86,6 +102,12 @@ export class SimActionExecutor {
     #scratch_classes;
     #collect_cb;
 
+    /**
+     * Between {@link begin_correction} and {@link end_correction}.
+     * @type {boolean}
+     */
+    #correction_open = false;
+
     /**
      * Optional hook fired at the top of {@link execute}, before
      * prior-bytes capture. Higher-level orchestrators install this
@@ -281,7 +303,7 @@ export class SimActionExecutor {
         // prod, and silent input loss is not something to ship behind one.
         if (sender_id > MAX_PEER_ID && sender_id !== SENDER_LOCAL) {
             throw new Error(
-                `SimActionExecutor.execute: sender_id ${sender_id} is not a peer id; remote peer ids must be in [0, ${MAX_PEER_ID}] — 253, 254 and 255 are reserved provenance markers`,
+                `SimActionExecutor.execute: sender_id ${sender_id} is not a peer id; remote peer ids must be in [0, ${MAX_PEER_ID}] — 252 to 255 are reserved provenance markers`,
             );
         }
 
@@ -524,4 +546,78 @@ export class SimActionExecutor {
         buffer.writeUint32(action_payload_end - action_payload_start);
         buffer.position = action_payload_end;
     }
+
+    /**
+     * Open a {@link SENDER_CORRECTED} record in the open frame: capture the prior state of every
+     * replicated component `entity_id` has, as {@link execute} captures an action's, so a rewind
+     * across the frame puts it back. The caller then overwrites the entity with the server's state
+     * and closes the record with {@link end_correction} — also when that overwrite throws, or the
+     * frame is left holding half a record.
+     *
+     * Every replicated component, because a correction is the server's whole state for the entity
+     * and the executor cannot know which of them the caller's deserialize writes.
+     *
+     * No authorization, no {@link before_execute}, no announcement: the caller writes, not this.
+     *
+     * @param {number} entity_id
+     */
+    begin_correction(entity_id) {
+        assert.isNonNegativeInteger(entity_id, 'entity_id');
+        assert.equal(this.#correction_open, false, 'begin_correction: a correction is already open');
+
+        const buffer = this.action_log.current_buffer();
+        const registry = this.component_registry;
+        const world = this.world;
+        const type_count = registry.type_count();
+
+        let count = 0;
+        for (let type_id = 0; type_id < type_count; type_id++) {
+            if (world.getComponent(entity_id, registry.class_of(type_id)) !== undefined) count++;
+        }
+
+        buffer.writeUintVar(count);
+
+        for (let type_id = 0; type_id < type_count; type_id++) {
+            const component = world.getComponent(entity_id, registry.class_of(type_id));
+            if (component === undefined) continue;
+
+            buffer.writeUintVar(entity_id);
+            buffer.writeUint8(type_id);
+
+            const len_position = buffer.position;
+            buffer.writeUint32(0); // placeholder
+            const payload_start = buffer.position;
+            registry.adapter_for_id(type_id).serialize(buffer, component);
+            const payload_end = buffer.position;
+
+            buffer.position = len_position;
+            buffer.writeUint32(payload_end - payload_start);
+            buffer.position = payload_end;
+        }
+
+        this.#correction_open = true;
+    }
+
+    /**
+     * Close the record {@link begin_correction} opened, carrying `length` bytes of `bytes` from
+     * `offset` — what a replay needs to apply the correction again. The record has no action: its
+     * action type byte is 0 and means nothing, and readers go by its sender.
+     *
+     * @param {Uint8Array} bytes
+     * @param {number} offset
+     * @param {number} length
+     */
+    end_correction(bytes, offset, length) {
+        assert.equal(this.#correction_open, true, 'end_correction: no correction is open');
+        assert.isNonNegativeInteger(length, 'length');
+
+        const buffer = this.action_log.current_buffer();
+
+        buffer.writeUint8(0);
+        buffer.writeUint8(SENDER_CORRECTED);
+        buffer.writeUint32(length);
+        buffer.writeBytes(bytes, offset, length);
+
+        this.#correction_open = false;
+    }
 }

package/src/engine/network/sim/Snapshotter.d.ts

@@ -46,6 +46,18 @@ export function snapshotter_emit({ buffer, world, slot_table, component_registry
     component_registry: ReplicatedComponentRegistry;
     entity_iter: (arg0: (arg0: number) => void) => void;
 }): void;
+/**
+ * Write one entity's record — network id, then each replicated component it has — in the format
+ * {@link snapshotter_emit} writes per entity. Allocates nothing: a page builder calls it once per
+ * entity it fits.
+ *
+ * @param {BinaryBuffer} buffer
+ * @param {EntityComponentDataset} world
+ * @param {ReplicationSlotTable} slot_table
+ * @param {ReplicatedComponentRegistry} component_registry
+ * @param {number} entity_id must be registered in the slot table
+ */
+export function snapshotter_write_entity(buffer: BinaryBuffer, world: EntityComponentDataset, slot_table: ReplicationSlotTable, component_registry: ReplicatedComponentRegistry, entity_id: number): void;
 /**
  * Apply a snapshot stream to a (typically empty) world, creating each entity
  * and attaching components.

package/src/engine/network/sim/Snapshotter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Snapshotter.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/Snapshotter.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;;;;;;GAUG;AACH,iGARW;IACV,MAAU,eAAe;IACzB,KAAS,yBAAyB;IAClC,UAAc,uBAAuB;IACrC,kBAAsB,8BAA8B;IACpD,WAAe,gBAAoB,MAAM,KAAG,IAAI,KAAG,IAAI,CAAC;CACrD,QAkDH;AAED;;;;;;;;;;;GAWG;AACH,iGARW;IACV,MAAU,eAAe;IACzB,UAAc,EAAE,MAAM,CAAC;IACvB,KAAS,yBAAyB;IAClC,UAAc,uBAAuB;IACrC,kBAAsB,8BAA8B;CACjD,QA6CH;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,6GARW;IACV,MAAU,eAAe;IACzB,UAAc,EAAE,MAAM,CAAC;IACvB,KAAS,yBAAyB;IAClC,UAAc,uBAAuB;IACrC,kBAAsB,8BAA8B;CACjD,QAgDH"}
+{"version":3,"file":"Snapshotter.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/Snapshotter.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;;;;;;GAUG;AACH,iGARW;IACV,MAAU,eAAe;IACzB,KAAS,yBAAyB;IAClC,UAAc,uBAAuB;IACrC,kBAAsB,8BAA8B;IACpD,WAAe,gBAAoB,MAAM,KAAG,IAAI,KAAG,IAAI,CAAC;CACrD,QAkDH;AAED;;;;;;;;;;GAUG;AACH,4LAFW,MAAM,QAgChB;AAED;;;;;;;;;;;GAWG;AACH,iGARW;IACV,MAAU,eAAe;IACzB,UAAc,EAAE,MAAM,CAAC;IACvB,KAAS,yBAAyB;IAClC,UAAc,uBAAuB;IACrC,kBAAsB,8BAA8B;CACjD,QA6CH;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,6GARW;IACV,MAAU,eAAe;IACzB,UAAc,EAAE,MAAM,CAAC;IACvB,KAAS,yBAAyB;IAClC,UAAc,uBAAuB;IACrC,kBAAsB,8BAA8B;CACjD,QAgDH"}

package/src/engine/network/sim/Snapshotter.js

@@ -93,6 +93,49 @@ export function snapshotter_emit({ buffer, world, slot_table, component_registry
     }
 }
 
+/**
+ * Write one entity's record — network id, then each replicated component it has — in the format
+ * {@link snapshotter_emit} writes per entity. Allocates nothing: a page builder calls it once per
+ * entity it fits.
+ *
+ * @param {BinaryBuffer} buffer
+ * @param {EntityComponentDataset} world
+ * @param {ReplicationSlotTable} slot_table
+ * @param {ReplicatedComponentRegistry} component_registry
+ * @param {number} entity_id must be registered in the slot table
+ */
+export function snapshotter_write_entity(buffer, world, slot_table, component_registry, entity_id) {
+    const network_id = slot_table.network_for(entity_id);
+    if (network_id < 0) {
+        throw new Error(`snapshotter_write_entity: entity ${entity_id} is not registered in the slot table`);
+    }
+
+    const type_count = component_registry.type_count();
+    let present = 0;
+    for (let type_id = 0; type_id < type_count; type_id++) {
+        if (world.hasComponent(entity_id, component_registry.class_of(type_id))) present++;
+    }
+
+    buffer.writeUintVar(network_id);
+    buffer.writeUint8(present);
+
+    for (let type_id = 0; type_id < type_count; type_id++) {
+        const klass = component_registry.class_of(type_id);
+        const component = world.getComponent(entity_id, klass);
+        if (component === undefined) continue;
+
+        buffer.writeUint8(type_id);
+        const len_position = buffer.position;
+        buffer.writeUint32(0);
+        const payload_start = buffer.position;
+        component_registry.adapter_for_id(type_id).serialize(buffer, component);
+        const payload_end = buffer.position;
+        buffer.position = len_position;
+        buffer.writeUint32(payload_end - payload_start);
+        buffer.position = payload_end;
+    }
+}
+
 /**
  * Apply a snapshot stream to a (typically empty) world, creating each entity
  * and attaching components.

package/src/engine/network/state/Baseline.d.ts

@@ -2,7 +2,7 @@
  * Per-peer "last acknowledged frame" tracker.
  *
  * The replicator sends actions for frames `[Baseline.last_acked(peer) + 1, current]`
- * to each peer. When the peer's ack arrives (via the {@link Channel}), it
+ * to each peer. When the peer's ack arrives (via its {@link Connection}), it
  * advances the baseline.
  *
  * Frame numbers are absolute uint32. At 60 Hz, 2^32 frames = 2.27 years —

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

@@ -4,7 +4,7 @@ import { assert } from "../../../core/assert.js";
  * Per-peer "last acknowledged frame" tracker.
  *
  * The replicator sends actions for frames `[Baseline.last_acked(peer) + 1, current]`
- * to each peer. When the peer's ack arrives (via the {@link Channel}), it
+ * to each peer. When the peer's ack arrives (via its {@link Connection}), it
  * advances the baseline.
  *
  * Frame numbers are absolute uint32. At 60 Hz, 2^32 frames = 2.27 years —

package/src/engine/network/state/FrameBufferRing.d.ts

@@ -15,12 +15,13 @@
  * owns storage and addressing and nothing else — it has no opinion about when a
  * frame may be opened or whether two may be open at once.
  *
- * Writers go through {@link open} then {@link commit}. Readers go through
- * {@link has}, {@link buffer_for} and {@link write_end_for}. A slot is claimed
- * by `open`, so it reads as present from that moment; its recorded length only
- * becomes meaningful at `commit`, which is why reading a frame that is still
- * being written yields the previous occupant's length. Owners that allow a
- * frame to stay open across calls are responsible for saying so.
+ * Writers go through {@link open} (or {@link resume}, to add to a frame) then
+ * {@link commit}. Readers go through {@link has}, {@link buffer_for} and
+ * {@link write_end_for}. A slot is claimed by `open`, so it reads as present
+ * from that moment; its recorded length is what was last committed — 0 for a
+ * slot `open` claimed, the old end for a frame `resume` reopened — so a reader
+ * sees none of what is still being written. Owners that allow a frame to stay
+ * open across calls are responsible for saying so.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -49,6 +50,24 @@ export class FrameBufferRing {
      * @returns {BinaryBuffer} positioned at 0, ready to be written
      */
     open(frame: number): BinaryBuffer;
+    /**
+     * Claim the slot for `frame` to write AFTER what it already holds: a slot holding `frame`
+     * hands back its buffer positioned at its committed end, and any other slot is claimed as
+     * {@link open} claims it. {@link commit} then fixes the longer length.
+     *
+     * @param {number} frame absolute frame number
+     * @returns {BinaryBuffer} positioned at the frame's committed end, ready to be written
+     */
+    resume(frame: number): BinaryBuffer;
+    /**
+     * Drop every slot's bytes and keep its frame: each frame the ring holds still reads as present,
+     * and as holding nothing.
+     */
+    empty(): void;
+    /**
+     * Release every slot: no frame reads as present until it is written again.
+     */
+    clear(): void;
     /**
      * Record how far the writer got, fixing the frame's length for readers.
      *

package/src/engine/network/state/FrameBufferRing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FrameBufferRing.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/state/FrameBufferRing.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IAoCI;;OAEG;IACH,4DAFW;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,mBAAmB,EAAE,MAAM,CAAA;KAAC,EAmB9E;IA5BD;;;;;OAKG;IACH,yBAFU,MAAM,CAED;IAwBf;;;;;;OAMG;IACH,YAHW,MAAM,GACJ,YAAY,CAcxB;IAED;;;;OAIG;IACH,cAFW,MAAM,QAQhB;IAED;;;;;OAKG;IACH,WAHW,MAAM,GACJ,OAAO,CAMnB;IAED;;;;;;OAMG;IACH,kBAHW,MAAM,GACJ,YAAY,CAYxB;IAED;;;;;;OAMG;IACH,qBAHW,MAAM,GACJ,MAAM,CAQlB;;CACJ;6BAtK4B,sCAAsC"}
+{"version":3,"file":"FrameBufferRing.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/state/FrameBufferRing.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IAoCI;;OAEG;IACH,4DAFW;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,mBAAmB,EAAE,MAAM,CAAA;KAAC,EAmB9E;IA5BD;;;;;OAKG;IACH,yBAFU,MAAM,CAED;IAwBf;;;;;;OAMG;IACH,YAHW,MAAM,GACJ,YAAY,CAkBxB;IAED;;;;;;;OAOG;IACH,cAHW,MAAM,GACJ,YAAY,CAgBxB;IAED;;;OAGG;IACH,cAEC;IAED;;OAEG;IACH,cAGC;IAED;;;;OAIG;IACH,cAFW,MAAM,QAQhB;IAED;;;;;OAKG;IACH,WAHW,MAAM,GACJ,OAAO,CAMnB;IAED;;;;;;OAMG;IACH,kBAHW,MAAM,GACJ,YAAY,CAYxB;IAED;;;;;;OAMG;IACH,qBAHW,MAAM,GACJ,MAAM,CAQlB;;CACJ;6BAnN4B,sCAAsC"}

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

@@ -18,12 +18,13 @@ import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
  * owns storage and addressing and nothing else — it has no opinion about when a
  * frame may be opened or whether two may be open at once.
  *
- * Writers go through {@link open} then {@link commit}. Readers go through
- * {@link has}, {@link buffer_for} and {@link write_end_for}. A slot is claimed
- * by `open`, so it reads as present from that moment; its recorded length only
- * becomes meaningful at `commit`, which is why reading a frame that is still
- * being written yields the previous occupant's length. Owners that allow a
- * frame to stay open across calls are responsible for saying so.
+ * Writers go through {@link open} (or {@link resume}, to add to a frame) then
+ * {@link commit}. Readers go through {@link has}, {@link buffer_for} and
+ * {@link write_end_for}. A slot is claimed by `open`, so it reads as present
+ * from that moment; its recorded length is what was last committed — 0 for a
+ * slot `open` claimed, the old end for a frame `resume` reopened — so a reader
+ * sees none of what is still being written. Owners that allow a frame to stay
+ * open across calls are responsible for saying so.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -104,9 +105,53 @@ export class FrameBufferRing {
 
         this.#frame_numbers[slot] = frame;
 
+        // Nothing of the new occupant is committed yet. Left alone, a slot claimed and never
+        // committed would report the previous occupant's length, and `resume` would write after it.
+        this.#write_ends[slot] = 0;
+
         return buffer;
     }
 
+    /**
+     * Claim the slot for `frame` to write AFTER what it already holds: a slot holding `frame`
+     * hands back its buffer positioned at its committed end, and any other slot is claimed as
+     * {@link open} claims it. {@link commit} then fixes the longer length.
+     *
+     * @param {number} frame absolute frame number
+     * @returns {BinaryBuffer} positioned at the frame's committed end, ready to be written
+     */
+    resume(frame) {
+        assert.isNonNegativeInteger(frame, 'frame');
+
+        const slot = frame % this.frame_capacity;
+
+        if (this.#frame_numbers[slot] !== frame) {
+            return this.open(frame);
+        }
+
+        const buffer = this.#buffers[slot];
+
+        buffer.position = this.#write_ends[slot];
+
+        return buffer;
+    }
+
+    /**
+     * Drop every slot's bytes and keep its frame: each frame the ring holds still reads as present,
+     * and as holding nothing.
+     */
+    empty() {
+        this.#write_ends.fill(0);
+    }
+
+    /**
+     * Release every slot: no frame reads as present until it is written again.
+     */
+    clear() {
+        this.#frame_numbers.fill(-1);
+        this.#write_ends.fill(0);
+    }
+
     /**
      * Record how far the writer got, fixing the frame's length for readers.
      *

package/src/engine/network/state/InputRing.d.ts

@@ -59,6 +59,10 @@ export class InputRing {
      * @param {function(BinaryBuffer): void} writer
      */
     write(frame: number, writer: (arg0: BinaryBuffer) => void): void;
+    /**
+     * Forget every frame's input: none reads as present until it is written again.
+     */
+    clear(): void;
     /**
      * @param {number} frame
      * @returns {boolean}

package/src/engine/network/state/InputRing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"InputRing.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/state/InputRing.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IAMI;;OAEG;IACH,qDAFW;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;KAAE,EAIlE;IAED;;;OAGG;IACH,6BAEC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,aAHW,MAAM,kCACkB,IAAI,QAQtC;IAED;;;OAGG;IACH,WAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;OAMG;IACH,kBAHW,MAAM,gBAKhB;IAED;;;OAGG;IACH,qBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,+BAJW,MAAM,aACN,MAAM,aACG,MAAM,4BAAgB,MAAM,KAAG,IAAI,QAmBtD;;CACJ"}
+{"version":3,"file":"InputRing.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/state/InputRing.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IAMI;;OAEG;IACH,qDAFW;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;KAAE,EAIlE;IAED;;;OAGG;IACH,6BAEC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,aAHW,MAAM,kCACkB,IAAI,QAQtC;IAED;;OAEG;IACH,cAEC;IAED;;;OAGG;IACH,WAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;OAMG;IACH,kBAHW,MAAM,gBAKhB;IAED;;;OAGG;IACH,qBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,+BAJW,MAAM,aACN,MAAM,aACG,MAAM,4BAAgB,MAAM,KAAG,IAAI,QAmBtD;;CACJ"}