@colyseus/schema 5.0.10 → 5.0.12

package/build/codegen/languages/dart.d.ts

@@ -0,0 +1,20 @@
+import { File, Context } from "../types.js";
+import { GenerateOptions } from "../api.js";
+export declare const name = "Dart/Flutter";
+/**
+ * Dart Code Generator
+ *
+ * Emits typed façades over the `colyseus` Flutter package's runtime: one
+ * `SchemaRef` subclass per schema, with typed getters over the shared native
+ * handle. Collection getters return `MapSchema<T>` / `ArraySchema<T>`, which
+ * also carry the field they came from — that is what
+ * `callbacks.onAdd(state.players, ...)` registers against.
+ */
+/**
+ * Generate individual files for each class/interface/enum
+ */
+export declare function generate(context: Context, options: GenerateOptions): File[];
+/**
+ * Generate a single bundled file containing all classes, interfaces, and enums
+ */
+export declare function renderBundle(context: Context, options: GenerateOptions): File;

package/build/codegen/types.d.ts

@@ -37,11 +37,31 @@ export declare class Enum implements IStructure {
     properties: Property[];
     addProperty(property: Property): void;
 }
+/**
+ * Statically-extracted `t.quantized()` options. `wrap` is already normalized
+ * from the source's `mode` string; emitters derive `range`/`span` via
+ * {@link resolveQuantized} so every language ships identical precomputed values.
+ */
+export interface QuantizedProperty {
+    min: number;
+    max: number;
+    bits: 8 | 16 | 32;
+    wrap: boolean;
+}
+/**
+ * Mirror of the runtime's `resolveQuantize()` scale math (wrap spreads 2^bits
+ * steps across [min,max); clamp maps the endpoints onto 0 and 2^bits-1).
+ */
+export declare function resolveQuantized(q: QuantizedProperty): {
+    range: number;
+    span: number;
+};
 export declare class Property {
     index: number;
     name: string;
     type: string;
     childType: string;
+    quantized?: QuantizedProperty;
     deprecated?: boolean;
 }
 export interface File {

package/build/decoder/Resync.d.ts

@@ -42,8 +42,8 @@ export declare function resyncTouchEntry(decoder: Decoder, ref: any, operation:
 /**
  * Mark a collection as present in the payload — even with zero entries.
  * The sweep only prunes collections reported here: absence means "not part
- * of full-sync" (@transient, view-invisible), where pruning would destroy
- * live data. Reflected clients have no @transient metadata, so payload
+ * of full-sync" (@patchOnly, view-invisible), where pruning would destroy
+ * live data. Reflected clients have no @patchOnly metadata, so payload
  * presence is the only reliable signal.
  */
 export declare function resyncMarkPresent(decoder: Decoder, refId: number): void;
@@ -52,7 +52,7 @@ export declare function resyncMarkPresent(decoder: Decoder, refId: number): void
  * entry the snapshot did not visit.
  *
  * Walks the tree from the root — NOT `root.refs` — for three reasons:
- * `@transient` fields are never part of a snapshot and must be left alone;
+ * `@patchOnly` fields are never part of a snapshot and must be left alone;
  * entries of subtrees removed by the sweep itself are left to the GC's
  * transitive walk (sweeping them directly would double-decrement shared
  * children); and collections the snapshot never mentions (emptied

package/build/encoder/ChangeTree.d.ts

@@ -8,7 +8,7 @@
  *
  *   - parentChain.ts     addParent / removeParent / find / has / getAll
  *   - liveIteration.ts   forEachLive
- *   - inheritedFlags.ts  filter / unreliable / transient / static inheritance
+ *   - inheritedFlags.ts  filter / unreliable / patchOnly / static inheritance
  *   - treeAttachment.ts  setRoot / setParent / forEachChild(+WithCtx)
  *
  * Public surface on ChangeTree is unchanged — methods are thin pass-throughs
@@ -51,6 +51,7 @@ export interface ChangeTreeNode {
 export interface ChangeTreeList {
     next?: ChangeTreeNode;
     tail?: ChangeTreeNode;
+    nextPosition: number;
 }
 export declare function createChangeTreeList(): ChangeTreeList;
 export interface ParentChain {
@@ -59,7 +60,7 @@ export interface ParentChain {
     next?: ParentChain;
 }
 export declare const IS_FILTERED = 1, IS_VISIBILITY_SHARED = 2, IS_NEW = 4;
-export declare const IS_UNRELIABLE = 8, IS_TRANSIENT = 16, IS_STATIC = 32;
+export declare const IS_UNRELIABLE = 8, IS_PATCH_ONLY = 16, IS_FULL_STATE_ONLY = 32;
 export declare const IS_STREAM_COLLECTION = 64;
 export declare const NEEDS_RESTAGE = 128;
 /**
@@ -95,8 +96,8 @@ export declare class ChangeTree<T extends Ref = any> implements ChangeRecorder {
     refTarget: T;
     metadata: Metadata;
     /**
-     * Per-class cache of encoder fn / filter fn / isSchema / filterBitmask /
-     * metadata, looked up once at construction. The encode loop reads
+     * Per-class cache of encoder fn / filter fn / isSchema / metadata /
+     * per-field arrays, looked up once at construction. The encode loop reads
      * `tree.encDescriptor` and never touches `ref.constructor` again. See
      * EncodeDescriptor.ts.
      */
@@ -129,7 +130,6 @@ export declare class ChangeTree<T extends Ref = any> implements ChangeRecorder {
     changesNode?: ChangeTreeNode;
     unreliableChangesNode?: ChangeTreeNode;
     visibleViews?: number[];
-    invisibleViews?: number[];
     tagViews?: Map<number, number[]>;
     /**
      * Per-view subscription bitmap — same layout as `visibleViews`. Set by
@@ -149,10 +149,10 @@ export declare class ChangeTree<T extends Ref = any> implements ChangeRecorder {
     set isNew(v: boolean);
     get isUnreliable(): boolean;
     set isUnreliable(v: boolean);
-    get isTransient(): boolean;
-    set isTransient(v: boolean);
-    get isStatic(): boolean;
-    set isStatic(v: boolean);
+    get isPatchOnly(): boolean;
+    set isPatchOnly(v: boolean);
+    get isFullStateOnly(): boolean;
+    set isFullStateOnly(v: boolean);
     get isStreamCollection(): boolean;
     set isStreamCollection(v: boolean);
     get needsRestage(): boolean;
@@ -160,7 +160,7 @@ export declare class ChangeTree<T extends Ref = any> implements ChangeRecorder {
     get hasFilteredFields(): boolean;
     ensureUnreliableRecorder(): ChangeRecorder;
     isFieldUnreliable(index: number): boolean;
-    isFieldStatic(index: number): boolean;
+    isFieldFullStateOnly(index: number): boolean;
     isFieldStream(index: number): boolean;
     constructor(ref: T);
     private _opAt;
@@ -219,6 +219,18 @@ export declare class ChangeTree<T extends Ref = any> implements ChangeRecorder {
      * fields (see annotations.ts), so the per-field unreliable flag here
      * always means "primitive value updates" — the structural-ADD-routes-
      * reliable footgun for ref-type fields can't reach this code path.
+     *
+     * `!isNew` holds an `@unreliable` field on the RELIABLE channel until this
+     * tree's own ADD has shipped there. A decoder can only apply a field write
+     * to a ref it already knows, so a value emitted before the ADD is dropped —
+     * permanently, if the field is never written again. `isNew` clears in
+     * `endEncode()`, i.e. after a reliable pass, and recording reliably is
+     * itself what enqueues the tree for that pass; the state is self-clearing
+     * and no tree can be stranded on the wrong channel. Mirrors `encodeAll`,
+     * which has always seeded these fields for late joiners.
+     *
+     * Ordering matters: `isFieldUnreliable` short-circuits on the class-level
+     * `hasAnyUnreliable`, so schemas without the modifier never read `flags`.
      */
     private _routeAndRecord;
     change(index: number, operation?: OPERATION): void;

package/build/encoder/EncodeDescriptor.d.ts

@@ -7,34 +7,33 @@ export interface EncodeDescriptor {
     isSchema: boolean;
     /**
      * Bit i set iff field i has a @view tag. 0 for collection trees.
-     * Lets `encodeChangeCb` do a single bitwise op instead of a
-     * per-field metadata[i]?.tag chase.
+     * Lets `encodeChangeCb` do a single bitwise op instead of a per-field
+     * metadata[i]?.tag chase. Fields 0–31 only, like the bitmasks below —
+     * `encodeChangeCb` reads `tags` past that.
      */
     filterBitmask: number;
     /**
      * Class-level "any field has the flag" booleans + per-field bitmasks.
-     * Hot path: per-mutation `_routeAndRecord` calls `isFieldStatic` and
+     * Hot path: per-mutation `_routeAndRecord` calls `isFieldFullStateOnly` and
      * `isFieldUnreliable`. The common case is "no static/unreliable fields
      * anywhere on this class" (booleans short-circuit before the symbol-keyed
      * metadata lookup); the secondary common case is "this class has some
      * such fields and we need to know if THIS field is one" — the bitmask
      * answers in one bitwise op instead of an `Array.includes` linear scan.
      *
-     * Bitmasks cover fields 0–31 only (matches the `filterBitmask` limitation).
-     * Fields ≥32 fall back to `Metadata.hasXAtIndex` — same handling as the
-     * filter-bitmask path.
+     * Bitmasks cover fields 0–31 only — shift counts wrap at 32. Fields ≥32
+     * fall back to `Metadata.hasXAtIndex`.
      */
-    hasAnyStatic: boolean;
+    hasAnyFullStateOnly: boolean;
     hasAnyUnreliable: boolean;
     hasAnyStream: boolean;
     /**
-     * Class-level "any field carries a `@view` tag" — covers fields both
-     * within and beyond index 31 (unlike `filterBitmask`, which only
-     * captures the low 32). Read by `ChangeTree.hasFilteredFields` to
-     * decide whether a parent tree must be included in a view's bootstrap.
+     * Class-level "any field carries a `@view` tag". Read by
+     * `ChangeTree.hasFilteredFields` to decide whether a parent tree must
+     * be included in a view's bootstrap.
      */
     hasAnyView: boolean;
-    staticBitmask: number;
+    fullStateOnlyBitmask: number;
     unreliableBitmask: number;
     /**
      * Bit i set iff field i holds a `t.stream(...)` collection. Hot encode

package/build/encoder/StateView.d.ts

@@ -1,5 +1,9 @@
 import { ChangeTree, Ref } from "./ChangeTree.js";
 import { OPERATION } from "../encoding/spec.js";
+import type { StreamSchema } from "../types/custom/StreamSchema.js";
+import type { MapSchema } from "../types/custom/MapSchema.js";
+import type { SetSchema } from "../types/custom/SetSchema.js";
+import type { CollectionSchema } from "../types/custom/CollectionSchema.js";
 export declare function createView(iterable?: boolean): StateView;
 export declare class StateView {
     iterable: boolean;
@@ -64,12 +68,6 @@ export declare class StateView {
     private _setSubscribed;
     /** Clear the subscription bit on `tree`. */
     private _clearSubscribed;
-    /** True iff this view has previously marked `tree` as invisible. */
-    isInvisible(tree: ChangeTree): boolean;
-    /** Mark `tree` as invisible to this view (used by encode loop). */
-    markInvisible(tree: ChangeTree): void;
-    /** Clear invisible bit. */
-    unmarkInvisible(tree: ChangeTree): void;
     /**
      * True iff this view shares at least one tag bit with `tree`.
      *
@@ -151,9 +149,29 @@ export declare class StateView {
      *   enqueued into `_pendingByView` so the priority pass drains them
      *   respecting `maxPerTick`.
      *
-     * Idempotent on re-subscribe. Subscribing to an already-subscribed
-     * collection is a no-op.
+     * On a streaming collection, pass a `priority` callback to order THIS
+     * client's backlog. It receives only the element, so whatever the
+     * client sorts by is captured in the closure — nothing is attached to
+     * the view, and both the element and the captured entity stay typed:
+     *
+     * ```ts
+     * onJoin(client) {
+     *     const player = this.state.players.get(client.sessionId);
+     *     client.view.subscribe(this.state.enemies, (enemy) =>
+     *         -((enemy.x - player.x) ** 2 + (enemy.y - player.y) ** 2));
+     * }
+     * ```
+     *
+     * A per-view callback overrides the collection's declaration-scope
+     * `.priority()` for this client only.
+     *
+     * Idempotent on re-subscribe: subscribing to an already-subscribed
+     * collection is a no-op, EXCEPT that a supplied `priority` always
+     * replaces the previous one — re-subscribe to retarget the ordering.
+     * Omitting the argument leaves any existing callback in place; pass
+     * `null` to drop it and fall back to the declaration-scope callback.
      */
+    subscribe<V>(collection: StreamSchema<V> | MapSchema<V, any> | SetSchema<V> | CollectionSchema<V>, priority?: ((element: V) => number) | null): this;
     subscribe(collection: Ref): this;
     /**
      * End a persistent subscription. Queues DELETE for every already-sent

package/build/encoder/changeTree/inheritedFlags.d.ts

@@ -6,7 +6,7 @@ import { type ChangeTree, type Ref } from "../ChangeTree.js";
  */
 export declare function checkIsFiltered(tree: ChangeTree, parent: Ref, parentIndex: number, _isNewChangeTree: boolean): void;
 /**
- * Inherit filter / unreliable / transient / static classification from
+ * Inherit filter / unreliable / patchOnly / static classification from
  * the parent field's annotation. Collections (MapSchema / ArraySchema /
  * etc.) inherit these from the Schema field that holds them.
  *

package/build/encoder/streaming.d.ts

@@ -30,6 +30,13 @@ export interface StreamableState {
      * Instance-level override: assign to `stream.priority`.
      */
     priority?: (view: any, element: any) => number;
+    /**
+     * Per-view priority registered by `StateView.subscribe(collection, fn)`.
+     * Takes precedence over the declaration-scope `priority` for that view.
+     * Receives only the element — the client's own entity is captured in
+     * the closure, so nothing has to be attached to the view.
+     */
+    priorityByView?: Map<number, (element: any) => number>;
 }
 export declare function createStreamableState(): StreamableState;
 /** Allocate `_stream` on first use (idempotent). Returns the state. */