@colyseus/schema 5.0.6 → 5.0.8

package/src/index.ts

@@ -79,6 +79,7 @@ export { getRawChangesCallback } from "./decoder/strategy/RawChanges.js";
 
 export { Encoder } from "./encoder/Encoder.js";
 export { Root } from "./encoder/Root.js";
+export { createPool, type SchemaPool, type PoolOptions } from "./encoder/Pool.js";
 export { encodeSchemaOperation, encodeArray, encodeKeyValueOperation, encodeMapEntry, encodeIndexedEntry } from "./encoder/EncodeOperation.js";
 export { ChangeTree, type Ref, type IRef } from "./encoder/ChangeTree.js";
 export { StateView } from "./encoder/StateView.js";
@@ -86,4 +87,13 @@ export { StateView } from "./encoder/StateView.js";
 export { Decoder } from "./decoder/Decoder.js";
 export { decodeSchemaOperation, decodeKeyValueOperation } from "./decoder/DecodeOperation.js";
 
-export { OPERATION } from "./encoding/spec.js";
+export { OPERATION } from "./encoding/spec.js";
+
+// Re-exported for `@colyseus/schema/input` — that subpath bundle is built
+// as a thin wrapper that imports identity-bearing modules from here at
+// runtime, so it needs `getEncodeDescriptor` available on the public surface.
+export { getEncodeDescriptor, type EncodeDescriptor } from "./encoder/EncodeDescriptor.js";
+
+// Symbols used by InputEncoder/InputDecoder via the runtime-externalized
+// `@colyseus/schema` import in `build/input/index.mjs`.
+export { $numFields, $values } from "./types/symbols.js";

package/src/input/InputDecoder.ts

@@ -34,21 +34,27 @@ export class InputDecoder<T extends Schema = any> {
     /**
      * 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.
+     * each decode. `onInput` receives the bound instance and the framework
+     * **seq** of that input (decoded from the packet's base seq + position) —
+     * the receiver dedupes the redundancy ring on it (monotonic: drop seq ≤
+     * last seen). Reads of the instance must be synchronous; downstream code
+     * should apply the input to game state, not retain the reference.
+     *
+     * Packet layout: `[baseSeq][len][body]…[len][body]` (oldest→newest);
+     * slot *i* has `seq = baseSeq + i`.
      *
      * Returns the number of inputs decoded.
      */
-    decodeAll(bytes: Uint8Array, onInput: (instance: T, index: number) => void): number {
+    decodeAll(bytes: Uint8Array, onInput: (instance: T, seq: number) => void): number {
         const it = this._it;
         it.offset = 0;
+        const baseSeq = decode.number(bytes, it);   // packet-level base seq (oldest slot)
         let count = 0;
         while (it.offset < bytes.length) {
             const len = decode.number(bytes, it);
             const end = it.offset + len;
             this._decoder.decode(bytes.subarray(it.offset, end));
-            onInput(this.instance, count);
+            onInput(this.instance, baseSeq + count);   // slot seq by position
             it.offset = end;
             count++;
         }

package/src/input/InputEncoder.ts

@@ -1,4 +1,3 @@
-import { OPERATION } from "../encoding/spec.js";
 import { $numFields, $values, $changes } from "../types/symbols.js";
 import { encode } from "../encoding/encode.js";
 import { Encoder } from "../encoder/Encoder.js";
@@ -26,31 +25,6 @@ export interface InputEncoderOptions {
      * 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;
 }
 
 const DEFAULT_SLOT_SIZE = 256;
@@ -60,17 +34,23 @@ const LENGTH_PREFIX_WORST_CASE = 5; // varint max for a uint32 length.
  * 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}.
+ * Always delta-encodes: each `encode()` emits only the fields that changed
+ * since the previous call (via the setter-populated ChangeTree dirty set),
+ * wrapping a standard {@link Encoder}. The first call (or first after
+ * {@link reset}) emits a full snapshot, since there's no baseline to diff
+ * against.
  *
- * **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.
+ * **Reliable mode** emits one delta per `encode()` — or an empty
+ * `Uint8Array` when nothing changed (the caller decides whether to send a
+ * body-less keep-alive or skip the tick). The bytes decode cleanly through
+ * the standard {@link Decoder}.
  *
- * **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.
+ * **Unreliable mode** pushes each delta onto a ring buffer of size
+ * `historySize` and emits the last N in one packet, each framed with a
+ * varint length prefix. A no-change tick still pushes an (empty,
+ * carry-forward) slot so every tick gets a consecutive framework seq. Use
+ * {@link InputDecoder.decodeAll} to walk the framed packet. Wire ops use
+ * absolute values, so re-applying a redundant slot is per-field idempotent.
  *
  * Flat primitive fields only. Nested Schema / collection fields throw
  * at construction.
@@ -79,32 +59,30 @@ export class InputEncoder<T extends Schema = any> {
     readonly instance: T;
     readonly mode: InputMode;
     readonly historySize: number;
-    readonly delta: boolean;
 
     private readonly _desc: EncodeDescriptor;
     private readonly _numFields: number;
 
-    // Reliable-mode output + its iterator. Auto-grown on overflow, so
-    // not `readonly` — `_encodeFull()` may swap in a larger buffer.
-    private _buffer: Uint8Array;
-    private readonly _it = { offset: 0 };
-
-    // Unreliable-mode ring state. `_outBuffer` is where the concatenated
-    // packet lives; `_slots` / `_slotLens` hold each snapshot's bytes.
+    // Unreliable-mode ring: `_slots`/`_slotLens` hold each snapshot; `_outBuffer` holds the concatenated packet.
     private _slots?: Uint8Array[];
     private readonly _slotLens?: number[];
     private _slotHead: number = 0;
     private _slotCount: number = 0;
     private _outBuffer?: Uint8Array;
+    // Monotonic per-tick input seq (unreliable only): ++ per pushed slot. The
+    // packet carries the OLDEST slot's seq once; the decoder derives each slot's
+    // seq by position (slots are consecutive — every tick pushes). This is the
+    // framework-owned seq that drives server-side dedupe of the redundancy ring
+    // WITHOUT the user adding a seq field. Monotonic across reset() so a
+    // reconnect that reuses the server buffer doesn't replay already-seen seqs.
+    private _seq: number = 0;
 
-    // Delta-mode delegate. Setter `$track` calls populate its
-    // ChangeTree; `encode()` drains dirty fields into its buffer.
-    private readonly _encoder?: Encoder<T>;
+    // Delta delegate; setters populate its ChangeTree, `encode()` drains dirty fields.
+    private readonly _encoder: Encoder<T>;
 
     constructor(instance: T, options: InputEncoderOptions = {}) {
         this.instance = instance;
         this.mode = options.mode ?? "reliable";
-        this.delta = options.delta ?? false;
         this.historySize = this.mode === "unreliable"
             ? Math.max(1, options.historySize ?? 3)
             : 1;
@@ -124,8 +102,6 @@ export class InputEncoder<T extends Schema = any> {
             }
         }
 
-        this._buffer = options.buffer ?? new Uint8Array(DEFAULT_SLOT_SIZE);
-
         if (this.mode === "unreliable") {
             this._slots = new Array(this.historySize);
             this._slotLens = new Array(this.historySize).fill(0);
@@ -137,113 +113,93 @@ export class InputEncoder<T extends Schema = any> {
             );
         }
 
-        if (this.delta) {
-            // Delegate to the standard Encoder — it attaches a Root and
-            // drains the setter-populated dirty set on each encode().
-            // Tracking stays enabled so setters keep populating it.
-            this._encoder = new Encoder<T>(instance);
-        } else {
-            // Full mode reads `$values` directly; setter-side tracking
-            // is pure overhead, so pause it.
-            instance.pauseTracking();
-        }
+        // Wrap a standard Encoder; keep tracking on so setters keep populating
+        // the dirty set we drain each encode().
+        this._encoder = new Encoder<T>(instance);
     }
 
     /**
-     * Encode the bound instance. Returns a subarray of an internal
+     * The framework input seq of the most recently encoded tick (unreliable
+     * mode): monotonic, ++ per `encode()`, kept across {@link reset}. `0` in
+     * reliable mode (which sequences inputs implicitly by message count). The
+     * client keys its reconciliation replay ring by this so the server's
+     * seq-value ack lines up across packet loss.
+     */
+    get seq(): number { return this._seq; }
+
+    /**
+     * Encode the bound instance's delta. 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.
+     * Output shape by mode:
+     * - `reliable`: only changed fields, or empty when nothing changed.
+     * - `unreliable`: ring of the last `historySize` deltas, length-framed
+     *   per slot. A no-change tick pushes an empty (carry-forward) slot but
+     *   still re-emits the ring. Empty only until the first slot is pushed.
      *
      * Buffers auto-grow on overflow; a one-time `console.warn` is
      * emitted the first time it happens.
      */
     encode(): Uint8Array {
-        const blob = this.delta ? this._produceDelta() : this._produceFull();
+        const blob = this._produceDelta();
         return this.mode === "reliable" ? blob : this._pushAndEmitRing(blob);
     }
 
     /**
      * 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.
+     * - Drops the unreliable ring buffer.
+     * - 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 {
         this._slotHead = 0;
         this._slotCount = 0;
-        if (this.delta) {
-            this._encoder!.discardChanges();
-            const tree = (this.instance as any)[$changes];
-            const values = (this.instance as any)[$values];
-            for (let i = 0; i <= this._numFields; i++) {
-                if (values[i] === undefined || values[i] === null) continue;
-                tree.markDirty(i);
-            }
+        this._encoder.discardChanges();
+        const tree = this.instance[$changes];
+        const values = this.instance[$values];
+        for (let i = 0; i <= this._numFields; i++) {
+            if (values[i] === undefined || values[i] === null) continue;
+            tree.markDirty(i);
         }
     }
 
+    /**
+     * Copy the bound instance's field values into `target` (a same-type instance)
+     * in place — no allocation, no `Object.keys` (cf. `Schema#assign`) and no
+     * `clone()`. For buffering a snapshot of the just-sent input into a reused
+     * slot (e.g. a client reconciliation/replay ring) without the transport
+     * having to reach into schema internals. The codec owns this because it owns
+     * the field representation. The in-place / alloc-free cousin of `clone()`,
+     * and the inverse direction of `Schema#assign(source)`.
+     */
+    copyInto(target: T): void {
+        const src = (this.instance as any)[$values];
+        const dst = (target as any)[$values];
+        for (let i = 0; i <= this._numFields; i++) dst[i] = src[i];
+    }
+
     // ────────────────────────────────────────────────────────────────────
-    // Blob producers — return a single snapshot (or delta) of the
-    // current instance. Caller routes by mode.
+    // Delta producer — one diff of the instance; caller routes by mode.
     // ────────────────────────────────────────────────────────────────────
 
-    /** Write every populated primitive field into `_buffer`. */
-    private _produceFull(): Uint8Array {
-        let buf = this._buffer;
-        const it = this._it;
-        this._writeFields(buf, it);
-        if (it.offset > buf.byteLength) {
-            buf = this._buffer = InputEncoder._grow(buf, it.offset, "reliable encode");
-            this._writeFields(buf, it);
-        }
-        return buf.subarray(0, it.offset);
-    }
-
     /** Delegate to the wrapped Encoder, then clear its dirty set. */
     private _produceDelta(): Uint8Array {
-        const bytes = this._encoder!.encode();
-        this._encoder!.discardChanges();
+        const bytes = this._encoder.encode();
+        this._encoder.discardChanges();
         return bytes;
     }
 
-    /** Emit every populated field as `(index|ADD)` + value. */
-    private _writeFields(buf: Uint8Array, it: { offset: number }): void {
-        const values = (this.instance as any)[$values];
-        const encoders = this._desc.encoders;
-        it.offset = 0;
-        for (let i = 0; i <= this._numFields; i++) {
-            const value = values[i];
-            if (value === undefined || value === null) continue;
-            buf[it.offset++] = (i | OPERATION.ADD) & 255;
-            (encoders[i] as (b: Uint8Array, v: any, it: any) => void)(buf, value, it);
-        }
-    }
-
     // ────────────────────────────────────────────────────────────────────
-    // Ring — push blob to the current slot, concat (oldest → newest)
-    // into the output buffer, return the framed packet.
+    // Ring — push blob to current slot, concat oldest→newest, return framed packet.
     // ────────────────────────────────────────────────────────────────────
 
     private _pushAndEmitRing(blob: Uint8Array): Uint8Array {
-        // Empty blob = no-change delta tick. Skip the push but re-emit
-        // the existing ring (redundancy). Empty ring → empty output.
-        if (blob.length === 0) {
-            if (this._slotCount === 0) return this._outBuffer!.subarray(0, 0);
-            return this._emitRing();
-        }
-
-        // Copy blob into the current slot, growing it if needed.
+        // Push a slot EVERY tick (even an empty delta) so ring seqs stay
+        // consecutive: the packet carries ONE base seq and the decoder derives
+        // each slot's seq by position. An empty slot decodes as carry-forward.
+        this._seq++;
         let slot = this._slots![this._slotHead];
         if (blob.length > slot.byteLength) {
             slot = this._slots![this._slotHead] = InputEncoder._grow(
@@ -259,8 +215,12 @@ export class InputEncoder<T extends Schema = any> {
     }
 
     private _emitRing(): Uint8Array {
-        // Upper bound: sum of slot byte counts + per-slot varint length.
-        let needed = 0;
+        // Packet layout: [baseSeq][len][slot]…[len][slot] (oldest→newest).
+        // baseSeq = the oldest slot's seq; consecutive slots ⇒ slot i has seq baseSeq + i.
+        const baseSeq = this._seq - this._slotCount + 1;
+
+        // Upper bound: baseSeq varint + sum of slot byte counts + per-slot varint length.
+        let needed = LENGTH_PREFIX_WORST_CASE;
         for (let i = 0; i < this._slotCount; i++) {
             needed += this._slotLens![i] + LENGTH_PREFIX_WORST_CASE;
         }
@@ -271,6 +231,7 @@ export class InputEncoder<T extends Schema = any> {
         }
 
         const outIt = { offset: 0 };
+        encode.number(out, baseSeq, outIt);   // packet-level base seq
         const oldest = (this._slotHead - this._slotCount + this.historySize) % this.historySize;
         for (let i = 0; i < this._slotCount; i++) {
             const idx = (oldest + i) % this.historySize;
@@ -283,9 +244,7 @@ export class InputEncoder<T extends Schema = any> {
     }
 
     // ────────────────────────────────────────────────────────────────────
-    // Buffer growth. Uint8Array writes past `byteLength` silently drop
-    // but `it.offset` still advances — callers detect overflow via the
-    // `offset > byteLength` check and re-encode into the grown buffer.
+    // Buffer growth. Writes past `byteLength` silently drop but `it.offset` still advances, so callers detect overflow via `offset > byteLength` and re-encode into the grown buffer.
     // ────────────────────────────────────────────────────────────────────
 
     private static _warned = false;
@@ -295,7 +254,7 @@ export class InputEncoder<T extends Schema = any> {
             InputEncoder._warned = true;
             console.warn(
                 `@colyseus/schema/input: InputEncoder buffer overflow in ${where}. ` +
-                `Growing to ${newSize} bytes. Pass a larger { buffer } option to avoid this at runtime.`
+                `Growing to ${newSize} bytes.`
             );
         }
         return new Uint8Array(newSize);

package/src/types/HelperTypes.ts

@@ -1,3 +1,4 @@
+import { $resyncPrune } from "./symbols.js";
 import type { Definition, DefinitionType, PrimitiveType, RawPrimitiveType } from "../annotations.js";
 import type { Schema } from "../Schema.js";
 import type { ArraySchema } from "./custom/ArraySchema.js";
@@ -20,6 +21,12 @@ export interface Collection<K = any, V = any, IT = V> {
     [Symbol.iterator](): IterableIterator<IT>;
     forEach(callback: Function): void;
     entries(): IterableIterator<[K, V]>;
+    /** See {@link $resyncPrune} — every collection kind must declare its resync-sweep semantics. */
+    [$resyncPrune](
+        visited: Set<number | string>,
+        prune: (value: V, identity: number | string) => void,
+        keep: (value: V) => void,
+    ): void;
 }
 
 export type InferValueType<T> =

package/src/types/TypeContext.ts

@@ -1,6 +1,7 @@
 import { Metadata } from "../Metadata.js";
 import { Schema } from "../Schema.js";
 import { $streamFieldIndexes, $viewFieldIndexes } from "./symbols.js";
+import { isQuantizedType } from "./quantize.js";
 
 export class TypeContext {
     types: { [id: number]: typeof Schema; } = {};
@@ -125,6 +126,12 @@ export class TypeContext {
                 continue;
             }
 
+            // Quantized fields are scalar — their object `type` only carries the
+            // descriptor, there's no child Schema to discover.
+            if (isQuantizedType(fieldType)) {
+                continue;
+            }
+
             if (typeof (fieldType) === "function") {
                 this.discoverTypes(fieldType as typeof Schema, klass, index, parentHasViewTag || fieldHasViewTag);
 

package/src/types/builder.ts

@@ -8,6 +8,7 @@ import type { DefinitionType, RawPrimitiveType } from "../annotations.js";
 import type { InferValueType, Constructor } from "./HelperTypes.js";
 import { $builder } from "./symbols.js";
 import { ARRAY_STREAM_NOT_SUPPORTED } from "../encoder/streaming.js";
+import { resolveQuantize, type QuantizeOptions } from "./quantize.js";
 
 type CollectionKind = "array" | "map" | "set" | "collection";
 
@@ -89,8 +90,23 @@ export class FieldBuilder<
         this._type = type;
     }
 
-    /** Provide a default value for this field. */
-    default(value: T): FieldBuilder<T, true, IsOptional> {
+    /**
+     * Provide a default value for this field.
+     *
+     * Pass a **factory function** `() => T` to build a FRESH value per instance
+     * (invoked once per construction) instead of sharing a single default — the
+     * clean way to default a ref to a plain custom class, or any field that must
+     * not share a mutable default across instances:
+     *
+     * ```ts
+     * acc: t.ref(GunAccuracy).noSync().default(() => new GunAccuracy()),
+     * ```
+     *
+     * Schema fields are never function-typed, so a function is always treated as a
+     * factory. A non-function value is shared (and cloned per instance if it is
+     * clone-able, e.g. a Schema/collection).
+     */
+    default(value: T | (() => T)): FieldBuilder<T, true, IsOptional> {
         this._default = value;
         this._hasDefault = true;
         return this as unknown as FieldBuilder<T, true, IsOptional>;
@@ -359,12 +375,27 @@ type RefHasDefault<C> =
         : true;
 
 interface RefFactory {
-    <C extends Constructor<Schema>>(ctor: C): FieldBuilder<InstanceType<C>, RefHasDefault<C>, false>;
+    <C extends Constructor>(ctor: C): FieldBuilder<InstanceType<C>, RefHasDefault<C>, false>;
 }
 
-const refFactory: RefFactory = (<C extends Constructor<Schema>>(ctor: C) =>
+const refFactory: RefFactory = (<C extends Constructor>(ctor: C) =>
     new FieldBuilder<InstanceType<C>>(ctor as unknown as DefinitionType)) as RefFactory;
 
+/**
+ * A bounded float carried on the wire as a fixed-width unsigned integer. App code
+ * reads/writes the FLOAT; the wire carries the quantized int and the field only
+ * ever yields `dequant(q)`, so client predict and server sim read the same value
+ * (no full-precision path to leak ⇒ no shot misprediction). See
+ * {@link QuantizeOptions} for the precision/wire trade-offs.
+ *
+ *     yaw:      t.quantized({ min: 0, max: TWO_PI, mode: "wrap" }), // 16-bit
+ *     pitch:    t.quantized({ min: -PITCH_LIMIT, max: PITCH_LIMIT }), // clamp (default)
+ *     throttle: t.quantized({ min: 0, max: 1, bits: 8 }),           // 1 byte
+ */
+function quantizedFactory(opts: QuantizeOptions): FieldBuilder<number> {
+    return new FieldBuilder<number>({ quantized: resolveQuantize(opts) } as unknown as DefinitionType);
+}
+
 export const t = Object.freeze({
     // Primitives
     string: primitive<string>("string"),
@@ -383,11 +414,37 @@ export const t = Object.freeze({
     bigint64: primitive<bigint>("bigint64"),
     biguint64: primitive<bigint>("biguint64"),
 
-    /** Reference to a Schema subtype. `t.array(Item)` usually reads better, but this is available when a plain ref is needed. */
+    /**
+     * Reference to a Schema subtype — `t.array(Item)` usually reads better, but
+     * this is available when a plain ref is needed.
+     *
+     * The target may also be a **non-Schema custom class**. A synced ref still
+     * requires it to be encodable — a `Schema` subclass, or a class retrofitted
+     * with `Metadata.setFields(...)` (both carry `[Symbol.metadata]`); a bare
+     * custom class is rejected at `schema()` time. A `.noSync()` (local-only)
+     * field accepts ANY zero-arg class and auto-instantiates one per parent.
+     */
     ref: refFactory,
     array: arrayFactory,
     map: mapFactory,
     set: setFactory,
     collection: collectionFactory,
     stream: streamFactory,
+
+    /**
+     * A bounded float quantized to a fixed-width unsigned int on the wire — half
+     * (or a quarter) the bytes of a `float32` at a precision you pick. The field
+     * reads/writes the float and only ever yields `dequant(q)`. {@see QuantizeOptions}
+     */
+    quantized: quantizedFactory,
+
+    /**
+     * Sugar for a full-circle wrapping angle in radians:
+     * `t.quantized({ min: 0, max: 2π, mode: "wrap", bits })` (default 16-bit,
+     * ~0.0055°/step). Any input angle is range-reduced into `[0, 2π)`. Render note:
+     * lerp interpolated remotes shortest-arc (`attach({ angle: true })`) — the
+     * wrap fixes the WIRE seam, not interpolation (see {@link QuantizeOptions.mode}).
+     */
+    angle: (opts?: { bits?: 8 | 16 | 32 }) =>
+        quantizedFactory({ min: 0, max: Math.PI * 2, mode: "wrap", bits: opts?.bits ?? 16 }),
 });