@colyseus/schema 4.0.19 → 5.0.0

package/src/bench_bloat.ts

@@ -0,0 +1,173 @@
+import { Encoder, Schema, type, MapSchema, ArraySchema } from "./index";
+
+// Must be set before constructing any Encoder — static BUFFER_SIZE is
+// read at Encoder construction time. Default 8KB overflows on the first
+// full-state encode (1000 entities), which used to skew measurements 2/3/6
+// by leaving the initial ADD wave half-encoded.
+Encoder.BUFFER_SIZE = 4 * 1024 * 1024;
+
+class Position extends Schema {
+    @type("number") x: number;
+    @type("number") y: number;
+}
+
+class Player extends Schema {
+    @type("string") name: string;
+    @type(Position) position = new Position();
+    @type(["number"]) scores = new ArraySchema<number>();
+}
+
+class State extends Schema {
+    @type({ map: Player }) players = new MapSchema<Player>();
+}
+
+// --- Measure 1: Memory ---
+globalThis.gc?.();
+const heapBefore = process.memoryUsage().heapUsed;
+
+const state = new State();
+const encoder = new Encoder(state);
+
+for (let i = 0; i < 1000; i++) {
+    const p = new Player();
+    p.name = `Player ${i}`;
+    p.position.x = i;
+    p.position.y = i;
+    for (let j = 0; j < 5; j++) p.scores.push(j);
+    state.players.set(`p${i}`, p);
+}
+
+globalThis.gc?.();
+const heapAfter = process.memoryUsage().heapUsed;
+console.log(`Heap delta (1000 entities): ${((heapAfter - heapBefore) / 1024 / 1024).toFixed(2)} MB`);
+
+// Initial encode
+encoder.encode();
+encoder.discardChanges();
+
+// --- Measure 2: Encode tick speed (small mutations) ---
+const iterations = 5000;
+const start = performance.now();
+for (let i = 0; i < iterations; i++) {
+    // Mutate 10 players (small tick)
+    for (let j = 0; j < 10; j++) {
+        const p = state.players.get(`p${j}`);
+        p.position.x++;
+        p.position.y++;
+    }
+    encoder.encode();
+    encoder.discardChanges();
+}
+const elapsed = performance.now() - start;
+console.log(`${iterations} encode ticks (10 mutations each): ${elapsed.toFixed(1)}ms (${(elapsed/iterations).toFixed(4)}ms/tick)`);
+
+// --- Measure 3: Encode tick speed (large mutations) ---
+const iterations2 = 1000;
+const start2 = performance.now();
+for (let i = 0; i < iterations2; i++) {
+    for (let j = 0; j < 100; j++) {
+        const p = state.players.get(`p${j}`);
+        p.position.x++;
+        p.position.y++;
+    }
+    encoder.encode();
+    encoder.discardChanges();
+}
+const elapsed2 = performance.now() - start2;
+console.log(`${iterations2} encode ticks (100 mutations each): ${elapsed2.toFixed(1)}ms (${(elapsed2/iterations2).toFixed(3)}ms/tick)`);
+
+// --- Measure 4: Entity creation speed ---
+const state2 = new State();
+const encoder2 = new Encoder(state2);
+const createStart = performance.now();
+for (let i = 0; i < 5000; i++) {
+    const p = new Player();
+    p.name = `P${i}`;
+    p.position.x = i;
+    p.position.y = i;
+    state2.players.set(`p${i}`, p);
+}
+const createElapsed = performance.now() - createStart;
+console.log(`Create 5000 entities: ${createElapsed.toFixed(1)}ms`);
+
+// --- Measure 5: encodeAll speed ---
+const encoder3 = new Encoder(state2);
+const encodeAllStart = performance.now();
+for (let i = 0; i < 100; i++) {
+    encoder3.encodeAll();
+}
+const encodeAllElapsed = performance.now() - encodeAllStart;
+console.log(`100x encodeAll (5000 entities): ${encodeAllElapsed.toFixed(1)}ms`);
+
+// --- Measure 6: GC pressure (heap growth over many ticks) ---
+globalThis.gc?.();
+const gcBefore = process.memoryUsage().heapUsed;
+for (let i = 0; i < 10000; i++) {
+    const p = state.players.get(`p${i % 100}`);
+    p.position.x++;
+    p.position.y++;
+    if (i % 10 === 0) {
+        encoder.encode();
+        encoder.discardChanges();
+    }
+}
+globalThis.gc?.();
+const gcAfter = process.memoryUsage().heapUsed;
+console.log(`GC pressure (10k mutations, 1k encode ticks): heap delta ${((gcAfter - gcBefore) / 1024).toFixed(1)} KB`);
+
+// --- Measure 7: Entity add/remove churn (exercises Root linked list) ---
+const churnState = new State();
+const churnEncoder = new Encoder(churnState);
+// Pre-populate
+for (let i = 0; i < 100; i++) {
+    const p = new Player();
+    p.name = `P${i}`;
+    p.position.x = i;
+    p.position.y = i;
+    churnState.players.set(`p${i}`, p);
+}
+churnEncoder.encode();
+churnEncoder.discardChanges();
+
+const churnStart = performance.now();
+for (let i = 0; i < 1000; i++) {
+    // Remove and re-add 10 entities
+    for (let j = 0; j < 10; j++) {
+        const key = `p${(i * 10 + j) % 100}`;
+        churnState.players.delete(key);
+    }
+    churnEncoder.encode();
+    churnEncoder.discardChanges();
+    for (let j = 0; j < 10; j++) {
+        const key = `p${(i * 10 + j) % 100}`;
+        const p = new Player();
+        p.name = key;
+        p.position.x = i;
+        p.position.y = j;
+        churnState.players.set(key, p);
+    }
+    churnEncoder.encode();
+    churnEncoder.discardChanges();
+}
+const churnElapsed = performance.now() - churnStart;
+console.log(`1000 entity churn cycles (10 remove+add each): ${churnElapsed.toFixed(1)}ms (${(churnElapsed/1000).toFixed(3)}ms/cycle)`);
+
+// --- Measure 9: Array push/pop churn ---
+class ArrayState extends Schema {
+    @type(["number"]) items = new ArraySchema<number>();
+}
+const arrayState = new ArrayState();
+const arrayEncoder = new Encoder(arrayState);
+for (let i = 0; i < 100; i++) arrayState.items.push(i);
+arrayEncoder.encode();
+arrayEncoder.discardChanges();
+
+const arrayStart = performance.now();
+for (let i = 0; i < 5000; i++) {
+    arrayState.items.push(100 + i);
+    arrayState.items.pop();
+    arrayEncoder.encode();
+    arrayEncoder.discardChanges();
+}
+const arrayElapsed = performance.now() - arrayStart;
+console.log(`5000 array push/pop ticks: ${arrayElapsed.toFixed(1)}ms (${(arrayElapsed/5000).toFixed(4)}ms/tick)`);

package/src/bench_decode.ts

@@ -0,0 +1,221 @@
+import { Encoder, Decoder, Schema, type, MapSchema, ArraySchema } from "./index";
+
+class Position extends Schema {
+    @type("number") x: number;
+    @type("number") y: number;
+}
+
+class Player extends Schema {
+    @type("string") name: string;
+    @type(Position) position = new Position();
+    @type(["number"]) scores = new ArraySchema<number>();
+}
+
+class State extends Schema {
+    @type({ map: Player }) players = new MapSchema<Player>();
+}
+
+function freshDecoder() {
+    return new Decoder(new State());
+}
+
+function clone(bytes: Uint8Array) {
+    return bytes.slice();
+}
+
+Encoder.BUFFER_SIZE = 4096 * 4096;
+
+// --- Build a server state with N entities ---
+const state = new State();
+const encoder = new Encoder(state);
+
+const N = 1000;
+for (let i = 0; i < N; i++) {
+    const p = new Player();
+    p.name = `Player ${i}`;
+    p.position.x = i;
+    p.position.y = i;
+    for (let j = 0; j < 5; j++) p.scores.push(j);
+    state.players.set(`p${i}`, p);
+}
+
+// --- Measure 1: Initial bootstrap decode (encodeAll on a fresh client) ---
+{
+    const bootstrapBytes = clone(encoder.encodeAll());
+    encoder.discardChanges();
+
+    const iterations = 200;
+    const start = performance.now();
+    for (let i = 0; i < iterations; i++) {
+        const decoder = freshDecoder();
+        decoder.decode(bootstrapBytes);
+    }
+    const elapsed = performance.now() - start;
+    console.log(
+        `Bootstrap decode (${N} entities) x${iterations}: ${elapsed.toFixed(1)}ms ` +
+        `(${(elapsed / iterations).toFixed(3)}ms/run, ${bootstrapBytes.length} bytes)`
+    );
+}
+
+// --- Measure 2: Steady-state small-tick decode (10 players per tick) ---
+{
+    const decoder = freshDecoder();
+    decoder.decode(clone(encoder.encodeAll()));
+    encoder.discardChanges();
+
+    const ticks = 5000;
+    // Pre-produce the byte frames so we measure decode only.
+    const frames: Uint8Array[] = new Array(ticks);
+    for (let i = 0; i < ticks; i++) {
+        for (let j = 0; j < 10; j++) {
+            const p = state.players.get(`p${j}`)!;
+            p.position.x++;
+            p.position.y++;
+        }
+        frames[i] = clone(encoder.encode());
+        encoder.discardChanges();
+    }
+
+    const start = performance.now();
+    for (let i = 0; i < ticks; i++) decoder.decode(frames[i]);
+    const elapsed = performance.now() - start;
+    const totalBytes = frames.reduce((s, f) => s + f.length, 0);
+    console.log(
+        `Small-tick decode (10 mutations/tick) x${ticks}: ${elapsed.toFixed(1)}ms ` +
+        `(${(elapsed / ticks).toFixed(4)}ms/tick, avg ${(totalBytes / ticks).toFixed(1)} bytes/tick)`
+    );
+}
+
+// --- Measure 3: Steady-state large-tick decode (100 players per tick) ---
+{
+    const decoder = freshDecoder();
+    decoder.decode(clone(encoder.encodeAll()));
+    encoder.discardChanges();
+
+    const ticks = 1000;
+    const frames: Uint8Array[] = new Array(ticks);
+    for (let i = 0; i < ticks; i++) {
+        for (let j = 0; j < 100; j++) {
+            const p = state.players.get(`p${j}`)!;
+            p.position.x++;
+            p.position.y++;
+        }
+        frames[i] = clone(encoder.encode());
+        encoder.discardChanges();
+    }
+
+    const start = performance.now();
+    for (let i = 0; i < ticks; i++) decoder.decode(frames[i]);
+    const elapsed = performance.now() - start;
+    const totalBytes = frames.reduce((s, f) => s + f.length, 0);
+    console.log(
+        `Large-tick decode (100 mutations/tick) x${ticks}: ${elapsed.toFixed(1)}ms ` +
+        `(${(elapsed / ticks).toFixed(3)}ms/tick, avg ${(totalBytes / ticks).toFixed(1)} bytes/tick)`
+    );
+}
+
+// --- Measure 4: Add/remove churn decode ---
+{
+    const churnState = new State();
+    const churnEncoder = new Encoder(churnState);
+    for (let i = 0; i < 100; i++) {
+        const p = new Player();
+        p.name = `P${i}`;
+        p.position.x = i;
+        p.position.y = i;
+        churnState.players.set(`p${i}`, p);
+    }
+
+    const decoder = new Decoder(new State());
+    decoder.decode(clone(churnEncoder.encodeAll()));
+    churnEncoder.discardChanges();
+
+    const cycles = 1000;
+    const frames: Uint8Array[] = [];
+    for (let i = 0; i < cycles; i++) {
+        for (let j = 0; j < 10; j++) {
+            const key = `p${(i * 10 + j) % 100}`;
+            churnState.players.delete(key);
+        }
+        frames.push(clone(churnEncoder.encode()));
+        churnEncoder.discardChanges();
+        for (let j = 0; j < 10; j++) {
+            const key = `p${(i * 10 + j) % 100}`;
+            const p = new Player();
+            p.name = key;
+            p.position.x = i;
+            p.position.y = j;
+            churnState.players.set(key, p);
+        }
+        frames.push(clone(churnEncoder.encode()));
+        churnEncoder.discardChanges();
+    }
+
+    const start = performance.now();
+    for (let i = 0; i < frames.length; i++) decoder.decode(frames[i]);
+    const elapsed = performance.now() - start;
+    console.log(
+        `Churn decode (${cycles} cycles, 10 remove+add each, ${frames.length} frames): ` +
+        `${elapsed.toFixed(1)}ms (${(elapsed / cycles).toFixed(3)}ms/cycle)`
+    );
+}
+
+// --- Measure 5: Array push/pop churn decode ---
+{
+    class ArrayState extends Schema {
+        @type(["number"]) items = new ArraySchema<number>();
+    }
+    const arrayState = new ArrayState();
+    const arrayEncoder = new Encoder(arrayState);
+    for (let i = 0; i < 100; i++) arrayState.items.push(i);
+
+    const decoder = new Decoder(new ArrayState());
+    decoder.decode(clone(arrayEncoder.encodeAll()));
+    arrayEncoder.discardChanges();
+
+    const ticks = 5000;
+    const frames: Uint8Array[] = new Array(ticks);
+    for (let i = 0; i < ticks; i++) {
+        arrayState.items.push(100 + i);
+        arrayState.items.pop();
+        frames[i] = clone(arrayEncoder.encode());
+        arrayEncoder.discardChanges();
+    }
+
+    const start = performance.now();
+    for (let i = 0; i < ticks; i++) decoder.decode(frames[i]);
+    const elapsed = performance.now() - start;
+    console.log(
+        `Array push/pop decode x${ticks}: ${elapsed.toFixed(1)}ms ` +
+        `(${(elapsed / ticks).toFixed(4)}ms/tick)`
+    );
+}
+
+// --- Measure 6: Heavy mutation per tick (every player + array items) ---
+{
+    const decoder = freshDecoder();
+    decoder.decode(clone(encoder.encodeAll()));
+    encoder.discardChanges();
+
+    const ticks = 200;
+    const frames: Uint8Array[] = new Array(ticks);
+    for (let i = 0; i < ticks; i++) {
+        for (let j = 0; j < N; j++) {
+            const p = state.players.get(`p${j}`)!;
+            p.position.x++;
+            p.position.y++;
+            p.scores[0] = i;
+        }
+        frames[i] = clone(encoder.encode());
+        encoder.discardChanges();
+    }
+
+    const start = performance.now();
+    for (let i = 0; i < ticks; i++) decoder.decode(frames[i]);
+    const elapsed = performance.now() - start;
+    const totalBytes = frames.reduce((s, f) => s + f.length, 0);
+    console.log(
+        `Heavy-tick decode (${N} players touched) x${ticks}: ${elapsed.toFixed(1)}ms ` +
+        `(${(elapsed / ticks).toFixed(3)}ms/tick, avg ${(totalBytes / ticks).toFixed(0)} bytes/tick)`
+    );
+}

package/src/bench_decode_mem.ts

@@ -0,0 +1,165 @@
+import { PerformanceObserver, constants } from "node:perf_hooks";
+import { Encoder, Decoder, Schema, type, MapSchema, ArraySchema } from "./index";
+
+class Position extends Schema {
+    @type("number") x: number;
+    @type("number") y: number;
+}
+
+class Player extends Schema {
+    @type("string") name: string;
+    @type(Position) position = new Position();
+    @type(["number"]) scores = new ArraySchema<number>();
+}
+
+class State extends Schema {
+    @type({ map: Player }) players = new MapSchema<Player>();
+}
+
+if (!globalThis.gc) {
+    console.error("Run with --expose-gc: npx tsx --expose-gc ...");
+    process.exit(1);
+}
+
+Encoder.BUFFER_SIZE = 4096 * 4096;
+
+// --- GC observer ---
+const gcStats = { count: 0, totalMs: 0, majorMs: 0, minorMs: 0 };
+const gcObserver = new PerformanceObserver((list) => {
+    for (const e of list.getEntries() as any) {
+        gcStats.count++;
+        gcStats.totalMs += e.duration;
+        if (e.detail?.kind === constants.NODE_PERFORMANCE_GC_MAJOR) gcStats.majorMs += e.duration;
+        else gcStats.minorMs += e.duration;
+    }
+});
+gcObserver.observe({ entryTypes: ["gc"], buffered: false });
+
+function resetGc() { gcStats.count = 0; gcStats.totalMs = 0; gcStats.majorMs = 0; gcStats.minorMs = 0; }
+function snapshotGc() { return { ...gcStats }; }
+function heap() {
+    globalThis.gc!();
+    globalThis.gc!();
+    return process.memoryUsage().heapUsed;
+}
+function mb(n: number) { return (n / 1024 / 1024).toFixed(2); }
+function kb(n: number) { return (n / 1024).toFixed(1); }
+
+// --- Build an encoder-side state once ---
+const state = new State();
+const encoder = new Encoder(state);
+const N = 1000;
+for (let i = 0; i < N; i++) {
+    const p = new Player();
+    p.name = `Player ${i}`;
+    p.position.x = i;
+    p.position.y = i;
+    for (let j = 0; j < 5; j++) p.scores.push(j);
+    state.players.set(`p${i}`, p);
+}
+const bootstrapBytes = encoder.encodeAll().slice();
+encoder.discardChanges();
+
+// Pre-produce steady-state frames (outside the timed region).
+const heavyFrames: Uint8Array[] = [];
+const HEAVY_TICKS = 200;
+for (let i = 0; i < HEAVY_TICKS; i++) {
+    for (let j = 0; j < N; j++) {
+        const p = state.players.get(`p${j}`)!;
+        p.position.x++;
+        p.position.y++;
+        p.scores[0] = i;
+    }
+    heavyFrames.push(encoder.encode().slice());
+    encoder.discardChanges();
+}
+
+type Stats = {
+    decoderHeapKb: number;
+    steadyHeapDeltaKb: number;
+    steadyGcCount: number;
+    steadyGcMs: number;
+    bootstrapMs: number;
+    heavyMs: number;
+};
+
+function run(): Stats {
+    const baseHeap = heap();
+
+    const decoder = new Decoder(new State());
+    const tBoot0 = performance.now();
+    decoder.decode(bootstrapBytes);
+    const bootstrapMs = performance.now() - tBoot0;
+
+    const decoderHeap = heap() - baseHeap;
+
+    resetGc();
+    const beforeSteady = process.memoryUsage().heapUsed;
+    const tHeavy0 = performance.now();
+    for (let i = 0; i < HEAVY_TICKS; i++) decoder.decode(heavyFrames[i]);
+    const heavyMs = performance.now() - tHeavy0;
+    const afterSteady = process.memoryUsage().heapUsed;
+    const gcSnap = snapshotGc();
+
+    return {
+        decoderHeapKb: decoderHeap / 1024,
+        steadyHeapDeltaKb: (afterSteady - beforeSteady) / 1024,
+        steadyGcCount: gcSnap.count,
+        steadyGcMs: gcSnap.totalMs,
+        bootstrapMs,
+        heavyMs,
+    };
+}
+
+// Warm (JIT seeding), discard result
+run();
+
+// Best-of-3 to get stable numbers
+let best: Stats | undefined;
+for (let i = 0; i < 3; i++) {
+    const s = run();
+    if (!best || s.heavyMs < best.heavyMs) best = s;
+}
+
+console.log("\n=== decoder memory + GC (best of 3) ===");
+console.log(
+    `bootstrap ${best!.bootstrapMs.toFixed(1)}ms | ` +
+    `heavy ${HEAVY_TICKS}t ${best!.heavyMs.toFixed(1)}ms (${(best!.heavyMs / HEAVY_TICKS).toFixed(3)}ms/tick) | ` +
+    `heap(decoder state, ${N} entities) ${kb(best!.decoderHeapKb * 1024)} KB | ` +
+    `heap-growth/steady ${kb(best!.steadyHeapDeltaKb * 1024)} KB | ` +
+    `GCs ${best!.steadyGcCount} (${best!.steadyGcMs.toFixed(1)}ms)`
+);
+
+// --- Multi-client scenario: 100 fresh decoders, each bootstrapped on the same bytes.
+// Answers "how much heap does N simultaneous clients cost?".
+function multiClient(numClients: number) {
+    const baseHeap = heap();
+    resetGc();
+    const decoders: Decoder[] = [];
+    const t0 = performance.now();
+    for (let i = 0; i < numClients; i++) {
+        const d = new Decoder(new State());
+        d.decode(bootstrapBytes);
+        decoders.push(d);
+    }
+    const elapsed = performance.now() - t0;
+    const gcSnap = snapshotGc();
+    const heapAfter = heap();
+    return {
+        decoders, // keep alive so GC can't reclaim during measurement
+        totalHeapKb: (heapAfter - baseHeap) / 1024,
+        elapsedMs: elapsed,
+        gcCount: gcSnap.count,
+        gcMs: gcSnap.totalMs,
+    };
+}
+
+console.log(`\n=== multi-client bootstrap (100 decoders, ${N} entities each) ===`);
+const mc = multiClient(100);
+console.log(
+    `${mc.elapsedMs.toFixed(0)}ms | ` +
+    `heap ${mb(mc.totalHeapKb * 1024)} MB | ` +
+    `GCs ${mc.gcCount} (${mc.gcMs.toFixed(1)}ms)`
+);
+
+gcObserver.disconnect();

package/src/bench_encode.ts

@@ -0,0 +1,108 @@
+import { nanoid } from "nanoid";
+import { Schema, type, MapSchema, ArraySchema, Encoder } from "./index";
+
+class Attribute extends Schema {
+    @type("string") name: string;
+    @type("number") value: number;
+}
+
+class Item extends Schema {
+    @type("number") price: number;
+    @type([ Attribute ]) attributes = new ArraySchema<Attribute>();
+}
+
+class Position extends Schema {
+    @type("number") x: number;
+    @type("number") y: number;
+}
+
+class Player extends Schema {
+    @type(Position) position = new Position();
+    @type({ map: Item }) items = new MapSchema<Item>();
+}
+
+class State extends Schema {
+    @type({ map: Player }) players = new MapSchema<Player>();
+    @type("string") currentTurn: string;
+}
+
+const state = new State();
+
+Encoder.BUFFER_SIZE = 4096 * 4096;
+const encoder = new Encoder(state);
+
+
+let now = Date.now();
+
+// for (let i = 0; i < 10000; i++) {
+//     const player = new Player();
+//     state.players.set(`p-${nanoid()}`, player);
+//
+//     player.position.x = (i + 1) * 100;
+//     player.position.y = (i + 1) * 100;
+//     for (let j = 0; j < 10; j++) {
+//         const item = new Item();
+//         player.items.set(`item-${j}`, item);
+//         item.price = (i + 1) * 50;
+//         for (let k = 0; k < 5; k++) {
+//             const attr = new Attribute();
+//             attr.name = `Attribute ${k}`;
+//             attr.value = k;
+//             item.attributes.push(attr);
+//         }
+//     }
+// }
+// console.log("time to make changes:", Date.now() - now);
+
+
+// measure time to .encodeAll()
+
+now = Date.now();
+// for (let i = 0; i < 1000; i++) {
+//     encoder.encodeAll();
+// }
+// console.log(Date.now() - now);
+
+const total = 100;
+const allEncodes = Date.now();
+
+let avgTimeToEncode = 0;
+let avgTimeToMakeChanges = 0;
+
+for (let i = 0; i < total; i++) {
+    now = Date.now();
+    for (let j = 0; j < 50; j++) {
+        const player = new Player();
+        state.players.set(`p-${nanoid()}`, player);
+
+        player.position.x = (j + 1) * 100;
+        player.position.y = (j + 1) * 100;
+        for (let k = 0; k < 10; k++) {
+            const item = new Item();
+            item.price = (j + 1) * 50;
+            for (let l = 0; l < 5; l++) {
+                const attr = new Attribute();
+                attr.name = `Attribute ${l}`;
+                attr.value = l;
+                item.attributes.push(attr);
+            }
+            player.items.set(`item-${k}`, item);
+        }
+    }
+    const timeToMakeChanges = Date.now() - now;
+    console.log("time to make changes:", timeToMakeChanges);
+    avgTimeToMakeChanges += timeToMakeChanges;
+
+    now = Date.now();
+    encoder.encode();
+    encoder.discardChanges();
+
+    const timeToEncode = Date.now() - now;
+    console.log("time to encode:", timeToEncode);
+    avgTimeToEncode += timeToEncode;
+}
+console.log("avg time to encode:", (avgTimeToEncode) / total);
+console.log("avg time to make changes:", (avgTimeToMakeChanges) / total);
+console.log("time for all encodes:", Date.now() - allEncodes);
+
+console.log(Array.from(encoder.encodeAll()).length, "bytes");