archetype-ecs-net 0.1.1

package/dist/NetServer.js

@@ -0,0 +1,166 @@
+import { createSnapshotDiffer } from './DirtyTracker.js';
+import { createClientView } from './InterestManager.js';
+import { ProtocolEncoder } from './Protocol.js';
+const EMPTY_KEY = '||';
+function deltaKey(d) {
+    if (d.enters.length === 0 && d.leaves.length === 0 && d.updates.length === 0)
+        return EMPTY_KEY;
+    // Sort copies — don't mutate the original arrays
+    const e = d.enters.length > 1 ? d.enters.slice().sort((a, b) => a - b) : d.enters;
+    const l = d.leaves.length > 1 ? d.leaves.slice().sort((a, b) => a - b) : d.leaves;
+    const u = d.updates.length > 1 ? d.updates.slice().sort((a, b) => a - b) : d.updates;
+    return `${e.join(',')}|${l.join(',')}|${u.join(',')}`;
+}
+// ── ws transport (default) ──────────────────────────────
+export function createWsTransport() {
+    let wss = null;
+    const clients = new Map();
+    return {
+        async start(port, handlers) {
+            const { WebSocketServer } = await import('ws');
+            let nextId = 1;
+            wss = new WebSocketServer({ port });
+            await new Promise((resolve, reject) => {
+                wss.once('listening', resolve);
+                wss.once('error', reject);
+            });
+            wss.on('connection', (ws) => {
+                const clientId = nextId++;
+                clients.set(clientId, ws);
+                handlers.onOpen(clientId);
+                ws.on('message', (data) => {
+                    const ab = data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+                    handlers.onMessage(clientId, ab);
+                });
+                ws.on('close', () => {
+                    clients.delete(clientId);
+                    handlers.onClose(clientId);
+                });
+            });
+        },
+        async stop() {
+            if (wss) {
+                for (const ws of clients.values())
+                    ws.terminate();
+                clients.clear();
+                await new Promise(r => wss.close(() => r()));
+                wss = null;
+            }
+        },
+        send(clientId, data) {
+            const ws = clients.get(clientId);
+            if (ws && ws.readyState === 1) {
+                ws.send(data);
+            }
+        },
+        broadcast(data) {
+            for (const ws of clients.values()) {
+                if (ws.readyState === 1)
+                    ws.send(data);
+            }
+        },
+    };
+}
+export function createNetServer(em, registry, config, transport) {
+    const encoder = new ProtocolEncoder();
+    const differ = createSnapshotDiffer(em, registry);
+    const tp = transport ?? createWsTransport();
+    const clientIds = new Set();
+    const clientViews = new Map();
+    const server = {
+        onConnect: null,
+        onDisconnect: null,
+        onMessage: null,
+        get clientCount() {
+            return clientIds.size;
+        },
+        get entityNetIds() {
+            return differ.entityNetIds;
+        },
+        send(clientId, data) {
+            tp.send(clientId, data);
+        },
+        start() {
+            return tp.start(config.port, {
+                onOpen(clientId) {
+                    clientIds.add(clientId);
+                    clientViews.set(clientId, createClientView());
+                    const fullState = encoder.encodeFullState(em, registry, differ.entityNetIds);
+                    tp.send(clientId, fullState);
+                    // Initialize the client view's known set to match the full state we just sent
+                    const knownNetIds = new Set(differ.entityNetIds.values());
+                    clientViews.get(clientId).initKnown(knownNetIds);
+                    server.onConnect?.(clientId);
+                },
+                onClose(clientId) {
+                    clientIds.delete(clientId);
+                    clientViews.delete(clientId);
+                    server.onDisconnect?.(clientId);
+                },
+                onMessage(clientId, data) {
+                    server.onMessage?.(clientId, data);
+                },
+            });
+        },
+        async stop() {
+            await tp.stop();
+            clientIds.clear();
+            clientViews.clear();
+        },
+        tick(filter) {
+            if (!filter) {
+                const buffer = differ.diffAndEncode(encoder);
+                if (clientIds.size === 0)
+                    return;
+                if (buffer.byteLength <= 7)
+                    return;
+                tp.broadcast(buffer);
+                return;
+            }
+            const changeset = differ.computeChangeset();
+            // Phase 1: compute all client deltas, group by identical content
+            const groups = new Map();
+            const extraEnterNetIds = new Set();
+            for (const clientId of clientIds) {
+                const view = clientViews.get(clientId);
+                if (!view)
+                    continue;
+                const interest = filter(clientId);
+                const delta = view.update(interest, changeset);
+                const key = deltaKey(delta);
+                if (key === EMPTY_KEY)
+                    continue;
+                let group = groups.get(key);
+                if (!group) {
+                    // Copy arrays — clientView reuses them on next update() call
+                    group = {
+                        delta: { enters: [...delta.enters], leaves: [...delta.leaves], updates: [...delta.updates] },
+                        clients: [],
+                    };
+                    groups.set(key, group);
+                }
+                group.clients.push(clientId);
+                // Collect view-enters that aren't global creates (need pre-encoding)
+                for (const netId of delta.enters) {
+                    if (!changeset.createdSet.has(netId))
+                        extraEnterNetIds.add(netId);
+                }
+            }
+            if (groups.size === 0) {
+                differ.flushSnapshots();
+                return;
+            }
+            // Phase 2: pre-encode all entities once
+            const cache = differ.preEncodeChangeset(encoder, changeset, extraEnterNetIds);
+            // Phase 3: compose per group from cached slices, send to all clients
+            for (const group of groups.values()) {
+                const buffer = differ.composeFromCache(encoder, cache, group.delta);
+                for (const clientId of group.clients) {
+                    tp.send(clientId, buffer);
+                }
+            }
+            differ.flushSnapshots();
+        },
+    };
+    return server;
+}

package/dist/Protocol.d.ts

@@ -0,0 +1,58 @@
+import type { EntityId, EntityManager } from 'archetype-ecs';
+import type { ComponentRegistry } from './ComponentRegistry.js';
+import type { NetMessage, WireType } from './types.js';
+export declare class ProtocolEncoder {
+    private buf;
+    private view;
+    private offset;
+    constructor(initialSize?: number);
+    private ensure;
+    writeU8(v: number): void;
+    writeU16(v: number): void;
+    writeU32(v: number): void;
+    private writeF32;
+    private writeF64;
+    private writeI8;
+    private writeI16;
+    private writeI32;
+    private writeString;
+    /** Reserve a u8 slot, returns the offset for backpatching */
+    reserveU8(): number;
+    /** Reserve a u16 slot, returns the offset for backpatching */
+    reserveU16(): number;
+    /** Write a u8 value at a previously reserved offset */
+    patchU8(off: number, v: number): void;
+    /** Write a u16 value at a previously reserved offset */
+    patchU16(off: number, v: number): void;
+    writeVarint(v: number): void;
+    writeBytes(data: Uint8Array): void;
+    writeField(type: WireType, value: unknown): void;
+    private writeComponentData;
+    /** Reset write position for reuse (no reallocation) */
+    reset(): void;
+    /** Returns a trimmed copy of the written bytes */
+    finish(): ArrayBuffer;
+    encodeFullState(em: EntityManager, registry: ComponentRegistry, entityNetIds: ReadonlyMap<EntityId, number>): ArrayBuffer;
+}
+export declare class ProtocolDecoder {
+    private view;
+    private bytes;
+    private offset;
+    private readU8;
+    private readU16;
+    private readU32;
+    private readF32;
+    private readF64;
+    private readI8;
+    private readI16;
+    private readI32;
+    private readString;
+    private readVarint;
+    private readField;
+    private readComponentData;
+    decode(buffer: ArrayBuffer, registry: ComponentRegistry): NetMessage;
+    private decodeFullState;
+    private decodeDelta;
+}
+export declare function encodeFullState(em: EntityManager, registry: ComponentRegistry, entityNetIds: ReadonlyMap<EntityId, number>): ArrayBuffer;
+export declare function decode(buffer: ArrayBuffer, registry: ComponentRegistry): NetMessage;

package/dist/Protocol.js

@@ -0,0 +1,356 @@
+import { MSG_DELTA, MSG_FULL } from './types.js';
+// ── Encoder ─────────────────────────────────────────────
+const INITIAL_BUFFER_SIZE = 4096;
+const textEncoder = new TextEncoder();
+export class ProtocolEncoder {
+    buf;
+    view;
+    offset = 0;
+    constructor(initialSize = INITIAL_BUFFER_SIZE) {
+        this.buf = new ArrayBuffer(initialSize);
+        this.view = new DataView(this.buf);
+    }
+    ensure(bytes) {
+        if (this.offset + bytes <= this.buf.byteLength)
+            return;
+        let newSize = this.buf.byteLength * 2;
+        while (newSize < this.offset + bytes)
+            newSize *= 2;
+        const newBuf = new ArrayBuffer(newSize);
+        new Uint8Array(newBuf).set(new Uint8Array(this.buf));
+        this.buf = newBuf;
+        this.view = new DataView(this.buf);
+    }
+    writeU8(v) {
+        this.ensure(1);
+        this.view.setUint8(this.offset, v);
+        this.offset += 1;
+    }
+    writeU16(v) {
+        this.ensure(2);
+        this.view.setUint16(this.offset, v, true);
+        this.offset += 2;
+    }
+    writeU32(v) {
+        this.ensure(4);
+        this.view.setUint32(this.offset, v, true);
+        this.offset += 4;
+    }
+    writeF32(v) {
+        this.ensure(4);
+        this.view.setFloat32(this.offset, v, true);
+        this.offset += 4;
+    }
+    writeF64(v) {
+        this.ensure(8);
+        this.view.setFloat64(this.offset, v, true);
+        this.offset += 8;
+    }
+    writeI8(v) {
+        this.ensure(1);
+        this.view.setInt8(this.offset, v);
+        this.offset += 1;
+    }
+    writeI16(v) {
+        this.ensure(2);
+        this.view.setInt16(this.offset, v, true);
+        this.offset += 2;
+    }
+    writeI32(v) {
+        this.ensure(4);
+        this.view.setInt32(this.offset, v, true);
+        this.offset += 4;
+    }
+    writeString(s) {
+        const encoded = textEncoder.encode(s);
+        this.writeU16(encoded.byteLength);
+        this.ensure(encoded.byteLength);
+        new Uint8Array(this.buf, this.offset, encoded.byteLength).set(encoded);
+        this.offset += encoded.byteLength;
+    }
+    /** Reserve a u8 slot, returns the offset for backpatching */
+    reserveU8() {
+        const off = this.offset;
+        this.writeU8(0);
+        return off;
+    }
+    /** Reserve a u16 slot, returns the offset for backpatching */
+    reserveU16() {
+        const off = this.offset;
+        this.writeU16(0);
+        return off;
+    }
+    /** Write a u8 value at a previously reserved offset */
+    patchU8(off, v) {
+        this.view.setUint8(off, v);
+    }
+    /** Write a u16 value at a previously reserved offset */
+    patchU16(off, v) {
+        this.view.setUint16(off, v, true);
+    }
+    writeVarint(v) {
+        if (v < 0 || v > 0xFFFFFFFF)
+            throw new RangeError(`Varint out of range: ${v}`);
+        while (v >= 0x80) {
+            this.writeU8((v & 0x7F) | 0x80);
+            v >>>= 7;
+        }
+        this.writeU8(v);
+    }
+    writeBytes(data) {
+        this.ensure(data.byteLength);
+        new Uint8Array(this.buf, this.offset, data.byteLength).set(data);
+        this.offset += data.byteLength;
+    }
+    writeField(type, value) {
+        switch (type) {
+            case 'f32':
+                this.writeF32(value);
+                break;
+            case 'f64':
+                this.writeF64(value);
+                break;
+            case 'i8':
+                this.writeI8(value);
+                break;
+            case 'i16':
+                this.writeI16(value);
+                break;
+            case 'i32':
+                this.writeI32(value);
+                break;
+            case 'u8':
+                this.writeU8(value);
+                break;
+            case 'u16':
+                this.writeU16(value);
+                break;
+            case 'u32':
+                this.writeU32(value);
+                break;
+            case 'string':
+                this.writeString(value);
+                break;
+        }
+    }
+    writeComponentData(fields, data) {
+        for (const field of fields) {
+            this.writeField(field.type, data[field.name]);
+        }
+    }
+    /** Reset write position for reuse (no reallocation) */
+    reset() {
+        this.offset = 0;
+    }
+    /** Returns a trimmed copy of the written bytes */
+    finish() {
+        return this.buf.slice(0, this.offset);
+    }
+    // ── Full state encoding ─────────────────────────────
+    encodeFullState(em, registry, entityNetIds) {
+        this.reset();
+        this.writeU8(MSG_FULL);
+        this.writeU32(registry.hash);
+        this.writeU16(entityNetIds.size);
+        for (const [entityId, netId] of entityNetIds) {
+            this.writeVarint(netId);
+            // Count components this entity has
+            const comps = [];
+            for (const reg of registry.components) {
+                if (em.hasComponent(entityId, reg.component)) {
+                    const data = em.getComponent(entityId, reg.component);
+                    if (data)
+                        comps.push({ reg, data: data });
+                }
+            }
+            this.writeU8(comps.length);
+            for (const { reg, data } of comps) {
+                this.writeU8(reg.wireId);
+                this.writeComponentData(reg.fields, data);
+            }
+        }
+        return this.finish();
+    }
+}
+// ── Decoder ─────────────────────────────────────────────
+const textDecoder = new TextDecoder();
+export class ProtocolDecoder {
+    view;
+    bytes;
+    offset = 0;
+    readU8() {
+        const v = this.view.getUint8(this.offset);
+        this.offset += 1;
+        return v;
+    }
+    readU16() {
+        const v = this.view.getUint16(this.offset, true);
+        this.offset += 2;
+        return v;
+    }
+    readU32() {
+        const v = this.view.getUint32(this.offset, true);
+        this.offset += 4;
+        return v;
+    }
+    readF32() {
+        const v = this.view.getFloat32(this.offset, true);
+        this.offset += 4;
+        return v;
+    }
+    readF64() {
+        const v = this.view.getFloat64(this.offset, true);
+        this.offset += 8;
+        return v;
+    }
+    readI8() {
+        const v = this.view.getInt8(this.offset);
+        this.offset += 1;
+        return v;
+    }
+    readI16() {
+        const v = this.view.getInt16(this.offset, true);
+        this.offset += 2;
+        return v;
+    }
+    readI32() {
+        const v = this.view.getInt32(this.offset, true);
+        this.offset += 4;
+        return v;
+    }
+    readString() {
+        const len = this.readU16();
+        const str = textDecoder.decode(this.bytes.subarray(this.offset, this.offset + len));
+        this.offset += len;
+        return str;
+    }
+    readVarint() {
+        let v = 0;
+        let shift = 0;
+        let b;
+        do {
+            if (shift >= 35)
+                throw new Error('Varint too long (corrupt data or >5 bytes)');
+            b = this.readU8();
+            v |= (b & 0x7F) << shift;
+            shift += 7;
+        } while (b >= 0x80);
+        return v >>> 0;
+    }
+    readField(type) {
+        switch (type) {
+            case 'f32': return this.readF32();
+            case 'f64': return this.readF64();
+            case 'i8': return this.readI8();
+            case 'i16': return this.readI16();
+            case 'i32': return this.readI32();
+            case 'u8': return this.readU8();
+            case 'u16': return this.readU16();
+            case 'u32': return this.readU32();
+            case 'string': return this.readString();
+        }
+    }
+    readComponentData(fields) {
+        const data = {};
+        for (const field of fields) {
+            data[field.name] = this.readField(field.type);
+        }
+        return data;
+    }
+    decode(buffer, registry) {
+        this.view = new DataView(buffer);
+        this.bytes = new Uint8Array(buffer);
+        this.offset = 0;
+        const msgType = this.readU8();
+        if (msgType === MSG_FULL) {
+            return this.decodeFullState(registry);
+        }
+        else if (msgType === MSG_DELTA) {
+            return this.decodeDelta(registry);
+        }
+        throw new Error(`Unknown message type: 0x${msgType.toString(16)}`);
+    }
+    decodeFullState(registry) {
+        const remoteHash = this.readU32();
+        if (remoteHash !== registry.hash) {
+            throw new Error(`Registry mismatch: server hash 0x${remoteHash.toString(16)} !== client hash 0x${registry.hash.toString(16)}. ` +
+                `Ensure server and client use identical component registrations (same names, fields, types, and order).`);
+        }
+        const entityCount = this.readU16();
+        const entities = new Map();
+        for (let e = 0; e < entityCount; e++) {
+            const netId = this.readVarint();
+            const compCount = this.readU8();
+            const compMap = new Map();
+            for (let c = 0; c < compCount; c++) {
+                const wireId = this.readU8();
+                const reg = registry.byWireId(wireId);
+                if (!reg)
+                    throw new Error(`Unknown wire ID: ${wireId}`);
+                compMap.set(wireId, this.readComponentData(reg.fields));
+            }
+            entities.set(netId, compMap);
+        }
+        return { type: MSG_FULL, entities };
+    }
+    decodeDelta(registry) {
+        // Created
+        const createdCount = this.readU16();
+        const created = new Map();
+        for (let i = 0; i < createdCount; i++) {
+            const netId = this.readVarint();
+            const compCount = this.readU8();
+            const compMap = new Map();
+            for (let c = 0; c < compCount; c++) {
+                const wireId = this.readU8();
+                const reg = registry.byWireId(wireId);
+                if (!reg)
+                    throw new Error(`Unknown wire ID: ${wireId}`);
+                compMap.set(wireId, this.readComponentData(reg.fields));
+            }
+            created.set(netId, compMap);
+        }
+        // Destroyed
+        const destroyedCount = this.readU16();
+        const destroyed = [];
+        for (let i = 0; i < destroyedCount; i++) {
+            destroyed.push(this.readVarint());
+        }
+        // Updated (grouped by entity)
+        const updatedEntityCount = this.readU16();
+        const updated = [];
+        for (let i = 0; i < updatedEntityCount; i++) {
+            const netId = this.readVarint();
+            const compCount = this.readU8();
+            for (let c = 0; c < compCount; c++) {
+                const wireId = this.readU8();
+                const fieldMask = this.readU16();
+                const reg = registry.byWireId(wireId);
+                if (!reg)
+                    throw new Error(`Unknown wire ID: ${wireId}`);
+                const validMask = (1 << reg.fields.length) - 1;
+                if (fieldMask & ~validMask) {
+                    throw new Error(`Invalid field mask 0x${fieldMask.toString(16)} for wire ID ${wireId}: ` +
+                        `has bits set beyond ${reg.fields.length} fields`);
+                }
+                const data = {};
+                for (let f = 0; f < reg.fields.length; f++) {
+                    if (fieldMask & (1 << f)) {
+                        data[reg.fields[f].name] = this.readField(reg.fields[f].type);
+                    }
+                }
+                updated.push({ netId, componentWireId: wireId, fieldMask, data });
+            }
+        }
+        return { type: MSG_DELTA, created, destroyed, updated };
+    }
+}
+// ── Convenience functions ───────────────────────────────
+const sharedEncoder = new ProtocolEncoder();
+const sharedDecoder = new ProtocolDecoder();
+export function encodeFullState(em, registry, entityNetIds) {
+    return sharedEncoder.encodeFullState(em, registry, entityNetIds);
+}
+export function decode(buffer, registry) {
+    return sharedDecoder.decode(buffer, registry);
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { createComponentRegistry } from './ComponentRegistry.js';
+export type { ComponentRegistry } from './ComponentRegistry.js';
+export { Networked } from './DirtyTracker.js';
+export { createNetServer, createWsTransport } from './NetServer.js';
+export type { NetServer, ServerTransport, TransportHandlers } from './NetServer.js';
+export { createNetClient } from './NetClient.js';
+export type { NetClient } from './NetClient.js';
+export type { NetworkConfig, ComponentRegistration, ClientId, } from './types.js';
+export type { InterestFilter } from './InterestManager.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createComponentRegistry } from './ComponentRegistry.js';
+export { Networked } from './DirtyTracker.js';
+export { createNetServer, createWsTransport } from './NetServer.js';
+export { createNetClient } from './NetClient.js';

package/dist/types.d.ts

@@ -0,0 +1,40 @@
+import type { ComponentDef } from 'archetype-ecs';
+export interface NetworkConfig {
+    port: number;
+    maxClients?: number;
+}
+export interface ComponentRegistration {
+    component: ComponentDef<any>;
+    name: string;
+}
+export type WireType = 'f32' | 'f64' | 'i8' | 'i16' | 'i32' | 'u8' | 'u16' | 'u32' | 'string';
+export interface FieldInfo {
+    name: string;
+    type: WireType;
+    byteSize: number;
+}
+export interface RegisteredComponent {
+    wireId: number;
+    name: string;
+    component: ComponentDef<any>;
+    fields: FieldInfo[];
+}
+export declare const MSG_FULL = 1;
+export declare const MSG_DELTA = 2;
+export interface FullStateMessage {
+    type: typeof MSG_FULL;
+    entities: Map<number, Map<number, Record<string, unknown>>>;
+}
+export interface DeltaMessage {
+    type: typeof MSG_DELTA;
+    created: Map<number, Map<number, Record<string, unknown>>>;
+    destroyed: number[];
+    updated: {
+        netId: number;
+        componentWireId: number;
+        fieldMask: number;
+        data: Record<string, unknown>;
+    }[];
+}
+export type NetMessage = FullStateMessage | DeltaMessage;
+export type ClientId = number;

package/dist/types.js

@@ -0,0 +1,3 @@
+// ── Protocol messages ───────────────────────────────────
+export const MSG_FULL = 0x01;
+export const MSG_DELTA = 0x02;

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "archetype-ecs-net",
+  "version": "0.1.1",
+  "description": "Network layer for archetype-ecs: dirty tracking + binary delta sync",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc --noEmit && npx tsx --test tests/*.test.ts example/example.test.ts"
+  },
+  "keywords": [
+    "ecs",
+    "networking",
+    "gamedev",
+    "archetype-ecs",
+    "binary-protocol",
+    "delta-sync"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "archetype-ecs": ">=1.2.0"
+  },
+  "dependencies": {
+    "ws": "^8.19.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.18.1",
+    "archetype-ecs": "^1.2.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.4.0"
+  },
+  "files": [
+    "dist",
+    "src"
+  ]
+}