@colyseus/schema 5.0.5 → 5.0.8

package/build/types/HelperTypes.d.ts

@@ -1,3 +1,4 @@
+import { $resyncPrune } from "./symbols.js";
 import type { PrimitiveType, RawPrimitiveType } from "../annotations.js";
 import type { Schema } from "../Schema.js";
 import type { ArraySchema } from "./custom/ArraySchema.js";
@@ -12,6 +13,8 @@ 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> = T extends FieldBuilder<infer V> ? V : T extends "string" ? string : T extends "number" ? number : T extends "int8" ? number : T extends "uint8" ? number : T extends "int16" ? number : T extends "uint16" ? number : T extends "int32" ? number : T extends "uint32" ? number : T extends "int64" ? number : T extends "uint64" ? number : T extends "float32" ? number : T extends "float64" ? number : T extends "boolean" ? boolean : T extends {
     type: infer ChildType extends PrimitiveType;
@@ -97,6 +100,28 @@ export type ToJSON<T> = NonFunctionProps<{
 } & {
     [K in ToJSONOptionalKeys<T>]?: ToJSONField<Exclude<T[K], undefined>>;
 }>;
+/**
+ * The plain DATA shape of a Schema instance type `T`: its synchronized fields
+ * with all `Schema` machinery stripped (`assign`, `clone`, `toJSON`, the
+ * change-tracking state, the internal symbol keys, …), so a plain object literal
+ * satisfies it. Field types — including narrowed primitives like
+ * `t.int8<-1 | 0 | 1>()` — are preserved exactly.
+ *
+ * Use it to type code that operates on schema-shaped *plain objects* rather than
+ * decoded instances: deterministic simulation / physics steps, synthesized or
+ * buffered input commands, plain DTOs, etc.
+ *
+ * ```ts
+ * function applyInput(state: Player, cmd: Data<MoveInput>) { … }
+ * applyInput(player, { moveX: 1, jump: false, dt });   // plain literal — OK
+ * ```
+ *
+ * Unlike {@link ToJSON} (a recursive *serialization* shape), this is a flat
+ * structural projection: nested Schema / collection fields keep their instance
+ * types, and it does not retain the non-method `Schema` members that `ToJSON`'s
+ * `NonFunctionProps` pass leaves behind.
+ */
+export type Data<T> = Omit<T, keyof Schema>;
 export type IsNever<T> = [T] extends [never] ? true : false;
 /**
  * Type helper for .assign() method - allows assigning values in a flexible way

package/build/types/builder.d.ts

@@ -7,6 +7,7 @@ import type { Schema } from "../Schema.js";
 import type { DefinitionType, RawPrimitiveType } from "../annotations.js";
 import type { InferValueType, Constructor } from "./HelperTypes.js";
 import { $builder } from "./symbols.js";
+import { type QuantizeOptions } from "./quantize.js";
 /**
  * Internal record produced by FieldBuilder#toDefinition() and consumed by schema().
  */
@@ -70,8 +71,23 @@ export declare class FieldBuilder<T = unknown, HasDefault extends boolean = fals
     private _noSync;
     private _streamPriority;
     constructor(type: DefinitionType);
-    /** 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>;
     /** Tag this field with a view tag (DEFAULT_VIEW_TAG when called without arg). */
     view(tag?: number): this;
     /** Mark this field as owned (encoder-side ownership filtering). */
@@ -217,8 +233,20 @@ type RefHasDefault<C> = C extends {
     };
 } ? (P extends readonly [] ? true : false) : 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>;
 }
+/**
+ * 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
+ */
+declare function quantizedFactory(opts: QuantizeOptions): FieldBuilder<number>;
 export declare const t: Readonly<{
     string: PrimitiveFactory<string>;
     number: PrimitiveFactory<number>;
@@ -235,12 +263,37 @@ export declare const t: Readonly<{
     float64: PrimitiveFactory<number>;
     bigint64: PrimitiveFactory<bigint>;
     biguint64: PrimitiveFactory<bigint>;
-    /** 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: typeof 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;
+    }) => FieldBuilder<number, false, false>;
 }>;
 export {};

package/build/types/custom/ArraySchema.d.ts

@@ -1,4 +1,4 @@
-import { $changes, $childType, $decoder, $deleteByIndex, $onEncodeEnd, $encoder, $filter, $getByIndex, $onDecodeEnd, $proxyTarget, $refId } from "../symbols.js";
+import { $changes, $childType, $decoder, $deleteByIndex, $onEncodeEnd, $encoder, $filter, $getByIndex, $onDecodeEnd, $proxyTarget, $refId, $reset, $resyncPrune } from "../symbols.js";
 import type { Schema } from "../../Schema.js";
 import { type IRef, ChangeTree } from "../../encoder/ChangeTree.js";
 import { OPERATION } from "../../encoding/spec.js";
@@ -14,6 +14,8 @@ export declare class ArraySchema<V = any> implements Array<V>, Collection<number
     protected tmpItems: V[];
     protected deletedIndexes: boolean[];
     protected isMovingItems: boolean;
+    /** Decode-side: `items` has holes (delete or gap-write) — `$onDecodeEnd` must compact. */
+    protected _needsCompaction: boolean;
     static [$encoder]: import("../../encoder/EncodeOperation.js").EncodeOperation<any>;
     static [$decoder]: import("../../decoder/DecodeOperation.js").DecodeOperation<any>;
     /** Integer tag read by `decodeKeyValueOperation` — see `CollectionKind`. */
@@ -57,6 +59,13 @@ export declare class ArraySchema<V = any> implements Array<V>, Collection<number
     protected $deleteAt(index: number, operation?: OPERATION): void;
     protected $setAt(index: number, value: V, operation: OPERATION): void;
     clear(): void;
+    /**
+     * Pool reset: empty this array and recycle its ChangeTree WITHOUT recording
+     * any wire op (the parent field's ADD/DELETE owns the wire). Recurses into
+     * ref-type children. Called by Schema.reset when a pooled entity has an
+     * array field. The instance must already be detached from the encoder.
+     */
+    [$reset](): void;
     /**
      * Combines two or more arrays.
      * @param items Additional items to add to the end of array1.
@@ -285,6 +294,7 @@ export declare class ArraySchema<V = any> implements Array<V>, Collection<number
     [$deleteByIndex](index: number): void;
     protected [$onEncodeEnd](): void;
     protected [$onDecodeEnd](): void;
+    [$resyncPrune](visited: Set<number | string>, prune: (value: V, identity: number | string) => void, keep: (value: V) => void): void;
     toArray(): V[];
     toJSON(): any[];
     clone(isDecoding?: boolean): ArraySchema<V>;

package/build/types/custom/CollectionSchema.d.ts

@@ -1,4 +1,4 @@
-import { $changes, $childType, $decoder, $deleteByIndex, $encoder, $filter, $getByIndex, $onEncodeEnd, $refId } from "../symbols.js";
+import { $changes, $childType, $decoder, $deleteByIndex, $encoder, $filter, $getByIndex, $onEncodeEnd, $refId, $reset, $resyncPrune } from "../symbols.js";
 import { ChangeTree, type IRef } from "../../encoder/ChangeTree.js";
 import { Collection } from "../HelperTypes.js";
 import { type StreamableState } from "../../encoder/streaming.js";
@@ -55,6 +55,13 @@ export declare class CollectionSchema<V = any> implements Collection<K, V>, IRef
     entries(): MapIterator<[number, V]>;
     delete(item: V): boolean;
     clear(): void;
+    /**
+     * Pool reset: empty this collection and recycle its ChangeTree WITHOUT
+     * recording any wire op (the parent field's ADD/DELETE owns the wire).
+     * Recurses into ref-type children. Called by Schema.reset when a pooled
+     * entity has a collection field. Must already be detached from the encoder.
+     */
+    [$reset](): void;
     has(value: V): boolean;
     forEach(callbackfn: (value: V, key: K, collection: CollectionSchema<V>) => void): void;
     values(): MapIterator<V>;
@@ -69,6 +76,7 @@ export declare class CollectionSchema<V = any> implements Collection<K, V>, IRef
     protected getIndex(index: number): number;
     [$getByIndex](index: number): any;
     [$deleteByIndex](index: number): void;
+    [$resyncPrune](visited: Set<number | string>, prune: (value: V, identity: number | string) => void, keep: (value: V) => void): void;
     protected [$onEncodeEnd](): void;
     _dropView(viewId: number): void;
     _unregister(): void;

package/build/types/custom/MapSchema.d.ts

@@ -1,4 +1,4 @@
-import { $changes, $childType, $decoder, $deleteByIndex, $onEncodeEnd, $encoder, $filter, $getByIndex, $refId } from "../symbols.js";
+import { $changes, $childType, $decoder, $deleteByIndex, $onEncodeEnd, $encoder, $filter, $getByIndex, $refId, $reset, $resyncPrune } from "../symbols.js";
 import { ChangeTree, IRef } from "../../encoder/ChangeTree.js";
 import { Collection } from "../HelperTypes.js";
 import { MapJournal } from "../../encoder/MapJournal.js";
@@ -78,6 +78,13 @@ export declare class MapSchema<V = any, K extends string = string> implements Ma
     get(key: K): V | undefined;
     delete(key: K): boolean;
     clear(): void;
+    /**
+     * Pool reset: empty this map and recycle its ChangeTree WITHOUT recording
+     * any wire op (the parent field's ADD/DELETE owns the wire). Recurses into
+     * ref-type children. Called by Schema.reset when a pooled entity has a
+     * map field. The instance must already be detached from the encoder.
+     */
+    [$reset](): void;
     has(key: K): boolean;
     forEach(callbackfn: (value: V, key: K, map: Map<K, V>) => void): void;
     entries(): MapIterator<[K, V]>;
@@ -92,6 +99,7 @@ export declare class MapSchema<V = any, K extends string = string> implements Ma
     protected getIndex(index: number): K;
     [$getByIndex](index: number): V | undefined;
     [$deleteByIndex](index: number): void;
+    [$resyncPrune](visited: Set<number | string>, prune: (value: V, identity: number | string) => void, keep: (value: V) => void): void;
     protected [$onEncodeEnd](): void;
     _dropView(viewId: number): void;
     _unregister(): void;

package/build/types/custom/SetSchema.d.ts

@@ -1,4 +1,4 @@
-import { $changes, $childType, $decoder, $deleteByIndex, $encoder, $filter, $getByIndex, $onEncodeEnd, $refId } from "../symbols.js";
+import { $changes, $childType, $decoder, $deleteByIndex, $encoder, $filter, $getByIndex, $onEncodeEnd, $refId, $reset, $resyncPrune } from "../symbols.js";
 import { Collection } from "../HelperTypes.js";
 import { ChangeTree, type IRef } from "../../encoder/ChangeTree.js";
 import { type StreamableState } from "../../encoder/streaming.js";
@@ -55,6 +55,13 @@ export declare class SetSchema<V = any> implements Collection<number, V>, IRef {
     entries(): MapIterator<[number, V]>;
     delete(item: V): boolean;
     clear(): void;
+    /**
+     * Pool reset: empty this set and recycle its ChangeTree WITHOUT recording
+     * any wire op (the parent field's ADD/DELETE owns the wire). Recurses into
+     * ref-type children. Called by Schema.reset when a pooled entity has a set
+     * field. The instance must already be detached from the encoder.
+     */
+    [$reset](): void;
     has(value: V): boolean;
     forEach(callbackfn: (value: V, key: number, collection: SetSchema<V>) => void): void;
     values(): MapIterator<V>;
@@ -69,6 +76,7 @@ export declare class SetSchema<V = any> implements Collection<number, V>, IRef {
     protected getIndex(index: number): number;
     [$getByIndex](index: number): any;
     [$deleteByIndex](index: number): void;
+    [$resyncPrune](visited: Set<number | string>, prune: (value: V, identity: number | string) => void, keep: (value: V) => void): void;
     protected [$onEncodeEnd](): void;
     _dropView(viewId: number): void;
     _unregister(): void;

package/build/types/custom/StreamSchema.d.ts

@@ -1,4 +1,4 @@
-import { $changes, $childType, $decoder, $deleteByIndex, $encoder, $filter, $getByIndex, $onEncodeEnd, $refId } from "../symbols.js";
+import { $changes, $childType, $decoder, $deleteByIndex, $encoder, $filter, $getByIndex, $onEncodeEnd, $refId, $resyncPrune } from "../symbols.js";
 import { ChangeTree, type IRef } from "../../encoder/ChangeTree.js";
 import { type StreamableState } from "../../encoder/streaming.js";
 import type { StateView } from "../../encoder/StateView.js";
@@ -104,6 +104,7 @@ export declare class StreamSchema<V = any> implements IRef {
     protected getIndex(index: number): number;
     [$getByIndex](index: number): V;
     [$deleteByIndex](index: number): void;
+    [$resyncPrune](): void;
     protected [$onEncodeEnd](): void;
     toArray(): V[];
     toJSON(): any[];

package/build/types/quantize.d.ts

@@ -0,0 +1,102 @@
+/**
+ * `t.quantized()` — a bounded float encoded as a fixed-width unsigned integer.
+ *
+ * A float that changes every frame within a known range (look angles, a
+ * normalized scalar, a unit-vector component) costs a full `float32` (4 value
+ * bytes). Mapping it onto `uint8`/`uint16`/`uint32` halves or quarters that at a
+ * precision you choose — e.g. a yaw on `uint16` is ~0.0055°/step, finer than any
+ * mouse, for 2 bytes instead of 4.
+ *
+ * Quantization is LOSSY, but lossy IDENTICALLY on both peers: the field only ever
+ * yields `dequant(q)`, so client prediction and server simulation read the SAME
+ * value and a predicted hitscan ray bit-matches the server's — the lossiness is
+ * vs. the original float, never between the two peers (see the reconciler note in
+ * `predict/reconciler.ts`).
+ *
+ * Portable by construction (a C/C#/Lua client must reproduce it bit-for-bit):
+ * rounding is explicit `floor(x + 0.5)` — NOT the language-default round, which
+ * disagrees on the `.5` case (JS half-up, C# banker's, C half-away) — and a
+ * wrapping range is reduced in the FLOAT domain BEFORE the integer step, so there
+ * is no huge-double→int cast (UB in C, throws in C#). All math is float64.
+ */
+export interface QuantizeOptions {
+    /** Inclusive lower bound of the value domain. */
+    min: number;
+    /** Upper bound of the value domain (inclusive when clamped, exclusive when wrapping). */
+    max: number;
+    /**
+     * Wire width in bits — a typed union, NOT a free integer: schema fields are
+     * byte-aligned, so only 8/16/32 change the wire (`bits: 13` would still occupy
+     * 2 bytes and mislead). Default 16.
+     */
+    bits?: 8 | 16 | 32;
+    /**
+     * Is the value CYCLIC (lives on a circle) or BOUNDED (has hard walls)? That is
+     * the whole choice — the wire size is identical either way.
+     *
+     * `"clamp"` (default) — for a BOUNDED value with hard ends (pitch, a health bar,
+     * a 0–1 throttle). A UNORM over `[min, max]` INCLUSIVE: both endpoints are exact
+     * + distinct, and out-of-range inputs CLAMP to the nearest end (`0` / `2^bits − 1`).
+     * Pitch past the limit stops AT the limit.
+     *
+     * `"wrap"` — for a CYCLIC value where `min` and `max` are the SAME point (an
+     * angle/heading, compass bearing, hue, phase). `[min, max)` over `2^bits` steps
+     * with the top folding onto the bottom; any input is range-reduced modulo
+     * `(max − min)` first, so a large accumulated or negative angle maps into the
+     * domain (yaw keeps spinning, never jams). `min` is exact; `max ≡ min`.
+     *
+     * Decision rule: does one step past the top return you to the bottom as the SAME
+     * physical thing? → `"wrap"`. Is the top a wall you can't cross? → `"clamp"`.
+     * Choosing wrong is a real bug: a clamped heading JAMS at the 0/2π seam; a wrapped
+     * pitch FLIPS the camera the instant you look a hair too far up.
+     *
+     * NB (cyclic fields): `"wrap"` fixes the WIRE seam, not rendering — a wrapped
+     * field that's interpolated must ALSO be lerped shortest-arc (the SDK predict
+     * `attach({ angle: true })`), or it unwinds the long way across the `0 ↔ max` seam.
+     */
+    mode?: "clamp" | "wrap";
+}
+/**
+ * Resolved, plain-data quantization descriptor stored on the field metadata as
+ * `{ quantized: QuantizeDescriptor }`. Both encode and decode derive `scale` from
+ * the same fields, so the two sides — and a future cross-language port — agree by
+ * construction. Serializable (no functions) so it can ride schema reflection.
+ */
+export interface QuantizeDescriptor {
+    min: number;
+    max: number;
+    bits: 8 | 16 | 32;
+    wrap: boolean;
+    /** Wire codec name — `"uint8" | "uint16" | "uint32"`, derived from `bits`. */
+    wire: "uint8" | "uint16" | "uint32";
+    /** `max − min`, the domain width. */
+    range: number;
+    /**
+     * The integer span used for the scale:
+     *  - wrapping: `2^bits` (the number of steps; the top step folds onto 0).
+     *  - clamped:  `2^bits − 1` (endpoints inclusive, so the max maps to it).
+     */
+    span: number;
+}
+/** Validate options and precompute the wire codec + scale span. */
+export declare function resolveQuantize(opts: QuantizeOptions): QuantizeDescriptor;
+/** Type guard for the `{ quantized: QuantizeDescriptor }` field-type shape. */
+export declare function isQuantizedType(type: any): type is {
+    quantized: QuantizeDescriptor;
+};
+/**
+ * Float → unsigned integer. Rounding is explicit half-up `floor(x + 0.5)`;
+ * wrapping ranges are reduced in the float domain first (no huge→int cast).
+ */
+export declare function quantize(desc: QuantizeDescriptor, value: number): number;
+/** Unsigned integer → float. Correctly-rounded mul/div ⇒ bit-identical across languages. */
+export declare function dequantize(desc: QuantizeDescriptor, q: number): number;
+/**
+ * Pre-baked encoder for a quantized field: quantize the (snapped) float held on
+ * the instance, then write it with the field's unsigned-int wire codec. Stored in
+ * `metadata[$encoders]` so the encode hot path reaches it via the fast lane,
+ * exactly like the pre-computed primitive encoders.
+ */
+export declare function makeQuantizedEncoder(desc: QuantizeDescriptor): (bytes: any, value: number, it: any) => void;
+/** Decode a quantized field: read the unsigned-int wire value, then dequantize. */
+export declare function decodeQuantized(desc: QuantizeDescriptor, bytes: any, it: any): number;

package/build/types/symbols.d.ts

@@ -5,6 +5,13 @@ export declare const $decoder = "~decoder";
 export declare const $filter = "~filter";
 export declare const $getByIndex = "~getByIndex";
 export declare const $deleteByIndex = "~deleteByIndex";
+/**
+ * Resync-sweep hook (see decoder/Resync.ts): prune every entry the rejoin
+ * snapshot did not visit. Each collection owns its storage-specific
+ * bookkeeping (journal pruning, compaction, item indexes); the generic
+ * DELETE/ref/callback bookkeeping arrives via the `prune`/`keep` callbacks.
+ */
+export declare const $resyncPrune = "~resyncPrune";
 /**
  * Used to hold ChangeTree instances whitin the structures.
  *
@@ -29,6 +36,14 @@ export declare const $proxyTarget: unique symbol;
  * (Discards changes for next serialization)
  */
 export declare const $onEncodeEnd = "~onEncodeEnd";
+/**
+ * Optional "reset" method on every poolable Ref (Schema + collections).
+ * Empties the instance's backing store and recycles its ChangeTree WITHOUT
+ * emitting any wire op, and recurses into ref-type children — so the instance
+ * can be returned to a SchemaPool and reused, avoiding the cost of `new`.
+ * See encoder/Pool.ts and Schema.reset().
+ */
+export declare const $reset = "~reset";
 /**
  * When decoding, this method is called after the instance is fully decoded
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colyseus/schema",
-  "version": "5.0.5",
+  "version": "5.0.8",
   "description": "Binary state serializer with delta encoding for games",
   "type": "module",
   "bin": {
@@ -8,10 +8,17 @@
     "schema-debug": "bin/schema-debug"
   },
   "scripts": {
+    "bench": "node bench/run.mjs",
+    "bench:compare": "node bench/run.mjs --compare",
+    "bench:snapshot": "bash bench/snapshot-build.sh",
+    "bench:gate": "node bench/run.mjs --assert --samples 3 --filter gate",
+    "profile:cpu": "node bench/profile.mjs --cpu",
+    "profile:heap": "node bench/profile.mjs --heap",
     "build": "tsc -p tsconfig.build.json && rollup -c rollup.config.mjs",
     "watch": "tsc -p tsconfig.build.json -w",
     "typecheck:build": "tsc -p tsconfig.build.json --noEmit",
     "test": "tsx --tsconfig tsconfig.test.json ./node_modules/mocha/bin/mocha.js \"test/*.test.ts\" \"test/**/*.test.ts\"",
+    "test:exports": "node test/verify-exports.mjs",
     "typecheck": "tsc -p tsconfig.test.json",
     "coverage": "c8 npm run test",
     "generate-test-1": "bin/schema-codegen test-external/PrimitiveTypes.ts --namespace SchemaTest.PrimitiveTypes --output ../colyseus-unity-sdk/Assets/Colyseus/Tests/Editor/ColyseusTests/Schema/PrimitiveTypes",

package/src/Metadata.ts

@@ -5,6 +5,7 @@ import { $decoder, $descriptors, $encoder, $encoders, $fieldIndexesByViewTag, $n
 import { ARRAY_STREAM_NOT_SUPPORTED } from "./encoder/streaming.js";
 import { encode } from "./encoding/encode.js";
 import { TypeContext } from "./types/TypeContext.js";
+import { isQuantizedType, makeQuantizedEncoder, resolveQuantize } from "./types/quantize.js";
 
 export type MetadataField = {
     type: DefinitionType,
@@ -54,6 +55,14 @@ export function getNormalizedType(type: any): DefinitionType  {
     if (Array.isArray(type)) {
         return { array: getNormalizedType(type[0]) };
 
+    } else if (isQuantizedType(type)) {
+        // `{ quantized: ... }` — a scalar wire type, NOT a collection/ref. Resolve
+        // raw options (the `@type({quantized:{min,max}})` path) once; an already-
+        // resolved descriptor (the `t.quantized()` builder path) passes through.
+        return (typeof (type.quantized as any).wire === "string")
+            ? type
+            : { quantized: resolveQuantize(type.quantized as any) } as any;
+
     } else if (typeof (type['type']) !== "undefined") {
         return type['type'];
 
@@ -146,8 +155,9 @@ export const Metadata = {
             configurable: true,
         });
 
-        // if child Ref/complex type, add to -4
-        if (typeof (metadata[index].type) !== "string") {
+        // if child Ref/complex type, add to -4. Quantized fields are scalar (their
+        // `type` is an object only to carry the descriptor) — not refs, so skip them.
+        if (typeof (metadata[index].type) !== "string" && !isQuantizedType(metadata[index].type)) {
             if (metadata[$refTypeFieldIndexes] === undefined) {
                 Object.defineProperty(metadata, $refTypeFieldIndexes, {
                     value: [],
@@ -216,11 +226,24 @@ export const Metadata = {
 
         metadata[$viewFieldIndexes].push(index);
 
-        if (!metadata[$fieldIndexesByViewTag][tag]) {
-            metadata[$fieldIndexesByViewTag][tag] = [];
+        // Populate $fieldIndexesByViewTag: for a bitmask tag, register the field
+        // index under each individual set bit so that view.add(obj, Tag.ONE) finds
+        // fields tagged @view(Tag.ONE|Tag.TWO).
+        // Negative tags (i.e. DEFAULT_VIEW_TAG = -1) are stored as-is.
+        if (tag < 0) {
+            if (!metadata[$fieldIndexesByViewTag][tag]) {
+                metadata[$fieldIndexesByViewTag][tag] = [];
+            }
+            metadata[$fieldIndexesByViewTag][tag].push(index);
+        } else {
+            for (let bits = tag; bits > 0; bits &= bits - 1) {
+                const bit = bits & (-bits); // isolate lowest set bit
+                if (!metadata[$fieldIndexesByViewTag][bit]) {
+                    metadata[$fieldIndexesByViewTag][bit] = [];
+                }
+                metadata[$fieldIndexesByViewTag][bit].push(index);
+            }
         }
-
-        metadata[$fieldIndexesByViewTag][tag].push(index);
     },
 
     setUnreliable(metadata: Metadata, fieldName: string) {
@@ -358,8 +381,8 @@ export const Metadata = {
             Object.defineProperty(target.prototype, fieldName, metadata[$descriptors][fieldName]);
         }
 
-        // Pre-compute encoder function for primitive types.
-        if (typeof normalized === "string") {
+        // Pre-compute encoder function for primitive + quantized types.
+        if (typeof normalized === "string" || isQuantizedType(normalized)) {
             if (!metadata[$encoders]) {
                 Object.defineProperty(metadata, $encoders, {
                     value: [],
@@ -368,7 +391,9 @@ export const Metadata = {
                     writable: true,
                 });
             }
-            metadata[$encoders][fieldIndex] = (encode as any)[normalized];
+            metadata[$encoders][fieldIndex] = (typeof normalized === "string")
+                ? (encode as any)[normalized]
+                : makeQuantizedEncoder((normalized as any).quantized);
         }
     },
 

package/src/Reflection.ts

@@ -8,6 +8,7 @@ import { Schema } from "./Schema.js";
 import { t, FieldBuilder } from "./types/builder.js";
 import { ArraySchema } from "./types/custom/ArraySchema.js";
 import { $encodeDescriptor, $numFields } from "./types/symbols.js";
+import { isQuantizedType, resolveQuantize } from "./types/quantize.js";
 
 /**
  * Static methods available on Reflection
@@ -52,10 +53,30 @@ interface ReflectionStatic {
 /**
  * Reflection
  */
+
+/**
+ * `t.quantized()` field descriptor as it rides the reflection handshake —
+ * schema-typed (bit-exact float64 bounds), NOT a string grammar, so every
+ * language port decodes it with the schema decoder it already has.
+ */
+export const QuantizedDescriptor = schema({
+    min: t.float64(),
+    max: t.float64(),
+    bits: t.uint8(),
+    mode: t.uint8(), // 0 = clamp, 1 = wrap
+}, "QuantizedDescriptor");
+export type QuantizedDescriptor = SchemaType<typeof QuantizedDescriptor>;
+
 export const ReflectionField = schema({
     name: t.string(),
     type: t.string(),
     referencedType: t.number(),
+    /** Primitive child of a collection (`array`/`map`/... of "string" etc.) —
+     *  its own slot, replacing the legacy `"array:string"` colon packing. */
+    childPrimitive: t.string(),
+    /** Set only on `t.quantized()` fields (`.optional()` — no auto-instantiated
+     *  default; its absence is the "not quantized" signal on decode). */
+    quantized: t.ref(QuantizedDescriptor).optional(),
 }, "ReflectionField");
 export type ReflectionField = SchemaType<typeof ReflectionField>;
 
@@ -147,6 +168,18 @@ Reflection.encode = function (encoder: Encoder, it: Iterator = { offset: 0 }) {
                 if (typeof (field.type) === "string") {
                     fieldType = field.type;
 
+                } else if (isQuantizedType(field.type)) {
+                    // Params ride as a schema-typed descriptor (bit-exact float64) —
+                    // no string grammar for the peer (or a language port) to parse.
+                    const d = field.type.quantized;
+                    fieldType = "quantized";
+                    const desc = new QuantizedDescriptor();
+                    desc.min = d.min;
+                    desc.max = d.max;
+                    desc.bits = d.bits;
+                    desc.mode = d.wrap ? 1 : 0;
+                    reflectionField.quantized = desc;
+
                 } else {
                     let childTypeSchema: typeof Schema;
 
@@ -161,7 +194,8 @@ Reflection.encode = function (encoder: Encoder, it: Iterator = { offset: 0 }) {
                         fieldType = Object.keys(field.type)[0];
 
                         if (typeof (field.type[fieldType as keyof typeof field.type]) === "string") {
-                            fieldType += ":" + field.type[fieldType as keyof typeof field.type]; // array:string
+                            // primitive child gets its own slot (was packed as "array:string")
+                            reflectionField.childPrimitive = field.type[fieldType as keyof typeof field.type] as string;
 
                         } else {
                             childTypeSchema = field.type[fieldType as keyof typeof field.type];
@@ -215,16 +249,20 @@ Reflection.decode = function <T extends Schema = Schema>(bytes: Uint8Array, it?:
         reflectionType.fields.forEach((field, i) => {
             const fieldIndex = parentFieldIndex + i;
 
-            if (field.referencedType !== undefined) {
-                let fieldType = field.type;
-                let refType: PrimitiveType = typeContext.get(field.referencedType);
-
-                // map or array of primitive type (-1)
-                if (!refType) {
-                    const typeInfo = field.type.split(":");
-                    fieldType = typeInfo[0];
-                    refType = typeInfo[1] as PrimitiveType; // string
-                }
+            if (field.quantized !== undefined) {
+                // Schema-typed descriptor → resolved codec (validation stays in
+                // resolveQuantize, same as the builder path).
+                const q = field.quantized;
+                Metadata.addField(metadata, fieldIndex, field.name, {
+                    quantized: resolveQuantize({ min: q.min, max: q.max, bits: q.bits as 8 | 16 | 32, mode: q.mode === 1 ? "wrap" : "clamp" }),
+                } as any);
+
+            } else if (field.referencedType !== undefined) {
+                const fieldType = field.type;
+                // Schema child by type id; a primitive child (referencedType -1)
+                // rides its own childPrimitive slot.
+                const refType: PrimitiveType = typeContext.get(field.referencedType)
+                    ?? field.childPrimitive as PrimitiveType;
 
                 if (fieldType === "ref") {
                     Metadata.addField(metadata, fieldIndex, field.name, refType);