@colyseus/schema 5.0.11 → 5.0.13

package/build/types/builder.d.ts

@@ -16,12 +16,11 @@ export interface BuilderDefinition {
     default?: any;
     hasDefault: boolean;
     view?: number;
-    owned?: boolean;
     unreliable?: boolean;
-    transient?: boolean;
+    patchOnly?: boolean;
     deprecated?: boolean;
     deprecatedThrows?: boolean;
-    static?: boolean;
+    fullStateOnly?: boolean;
     stream?: boolean;
     optional?: boolean;
     /** Local-only field: typed + initialized, but never registered for sync. */
@@ -60,12 +59,11 @@ export declare class FieldBuilder<T = unknown, HasDefault extends boolean = fals
     private _default;
     private _hasDefault;
     private _view;
-    private _owned;
     private _unreliable;
-    private _transient;
+    private _patchOnly;
     private _deprecated;
     private _deprecatedThrows;
-    private _static;
+    private _fullStateOnly;
     private _stream;
     private _optional;
     private _noSync;
@@ -90,28 +88,36 @@ export declare class FieldBuilder<T = unknown, HasDefault extends boolean = fals
     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). */
-    owned(): this;
     /**
      * Mark this field as unreliable — tick patches emit it on the unreliable
      * transport channel. Still persisted to full-sync snapshots unless also
-     * tagged with `.transient()`.
+     * tagged with `.patchOnly()`. Primitive fields only.
+     *
+     * The field's FIRST value still travels the reliable channel, as part of
+     * the owning instance's ADD; only later mutations become unreliable. A
+     * decoder cannot apply a write to a ref it has not been told about, so a
+     * value emitted ahead of that ADD would be dropped — and lost for good if
+     * the field is never written again.
      */
     unreliable(): this;
     /**
-     * Mark this field as transient — NOT persisted to full-sync snapshots
-     * (`encodeAll` / `encodeAllView`). Late-joining clients see the field
-     * only after its next mutation is emitted on a tick patch. Orthogonal
-     * to `.unreliable()`.
+     * Deliver this field on tick patches ONLY — it is never written to a
+     * full-state sync (`encodeAll` / `encodeAllView`). Late-joining clients
+     * see the field only after its next mutation is emitted on a patch.
+     * The mirror of `.fullStateOnly()`, and orthogonal to `.unreliable()`.
      */
-    transient(): this;
+    patchOnly(): this;
     /**
-     * Mark this field as static.
-     * - Primitive / Schema fields: synchronized once, skips change tracking.
-     * - Stream fields (`t.stream(X).static()`): child elements are frozen
-     *   after add — post-add field mutations on elements become no-ops.
+     * Deliver this field in the full state sync ONLY (`encodeAll` /
+     * `encodeAllView`) — it never enters a tick patch. A client receives it
+     * on join (and again on a resync); writes after that are not tracked.
+     * The mirror of `.patchOnly()`.
+     *
+     * The field itself is NOT frozen — it stays mutable server-side, only
+     * its propagation stops. On a stream field (`t.stream(X).fullStateOnly()`)
+     * the same rule applies per element: post-add mutations are no-ops.
      */
-    static(): this;
+    fullStateOnly(): this;
     /**
      * Mark this field as **local-only** — it is typed and initialized on the
      * instance (so `.default()` and the inferred instance type still apply),
@@ -121,8 +127,8 @@ export declare class FieldBuilder<T = unknown, HasDefault extends boolean = fals
      * Useful for server-side scratch state, per-peer UI state, or values you
      * want on the class for typing convenience without paying any sync cost.
      *
-     * Mutually exclusive with the sync-only modifiers (`.view()`, `.owned()`,
-     * `.unreliable()`, `.transient()`, `.static()`, `.stream()`) — combining
+     * Mutually exclusive with the sync-only modifiers (`.view()`,
+     * `.unreliable()`, `.patchOnly()`, `.fullStateOnly()`, `.stream()`) — combining
      * them throws at `schema()` time.
      *
      * ```ts
@@ -154,9 +160,12 @@ export declare class FieldBuilder<T = unknown, HasDefault extends boolean = fals
      * higher return values emit first. Does nothing in broadcast mode
      * (shared `encode()` drains FIFO). Only meaningful on stream fields.
      *
+     * `StateView` carries no position of its own — attach whatever the
+     * callback needs to sort by (`view` is loosely typed for this).
+     *
      * ```ts
      * t.stream(Enemy).priority((view, enemy) =>
-     *     -dist2(view.anchor, enemy)
+     *     -((enemy.x - view.x) ** 2 + (enemy.y - view.y) ** 2)
      * )
      * ```
      */

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

@@ -63,6 +63,23 @@ export declare class ArraySchema<V = any> implements Array<V>, Collection<number
      * land on the wrong wire slots.
      */
     protected $wireIndex(index: number): number;
+    /**
+     * Re-point children at their wire slot. `ChangeTree._parentIndex` caches
+     * the slot a child holds in `tmpItems`, and StateView addresses per-view
+     * ADD/DELETE with it — so a reorder that leaves it behind aims those ops
+     * at whichever element inherited the slot (issue #231).
+     *
+     * The filter check is a correctness boundary, not a tunable: StateView is
+     * the only reader and reaches the index only through a filtered array
+     * (`addParentOf` bails on `hasFilteredFields`, `remove` on the child's
+     * `isFiltered`). Everything else stops at the flag read instead of walking
+     * its children every tick.
+     *
+     * Callers name the lowest slot that moved as `from`. Compaction cannot, so
+     * it hands over the pre-compaction layout as `staged` and the unchanged
+     * prefix is skipped instead. Either way tail churn walks nothing.
+     */
+    protected $reindexChildren(from: number, staged?: V[]): void;
     protected $changeAt(index: number, value: V): number | undefined;
     protected $deleteAt(index: number, operation?: OPERATION): void;
     protected $setAt(index: number, value: V, operation: OPERATION): void;

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

@@ -11,7 +11,7 @@ import type { Schema } from "../../Schema.js";
  * per-client and drained in priority order (callback on StateView) up to
  * `maxPerTick` per encode pass. Field mutations on already-sent elements
  * propagate through the normal reliable channel without consuming the
- * per-tick budget. Chain `.static()` on the field builder to suppress
+ * per-tick budget. Chain `.fullStateOnly()` on the field builder to suppress
  * post-add mutation tracking entirely.
  */
 export declare class StreamSchema<V = any> implements IRef {

package/build/types/symbols.d.ts

@@ -66,16 +66,10 @@ export declare const $builder = "~builder";
  * Metadata
  */
 export declare const $descriptors = "~descriptors";
-/**
- * Per-class bitmask: bit i set iff field i carries a @view tag.
- * Lazily computed from $viewFieldIndexes on first encode pass.
- * Skips the per-field metadata[i].tag property chase in the hot encode loop.
- */
-export declare const $filterBitmask = "~__filterBitmask";
 /**
  * Cached per-class encode descriptor: bundles encoder fn, filter fn,
- * metadata, isSchema flag, and filterBitmask into one object stashed on
- * the constructor. Replaces 5 separate per-tree property chases /
+ * metadata, isSchema flag and the per-field arrays into one object stashed
+ * on the constructor. Replaces several separate per-tree property chases /
  * function calls in the encode loop with a single property load.
  */
 export declare const $encodeDescriptor = "~__encodeDescriptor";
@@ -85,7 +79,7 @@ export declare const $refTypeFieldIndexes = "~__refTypeFieldIndexes";
 export declare const $viewFieldIndexes = "~__viewFieldIndexes";
 export declare const $fieldIndexesByViewTag = "$__fieldIndexesByViewTag";
 export declare const $unreliableFieldIndexes = "~__unreliableFieldIndexes";
-export declare const $transientFieldIndexes = "~__transientFieldIndexes";
-export declare const $staticFieldIndexes = "~__staticFieldIndexes";
+export declare const $patchOnlyFieldIndexes = "~__patchOnlyFieldIndexes";
+export declare const $fullStateOnlyFieldIndexes = "~__fullStateOnlyFieldIndexes";
 export declare const $streamFieldIndexes = "~__streamFieldIndexes";
 export declare const $streamPriorities = "~__streamPriorities";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colyseus/schema",
-  "version": "5.0.11",
+  "version": "5.0.13",
   "description": "Binary state serializer with delta encoding for games",
   "type": "module",
   "bin": {

package/src/Metadata.ts

@@ -1,22 +1,31 @@
 import { DefinitionType, getPropertyDescriptor } from "./annotations.js";
 import { Schema } from "./Schema.js";
 import { getType, registeredTypes, TypeDefinition } from "./types/registry.js";
-import { $decoder, $descriptors, $encoder, $encoders, $fieldIndexesByViewTag, $numFields, $refTypeFieldIndexes, $staticFieldIndexes, $streamFieldIndexes, $streamPriorities, $track, $transientFieldIndexes, $unreliableFieldIndexes, $viewFieldIndexes } from "./types/symbols.js";
+import { $decoder, $descriptors, $encoder, $encoders, $fieldIndexesByViewTag, $numFields, $refTypeFieldIndexes, $fullStateOnlyFieldIndexes, $streamFieldIndexes, $streamPriorities, $track, $patchOnlyFieldIndexes, $unreliableFieldIndexes, $viewFieldIndexes } from "./types/symbols.js";
 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";
 
+/**
+ * Field indexes ride in the low 6 bits of the operation byte
+ * (`(index | operation) & 255`), which leaves room for 0..63. Index 63 is
+ * given up: `DELETE_AND_ADD | 63` is 255, the same byte the decoder claims
+ * as SWITCH_TO_STRUCTURE before any field decoder sees it. Every nullable
+ * field can produce that operation (delete-then-set in one tick merges to
+ * DELETE_AND_ADD), so the slot is unusable rather than partly usable.
+ */
+export const MAX_FIELDS = 63;
+
 export type MetadataField = {
     type: DefinitionType,
     name: string,
     index: number,
     tag?: number,
     unreliable?: boolean,
-    transient?: boolean,
+    patchOnly?: boolean,
     deprecated?: boolean,
-    owned?: boolean,
-    static?: boolean,
+    fullStateOnly?: boolean,
     stream?: boolean,
     optional?: boolean,
 };
@@ -27,8 +36,8 @@ export type Metadata =
     { [$fieldIndexesByViewTag]: {[tag: number]: number[]}; } & // field indexes by "view" tag
     { [$refTypeFieldIndexes]: number[]; } & // all field indexes containing Ref types (Schema, ArraySchema, MapSchema, etc)
     { [$unreliableFieldIndexes]: number[]; } & // all field indexes tagged with @unreliable
-    { [$transientFieldIndexes]: number[]; } & // all field indexes tagged with @transient (not persisted to snapshots)
-    { [$staticFieldIndexes]: number[]; } & // all field indexes tagged with @static (not tracked after assignment)
+    { [$patchOnlyFieldIndexes]: number[]; } & // all field indexes tagged with @patchOnly (not persisted to snapshots)
+    { [$fullStateOnlyFieldIndexes]: number[]; } & // all field indexes tagged @fullStateOnly / .fullStateOnly() (not tracked after assignment)
     { [$streamFieldIndexes]: number[]; } & // all field indexes holding a t.stream(...) collection
     { [$streamPriorities]: { [field: number]: (view: any, element: any) => number }; } & // per-stream-field priority callback declared at schema definition time
     { [$encoders]: Array<(bytes: Uint8Array, value: any, it: any) => void>; } & // pre-computed encoder fn per primitive field
@@ -107,12 +116,14 @@ function isTSEnum(_enum: any) {
 export const Metadata = {
 
     addField(metadata: any, index: number, name: string, type: DefinitionType, descriptor?: PropertyDescriptor) {
-        if (index > 64) {
-            throw new Error(`Can't define field '${name}'.\nSchema instances may only have up to 64 fields.`);
+        // `index` is 0-based, so 62 is the last usable slot — see MAX_FIELDS
+        // for why 63 is off limits.
+        if (index >= MAX_FIELDS) {
+            throw new Error(`Can't define field '${name}'.\nSchema instances may only have up to ${MAX_FIELDS} fields.`);
         }
 
         metadata[index] = Object.assign(
-            metadata[index] || {}, // avoid overwriting previous field metadata (@owned / @deprecated)
+            metadata[index] || {}, // avoid overwriting previous field metadata (@deprecated / @unreliable)
             {
                 type: getNormalizedType(type),
                 index,
@@ -278,34 +289,50 @@ export const Metadata = {
         metadata[$unreliableFieldIndexes].push(index);
     },
 
-    setTransient(metadata: Metadata, fieldName: string) {
+    setPatchOnly(metadata: Metadata, fieldName: string) {
         const index = metadata[fieldName];
-        metadata[index].transient = true;
+        // patchOnly + fullStateOnly are the only two delivery channels —
+        // excluding a field from both would silently never reach a client.
+        // (The builder validates earlier; this guards the decorator path.)
+        if (metadata[index].fullStateOnly) {
+            throw new Error(
+                `field "${fieldName}" cannot be both patchOnly and fullStateOnly — ` +
+                `those are the only two delivery channels, so the field would never reach a client.`
+            );
+        }
+        metadata[index].patchOnly = true;
 
-        if (!metadata[$transientFieldIndexes]) {
-            Object.defineProperty(metadata, $transientFieldIndexes, {
+        if (!metadata[$patchOnlyFieldIndexes]) {
+            Object.defineProperty(metadata, $patchOnlyFieldIndexes, {
                 value: [],
                 enumerable: false,
                 configurable: true,
                 writable: true,
             });
         }
-        metadata[$transientFieldIndexes].push(index);
+        metadata[$patchOnlyFieldIndexes].push(index);
     },
 
-    setStatic(metadata: Metadata, fieldName: string) {
+    setFullStateOnly(metadata: Metadata, fieldName: string) {
         const index = metadata[fieldName];
-        metadata[index].static = true;
+        // Mirror of the guard in setPatchOnly — covers both decorator orders.
+        if (metadata[index].patchOnly) {
+            throw new Error(
+                `field "${fieldName}" cannot be both patchOnly and fullStateOnly — ` +
+                `those are the only two delivery channels, so the field would never reach a client.`
+            );
+        }
+        metadata[index].fullStateOnly = true;
 
-        if (!metadata[$staticFieldIndexes]) {
-            Object.defineProperty(metadata, $staticFieldIndexes, {
+        if (!metadata[$fullStateOnlyFieldIndexes]) {
+            Object.defineProperty(metadata, $fullStateOnlyFieldIndexes, {
                 value: [],
                 enumerable: false,
                 configurable: true,
                 writable: true,
             });
         }
-        metadata[$staticFieldIndexes].push(index);
+        metadata[$fullStateOnlyFieldIndexes].push(index);
     },
 
     setStream(metadata: Metadata, fieldName: string) {
@@ -503,20 +530,20 @@ export const Metadata = {
                     });
                 }
 
-                // $transientFieldIndexes
-                if (parentMetadata[$transientFieldIndexes] !== undefined) {
-                    Object.defineProperty(metadata, $transientFieldIndexes, {
-                        value: [...parentMetadata[$transientFieldIndexes]],
+                // $patchOnlyFieldIndexes
+                if (parentMetadata[$patchOnlyFieldIndexes] !== undefined) {
+                    Object.defineProperty(metadata, $patchOnlyFieldIndexes, {
+                        value: [...parentMetadata[$patchOnlyFieldIndexes]],
                         enumerable: false,
                         configurable: true,
                         writable: true,
                     });
                 }
 
-                // $staticFieldIndexes
-                if (parentMetadata[$staticFieldIndexes] !== undefined) {
-                    Object.defineProperty(metadata, $staticFieldIndexes, {
-                        value: [...parentMetadata[$staticFieldIndexes]],
+                // $fullStateOnlyFieldIndexes
+                if (parentMetadata[$fullStateOnlyFieldIndexes] !== undefined) {
+                    Object.defineProperty(metadata, $fullStateOnlyFieldIndexes, {
+                        value: [...parentMetadata[$fullStateOnlyFieldIndexes]],
                         enumerable: false,
                         configurable: true,
                         writable: true,
@@ -586,12 +613,12 @@ export const Metadata = {
         return metadata?.[$unreliableFieldIndexes]?.includes(index);
     },
 
-    hasTransientAtIndex(metadata: Metadata, index: number) {
-        return metadata?.[$transientFieldIndexes]?.includes(index);
+    hasPatchOnlyAtIndex(metadata: Metadata, index: number) {
+        return metadata?.[$patchOnlyFieldIndexes]?.includes(index);
     },
 
-    hasStaticAtIndex(metadata: Metadata, index: number) {
-        return metadata?.[$staticFieldIndexes]?.includes(index);
+    hasFullStateOnlyAtIndex(metadata: Metadata, index: number) {
+        return metadata?.[$fullStateOnlyFieldIndexes]?.includes(index);
     },
 
     hasStreamAtIndex(metadata: Metadata, index: number) {

package/src/annotations.ts

@@ -37,12 +37,12 @@ export type PrimitiveType = RawPrimitiveType | typeof Schema | object;
 // TODO: infer "default" value type correctly.
 export type DefinitionType<T extends PrimitiveType = PrimitiveType> = T
     | T[]
-    | { type: T, default?: InferValueType<T>, view?: boolean | number, sync?: boolean, owned?: boolean }
-    | { array: T, default?: ArraySchema<InferValueType<T>>, view?: boolean | number, sync?: boolean, owned?: boolean }
-    | { map: T, default?: MapSchema<InferValueType<T>>, view?: boolean | number, sync?: boolean, owned?: boolean }
-    | { collection: T, default?: CollectionSchema<InferValueType<T>>, view?: boolean | number, sync?: boolean, owned?: boolean }
-    | { set: T, default?: SetSchema<InferValueType<T>>, view?: boolean | number, sync?: boolean, owned?: boolean }
-    | { stream: T, default?: StreamSchema<InferValueType<T>>, view?: boolean | number, sync?: boolean, owned?: boolean, priority?: (view: any, element: InferValueType<T>) => number };
+    | { type: T, default?: InferValueType<T>, view?: boolean | number, sync?: boolean }
+    | { array: T, default?: ArraySchema<InferValueType<T>>, view?: boolean | number, sync?: boolean }
+    | { map: T, default?: MapSchema<InferValueType<T>>, view?: boolean | number, sync?: boolean }
+    | { collection: T, default?: CollectionSchema<InferValueType<T>>, view?: boolean | number, sync?: boolean }
+    | { set: T, default?: SetSchema<InferValueType<T>>, view?: boolean | number, sync?: boolean }
+    | { stream: T, default?: StreamSchema<InferValueType<T>>, view?: boolean | number, sync?: boolean, priority?: (view: any, element: InferValueType<T>) => number };
 
 export type Definition = { [field: string]: DefinitionType };
 
@@ -237,27 +237,46 @@ export function view<T> (tag: number = DEFAULT_VIEW_TAG) {
     }
 }
 
-export function owned<T> (target: T, field: string) {
-    const metadata = Metadata.initialize(target.constructor as typeof Schema);
-    metadata[metadata[field]].owned = true;
-}
-
+/**
+ * `@unreliable` — route a field onto the unreliable transport channel, so a
+ * dropped update costs one stale value instead of stalling the ordered stream
+ * behind a retransmit. Primitive fields only (see `Metadata.setUnreliable`).
+ *
+ * The field's FIRST value still travels the reliable channel, as part of the
+ * owning instance's ADD; only later mutations become unreliable. A decoder
+ * cannot apply a write to a ref it has not been told about, so a value emitted
+ * ahead of that ADD would be dropped — and lost for good if the field is never
+ * written again.
+ */
 export function unreliable<T> (target: T, field: string) {
     const metadata = Metadata.initialize(target.constructor as typeof Schema);
     Metadata.setUnreliable(metadata, field);
 }
 
 /**
- * @transient — mark a field as not persisted to snapshots (encodeAll /
- * encodeAllView). Transient fields are still emitted on per-tick patches
+ * @patchOnly — mark a field as not persisted to snapshots (encodeAll /
+ * encodeAllView). PatchOnly fields are still emitted on per-tick patches
  * (reliable or unreliable), but late-joining clients won't see them until
  * the next mutation.
  *
  * Orthogonal to @unreliable: a field can be either, both, or neither.
  */
-export function transient<T> (target: T, field: string) {
+export function patchOnly<T> (target: T, field: string) {
     const metadata = Metadata.initialize(target.constructor as typeof Schema);
-    Metadata.setTransient(metadata, field);
+    Metadata.setPatchOnly(metadata, field);
+}
+
+/**
+ * @fullStateOnly — mark a field as delivered in the full state sync only
+ * (encodeAll / encodeAllView), never on per-tick patches. Writes after a
+ * client has joined are not propagated to it — populate these fields
+ * before clients connect (e.g. during onCreate).
+ *
+ * The exact mirror of @patchOnly — the two are mutually exclusive.
+ */
+export function fullStateOnly<T> (target: T, field: string) {
+    const metadata = Metadata.initialize(target.constructor as typeof Schema);
+    Metadata.setFullStateOnly(metadata, field);
 }
 
 export function type (
@@ -772,11 +791,10 @@ export function schema<
     };
 
     const viewTagFields: { [field: string]: number } = {};
-    const ownedFields: string[] = [];
     const unreliableFields: string[] = [];
-    const transientFields: string[] = [];
+    const patchOnlyFields: string[] = [];
     const deprecatedFields: { [field: string]: boolean } = {};
-    const staticFields: string[] = [];
+    const fullStateOnlyFields: string[] = [];
     const streamFields: string[] = [];
     const streamPriorityFields: { [field: string]: (view: any, element: any) => number } = {};
     const optionalFields: string[] = [];
@@ -791,11 +809,11 @@ export function schema<
                 // Local-only field: skip metadata registration entirely so it is
                 // never encoded/decoded, but still seed its construction default
                 // (honoring `.default()` and collection/ref auto-instantiation).
-                if (def.view !== undefined || def.owned || def.unreliable ||
-                    def.transient || def.static || def.stream) {
+                if (def.view !== undefined || def.unreliable ||
+                    def.patchOnly || def.fullStateOnly || def.stream) {
                     throw new Error(
                         `schema(${name ? `'${name}'` : ""}): field '${fieldName}' uses .noSync() ` +
-                        `together with a sync-only modifier (.view/.owned/.unreliable/.transient/.static/.stream). ` +
+                        `together with a sync-only modifier (.view/.unreliable/.patchOnly/.fullStateOnly/.stream). ` +
                         `A local-only field cannot be synchronized.`
                     );
                 }
@@ -803,6 +821,16 @@ export function schema<
                 continue;
             }
 
+            // The two delivery channels are exhaustive: excluding a field from
+            // both leaves it with nowhere to go — a silent .noSync().
+            if (def.patchOnly && def.fullStateOnly) {
+                throw new Error(
+                    `schema(${name ? `'${name}'` : ""}): field '${fieldName}' uses .patchOnly() ` +
+                    `together with .fullStateOnly(). Those are the only two delivery channels, ` +
+                    `so the field would never reach a client — use .noSync() if that is intended.`
+                );
+            }
+
             const normalizedType = getNormalizedType(def.type);
             // A synced ref must be encodable (a Schema, or Metadata.setFields()'d) — reject a bare class.
             if (typeof normalizedType === "function" && !Schema.is(normalizedType)) {
@@ -814,11 +842,10 @@ export function schema<
             fields[fieldName] = normalizedType;
 
             if (def.view !== undefined) { viewTagFields[fieldName] = def.view; }
-            if (def.owned) { ownedFields.push(fieldName); }
             if (def.unreliable) { unreliableFields.push(fieldName); }
-            if (def.transient) { transientFields.push(fieldName); }
+            if (def.patchOnly) { patchOnlyFields.push(fieldName); }
             if (def.deprecated) { deprecatedFields[fieldName] = def.deprecatedThrows; }
-            if (def.static) { staticFields.push(fieldName); }
+            if (def.fullStateOnly) { fullStateOnlyFields.push(fieldName); }
             if (def.stream) { streamFields.push(fieldName); }
             if (def.streamPriority !== undefined) { streamPriorityFields[fieldName] = def.streamPriority; }
             if (def.optional) { optionalFields.push(fieldName); }
@@ -903,23 +930,20 @@ export function schema<
     for (const fieldName in viewTagFields) {
         view(viewTagFields[fieldName])(klass.prototype, fieldName);
     }
-    for (const fieldName of ownedFields) {
-        owned(klass.prototype, fieldName);
-    }
     for (const fieldName of unreliableFields) {
         unreliable(klass.prototype, fieldName);
     }
-    for (const fieldName of transientFields) {
-        transient(klass.prototype, fieldName);
+    for (const fieldName of patchOnlyFields) {
+        patchOnly(klass.prototype, fieldName);
     }
     for (const fieldName in deprecatedFields) {
         deprecated(deprecatedFields[fieldName])(klass.prototype, fieldName);
     }
 
-    if (staticFields.length > 0 || streamFields.length > 0) {
+    if (fullStateOnlyFields.length > 0 || streamFields.length > 0) {
         const metadata = (klass as any)[Symbol.metadata] as Metadata;
-        for (const fieldName of staticFields) {
-            Metadata.setStatic(metadata, fieldName);
+        for (const fieldName of fullStateOnlyFields) {
+            Metadata.setFullStateOnly(metadata, fieldName);
         }
         for (const fieldName of streamFields) {
             Metadata.setStream(metadata, fieldName);

package/src/codegen/api.ts

@@ -14,8 +14,9 @@ import * as java from "./languages/java.js";
 import * as lua from "./languages/lua.js";
 import * as c from "./languages/c.js";
 import * as gdscript from "./languages/gdscript.js";
+import * as dart from "./languages/dart.js";
 
-export const generators: Record<string, any> = { csharp, cpp, haxe, ts, js, java, lua, c, gdscript, };
+export const generators: Record<string, any> = { csharp, cpp, haxe, ts, js, java, lua, c, gdscript, dart, };
 
 export interface GenerateOptions {
     files: string[],

package/src/codegen/languages/c.ts

@@ -1,4 +1,4 @@
-import { Class, Property, File, getCommentHeader, getInheritanceTree, Context } from "../types.js";
+import { Class, Property, File, getCommentHeader, getInheritanceTree, Context, resolveQuantized } from "../types.js";
 import { GenerateOptions } from "../api.js";
 
 export const name = "C";
@@ -20,6 +20,7 @@ const typeMaps: { [key: string]: string } = {
     "uint64": "uint64_t",
     "float32": "float",
     "float64": "double",
+    "quantized": "double",
 };
 
 /**
@@ -42,6 +43,7 @@ const fieldTypeMaps: { [key: string]: string } = {
     "ref": "COLYSEUS_FIELD_REF",
     "array": "COLYSEUS_FIELD_ARRAY",
     "map": "COLYSEUS_FIELD_MAP",
+    "quantized": "COLYSEUS_FIELD_QUANTIZED",
 };
 
 const COMMON_INCLUDES = `#include "colyseus/schema/types.h"
@@ -202,11 +204,22 @@ function generateFieldsArray(klass: Class, typeName: string, snakeName: string,
         return `static const colyseus_field_t ${snakeName}_fields[] = {};`;
     }
 
+    // one pre-resolved static descriptor per quantized field
+    const descriptors = allProperties
+        .filter(prop => prop.quantized)
+        .map(prop => {
+            const q = prop.quantized;
+            const { range, span } = resolveQuantized(q);
+            return `static const colyseus_quantized_descriptor_t ${snakeName}_${prop.name}_quantized = {${q.min}, ${q.max}, ${range}, ${span}, ${q.bits}, ${q.wrap}};`;
+        });
+
     const fields = allProperties.map((prop, i) => {
         const fieldType = getFieldType(prop);
         const typeString = getFieldTypeString(prop);
 
         let vtableRef = "NULL";
+        let childPrimitiveRef = "NULL";
+        let quantizedRef = "NULL";
 
         if (prop.type === "ref" && prop.childType && !typeMaps[prop.childType]) {
             const childSnake = toSnakeCase(prop.childType);
@@ -214,12 +227,17 @@ function generateFieldsArray(klass: Class, typeName: string, snakeName: string,
         } else if ((prop.type === "array" || prop.type === "map") && prop.childType && !typeMaps[prop.childType]) {
             const childSnake = toSnakeCase(prop.childType);
             vtableRef = `&${childSnake}_vtable`;
+        } else if ((prop.type === "array" || prop.type === "map") && prop.childType) {
+            // collection of primitives — the decoder strcmp()s this to pick the reader
+            childPrimitiveRef = `"${prop.childType}"`;
+        } else if (prop.quantized) {
+            quantizedRef = `&${snakeName}_${prop.name}_quantized`;
         }
 
-        return `    {${prop.index}, "${prop.name}", ${fieldType}, "${typeString}", offsetof(${typeName}, ${prop.name}), ${vtableRef}, NULL}`;
+        return `    {${prop.index}, "${prop.name}", ${fieldType}, "${typeString}", offsetof(${typeName}, ${prop.name}), ${vtableRef}, ${childPrimitiveRef}, ${quantizedRef}}`;
     }).join(",\n");
 
-    return `static const colyseus_field_t ${snakeName}_fields[] = {
+    return `${descriptors.length ? descriptors.join("\n") + "\n\n" : ""}static const colyseus_field_t ${snakeName}_fields[] = {
 ${fields}
 };`;
 }

package/src/codegen/languages/csharp.ts

@@ -191,7 +191,13 @@ function generateProperty(prop: Property, indent: string = "") {
     let langType: string;
     let initializer = "";
 
-    if (prop.childType) {
+    if (prop.quantized) {
+        const q = prop.quantized;
+        typeArgs += `, QuantizeMin = ${q.min}, QuantizeMax = ${q.max}, QuantizeBits = ${q.bits}, QuantizeWrap = ${q.wrap}`;
+        langType = "double";
+        initializer = "default(double)";
+
+    } else if (prop.childType) {
         const isUpcaseFirst = prop.childType.match(/^[A-Z]/);
 
         langType = getType(prop);