@colyseus/schema 4.0.20 → 5.0.1

package/build/input/InputDecoder.d.ts

@@ -0,0 +1,32 @@
+import type { Schema } from "../Schema.js";
+/**
+ * Bound single-struct decoder for input packets. Wraps the standard
+ * `Decoder` so bytes emitted by `InputEncoder` land on the bound instance.
+ *
+ * - `decode(bytes)`: single-input packet (reliable mode).
+ * - `decodeAll(bytes, cb)`: multi-input length-framed packet (unreliable
+ *   mode). Invokes `cb` with the mutated instance once per framed input,
+ *   oldest → newest. The instance is re-used across callbacks — consume
+ *   synchronously (apply to game state) rather than holding the reference.
+ */
+export declare class InputDecoder<T extends Schema = any> {
+    readonly instance: T;
+    private readonly _decoder;
+    private readonly _it;
+    constructor(instance: T);
+    /**
+     * Decode a single-input (reliable) packet into the bound instance.
+     * Returns the instance for chaining.
+     */
+    decode(bytes: Uint8Array): T;
+    /**
+     * Walk a multi-input (unreliable) packet, decoding each length-framed
+     * input into the bound instance in order and invoking `onInput` after
+     * each decode. `onInput` receives the bound instance itself — reads
+     * must be synchronous; downstream code should apply the input to game
+     * state, not retain the reference.
+     *
+     * Returns the number of inputs decoded.
+     */
+    decodeAll(bytes: Uint8Array, onInput: (instance: T, index: number) => void): number;
+}

package/build/input/InputEncoder.d.ts

@@ -0,0 +1,117 @@
+import type { Schema } from "../Schema.js";
+/**
+ * Delivery-channel hint. Controls the wire layout:
+ * - `"reliable"`: single input per packet, no framing — bytes are
+ *   wire-compatible with the standard {@link Decoder}.
+ * - `"unreliable"`: ring buffer of the last `historySize` inputs packed
+ *   into one packet, each prefixed with a varint length. Gives the
+ *   receiver redundancy against dropped packets. Use
+ *   {@link InputDecoder.decodeAll} on the receiving end.
+ */
+export type InputMode = "reliable" | "unreliable";
+export interface InputEncoderOptions {
+    /** Defaults to `"reliable"`. */
+    mode?: InputMode;
+    /**
+     * Unreliable-mode only. Number of past inputs to pack into each
+     * packet as redundancy against drops. Default: 3. Ignored in
+     * reliable mode (always exactly one input per packet).
+     */
+    historySize?: number;
+    /**
+     * When `true`, `encode()` emits only fields that changed since the
+     * previous call. First call (or first after `reset()`) still emits
+     * a full snapshot since there's no baseline to diff against.
+     *
+     * **Reliable mode:** returns an empty `Uint8Array` when nothing
+     * changed — caller can skip sending.
+     *
+     * **Unreliable mode:** no-change ticks don't push a new ring slot
+     * (avoids bloating the ring with empties); the existing ring is
+     * still re-emitted for redundancy. Wire ops use absolute values so
+     * cross-packet re-application is per-field idempotent.
+     *
+     * Decoder side is unchanged in either case: `(index|ADD)` wire ops
+     * apply to the bound instance; fields absent from a packet stay at
+     * their previously decoded value.
+     */
+    delta?: boolean;
+    /**
+     * Override the reliable-mode output buffer. Default: 256 bytes,
+     * auto-grown on overflow.
+     */
+    buffer?: Uint8Array;
+}
+/**
+ * Bound single-struct encoder for client→server input packets. Holds a
+ * reference to a Schema instance and produces wire-compatible bytes.
+ *
+ * **Reliable mode** emits one snapshot per `encode()`. The bytes decode
+ * cleanly through the standard {@link Decoder}.
+ *
+ * **Unreliable mode** pushes each snapshot onto a ring buffer of size
+ * `historySize` and emits the last N snapshots in one packet, each
+ * framed with a varint length prefix. Use {@link InputDecoder.decodeAll}
+ * to walk the framed packet on the receiving end.
+ *
+ * **Delta** (`delta: true`, any mode) wraps a standard {@link Encoder}
+ * and emits only fields that changed since the last call, via the
+ * setter-populated ChangeTree dirty set.
+ *
+ * Flat primitive fields only. Nested Schema / collection fields throw
+ * at construction.
+ */
+export declare class InputEncoder<T extends Schema = any> {
+    readonly instance: T;
+    readonly mode: InputMode;
+    readonly historySize: number;
+    readonly delta: boolean;
+    private readonly _desc;
+    private readonly _numFields;
+    private _buffer;
+    private readonly _it;
+    private _slots?;
+    private readonly _slotLens?;
+    private _slotHead;
+    private _slotCount;
+    private _outBuffer?;
+    private readonly _encoder?;
+    constructor(instance: T, options?: InputEncoderOptions);
+    /**
+     * Encode the bound instance. Returns a subarray of an internal
+     * buffer — copy if retaining across calls.
+     *
+     * Output shape by configuration:
+     * - `reliable` + full: one snapshot's worth of bytes.
+     * - `reliable` + delta: only changed fields, or empty when nothing
+     *   changed.
+     * - `unreliable` + full: ring of last `historySize` snapshots,
+     *   length-framed per slot.
+     * - `unreliable` + delta: ring of last `historySize` deltas. No-
+     *   change ticks don't push a new slot but still re-emit the ring.
+     *   Empty only until the first change has been pushed.
+     *
+     * Buffers auto-grow on overflow; a one-time `console.warn` is
+     * emitted the first time it happens.
+     */
+    encode(): Uint8Array;
+    /**
+     * Reset the encoder's internal state:
+     * - Unreliable mode: drops the ring buffer.
+     * - Delta mode: re-marks every currently populated field as dirty,
+     *   so the next `encode()` emits a fresh full snapshot.
+     *
+     * Useful on disconnect / reconnect / scene transitions.
+     */
+    reset(): void;
+    /** Write every populated primitive field into `_buffer`. */
+    private _produceFull;
+    /** Delegate to the wrapped Encoder, then clear its dirty set. */
+    private _produceDelta;
+    /** Emit every populated field as `(index|ADD)` + value. */
+    private _writeFields;
+    private _pushAndEmitRing;
+    private _emitRing;
+    private static _warned;
+    private static _grow;
+}