archetype-ecs-net 0.1.1

package/dist/DirtyTracker.js

@@ -0,0 +1,348 @@
+import { component } from 'archetype-ecs';
+import { MSG_DELTA } from './types.js';
+/** Tag component — add to any entity that should be synced over the network */
+export const Networked = component('Networked');
+export function createSnapshotDiffer(em, registry) {
+    // Enable core-level change tracking + double-buffered snapshots
+    em.enableTracking(Networked);
+    // Precompute field refs per registered component
+    // Each field also carries its index within the component for bitmask building
+    const compFields = [];
+    for (const reg of registry.components) {
+        const refs = [];
+        for (let fi = 0; fi < reg.fields.length; fi++) {
+            const field = reg.fields[fi];
+            refs.push({ name: field.name, ref: reg.component[field.name], fieldIdx: fi });
+        }
+        compFields.push({ wireId: reg.wireId, refs });
+    }
+    // Max wireId for pre-allocating sparse bitmask array
+    const maxWireId = compFields.length > 0 ? compFields[compFields.length - 1].wireId : 0;
+    let firstDiff = true;
+    let nextNetId = 1;
+    const entityToNetId = new Map();
+    const netIdToEntityMap = new Map();
+    // ── Shared helper: encode all components of an entity from live ECS ──
+    function writeEntityComponents(encoder, eid) {
+        const compCountOff = encoder.reserveU8();
+        let compCount = 0;
+        for (const cf of compFields) {
+            const firstVal = em.get(eid, cf.refs[0].ref);
+            if (firstVal === undefined)
+                continue;
+            compCount++;
+            encoder.writeU8(cf.wireId);
+            for (const f of cf.refs) {
+                const regField = registry.components[cf.wireId].fields[f.fieldIdx];
+                encoder.writeField(regField.type, em.get(eid, f.ref));
+            }
+        }
+        encoder.patchU8(compCountOff, compCount);
+    }
+    // ── Shared helper: flush ECS changes + handle first-diff ──
+    function flushAndPrepare() {
+        const changes = em.flushChanges();
+        const coreCreated = changes.created;
+        const coreDestroyed = changes.destroyed;
+        if (firstDiff) {
+            firstDiff = false;
+            const existing = em.query([Networked]);
+            for (const eid of existing) {
+                if (!coreCreated.has(eid))
+                    coreCreated.add(eid);
+            }
+        }
+        return { coreCreated, coreDestroyed };
+    }
+    // ── Shared helper: process creates + destroys, update netId maps ──
+    function processCreateDestroy(coreCreated, coreDestroyed) {
+        // Collect destroyed netIds before removing from map
+        const destroyed = [];
+        for (const eid of coreDestroyed) {
+            const netId = entityToNetId.get(eid);
+            if (netId !== undefined) {
+                destroyed.push(netId);
+                entityToNetId.delete(eid);
+                netIdToEntityMap.delete(netId);
+            }
+        }
+        // Assign netIds to created entities (excluding immediately destroyed)
+        const created = [];
+        for (const eid of coreCreated) {
+            if (coreDestroyed.has(eid))
+                continue;
+            const netId = nextNetId++;
+            entityToNetId.set(eid, netId);
+            netIdToEntityMap.set(netId, eid);
+            created.push({ netId, entityId: eid });
+        }
+        return { created, destroyed };
+    }
+    // ── Shared helper: collect dirty entries from archetype iteration ──
+    function collectDirty(coreCreated, coreDestroyed) {
+        const dirty = [];
+        em.forEach([Networked], (a) => {
+            const count = a.count;
+            const entityIds = a.entityIds;
+            const snapCount = a.snapshotCount;
+            const snapEids = a.snapshotEntityIds;
+            if (!snapEids || snapCount === 0)
+                return;
+            const minCount = count < snapCount ? count : snapCount;
+            const fieldArrs = [];
+            for (const cf of compFields) {
+                for (const f of cf.refs) {
+                    const front = a.field(f.ref);
+                    const back = a.snapshot(f.ref);
+                    if (front && back) {
+                        const regField = registry.components[cf.wireId].fields[f.fieldIdx];
+                        fieldArrs.push({ wireId: cf.wireId, fieldIdx: f.fieldIdx, front, back, type: regField.type });
+                    }
+                }
+            }
+            if (fieldArrs.length === 0)
+                return;
+            for (let i = 0; i < minCount; i++) {
+                const eid = entityIds[i];
+                if (eid !== snapEids[i])
+                    continue;
+                if (coreCreated.has(eid) || coreDestroyed.has(eid))
+                    continue;
+                const netId = entityToNetId.get(eid);
+                if (netId === undefined)
+                    continue;
+                let hasDirty = false;
+                const masks = new Uint16Array(maxWireId + 1);
+                for (let f = 0; f < fieldArrs.length; f++) {
+                    const fa = fieldArrs[f];
+                    if (fa.front[i] !== fa.back[i]) {
+                        masks[fa.wireId] |= (1 << fa.fieldIdx);
+                        hasDirty = true;
+                    }
+                }
+                if (hasDirty) {
+                    dirty.push({ netId, entityId: eid, dirtyMasks: masks });
+                }
+            }
+        });
+        return dirty;
+    }
+    // ── Shared helper: encode a dirty entry's updated fields ──
+    function encodeDirtyEntity(encoder, entry) {
+        encoder.writeVarint(entry.netId);
+        const compCountOff = encoder.reserveU8();
+        let compCount = 0;
+        for (let w = 0; w <= maxWireId; w++) {
+            const mask = entry.dirtyMasks[w];
+            if (mask === 0)
+                continue;
+            compCount++;
+            encoder.writeU8(w);
+            encoder.writeU16(mask);
+            // Write dirty field values from live ECS
+            for (const f of compFields[w].refs) {
+                if (mask & (1 << f.fieldIdx)) {
+                    const regField = registry.components[w].fields[f.fieldIdx];
+                    encoder.writeField(regField.type, em.get(entry.entityId, f.ref));
+                }
+            }
+        }
+        encoder.patchU8(compCountOff, compCount);
+    }
+    return {
+        get entityNetIds() {
+            return entityToNetId;
+        },
+        get netIdToEntity() {
+            return netIdToEntityMap;
+        },
+        // ── Broadcast mode: original fused diff+encode (unchanged behavior) ──
+        diffAndEncode(encoder) {
+            const changes = em.flushChanges();
+            const coreCreated = changes.created;
+            const coreDestroyed = changes.destroyed;
+            // First diff: treat all existing Networked entities as created
+            if (firstDiff) {
+                firstDiff = false;
+                const existing = em.query([Networked]);
+                for (const eid of existing) {
+                    if (!coreCreated.has(eid))
+                        coreCreated.add(eid);
+                }
+            }
+            // Collect destroyed netIds before removing from map
+            const destroyed = [];
+            for (const eid of coreDestroyed) {
+                const netId = entityToNetId.get(eid);
+                if (netId !== undefined) {
+                    destroyed.push(netId);
+                    entityToNetId.delete(eid);
+                    netIdToEntityMap.delete(netId);
+                }
+            }
+            // ── Start encoding ────────────────────────────────
+            encoder.reset();
+            encoder.writeU8(MSG_DELTA);
+            // Created: assign netIds, encode component data directly from ECS
+            const createdEntities = [];
+            for (const eid of coreCreated) {
+                if (!coreDestroyed.has(eid))
+                    createdEntities.push(eid);
+            }
+            encoder.writeU16(createdEntities.length);
+            for (const eid of createdEntities) {
+                const netId = nextNetId++;
+                entityToNetId.set(eid, netId);
+                netIdToEntityMap.set(netId, eid);
+                encoder.writeVarint(netId);
+                writeEntityComponents(encoder, eid);
+            }
+            // Destroyed
+            encoder.writeU16(destroyed.length);
+            for (const netId of destroyed)
+                encoder.writeVarint(netId);
+            // Updated — backpatch count, write directly from front buffers
+            const updateCountOff = encoder.reserveU16();
+            let updateCount = 0;
+            em.forEach([Networked], (a) => {
+                const count = a.count;
+                const entityIds = a.entityIds;
+                const snapCount = a.snapshotCount;
+                const snapEids = a.snapshotEntityIds;
+                if (!snapEids || snapCount === 0)
+                    return;
+                const minCount = count < snapCount ? count : snapCount;
+                const fieldArrs = [];
+                for (const cf of compFields) {
+                    for (const f of cf.refs) {
+                        const front = a.field(f.ref);
+                        const back = a.snapshot(f.ref);
+                        if (front && back) {
+                            const regField = registry.components[cf.wireId].fields[f.fieldIdx];
+                            fieldArrs.push({ wireId: cf.wireId, fieldIdx: f.fieldIdx, front, back, type: regField.type });
+                        }
+                    }
+                }
+                if (fieldArrs.length === 0)
+                    return;
+                const dirtyMasks = new Uint16Array(maxWireId + 1);
+                for (let i = 0; i < minCount; i++) {
+                    const eid = entityIds[i];
+                    if (eid !== snapEids[i])
+                        continue;
+                    if (coreCreated.has(eid) || coreDestroyed.has(eid))
+                        continue;
+                    const netId = entityToNetId.get(eid);
+                    if (netId === undefined)
+                        continue;
+                    let hasDirty = false;
+                    for (let f = 0; f < fieldArrs.length; f++) {
+                        const fa = fieldArrs[f];
+                        if (fa.front[i] !== fa.back[i]) {
+                            dirtyMasks[fa.wireId] |= (1 << fa.fieldIdx);
+                            hasDirty = true;
+                        }
+                    }
+                    if (hasDirty) {
+                        updateCount++;
+                        encoder.writeVarint(netId);
+                        const compCountOff = encoder.reserveU8();
+                        let compCount = 0;
+                        for (let w = 0; w <= maxWireId; w++) {
+                            const mask = dirtyMasks[w];
+                            if (mask === 0)
+                                continue;
+                            dirtyMasks[w] = 0;
+                            compCount++;
+                            encoder.writeU8(w);
+                            encoder.writeU16(mask);
+                            for (let f = 0; f < fieldArrs.length; f++) {
+                                const fa = fieldArrs[f];
+                                if (fa.wireId === w && (mask & (1 << fa.fieldIdx))) {
+                                    encoder.writeField(fa.type, fa.front[i]);
+                                }
+                            }
+                        }
+                        encoder.patchU8(compCountOff, compCount);
+                    }
+                    else {
+                        for (let w = 0; w <= maxWireId; w++)
+                            dirtyMasks[w] = 0;
+                    }
+                }
+            });
+            encoder.patchU16(updateCountOff, updateCount);
+            em.flushSnapshots();
+            return encoder.finish();
+        },
+        // ── Interest mode: Phase 1 — compute changeset ──
+        computeChangeset() {
+            const { coreCreated, coreDestroyed } = flushAndPrepare();
+            const { created, destroyed } = processCreateDestroy(coreCreated, coreDestroyed);
+            const dirty = collectDirty(coreCreated, coreDestroyed);
+            const createdSet = new Set();
+            for (const c of created)
+                createdSet.add(c.netId);
+            const destroyedSet = new Set();
+            for (const d of destroyed)
+                destroyedSet.add(d);
+            return { created, destroyed, dirty, createdSet, destroyedSet };
+        },
+        preEncodeChangeset(encoder, changeset, extraEnterNetIds) {
+            const enterSlices = new Map();
+            const updateSlices = new Map();
+            // Pre-encode created entities (global creates that may enter views)
+            for (const entry of changeset.created) {
+                encoder.reset();
+                encoder.writeVarint(entry.netId);
+                writeEntityComponents(encoder, entry.entityId);
+                enterSlices.set(entry.netId, new Uint8Array(encoder.finish()));
+            }
+            // Pre-encode extra enters (existing entities entering a client's view)
+            for (const netId of extraEnterNetIds) {
+                if (enterSlices.has(netId))
+                    continue; // already encoded as created
+                const eid = netIdToEntityMap.get(netId);
+                if (eid === undefined)
+                    continue;
+                encoder.reset();
+                encoder.writeVarint(netId);
+                writeEntityComponents(encoder, eid);
+                enterSlices.set(netId, new Uint8Array(encoder.finish()));
+            }
+            // Pre-encode dirty entity updates
+            for (const entry of changeset.dirty) {
+                encoder.reset();
+                encodeDirtyEntity(encoder, entry);
+                updateSlices.set(entry.netId, new Uint8Array(encoder.finish()));
+            }
+            return { enterSlices, updateSlices };
+        },
+        composeFromCache(encoder, cache, clientDelta) {
+            encoder.reset();
+            encoder.writeU8(MSG_DELTA);
+            // Created section
+            encoder.writeU16(clientDelta.enters.length);
+            for (const netId of clientDelta.enters) {
+                const slice = cache.enterSlices.get(netId);
+                if (slice)
+                    encoder.writeBytes(slice);
+            }
+            // Destroyed section
+            encoder.writeU16(clientDelta.leaves.length);
+            for (const netId of clientDelta.leaves)
+                encoder.writeVarint(netId);
+            // Updated section
+            encoder.writeU16(clientDelta.updates.length);
+            for (const netId of clientDelta.updates) {
+                const slice = cache.updateSlices.get(netId);
+                if (slice)
+                    encoder.writeBytes(slice);
+            }
+            return encoder.finish();
+        },
+        flushSnapshots() {
+            em.flushSnapshots();
+        },
+    };
+}

package/dist/InterestManager.d.ts

@@ -0,0 +1,25 @@
+import type { ClientId } from './types.js';
+import type { Changeset } from './DirtyTracker.js';
+/**
+ * Per-client interest filter callback.
+ * Return the set of netIds that should be visible to this client.
+ */
+export type InterestFilter = (clientId: ClientId) => ReadonlySet<number>;
+/** Describes what changed for a specific client this tick */
+export interface ClientDelta {
+    /** NetIds to send as "created" (entered view or globally new + in view) */
+    readonly enters: number[];
+    /** NetIds to send as "destroyed" (left view or globally destroyed + was known) */
+    readonly leaves: number[];
+    /** NetIds to send field updates for (dirty + in view + already known) */
+    readonly updates: number[];
+}
+export interface ClientView {
+    /** The set of netIds this client currently knows about */
+    readonly knownEntities: ReadonlySet<number>;
+    /** Pre-populate known set (e.g., after sending filtered full state on connect) */
+    initKnown(netIds: ReadonlySet<number>): void;
+    /** Compute enter/leave/update delta for this tick */
+    update(currentInterest: ReadonlySet<number>, changeset: Changeset): ClientDelta;
+}
+export declare function createClientView(): ClientView;

package/dist/InterestManager.js

@@ -0,0 +1,71 @@
+export function createClientView() {
+    const known = new Set();
+    // Reusable arrays to avoid GC pressure
+    const enters = [];
+    const leaves = [];
+    const updates = [];
+    return {
+        get knownEntities() {
+            return known;
+        },
+        initKnown(netIds) {
+            known.clear();
+            for (const id of netIds)
+                known.add(id);
+        },
+        update(interest, changeset) {
+            enters.length = 0;
+            leaves.length = 0;
+            updates.length = 0;
+            const destroyedSet = changeset.destroyedSet;
+            const createdSet = changeset.createdSet;
+            // 1. Globally destroyed entities that this client knew about → leave
+            for (const netId of changeset.destroyed) {
+                if (known.has(netId)) {
+                    leaves.push(netId);
+                    known.delete(netId);
+                }
+            }
+            // 2. Globally created entities that are in interest → enter
+            for (const entry of changeset.created) {
+                if (interest.has(entry.netId)) {
+                    enters.push(entry.netId);
+                    known.add(entry.netId);
+                }
+            }
+            // 3. Interest transitions for existing entities
+            //    - In known but NOT in interest → leave (entity left view)
+            //    - In interest but NOT in known → enter (entity entered view)
+            for (const netId of known) {
+                if (!interest.has(netId) && !destroyedSet.has(netId)) {
+                    leaves.push(netId);
+                }
+            }
+            // Remove leaves from known
+            for (const netId of leaves)
+                known.delete(netId);
+            for (const netId of interest) {
+                if (!known.has(netId) && !createdSet.has(netId) && !destroyedSet.has(netId)) {
+                    enters.push(netId);
+                    known.add(netId);
+                }
+            }
+            // 4. Dirty entities that are in known (and not just entered) → update
+            for (const entry of changeset.dirty) {
+                if (known.has(entry.netId) && !createdSet.has(entry.netId)) {
+                    // Check it's not a fresh enter (enters already get full data)
+                    let isEnter = false;
+                    for (let i = 0; i < enters.length; i++) {
+                        if (enters[i] === entry.netId) {
+                            isEnter = true;
+                            break;
+                        }
+                    }
+                    if (!isEnter)
+                        updates.push(entry.netId);
+                }
+            }
+            return { enters, leaves, updates };
+        },
+    };
+}

package/dist/NetClient.d.ts

@@ -0,0 +1,14 @@
+import type { EntityManager } from 'archetype-ecs';
+import type { ComponentRegistry } from './ComponentRegistry.js';
+export interface NetClient {
+    /** Connect to server */
+    connect(url: string): void;
+    /** Disconnect from server */
+    disconnect(): void;
+    /** Whether currently connected */
+    readonly connected: boolean;
+    /** Callbacks */
+    onConnected: (() => void) | null;
+    onDisconnected: (() => void) | null;
+}
+export declare function createNetClient(em: EntityManager, registry: ComponentRegistry): NetClient;

package/dist/NetClient.js

@@ -0,0 +1,123 @@
+import { ProtocolDecoder } from './Protocol.js';
+import { MSG_DELTA, MSG_FULL } from './types.js';
+export function createNetClient(em, registry) {
+    const decoder = new ProtocolDecoder();
+    let ws = null;
+    // Map wireId → component def for fast lookup during apply
+    const wireToComponent = new Map();
+    for (const reg of registry.components) {
+        wireToComponent.set(reg.wireId, reg);
+    }
+    // netId → local entity ID mapping
+    const netToEntity = new Map();
+    function applyFullState(msg) {
+        // Clear all existing entities and mappings
+        for (const id of em.getAllEntities()) {
+            em.destroyEntity(id);
+        }
+        netToEntity.clear();
+        // Recreate entities with their components
+        for (const [netId, compMap] of msg.entities) {
+            const args = [];
+            for (const [wireId, data] of compMap) {
+                const reg = wireToComponent.get(wireId);
+                if (reg) {
+                    args.push(reg.component, data);
+                }
+            }
+            const localId = args.length > 0
+                ? em.createEntityWith(...args)
+                : em.createEntity();
+            netToEntity.set(netId, localId);
+        }
+    }
+    function applyDelta(msg) {
+        // Apply creates
+        for (const [netId, compMap] of msg.created) {
+            const args = [];
+            for (const [wireId, data] of compMap) {
+                const reg = wireToComponent.get(wireId);
+                if (reg)
+                    args.push(reg.component, data);
+            }
+            const localId = args.length > 0
+                ? em.createEntityWith(...args)
+                : em.createEntity();
+            netToEntity.set(netId, localId);
+        }
+        // Apply destroys
+        for (const netId of msg.destroyed) {
+            const localId = netToEntity.get(netId);
+            if (localId !== undefined) {
+                em.destroyEntity(localId);
+                netToEntity.delete(netId);
+            }
+        }
+        // Apply updates
+        for (const update of msg.updated) {
+            const localId = netToEntity.get(update.netId);
+            if (localId === undefined)
+                continue;
+            const reg = wireToComponent.get(update.componentWireId);
+            if (!reg)
+                continue;
+            for (const [fieldName, value] of Object.entries(update.data)) {
+                const fieldRef = reg.component[fieldName];
+                if (fieldRef) {
+                    em.set(localId, fieldRef, value);
+                }
+            }
+        }
+    }
+    const client = {
+        onConnected: null,
+        onDisconnected: null,
+        get connected() {
+            return ws !== null && ws.readyState === WebSocket.OPEN;
+        },
+        connect(url) {
+            if (ws) {
+                ws.close();
+            }
+            ws = new WebSocket(url);
+            ws.binaryType = 'arraybuffer';
+            ws.onopen = () => {
+                client.onConnected?.();
+            };
+            ws.onmessage = (event) => {
+                const buffer = event.data;
+                const msg = decoder.decode(buffer, registry);
+                if (msg.type === MSG_FULL) {
+                    applyFullState(msg);
+                }
+                else if (msg.type === MSG_DELTA) {
+                    applyDelta(msg);
+                }
+            };
+            ws.onclose = () => {
+                if (ws === null)
+                    return; // already handled by onerror
+                ws = null;
+                client.onDisconnected?.();
+            };
+            ws.onerror = () => {
+                if (ws === null)
+                    return;
+                const sock = ws;
+                ws = null;
+                client.onDisconnected?.();
+                try {
+                    sock.close();
+                }
+                catch { /* ignore */ }
+            };
+        },
+        disconnect() {
+            if (ws) {
+                ws.close();
+                ws = null;
+            }
+        },
+    };
+    return client;
+}

package/dist/NetServer.d.ts

@@ -0,0 +1,35 @@
+import type { EntityId, EntityManager } from 'archetype-ecs';
+import type { ComponentRegistry } from './ComponentRegistry.js';
+import type { InterestFilter } from './InterestManager.js';
+import type { ClientId, NetworkConfig } from './types.js';
+export interface ServerTransport {
+    start(port: number, handlers: TransportHandlers): Promise<void>;
+    stop(): Promise<void>;
+    send(clientId: ClientId, data: ArrayBuffer): void;
+    broadcast(data: ArrayBuffer): void;
+}
+export interface TransportHandlers {
+    onOpen(clientId: ClientId): void;
+    onClose(clientId: ClientId): void;
+    onMessage(clientId: ClientId, data: ArrayBuffer): void;
+}
+export declare function createWsTransport(): ServerTransport;
+export interface NetServer {
+    /** Start listening */
+    start(): Promise<void>;
+    /** Stop server and disconnect all clients */
+    stop(): Promise<void>;
+    /** Diff, encode, send. Without filter: broadcast to all. With filter: per-client interest. */
+    tick(filter?: InterestFilter): void;
+    /** Send a custom message to a specific client */
+    send(clientId: ClientId, data: ArrayBuffer): void;
+    /** Number of connected clients */
+    readonly clientCount: number;
+    /** Entity → netId mapping (assigned during tick) */
+    readonly entityNetIds: ReadonlyMap<EntityId, number>;
+    /** Callbacks */
+    onConnect: ((clientId: ClientId) => void) | null;
+    onDisconnect: ((clientId: ClientId) => void) | null;
+    onMessage: ((clientId: ClientId, data: ArrayBuffer) => void) | null;
+}
+export declare function createNetServer(em: EntityManager, registry: ComponentRegistry, config: NetworkConfig, transport?: ServerTransport): NetServer;