@woosh/meep-engine/src/engine/network/state/MutationLedger.d.ts

Pure JavaScript game engine. Fully featured and production ready.

/**
 * Append-only per-tick log of "which entities mutated this tick", recorded as
 * compact varint sequences in a single backing buffer.
 *
 * Used by the server to answer the recovery query: *"which entities changed
 * between tick X and tick Y?"* — the client asks this when it detects loss
 * beyond the ActionLog retry window, so it can request the current state of
 * just those entities instead of a full re-init.
 *
 * Keeps one global log (NOT per-client). Entry header per tick is small
 * (`{tick, offset, length}` = ~16 bytes); the per-id payload is one varint
 * each. At 60 Hz with 1k mutations/sec this is ~60 KB/min uncompacted.
 *
 * Trim: caller invokes {@link drop_through} periodically to release old
 * ticks. The backing buffer is re-packed in place via `Uint8Array.copyWithin`
 * so memory stays bounded. Beyond the retained window, the recovery answer
 * is "you're too far behind — full re-init."
 *
 * @author Alex Goldring
 * @copyright Company Named Limited (c) 2025
 */
export class MutationLedger {
    /**
     * @param {{ initial_buffer_size?: number }} [options]
     */
    constructor({ initial_buffer_size }?: {
        initial_buffer_size?: number;
    });
    /**
     * Record the contents of `changed_set` as the mutations for `tick_number`.
     * Tick numbers must be monotonically non-decreasing across calls; recording
     * the same tick twice appends a second entry (which is fine — range
     * queries will union them).
     *
     * @param {number} tick_number
     * @param {ChangedEntitySet} changed_set
     */
    record_tick(tick_number: number, changed_set: ChangedEntitySet): void;
    /**
     * Read every network ID recorded in any tick within `[start_tick, end_tick]`
     * (inclusive on both ends) and add it to `output_set`. Duplicate IDs across
     * ticks are deduped naturally by the set.
     *
     * @param {ChangedEntitySet} output_set caller-owned destination; not cleared
     * @param {number} start_tick
     * @param {number} end_tick
     */
    entities_changed_in_range(output_set: ChangedEntitySet, start_tick: number, end_tick: number): void;
    /**
     * Drop all entries whose tick is `<=` `tick_number` and reclaim their
     * buffer space. After this call, queries below `tick_number` return nothing.
     *
     * @param {number} tick_number
     */
    drop_through(tick_number: number): void;
    /**
     * Earliest tick still recorded, or -1 if empty.
     * @returns {number}
     */
    earliest_recorded_tick(): number;
    /**
     * Most recent tick recorded, or -1 if empty.
     * @returns {number}
     */
    latest_recorded_tick(): number;
    /**
     * Number of recorded ticks (not network IDs).
     * @returns {number}
     */
    size(): number;
    /**
     * Bytes currently held in the backing buffer (after any drops).
     * @returns {number}
     */
    byte_size(): number;
    /**
     * Drop everything.
     */
    clear(): void;
    #private;
}
//# sourceMappingURL=MutationLedger.d.ts.map