@colyseus/schema 5.0.11 → 5.0.13

package/src/codegen/languages/dart.ts

@@ -0,0 +1,274 @@
+import {
+    Class,
+    Property,
+    File,
+    getCommentHeader,
+    Interface,
+    Enum,
+    Context,
+} from "../types.js";
+import { GenerateOptions } from "../api.js";
+
+export const name = "Dart/Flutter";
+
+/**
+ * Dart types for interface (plain message) properties. Schema scalar getters
+ * don't use this table: the `colyseus` package reads every numeric field as
+ * `double` through `SchemaView`, so all numeric schema types collapse there.
+ */
+const typeMaps: { [key: string]: string } = {
+    "string": "String",
+    "number": "double",
+    "boolean": "bool",
+    "int8": "double",
+    "uint8": "double",
+    "int16": "double",
+    "uint16": "double",
+    "int32": "double",
+    "uint32": "double",
+    "int64": "double",
+    "uint64": "double",
+    "float32": "double",
+    "float64": "double",
+}
+
+const enumNames = new Set<string>();
+
+const COMMON_IMPORTS = `import 'package:colyseus/colyseus.dart';`;
+
+// Field names come from the server schema and may not be lowerCamelCase.
+const LINT_HEADER = `// ignore_for_file: non_constant_identifier_names, constant_identifier_names`;
+
+const distinct = (value: string, index: number, self: string[]) =>
+    self.indexOf(value) === index;
+
+const isSchemaType = (childType: string) =>
+    childType !== undefined && /^[A-Z]/.test(childType) && !enumNames.has(childType);
+
+/**
+ * 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 function generate(context: Context, options: GenerateOptions): File[] {
+    context.enums.forEach((structure) => enumNames.add(structure.name));
+
+    return [
+        ...context.classes.map(klass => ({
+            name: `${klass.name}.dart`,
+            content: generateClass(klass, context.classes)
+        })),
+        ...context.interfaces.map(structure => ({
+            name: `${structure.name}.dart`,
+            content: generateInterface(structure),
+        })),
+        ...context.enums.filter(structure => structure.name !== 'OPERATION').map((structure) => ({
+            name: `${structure.name}.dart`,
+            content: generateEnum(structure),
+        })),
+    ];
+}
+
+/**
+ * Generate a single bundled file containing all classes, interfaces, and enums
+ */
+export function renderBundle(context: Context, options: GenerateOptions): File {
+    const fileName = options.namespace ? `${options.namespace}.dart` : "schema.dart";
+
+    context.enums.forEach((structure) => enumNames.add(structure.name));
+
+    const bodies = [
+        ...context.classes.map(klass => generateClassBody(klass, context.classes)),
+        ...context.interfaces.map(iface => generateInterfaceBody(iface)),
+        ...context.enums
+            .filter(structure => structure.name !== 'OPERATION')
+            .map(e => generateEnumBody(e)),
+    ].join("\n\n");
+
+    const content = `${getCommentHeader()}
+${LINT_HEADER}
+
+${COMMON_IMPORTS}
+
+${bodies}
+`;
+
+    return { name: fileName, content };
+}
+
+/**
+ * Generate just the class body (without imports) for bundling
+ */
+function generateClassBody(klass: Class, allClasses: Class[]): string {
+    // `SchemaRef` is a `base` class, so subclasses carry a modifier: `base`
+    // when the class is itself extended (extendable from any file), `final`
+    // otherwise.
+    const isExtended = allClasses.some(other => other.extends === klass.name);
+    const modifier = isExtended ? "base" : "final";
+    const parent = (klass.extends === "Schema") ? "SchemaRef" : klass.extends;
+
+    const getters = klass.properties
+        .map(prop => generateGetter(prop))
+        .filter(Boolean)
+        .join("\n");
+
+    return `${modifier} class ${klass.name} extends ${parent} {
+  ${klass.name}(super.handle);
+
+${getters}
+}`;
+}
+
+/**
+ * Generate a complete class file with imports (for individual file mode)
+ */
+function generateClass(klass: Class, allClasses: Class[]) {
+    const localRefs = klass.properties
+        .filter(prop => isSchemaType(prop.childType))
+        .map(prop => prop.childType)
+        .concat(klass.extends !== "Schema" ? [klass.extends] : [])
+        .filter(distinct)
+        .filter(ref => ref !== klass.name)
+        .map(ref => `import '${ref}.dart';`)
+        .join("\n");
+
+    return `${getCommentHeader()}
+${LINT_HEADER}
+
+${COMMON_IMPORTS}
+${localRefs ? localRefs + "\n" : ""}
+${generateClassBody(klass, allClasses)}
+`;
+}
+
+/**
+ * The Dart type a scalar schema field reads as, or undefined when the field
+ * can only be read dynamically (enum-typed and unknown types).
+ */
+function scalarDartType(type: string): string | undefined {
+    if (type === "string") { return "String"; }
+    if (type === "boolean") { return "bool"; }
+    if (typeMaps[type] === "double" || type === "quantized" || type === "number") { return "double"; }
+    return undefined;
+}
+
+function generateGetter(prop: Property): string {
+    const deprecation = (prop.deprecated)
+        ? `  @Deprecated("field '${prop.name}' is deprecated.")\n`
+        : '';
+
+    let body: string;
+
+    if (prop.childType && isSchemaType(prop.childType)) {
+        if (prop.type === "ref") {
+            body = `  ${prop.childType}? get ${prop.name} => refOf('${prop.name}', ${prop.childType}.new);`;
+        } else if (prop.type === "map") {
+            body = `  MapSchema<${prop.childType}> get ${prop.name} => mapOf('${prop.name}', ${prop.childType}.new);`;
+        } else {
+            body = `  ArraySchema<${prop.childType}> get ${prop.name} => arrayOf('${prop.name}', ${prop.childType}.new);`;
+        }
+    } else if (prop.childType) {
+        const child = typeMaps[prop.childType] ?? "dynamic";
+        if (prop.type === "map") {
+            body = `  MapSchema<${child}> get ${prop.name} => primitiveMapOf('${prop.name}');`;
+        } else if (prop.type === "array") {
+            body = `  ArraySchema<${child}> get ${prop.name} => primitiveArrayOf('${prop.name}');`;
+        } else {
+            // A "ref" with a primitive child has no typed shape to offer.
+            body = `  dynamic get ${prop.name} => this['${prop.name}'];`;
+        }
+    } else {
+        const dartType = scalarDartType(prop.type);
+        if (dartType === "String") {
+            body = `  String get ${prop.name} => view.getString('${prop.name}') ?? '';`;
+        } else if (dartType === "bool") {
+            body = `  bool get ${prop.name} => view.getBool('${prop.name}');`;
+        } else if (dartType === "double") {
+            body = `  double get ${prop.name} => view['${prop.name}'];`;
+        } else {
+            // Enum-typed or unknown: read through the untyped accessor.
+            body = `  dynamic get ${prop.name} => this['${prop.name}'];`;
+        }
+    }
+
+    return deprecation + body;
+}
+
+/**
+ * Generate just the interface body for bundling
+ */
+function generateInterfaceBody(struct: Interface): string {
+    const fields = struct.properties
+        .map(prop => `  ${getInterfaceType(prop)}? ${prop.name};`)
+        .join("\n");
+
+    return `class ${struct.name} {
+${fields}
+}`;
+}
+
+/**
+ * Generate a complete interface file (for individual file mode)
+ */
+function generateInterface(struct: Interface) {
+    const localRefs = struct.properties
+        .filter(prop => isSchemaType(prop.childType ?? (typeMaps[prop.type] ? undefined : prop.type)))
+        .map(prop => prop.childType ?? prop.type)
+        .filter(distinct)
+        .map(ref => `import '${ref}.dart';`)
+        .join("\n");
+
+    return `${getCommentHeader()}
+${LINT_HEADER}
+${localRefs ? "\n" + localRefs + "\n" : ""}
+${generateInterfaceBody(struct)}
+`;
+}
+
+function getInterfaceType(prop: Property): string {
+    if (prop.type === "array") {
+        return `List<${typeMaps[prop.childType] ?? prop.childType ?? "dynamic"}>`;
+    }
+    return typeMaps[prop.type] ?? prop.type ?? "dynamic";
+}
+
+/**
+ * Generate just the enum body for bundling: a namespace of consts, since
+ * Colyseus enums may carry string or float values Dart enums can't.
+ */
+function generateEnumBody(_enum: Enum): string {
+    const members = _enum.properties
+        .map((prop, i) => {
+            let value: string;
+            if (prop.type) {
+                value = isNaN(Number(prop.type)) ? `"${prop.type}"` : `${Number(prop.type)}`;
+            } else {
+                value = `${i}`;
+            }
+            return `  static const ${prop.name} = ${value};`;
+        })
+        .join("\n");
+
+    return `abstract final class ${_enum.name} {
+${members}
+}`;
+}
+
+/**
+ * Generate a complete enum file (for individual file mode)
+ */
+function generateEnum(_enum: Enum) {
+    return `${getCommentHeader()}
+${LINT_HEADER}
+
+${generateEnumBody(_enum)}
+`;
+}

package/src/codegen/languages/haxe.ts

@@ -94,7 +94,13 @@ function generateProperty(prop: Property) {
     let initializer = "";
     let typeArgs = `"${prop.type}"`;
 
-    if (prop.childType) {
+    if (prop.quantized) {
+        const q = prop.quantized;
+        typeArgs += `, {min: ${q.min}, max: ${q.max}, bits: ${q.bits}, mode: ${q.wrap ? 1 : 0}}`;
+        langType = "Float";
+        initializer = "0";
+
+    } else if (prop.childType) {
         const isUpcaseFirst = prop.childType.match(/^[A-Z]/);
 
         if (isUpcaseFirst) {

package/src/codegen/languages/lua.ts

@@ -26,10 +26,14 @@ const typeMaps: { [key: string]: string } = {
 }
 
 const COMMON_IMPORTS = `local schema = require 'colyseus.serializer.schema.schema'`;
+const QUANTIZE_IMPORT = `local quantize = require 'colyseus.serializer.schema.quantize'`;
 
 const distinct = (value: string, index: number, self: string[]) =>
     self.indexOf(value) === index;
 
+const hasQuantized = (classes: Class[]) =>
+    classes.some(klass => klass.properties.some(prop => prop.quantized));
+
 /**
  * Generate individual files for each class
  */
@@ -51,7 +55,7 @@ export function renderBundle(context: Context, options: GenerateOptions): File {
 
     const content = `${getCommentHeader().replace(/\/\//mg, "--")}
 
-${COMMON_IMPORTS}
+${COMMON_IMPORTS}${hasQuantized(context.classes) ? `\n${QUANTIZE_IMPORT}` : ""}
 
 ${classBodies.join("\n\n")}
 
@@ -104,7 +108,7 @@ function generateClass(klass: Class, namespace: string, allClasses: Class[]) {
 
     return `${getCommentHeader().replace(/\/\//mg, "--")}
 
-${COMMON_IMPORTS}
+${COMMON_IMPORTS}${hasQuantized([klass]) ? `\n${QUANTIZE_IMPORT}` : ""}
 ${localRequires}
 
 ${generateClassBody(klass)}
@@ -116,7 +120,12 @@ return ${klass.name}
 function generatePropertyDeclaration(prop: Property) {
     let typeArgs: string;
 
-    if (prop.childType) {
+    if (prop.quantized) {
+        // resolve at class-definition time — the decoder expects `.wire`/`.span`
+        const q = prop.quantized;
+        typeArgs = `{ quantized = quantize.resolve({ min = ${q.min}, max = ${q.max}, bits = ${q.bits}, mode = ${q.wrap ? 1 : 0} }) }`;
+
+    } else if (prop.childType) {
         const isUpcaseFirst = prop.childType.match(/^[A-Z]/);
 
         if (isUpcaseFirst) {
@@ -145,7 +154,10 @@ function generatePropertyDeclaration(prop: Property) {
 }
 
 function getLUATypeAnnotation(prop: Property) {
-    if (prop.type === "ref") {
+    if (prop.type === "quantized") {
+        return "number";
+
+    } else if (prop.type === "ref") {
         return prop.childType;
 
     } else if (prop.type === "array") {

package/src/codegen/languages/ts.ts

@@ -158,6 +158,11 @@ function generateProperty(prop: Property) {
                 : `{ set: "${prop.childType}" }`;
         }
 
+    } else if (prop.quantized) {
+        const q = prop.quantized;
+        langType = "number";
+        typeArgs = `{ quantized: { min: ${q.min}, max: ${q.max}, bits: ${q.bits}${q.wrap ? `, mode: "wrap"` : ""} } }`;
+
     } else {
         langType = typeMaps[prop.type];
         typeArgs = `"${prop.type}"`;

package/src/codegen/parser.ts

@@ -1,7 +1,7 @@
 import * as ts from "typescript";
 import * as path from "path";
 import { readFileSync } from "fs";
-import { IStructure, Class, Interface, Property, Context, Enum } from "./types.js";
+import { IStructure, Class, Interface, Property, Context, Enum, QuantizedProperty } from "./types.js";
 
 let currentStructure: IStructure;
 let currentProperty: Property;
@@ -36,6 +36,91 @@ function extractBuilderBase(node: ts.CallExpression): { methodName: string, firs
     }
 }
 
+/**
+ * Statically evaluate a numeric option expression. Codegen has no runtime, so
+ * only constant arithmetic is supported: literals, unary +/-, `Math.PI`-style
+ * constants and add/sub/mul/div combinations of those (e.g. `Math.PI * 2`).
+ * Returns
+ * undefined for anything it cannot resolve (a `const` reference, a call).
+ */
+function evalNumericExpression(node: ts.Expression): number | undefined {
+    if (ts.isNumericLiteral(node)) {
+        return Number(node.text);
+    }
+    if (ts.isParenthesizedExpression(node)) {
+        return evalNumericExpression(node.expression);
+    }
+    if (ts.isPrefixUnaryExpression(node)) {
+        const operand = evalNumericExpression(node.operand as ts.Expression);
+        if (operand === undefined) { return undefined; }
+        if (node.operator === ts.SyntaxKind.MinusToken) { return -operand; }
+        if (node.operator === ts.SyntaxKind.PlusToken) { return operand; }
+        return undefined;
+    }
+    if (ts.isPropertyAccessExpression(node) && node.expression.getText() === "Math") {
+        const constant = (Math as any)[node.name.text];
+        return (typeof constant === "number") ? constant : undefined;
+    }
+    if (ts.isBinaryExpression(node)) {
+        const left = evalNumericExpression(node.left);
+        const right = evalNumericExpression(node.right);
+        if (left === undefined || right === undefined) { return undefined; }
+        switch (node.operatorToken.kind) {
+            case ts.SyntaxKind.PlusToken: return left + right;
+            case ts.SyntaxKind.MinusToken: return left - right;
+            case ts.SyntaxKind.AsteriskToken: return left * right;
+            case ts.SyntaxKind.SlashToken: return left / right;
+            default: return undefined;
+        }
+    }
+    return undefined;
+}
+
+/**
+ * Extract `{ min, max, bits?, mode? }` from a `t.quantized({...})` /
+ * `@type({ quantized: {...} })` object literal. Throws on anything codegen
+ * cannot statically resolve — silently dropping an option would generate a
+ * client that decodes every value of that field wrong.
+ */
+function parseQuantizedOptions(node: ts.Expression | undefined, propertyName: string): QuantizedProperty {
+    const fail = (reason: string): never => {
+        throw new Error(
+            `schema-codegen: cannot statically resolve t.quantized() options of field '${propertyName}' — ${reason}. ` +
+            `Use literal numbers or constant Math expressions (e.g. \`Math.PI * 2\`).`
+        );
+    };
+
+    if (!node || !ts.isObjectLiteralExpression(node)) {
+        return fail("expected an inline `{ min, max, ... }` object literal");
+    }
+
+    const result: Partial<QuantizedProperty> & { mode?: string } = {};
+    for (const prop of node.properties) {
+        if (!ts.isPropertyAssignment(prop) || !prop.name) { continue; }
+        const key = (prop.name as ts.Identifier).text;
+
+        if (key === "mode") {
+            if (!ts.isStringLiteral(prop.initializer)) { return fail("`mode` must be a string literal"); }
+            result.mode = prop.initializer.text;
+        } else if (key === "min" || key === "max" || key === "bits") {
+            const value = evalNumericExpression(prop.initializer);
+            if (value === undefined) { return fail(`\`${key}\` is not a constant expression`); }
+            result[key] = value as any;
+        }
+    }
+
+    if (typeof result.min !== "number" || typeof result.max !== "number") {
+        return fail("`min` and `max` are required");
+    }
+
+    const bits = result.bits ?? 16;
+    if (bits !== 8 && bits !== 16 && bits !== 32) {
+        return fail("`bits` must be 8, 16 or 32");
+    }
+
+    return { min: result.min, max: result.max, bits, wrap: result.mode === "wrap" };
+}
+
 function defineProperty(property: Property, initializer: any) {
     // Builder-style: t.number(), t.array(Item), t.map(Item).view(), etc.
     if (ts.isCallExpression(initializer)) {
@@ -51,6 +136,9 @@ function defineProperty(property: Property, initializer: any) {
                 if (base.firstArg) {
                     property.childType = (base.firstArg as any).text ?? base.firstArg.getText();
                 }
+            } else if (base.methodName === "quantized") {
+                property.type = "quantized";
+                property.quantized = parseQuantizedOptions(base.firstArg, property.name);
             } else {
                 property.type = base.methodName;
             }
@@ -63,8 +151,14 @@ function defineProperty(property: Property, initializer: any) {
         property.childType = initializer.text;
 
     } else if (initializer.kind == ts.SyntaxKind.ObjectLiteralExpression) {
-        property.type = initializer.properties[0].name.text;
-        property.childType = initializer.properties[0].initializer.text;
+        if (initializer.properties[0].name.text === "quantized") {
+            // decorator-style: @type({ quantized: { min, max, ... } })
+            property.type = "quantized";
+            property.quantized = parseQuantizedOptions(initializer.properties[0].initializer, property.name);
+        } else {
+            property.type = initializer.properties[0].name.text;
+            property.childType = initializer.properties[0].initializer.text;
+        }
 
     } else if (initializer.kind == ts.SyntaxKind.ArrayLiteralExpression) {
         property.type = "array";

package/src/codegen/types.ts

@@ -125,11 +125,35 @@ export class Enum implements IStructure {
     }
 }
 
+/**
+ * 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 function resolveQuantized(q: QuantizedProperty) {
+    return {
+        range: q.max - q.min,
+        span: q.wrap ? 2 ** q.bits : 2 ** q.bits - 1,
+    };
+}
+
 export class Property {
     index: number;
     name: string;
     type: string;
     childType: string;
+    quantized?: QuantizedProperty;
     deprecated?: boolean;
 }
 

package/src/decoder/Resync.ts

@@ -1,6 +1,6 @@
 import { OPERATION } from "../encoding/spec.js";
 import { Schema } from "../Schema.js";
-import { $proxyTarget, $refId, $refTypeFieldIndexes, $resyncPrune, $transientFieldIndexes } from "../types/symbols.js";
+import { $proxyTarget, $refId, $refTypeFieldIndexes, $resyncPrune, $patchOnlyFieldIndexes } from "../types/symbols.js";
 import type { Metadata } from "../Metadata.js";
 import type { Decoder } from "./Decoder.js";
 import type { DataChange } from "./DecodeOperation.js";
@@ -76,8 +76,8 @@ export function resyncTouchEntry(
 /**
  * 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 function resyncMarkPresent(decoder: Decoder, refId: number) {
@@ -90,7 +90,7 @@ export function resyncMarkPresent(decoder: Decoder, refId: number) {
  * 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
@@ -115,12 +115,12 @@ function sweepSchema(decoder: Decoder, ref: Schema, seen: Set<number>, allChange
     const metadata: Metadata = (ref.constructor as typeof Schema)[Symbol.metadata];
     const refIndexes = metadata?.[$refTypeFieldIndexes] as number[] | undefined;
     if (refIndexes === undefined) { return; }
-    const transient = metadata[$transientFieldIndexes] as number[] | undefined;
+    const patchOnly = metadata[$patchOnlyFieldIndexes] as number[] | undefined;
 
     for (let i = 0; i < refIndexes.length; i++) {
         const fieldIndex = refIndexes[i];
-        // @transient fields are never in a snapshot — leave them alone.
-        if (transient !== undefined && transient.includes(fieldIndex)) { continue; }
+        // @patchOnly fields are never in a snapshot — leave them alone.
+        if (patchOnly !== undefined && patchOnly.includes(fieldIndex)) { continue; }
 
         const field = metadata[fieldIndex];
         const value = (ref as any)[field.name];
@@ -142,7 +142,7 @@ function sweepCollection(decoder: Decoder, coll: any, seen: Set<number>, allChan
 
     // `undefined` = the collection never appeared in the payload at all
     // (not even as its parent's field op) — it is not part of full-sync
-    // (@transient, view-invisible) and must be left alone. An empty Set
+    // (@patchOnly, view-invisible) and must be left alone. An empty Set
     // means "present with zero entries" → prune everything.
     const visited = decoder.resyncVisited!.get(refId);
     if (visited === undefined) { return; }

package/src/encoder/ChangeRecorder.ts

@@ -76,7 +76,7 @@ const _invokeNoCtx = (
 ) => cb(index, op);
 
 // ──────────────────────────────────────────────────────────────────────────
-// SchemaChangeRecorder — bitmask + Uint8Array, for Schema types (≤64 fields)
+// SchemaChangeRecorder — bitmask + Uint8Array, for Schema types (≤63 fields)
 // ──────────────────────────────────────────────────────────────────────────
 
 /**