@colyseus/core 0.17.44 → 0.18.1

package/build/input/InputBuffer.d.ts

@@ -0,0 +1,226 @@
+import type { ClientPrivate } from '../Transport.ts';
+import type { ConsumeOptions, IdleInput, InputAccessor, SanitizeInput } from './types.ts';
+/**
+ * @internal Validate a `subSteps` count. Throws on a fractional/non-positive
+ * value: both sides loop `subSteps` times at `dt/subSteps`, so anything but a
+ * whole number is a determinism bug, not a tunable. Shared by `defineInput`
+ * and `setFixedTimestep`.
+ */
+export declare function validateSubSteps(subSteps: number | undefined, source: string): number | undefined;
+/**
+ * @internal Compile a {@link SanitizeInput} spec into the per-frame function the
+ * decode path applies. The map form precompiles to dense min/max arrays walked
+ * with the NaN-safe branch clamp; the callback form passes through.
+ */
+export declare function compileSanitizer<I>(spec: SanitizeInput<I>): (input: I) => void;
+/** @internal */
+export declare class InputBufferImpl<I = any> {
+    /** Pending snapshots, indexed `[_head, _items.length)`. Consumed inputs are
+     *  NOT spliced off per-read — `_head` advances and the prefix is reclaimed in
+     *  bulk by {@link compact} (a `shift()` per read is O(n), so a burst would be
+     *  O(n²)). `_renderTimes`/`_reckonTimes` stay parallel to `_items`. */
+    private _items;
+    /** Read cursor: index of the oldest UNCONSUMED input (== `_items.length` when empty). */
+    private _head;
+    private _lastSeq;
+    private readonly _maxSize;
+    private readonly _seqField;
+    /**
+     * Cumulative count of inputs CONSUMED from this buffer (via any consume
+     * primitive — {@link next}/{@link take}/{@link drain}/{@link consume} — plus
+     * {@link clear} and overflow). Consumed = "removed from the pending set",
+     * whether applied to state or discarded. The server echoes this in the TIMED
+     * prefix as the reconciliation ack: how many of the client's inputs are
+     * reflected in (or finished influencing) the authoritative state, which lags
+     * the receive counter by inputs still buffered. Distinct from
+     * `_receivedInputCount` (receive-time, for RTT), which leads the state.
+     */
+    consumedCount: number;
+    /** Render times parallel to `_items` (server-clock ms; `0` when unset). */
+    private _renderTimes;
+    /** Render time of the most recently drained input (see {@link renderTime}). */
+    private _lastRenderTime;
+    /** Reckon-display stamps parallel to `_items` — the client's serverNow
+     *  estimate at input-sample time, i.e. the instant its forward-reckoned
+     *  entities were displayed at (server-clock ms; `0` when unset). */
+    private _reckonTimes;
+    /** Reckon stamp of the most recently consumed input (see {@link reckonTime}). */
+    private _lastReckonTime;
+    /** Framework wire seq per buffered input (parallel to `_items`) — UNRELIABLE
+     *  ONLY, lazily created on the first seq-carrying push. Reliable inputs are
+     *  contiguous, so their consumed-seq-value is always exactly {@link consumedCount}
+     *  and needs no parallel array; `undefined` here marks that (the common, default
+     *  path pays nothing). A buffer is single-mode, so this is either never created
+     *  (reliable) or created once and kept parallel (unreliable). */
+    private _seqs?;
+    /** Seq VALUE of the last consumed input — the reconciliation ack echoed to the
+     *  client (see {@link ackSeq}). Only meaningful when {@link _seqs} is tracked
+     *  (unreliable); reliable's ack falls back to {@link consumedCount}. */
+    private _lastConsumedSeq;
+    /** Whether the most recently produced frame was a synthesized idle (see {@link wasIdle}). */
+    private _lastWasIdle;
+    /** Reused {@link consume} iterator (lazily minted) + its per-call state, so a
+     *  per-tick loop allocates no generator frame. `_iterRemaining` snapshots the
+     *  COUNT to walk — a count, not an index: mid-pass mutations (`next()`/`take()`/
+     *  `clear()`/compaction) shift indices but can only shorten a count-based pass,
+     *  never point it past the tail. `_iterIdle` is an optional trailing synthesized
+     *  frame; `_iterActive` guards against a nested consume() clobbering the shared
+     *  `_iterRes`. */
+    private _iter?;
+    private _iterRemaining;
+    private _iterActive;
+    private _iterIdle?;
+    private readonly _iterRes;
+    /** Input schema ctor — mints the reused idle frame; idle is off without it. */
+    private readonly _ctor?;
+    /** Client slice this buffer belongs to (the live object is `Client & ClientPrivate`)
+     *  — feeds the idle callback's ctx (latest + sessionId). */
+    private readonly _client?;
+    /** Room-level idle policy (`defineInput({ idle })`) — the bare-call default. */
+    private readonly _roomIdle?;
+    /** Reused synthesized idle frame + the schema's field names/defaults (lazy). */
+    private _idle?;
+    private _fieldNames?;
+    private _defaults?;
+    /** Reused ctx for the idle callback form (see {@link IdleContext}). */
+    private readonly _idleCtx;
+    constructor(maxSize: number, seqField: string | undefined, ctor?: new () => I, client?: Pick<ClientPrivate, '_input'> & {
+        sessionId: string;
+    }, idle?: IdleInput<I>);
+    /** The effective idle policy for one consume call: per-call `false` suppresses,
+     *  per-call value overrides, else the room-level default (or none). */
+    private effectiveIdle;
+    /** Resolve an {@link IdleInput} to overrides — invokes the callback form
+     *  LAZILY, here at synthesis time (the buffer is known to be empty). */
+    private resolveIdle;
+    /**
+     * The synthesized "no input this tick" frame: schema defaults overlaid with
+     * `overrides` (`true` = none). Copies BY FIELD NAME from the schema metadata —
+     * schema fields are prototype accessors (no own props), so `Object.assign`
+     * can't source from a schema instance; the name walk reads getters, letting
+     * `overrides` be a plain partial OR a schema instance (e.g. `latest`).
+     * ONE reused instance — refilled per call, never advances the ack.
+     */
+    private idleFrame;
+    /** The idle frame to synthesize on an empty tick (room policy or per-call
+     *  `opts.idle`), or `undefined` when no policy is in effect. Reuses the single
+     *  idle instance; never advances the ack. Callers set {@link wasIdle}. */
+    private idleFrameOnEmpty;
+    /** Consume the input at the cursor: advance cursor + ack, stamp THIS input's
+     *  render/reckon times, clear {@link wasIdle}. The shared per-input step behind
+     *  {@link next}, {@link consume}'s iterator, and the re-entrant fallback. */
+    private stepHead;
+    /** Drop ALL slots, reusing the backing arrays' capacity — the zero-GC reset for
+     *  the consume/next path ({@link compact}/{@link clear}). `drain()` deliberately
+     *  does NOT use this (it returns an array, so fresh `[]` is faster there). */
+    private truncate;
+    /**
+     * Append a decoded input snapshot. `seq` is the framework wire seq (unreliable);
+     * omit it for reliable inputs, which get an implicit monotonic receive count so
+     * {@link ackSeq} stays well-defined in both modes.
+     */
+    push(snapshot: I, renderTime?: number, reckonTime?: number, seq?: number): void;
+    /** Reclaim the consumed prefix `[0, _head)`. Free when fully drained (reuse the
+     *  arrays); otherwise splice only once the cursor passes {@link COMPACT_THRESHOLD},
+     *  so the amortized per-input cost stays O(1). */
+    private compact;
+    /** Returns true if `value` hasn't been seen, and updates the last-seen marker. */
+    accept(value: number): boolean;
+    drain(opts?: ConsumeOptions<I>): I[];
+    /** Consume the single oldest input (ack advances by one); `undefined` if
+     *  empty — or the synthesized idle frame when an idle policy is in effect. */
+    next(opts?: ConsumeOptions<I>): I | undefined;
+    /** Consume up to `n` oldest inputs (ack advances by the count actually taken). */
+    take(n: number): I[];
+    /**
+     * Iterate pending inputs one at a time (per-yield ack + stamp updates), or
+     * exactly one synthesized idle frame on an empty buffer with a policy in
+     * effect. See {@link InputAccessor.consume}.
+     *
+     * Returns a POOLED iterator (reused across calls — no generator frame, no
+     * per-call allocation) that consumes at most the pending count snapshotted at
+     * the call — never past the live tail — plus one optional trailing idle frame.
+     * The cursor advances per `next()`, so `break` (which calls `return()`)
+     * leaves the rest buffered and compacts. A nested
+     * `consume()` of the SAME buffer while one is live falls back to a fresh
+     * generator so the pooled `_iterRes` isn't clobbered (nesting is meaningless —
+     * both share the cursor — but it must not corrupt).
+     */
+    consume(opts?: ConsumeOptions<I>): IterableIterator<I>;
+    [Symbol.iterator](): IterableIterator<I>;
+    /** Lazily mint the reused iterator. Closures over `this` so it reads the
+     *  private cursor directly; one `_iterRes` is reused — read each result before
+     *  the next `next()`, as `for..of` / spread / `Array.from` all do. */
+    private ensureIter;
+    /** Re-entrant fallback: a fresh generator for a nested `consume()` of this same
+     *  buffer (the pooled iterator is single-active). Same accounting + compaction. */
+    private consumeGen;
+    peek(): I[];
+    at(value: number): I | undefined;
+    get size(): number;
+    /** Render time (server-clock ms) of the most recently drained input; `0`
+     *  until the first render-time-stamped input is drained. */
+    get renderTime(): number;
+    /** Reckon-display stamp of the most recently consumed input — the client's
+     *  serverNow estimate when it sampled that input, i.e. the EXACT instant its
+     *  forward-reckoned entities were displayed at. Same consume semantics as
+     *  {@link renderTime}. RAW: stays `0` until stamped — the resolved,
+     *  always-usable value is the accessor's `reckonTime`
+     *  (`room.inputs.get(sid)`); `rewind.lastSeenBy()`'s midpoint-reconstruction
+     *  fallback depends on this raw `0`. */
+    get reckonTime(): number;
+    /** Seq VALUE of the last consumed input — the reconciliation ack sent to the
+     *  client. Reliable (no wire seq tracked): falls back to {@link consumedCount}
+     *  for free. Unreliable: the framework wire seq, so a fully-dropped input doesn't
+     *  make the ack lag the client's sent seq by the lost count. `0` before the first
+     *  consume. */
+    get ackSeq(): number;
+    /** Whether the most recently produced frame was a synthesized idle (see {@link wasIdle}). */
+    get wasIdle(): boolean;
+    clear(): void;
+}
+/**
+ * Default per-client accessor. Reads `_input` and `_inputBuffer` off the
+ * client at access time — both are nullable until the room declares input
+ * via `defineInput()`. Cached as `client._inputAccessor` at join, so
+ * `room.inputs.get(sessionId)` is a Map lookup + property read.
+ *
+ * @internal
+ */
+export declare class InputAccessorImpl<I = any> implements InputAccessor<I> {
+    private _client;
+    /** Current room time (`clock.elapsedTime`) — resolves the {@link reckonTime}
+     *  fallback. Threaded by `RoomInput.allocate()`; optional so bare
+     *  constructions (tests) keep the raw 0. */
+    private _nowOf?;
+    constructor(client: ClientPrivate, nowOf?: () => number);
+    get latest(): I | undefined;
+    at(value: number): I | undefined;
+    consume(opts?: ConsumeOptions<I>): IterableIterator<I>;
+    [Symbol.iterator](): IterableIterator<I>;
+    drain(opts?: ConsumeOptions<I>): I[];
+    next(): I | undefined;
+    next(opts: {
+        idle: IdleInput<I>;
+    }): I;
+    take(n: number): I[];
+    peek(): I[];
+    get size(): number;
+    get consumedCount(): number;
+    get wasIdle(): boolean;
+    clear(): void;
+    get renderTime(): number;
+    /** @internal RAW reckon stamp (0 until stamped). The rewind binding reads
+     *  THIS, not the resolved getter below: `Rewind._aim`'s midpoint fallback
+     *  must still see 0 for unstamped clients (a resolved value would silently
+     *  take the direct-stamp clamp path). */
+    get rawReckonTime(): number;
+    get reckonTime(): number;
+}
+/**
+ * Returned by `room.inputs.get(sessionId)` for unknown sessions and for rooms
+ * that didn't call `defineInput()`.
+ *
+ * @internal
+ */
+export declare const NO_OP_INPUT_ACCESSOR: InputAccessor<any>;