@woosh/meep-engine 2.138.0 → 2.138.1

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

@@ -0,0 +1,189 @@
+import { assert } from "../../../core/assert.js";
+import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
+
+/**
+ * Per-frame ring of action records.
+ *
+ * Each frame's `BinaryBuffer` holds a sequence of action records. One record per
+ * `SimActionExecutor.execute` call:
+ *
+ * ```
+ *   varint:    prior_state_count
+ *   loop:
+ *     varint:  entity_id
+ *     uint8:   component_type_id   (assigned by the ReplicatedComponentRegistry)
+ *     uint32:  prior_payload_len
+ *     bytes:   prior_payload       (adapter.serialize of the component's prior state)
+ *   uint8:     action_type_id
+ *   uint8:     sender_id           (peer that originated the action; local-only,
+ *                                   STRIPPED by Replicator before send)
+ *   uint32:    action_payload_len
+ *   bytes:     action_payload      (the action's own serialize output)
+ * ```
+ *
+ * Self-describing: records can be skipped without consulting the action registry,
+ * which means rewind code can walk records forward to find boundaries, then
+ * iterate backward to apply prior states — no need to instantiate any actions.
+ *
+ * Note that `sender_id` is recorded in-buffer for local rollback orchestrators
+ * (stable-sort tie-breaking by sender on replay) but never crosses the wire —
+ * {@link Replicator#pack_for_peer} strips it and the receiver derives sender
+ * from the inbound packet's peer_id, so a hostile peer cannot impersonate.
+ *
+ * Ring depth is set at construction. When the ring fills, the oldest frame's
+ * buffer is recycled for the new frame.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2025
+ */
+export class ActionLog {
+    #buffers;
+    #frame_numbers;
+    #write_ends;
+    #current_frame;
+
+
+    /**
+     * @param {{ frame_capacity: number, initial_buffer_size?: number }} options
+     */
+    constructor({ frame_capacity, initial_buffer_size = 4096 }) {
+        if (!Number.isInteger(frame_capacity) || frame_capacity <= 0) {
+            throw new Error(`ActionLog: frame_capacity must be a positive integer, got ${frame_capacity}`);
+        }
+
+        /**
+         * @readonly
+         * @type {number}
+         */
+        this.frame_capacity = frame_capacity;
+
+        /**
+         * Per-frame buffers. Index by `frame % frame_capacity`.
+         * @type {BinaryBuffer[]}
+         * @private
+         */
+        this.#buffers = new Array(frame_capacity);
+
+        /**
+         * Per-frame absolute frame numbers (so we can detect "this slot is stale").
+         * `-1` means the slot has not yet been used.
+         * @type {Int32Array}
+         * @private
+         */
+        this.#frame_numbers = new Int32Array(frame_capacity).fill(-1);
+
+        /**
+         * Per-frame "write end" position. The buffer's own `position` is reused
+         * when actively writing; this is captured at frame_end so readers know
+         * where the meaningful data ends.
+         * @type {Int32Array}
+         * @private
+         */
+        this.#write_ends = new Int32Array(frame_capacity);
+
+        for (let i = 0; i < frame_capacity; i++) {
+            this.#buffers[i] = new BinaryBuffer();
+            this.#buffers[i].setCapacity(initial_buffer_size);
+        }
+
+        /**
+         * Frame number currently being written to, or -1 if no frame is open.
+         * @type {number}
+         * @private
+         */
+        this.#current_frame = -1;
+    }
+
+    /**
+     * Open a new frame for writing. Recycles the oldest slot if the ring is full.
+     *
+     * @param {number} frame absolute frame number
+     */
+    begin_frame(frame) {
+        assert.isNonNegativeInteger(frame, 'frame');
+
+        if (this.#current_frame !== -1) {
+            throw new Error(`ActionLog.begin_frame: previous frame ${this.#current_frame} still open; call end_frame first`);
+        }
+
+        const slot = frame % this.frame_capacity;
+        const buffer = this.#buffers[slot];
+
+        buffer.position = 0;
+        this.#frame_numbers[slot] = frame;
+        this.#current_frame = frame;
+    }
+
+    /**
+     * Close the currently-open frame.
+     */
+    end_frame() {
+        if (this.#current_frame === -1) {
+            throw new Error(`ActionLog.end_frame: no frame is open`);
+        }
+        const slot = this.#current_frame % this.frame_capacity;
+        this.#write_ends[slot] = this.#buffers[slot].position;
+        this.#current_frame = -1;
+    }
+
+    /**
+     * Get the buffer for the currently-open frame for direct writing.
+     *
+     * @returns {BinaryBuffer}
+     */
+    current_buffer() {
+        if (this.#current_frame === -1) {
+            throw new Error(`ActionLog.current_buffer: no frame is open`);
+        }
+        return this.#buffers[this.#current_frame % this.frame_capacity];
+    }
+
+    /**
+     * Has the given frame number ever been written, and is it still in the ring?
+     *
+     * @param {number} frame
+     * @returns {boolean}
+     */
+    has_frame(frame) {
+        assert.isNonNegativeInteger(frame, 'frame');
+        const slot = frame % this.frame_capacity;
+        return this.#frame_numbers[slot] === frame;
+    }
+
+    /**
+     * Read-only access to a closed frame's buffer. Throws if the frame is not in the ring.
+     * 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, `__write_ends[slot]` still holds the previous occupant's
+     * length — `buffer_for`/`write_end_for` would return mismatched
+     * buffer-contents-vs-length and any reader would walk garbage.
+     *
+     * @param {number} frame
+     * @returns {BinaryBuffer}
+     */
+    buffer_for(frame) {
+        assert.isNonNegativeInteger(frame, 'frame');
+        if (!this.has_frame(frame)) {
+            throw new Error(`ActionLog.buffer_for: frame ${frame} is not present in the ring`);
+        }
+        const slot = frame % this.frame_capacity;
+        const buffer = this.#buffers[slot];
+        buffer.position = 0;
+        return buffer;
+    }
+
+    /**
+     * Number of valid bytes written to the given frame's buffer.
+     * @param {number} frame
+     * @returns {number}
+     */
+    write_end_for(frame) {
+        assert.isNonNegativeInteger(frame, 'frame');
+        if (!this.has_frame(frame)) {
+            throw new Error(`ActionLog.write_end_for: frame ${frame} is not present in the ring`);
+        }
+        const slot = frame % this.frame_capacity;
+        return this.#write_ends[slot];
+    }
+}

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

@@ -0,0 +1,58 @@
+/**
+ * The blend math an adapter performs. Read by higher-level wiring to
+ * decide whether the adapter is compatible with the current rendering
+ * pipeline.
+ */
+export type InterpolationKind = number;
+/**
+ * The blend math an adapter performs. Read by higher-level wiring to
+ * decide whether the adapter is compatible with the current rendering
+ * pipeline.
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const InterpolationKind: Readonly<{
+    /** No blending — output is one of the two snapshots exactly. */
+    Discrete: 0;
+    /** Linear blend at fractional `t ∈ [0, 1]` between two snapshots. */
+    Linear: 1;
+    /** Cubic between four samples. Reserved; not yet supported. */
+    Cubic: 2;
+}>;
+/**
+ * Per-component-type interpolator: reads two encoded snapshots of one
+ * component from `source`, blends by `t`, writes the result to
+ * `out_buffer` in the SAME wire format so the receiver can deserialize
+ * directly via the corresponding `BinaryClassSerializationAdapter`.
+ *
+ * Pair with {@link InterpolationLog}, which resolves
+ * `(network_id, type_id, tick) → byte offset` so the adapter only sees
+ * offsets.
+ *
+ * Subclasses override `kind` if their blend math is non-linear; the
+ * default is `Linear`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2025
+ */
+export class BinaryInterpolationAdapter {
+    /** @type {number} one of {@link InterpolationKind} */
+    kind: number;
+    /**
+     * Advance `out_buffer.position` past the bytes written. `source.position`
+     * may be mutated freely (the log restores it).
+     *
+     * `first_offset === second_offset` is the degenerate "snap to single
+     * snapshot" case — implementations don't need to special-case it; the
+     * blend at any `t` reduces to the input.
+     *
+     * @param {BinaryBuffer} out_buffer
+     * @param {BinaryBuffer} source
+     * @param {number} first_offset byte position of snapshot A
+     * @param {number} second_offset byte position of snapshot B
+     * @param {number} t blend fraction in [0, 1]; 0 ⇒ A, 1 ⇒ B
+     */
+    interpolate(out_buffer: BinaryBuffer, source: BinaryBuffer, first_offset: number, second_offset: number, t: number): void;
+}
+//# sourceMappingURL=BinaryInterpolationAdapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BinaryInterpolationAdapter.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/BinaryInterpolationAdapter.js"],"names":[],"mappings":";;;;;gCAMU,MAAM;AANhB;;;;;;;GAOG;AACH;IACI,gEAAgE;;IAEhE,qEAAqE;;IAErE,+DAA+D;;GAEhE;AAEH;;;;;;;;;;;;;;;GAeG;AACH;IAEI,sDAAsD;IACtD,MADW,MAAM,CACe;IAEhC;;;;;;;;;;;;;OAaG;IACH,0EAJW,MAAM,iBACN,MAAM,KACN,MAAM,QAIhB;CACJ"}

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

@@ -0,0 +1,56 @@
+/**
+ * The blend math an adapter performs. Read by higher-level wiring to
+ * decide whether the adapter is compatible with the current rendering
+ * pipeline.
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const InterpolationKind = Object.freeze({
+    /** No blending — output is one of the two snapshots exactly. */
+    Discrete: 0,
+    /** Linear blend at fractional `t ∈ [0, 1]` between two snapshots. */
+    Linear: 1,
+    /** Cubic between four samples. Reserved; not yet supported. */
+    Cubic: 2,
+});
+
+/**
+ * Per-component-type interpolator: reads two encoded snapshots of one
+ * component from `source`, blends by `t`, writes the result to
+ * `out_buffer` in the SAME wire format so the receiver can deserialize
+ * directly via the corresponding `BinaryClassSerializationAdapter`.
+ *
+ * Pair with {@link InterpolationLog}, which resolves
+ * `(network_id, type_id, tick) → byte offset` so the adapter only sees
+ * offsets.
+ *
+ * Subclasses override `kind` if their blend math is non-linear; the
+ * default is `Linear`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2025
+ */
+export class BinaryInterpolationAdapter {
+
+    /** @type {number} one of {@link InterpolationKind} */
+    kind = InterpolationKind.Linear;
+
+    /**
+     * Advance `out_buffer.position` past the bytes written. `source.position`
+     * may be mutated freely (the log restores it).
+     *
+     * `first_offset === second_offset` is the degenerate "snap to single
+     * snapshot" case — implementations don't need to special-case it; the
+     * blend at any `t` reduces to the input.
+     *
+     * @param {BinaryBuffer} out_buffer
+     * @param {BinaryBuffer} source
+     * @param {number} first_offset byte position of snapshot A
+     * @param {number} second_offset byte position of snapshot B
+     * @param {number} t blend fraction in [0, 1]; 0 ⇒ A, 1 ⇒ B
+     */
+    interpolate(out_buffer, source, first_offset, second_offset, t) {
+        throw new Error('BinaryInterpolationAdapter subclasses must override interpolate(out, src, off_a, off_b, t).');
+    }
+}

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

@@ -0,0 +1,165 @@
+/**
+ * Per-tick recording of replicated component state for snapshot interpolation.
+ *
+ * Two ring buffers — both wrap at tick boundaries only:
+ *
+ *   - `__buffer` (BinaryBuffer): raw component bytes, written via `begin_record`
+ *     / `end_record`. Variable size per record.
+ *
+ *   - `__records` (Uint32Array): the metadata table, holding one row per
+ *     `(network_id, type_id, byte_offset, byte_length)` plus a bloom-filter
+ *     header every {@link METADATA_PAGE_SIZE} records. The structure:
+ *
+ *       page = [bloom_0..7] [rec_0_n, _t, _o, _l] ... [rec_38_n, _t, _o, _l]
+ *
+ *     A new page header is written at `begin_tick` and then again every 39
+ *     records within a tick. The bloom filter is keyed by `network_id`, so a
+ *     `locate(network_id, type_id)` can skip whole pages with a single 256-bit
+ *     check before falling back to a per-record scan inside the page. Pages
+ *     never straddle tick boundaries.
+ *
+ * Per-tick metadata is small: byte range + word range in `__records` + record
+ * count. The oldest tick is tracked explicitly (`__oldest_tick`) so the squash
+ * check at each {@link begin_tick} is amortized O(1) — squash the oldest while
+ * it overlaps the new write region, advance the pointer, repeat.
+ *
+ * Pair with {@link BinaryInterpolationAdapter} concrete subclasses (e.g.
+ * {@link Vector3InterpolationAdapter}) which know each component type's
+ * encoding and blend math.
+ *
+ * Typical receive-side use:
+ * ```
+ *   onFrameApplied(_, frame_number) {
+ *       log.begin_tick(frame_number);
+ *       const buf = log.begin_record(network_id, type_id);
+ *       adapter.serialize(buf, value);
+ *       log.end_record();
+ *       log.end_tick();
+ *   }
+ * ```
+ *
+ * Typical render-time use:
+ * ```
+ *   const ok = log.interpolate(out_buffer, network_id, type_id, tick_a, tick_b, t, adapter);
+ *   if (ok) { /* deserialize from out_buffer into the live component }
+ * ```
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2025
+ */
+export class InterpolationLog {
+    /**
+     * @param {{ buffer_capacity_bytes?: number, records_capacity?: number }} [options]
+     *   `records_capacity` is in *records* (not bytes); the underlying word
+     *   array is sized large enough to fit that many records plus their pages'
+     *   bloom-filter headers.
+     */
+    constructor({ buffer_capacity_bytes, records_capacity }?: {
+        buffer_capacity_bytes?: number;
+        records_capacity?: number;
+    });
+    /** @readonly @type {number} */
+    readonly buffer_capacity: number;
+    /** @readonly @type {number} */
+    readonly records_capacity: number;
+    /**
+     * Open a new tick for recording. May wrap either ring at this point — but
+     * never mid-tick, so a single tick's data is always contiguous in both
+     * the byte buffer and the metadata table. After wrapping, any old tick
+     * whose data overlaps the new write region is squashed (in oldest-first
+     * order) and `__oldest_tick` advances.
+     *
+     * @param {number} tick non-negative integer
+     */
+    begin_tick(tick: number): void;
+    /**
+     * Begin recording one component. Returns the underlying byte buffer
+     * positioned at the next write slot — the caller writes the component
+     * payload directly (e.g. via a `BinaryClassSerializationAdapter.serialize`
+     * call), then calls {@link end_record} to finalize the (offset, length).
+     *
+     * Splitting begin/end (vs. taking a write callback) avoids the per-record
+     * closure allocation and lets the caller pass the buffer straight to an
+     * adapter without wrapping.
+     *
+     * @param {number} network_id
+     * @param {number} type_id component type id (small integer; matches the registry)
+     * @returns {BinaryBuffer} the log's byte buffer, positioned for writing the payload
+     */
+    begin_record(network_id: number, type_id: number): BinaryBuffer;
+    /**
+     * Finalize the in-progress record opened by {@link begin_record}. Reads
+     * the buffer's current position to compute the payload length, inserts
+     * the network_id into the current page's bloom filter, writes the row to
+     * the metadata table, and advances the cursors.
+     */
+    end_record(): void;
+    /**
+     * Close the currently-open tick. Updates the max-observed-tick sizes so
+     * the next {@link begin_tick} can size its wrap heuristic correctly.
+     *
+     * Throws if a record is still open — silently dropping the in-progress
+     * record's metadata (offset/length) would leak buffer space and produce
+     * stale bytes that no one can locate.
+     */
+    end_tick(): void;
+    /**
+     * @param {number} tick
+     * @returns {boolean} true if the tick has live (non-squashed) data
+     */
+    has_tick(tick: number): boolean;
+    /**
+     * Find a component's stored slice within a tick. Walks the tick's pages,
+     * bloom-filter-skipping pages that don't contain `network_id`, and
+     * scanning records inside any page where the bloom hits.
+     *
+     * On success, writes `out[out_offset+0] = byte_offset` and
+     * `out[out_offset+1] = byte_length`.
+     *
+     * @param {number[]|Uint32Array} out
+     * @param {number} out_offset
+     * @param {number} tick
+     * @param {number} network_id
+     * @param {number} type_id
+     * @returns {boolean} false if the tick is missing/squashed or doesn't carry this component
+     */
+    locate(out: number[] | Uint32Array, out_offset: number, tick: number, network_id: number, type_id: number): boolean;
+    /**
+     * Interpolate one component between two ticks via `adapter` and write the
+     * result to `out_buffer` at its current position.
+     *
+     * Outcome by available data:
+     *   - Both ticks carry the component → adapter blends them at `t`.
+     *   - Only one carries it → adapter is called with the same offset twice
+     *     (snap to the surviving snapshot; `t` is irrelevant).
+     *   - Neither carries it → returns false; `out_buffer` is unchanged.
+     *
+     * @param {BinaryBuffer} out_buffer
+     * @param {number} network_id
+     * @param {number} type_id
+     * @param {number} tick_a
+     * @param {number} tick_b
+     * @param {number} t
+     * @param {BinaryInterpolationAdapter} adapter
+     * @returns {boolean} true if a payload was written; false if neither tick has the component
+     */
+    interpolate(out_buffer: BinaryBuffer, network_id: number, type_id: number, tick_a: number, tick_b: number, t: number, adapter: BinaryInterpolationAdapter): boolean;
+    /**
+     * Number of ticks currently held. Squashed ticks are excluded.
+     * @returns {number}
+     */
+    size(): number;
+    /**
+     * Tick number of the oldest live tick, or -1 if empty.
+     * @returns {number}
+     */
+    oldest_tick(): number;
+    /**
+     * Drop all recorded ticks. Resets both ring cursors to 0. Useful on
+     * reconnect or level transition.
+     */
+    clear(): void;
+    #private;
+}
+import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
+//# sourceMappingURL=InterpolationLog.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"InterpolationLog.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/InterpolationLog.js"],"names":[],"mappings":"AA6EA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH;IAkBI;;;;;OAKG;IACH,0DALW;QAAE,qBAAqB,CAAC,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE,EAkGvE;IA9EG,+BAA+B;IAC/B,0BADqB,MAAM,CACiB;IAe5C,+BAA+B;IAC/B,2BADqB,MAAM,CACa;IA+D5C;;;;;;;;OAQG;IACH,iBAFW,MAAM,QAkEhB;IAED;;;;;;;;;;;;;OAaG;IACH,yBAJW,MAAM,WACN,MAAM,GACJ,YAAY,CAmCxB;IAED;;;;;OAKG;IACH,mBAsDC;IAED;;;;;;;OAOG;IACH,iBAeC;IAED;;;OAGG;IACH,eAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;;;;;;OAcG;IACH,YAPW,MAAM,EAAE,GAAC,WAAW,cACpB,MAAM,QACN,MAAM,cACN,MAAM,WACN,MAAM,GACJ,OAAO,CA+BnB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,wBATW,YAAY,cACZ,MAAM,WACN,MAAM,UACN,MAAM,UACN,MAAM,KACN,MAAM,wCAEJ,OAAO,CAuBnB;IAED;;;OAGG;IACH,QAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,eAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,cASC;;CACJ;6BArkB4B,sCAAsC"}