@colyseus/core 0.18.0 → 0.18.1

package/build/input/InputBuffer.d.ts

@@ -1,134 +1,224 @@
 import type { ClientPrivate } from '../Transport.ts';
+import type { ConsumeOptions, IdleInput, InputAccessor, SanitizeInput } from './types.ts';
 /**
- * Names of fields on `I` whose values are `number` — used by
- * `Room.defineInput()` to constrain `seqField` to actually-numeric fields
- * on the input schema. Filters out booleans, strings, methods, etc.
+ * @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 type NumericFieldsOf<I> = {
-    [K in keyof I]: I[K] extends number ? (K extends string ? K : never) : never;
-}[keyof I];
+export declare function validateSubSteps(subSteps: number | undefined, source: string): number | undefined;
 /**
- * Internal: input configuration captured by `Room.defineInput()`. The schema
- * constructor is stored here so the runtime doesn't need to know it through
- * the public `room.input` (which is now a callable accessor).
- *
- * @internal
+ * @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 interface InputOptions {
+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;
     /**
-     * Schema constructor used to allocate per-client input instances on join.
-     * Captured by `defineInput()` from its `type` argument.
-     *
-     * Typed loosely (`new () => any`) to sidestep type-identity issues across
-     * duplicate `@colyseus/schema` installs; the runtime calls
-     * `instance.clone()` and friends, which match by shape.
+     * 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.
      */
-    ctor: new () => any;
+    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;
     /**
-     * Name of a monotonically-increasing numeric field on the input schema used
-     * to order and dedupe incoming frames. When set, the framework:
-     * - Drops redundant frames (`input[seqField]` ≤ the last-seen value are
-     *   discarded before they enter the buffer). Matches the unreliable-mode
-     *   ring-redundancy pattern out of the box.
-     * - Powers `room.input(sessionId).at(value)` lookups.
-     *
-     * Despite the name, "seq" here is broader than an integer counter — any
-     * monotonic numeric field works:
-     * - **Sequence counter** (`"seq"`, `"tick"`, `"frame"`) — typical for
-     *   lockstep / rollback netcode (Photon Quantum, GGPO).
-     * - **Timestamp** (`"timestamp"`, milliseconds or seconds) — useful for
-     *   variable-rate clients, lag compensation, hit registration (Unreal CMC
-     *   uses float-seconds timestamps via `FSavedMove_Character.TimeStamp`).
-     *
-     * Whichever you use, the field must increase monotonically across frames
-     * for dedupe to work.
+     * 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.
      */
-    seqField?: string;
+    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;
     /**
-     * > 0 enables per-client buffering of cloned snapshots — required for
-     * `room.input(sessionId).drain() / .peek() / .at()` to return populated
-     * data. Oldest drops on overflow. Set to `0` to disable (`.latest` still
-     * works).
+     * 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.
      */
-    bufferMaxSize: number;
-}
-/**
- * Per-client input accessor returned by `room.input(sessionId)`. Combines the
- * latest decoded instance with the (optional) snapshot ring buffer.
- *
- * - {@link latest} — the bound Schema instance, mutated in place by the
- *   decoder. Cheapest read; use when only the most recent state matters.
- * - {@link drain} / {@link peek} / {@link at} — populated when
- *   `defineInput()` was called with `bufferMaxSize > 0` (default 32).
- *   Use for rollback netcode / lockstep where every frame matters.
- *
- * Returned for unknown sessionIds and rooms without `defineInput()` is a
- * frozen no-op accessor (latest=undefined, drain/peek=[], at=undefined,
- * size=0, clear=no-op).
- */
-export interface InputAccessor<I = any> {
-    /** Latest decoded input. `undefined` when unknown sessionId or no input declared. */
-    readonly latest: I | undefined;
+    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[];
     /**
-     * Find the buffered snapshot whose `[seqField]` equals `value`. The field
-     * name is the Room's `defineInput()` `seqField`. Linear scan — cheap for
-     * typical buffer sizes; not intended for very large rings. Returns
-     * `undefined` when no match is buffered (or `seqField` isn't configured).
+     * 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}.
      *
-     * Useful for tick-aligned retrieval (lockstep, rollback).
+     * 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).
      */
-    at(value: number): I | undefined;
-    /** Take everything buffered (oldest → newest) and clear. Snapshots are safe to retain. */
-    drain(): I[];
-    /** Read everything buffered without consuming. */
-    peek(): I[];
-    /** Number of snapshots currently buffered. */
-    readonly size: number;
-    /** Drop all buffered snapshots (also resets the dedupe tracker). */
-    clear(): void;
-}
-/**
- * Callable returned by `Room.defineInput()`. Assign it to `this.input` and
- * call `room.input(sessionId)` per tick to read each client's latest input
- * and/or buffered snapshots.
- */
-export type InputAPI<I = any> = (sessionId: string) => InputAccessor<I>;
-/** @internal */
-export declare class InputBufferImpl<I = any> {
-    private _items;
-    private _lastSeq;
-    private readonly _maxSize;
-    private readonly _seqField;
-    constructor(maxSize: number, seqField: string | undefined);
-    push(snapshot: I): void;
-    /** Returns true if `value` hasn't been seen, and updates the last-seen marker. */
-    accept(value: number): boolean;
-    drain(): I[];
+    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.input(sessionId)` is a Map lookup + property read.
+ * `room.inputs.get(sessionId)` is a Map lookup + property read.
  *
  * @internal
  */
 export declare class InputAccessorImpl<I = any> implements InputAccessor<I> {
     private _client;
-    constructor(client: ClientPrivate);
+    /** 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;
-    drain(): I[];
+    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.input(sessionId)` for unknown sessions and for rooms
+ * Returned by `room.inputs.get(sessionId)` for unknown sessions and for rooms
  * that didn't call `defineInput()`.
  *
  * @internal