archetype-ecs-net 0.1.1

package/README.md

@@ -0,0 +1,287 @@
+<p align="center">
+  <br>
+  <img src="https://em-content.zobj.net/source/apple/391/satellite-antenna_1f4e1.png" width="80" />
+  <br><br>
+  <strong>archetype-ecs-net</strong>
+  <br>
+  <sub>Binary delta sync over WebSocket for archetype-ecs.</sub>
+  <br><br>
+  <a href="https://www.npmjs.com/package/archetype-ecs-net"><img src="https://img.shields.io/npm/v/archetype-ecs-net.svg?style=flat-square&color=000" alt="npm" /></a>
+  <a href="https://github.com/RvRooijen/archetype-ecs-net/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/archetype-ecs-net.svg?style=flat-square&color=000" alt="license" /></a>
+</p>
+
+---
+
+Network layer for [archetype-ecs](https://github.com/RvRooijen/archetype-ecs). Tag entities with `Networked`, call `tick()` every frame — clients get binary deltas automatically.
+
+```
+npm i archetype-ecs-net
+```
+
+---
+
+### The full picture in 30 lines
+
+```ts
+import { createEntityManager, component } from 'archetype-ecs'
+import { createComponentRegistry, createNetServer, Networked } from 'archetype-ecs-net'
+
+const Position = component('Position', { x: 'f32', y: 'f32' })
+const Velocity = component('Velocity', { vx: 'f32', vy: 'f32' })
+
+const registry = createComponentRegistry([
+  { component: Position, name: 'Position' },
+  { component: Velocity, name: 'Velocity' },
+])
+
+const em = createEntityManager()
+
+// Spawn networked entities
+for (let i = 0; i < 1000; i++) {
+  em.createEntityWith(
+    Position, { x: Math.random() * 800, y: Math.random() * 600 },
+    Velocity, { vx: 1, vy: 1 },
+    Networked,
+  )
+}
+
+const server = createNetServer(em, registry, { port: 9001 })
+await server.start()
+
+// Game loop
+setInterval(() => {
+  em.forEach([Position, Velocity], (a) => {
+    const px = a.field(Position.x), py = a.field(Position.y)
+    const vx = a.field(Velocity.vx), vy = a.field(Velocity.vy)
+    for (let i = 0; i < a.count; i++) { px[i] += vx[i]; py[i] += vy[i] }
+  })
+  server.tick()  // diff → encode → broadcast
+}, 50)
+```
+
+Game systems don't need to change — `tick()` diffs the raw TypedArrays against a double-buffered snapshot.
+
+---
+
+### How it works
+
+```
+Game systems write to TypedArrays (front buffer)
+            │
+            ▼
+     server.tick()
+            │
+     ┌──────┴──────┐
+     │  diff front  │   Compare front[i] !== back[i] per field
+     │  vs back     │   Only iterates Networked archetypes
+     └──────┬──────┘
+            │
+     ┌──────┴──────┐
+     │   encode     │   Binary protocol: u8 wire IDs, field bitmasks
+     └──────┬──────┘
+            │
+     ┌──────┴──────┐
+     │  broadcast   │   WebSocket binary frames
+     └──────┬──────┘
+            │
+     ┌──────┴──────┐
+     │  flush       │   .set() memcpy front → back per field
+     └─────────────┘
+```
+
+Each tracked archetype keeps a back-buffer copy of its TypedArrays. `flushSnapshots()` copies front→back with `.set()` per field.
+
+---
+
+### Client
+
+```ts
+import { createEntityManager, component } from 'archetype-ecs'
+import { createComponentRegistry, createNetClient } from 'archetype-ecs-net'
+
+// Same components, same registration order as server
+const Position = component('Position', { x: 'f32', y: 'f32' })
+const Velocity = component('Velocity', { vx: 'f32', vy: 'f32' })
+
+const registry = createComponentRegistry([
+  { component: Position, name: 'Position' },
+  { component: Velocity, name: 'Velocity' },
+])
+
+const em = createEntityManager()
+const client = createNetClient(em, registry)
+
+client.onConnected = () => console.log('connected')
+client.connect('ws://localhost:9001')
+
+// On connect: receives full state snapshot
+// Every tick: receives binary delta, auto-applied to local EM
+```
+
+The client uses the browser `WebSocket` API — no server-side dependencies needed client-side.
+
+---
+
+### Component registry
+
+Both server and client must register the same components in the same order. This assigns stable `u8` wire IDs (0–255) used in the binary protocol. Each component supports up to 16 fields (u16 bitmask).
+
+```ts
+const registry = createComponentRegistry([
+  { component: Position, name: 'Position' },   // wireId 0
+  { component: Velocity, name: 'Velocity' },   // wireId 1
+  { component: Health,   name: 'Health' },      // wireId 2
+])
+```
+
+Field types are introspected from the component schema — `f32`, `i32`, `string`, etc. — and encoded with their native byte size on the wire.
+
+---
+
+### Networked tag
+
+Only entities with the `Networked` tag component are tracked and synced:
+
+```ts
+import { Networked } from 'archetype-ecs-net'
+
+// This entity is synced
+em.createEntityWith(Position, { x: 0, y: 0 }, Networked)
+
+// This entity is local-only
+em.createEntityWith(Position, { x: 0, y: 0 })
+```
+
+Removing the `Networked` tag triggers a destroy on all clients. Adding it triggers a create.
+
+---
+
+### Binary protocol
+
+Binary format. Field values are written with their native byte size, no JSON encoding.
+
+**Full state** (sent on client connect):
+```
+[u8 0x01] [u32 registryHash] [u16 entityCount]
+  for each: [varint netId] [u8 componentCount]
+    for each: [u8 wireId] [field values in schema order]
+```
+
+**Delta** (sent every tick):
+```
+[u8 0x02]
+  [u16 createdCount]  → varint netId + full component data per entity
+  [u16 destroyedCount] → varint netIds only
+  [u16 updatedEntityCount]
+    for each: [varint netId] [u8 compCount]
+      for each: [u8 wireId] [u16 fieldMask] [changed field values]
+```
+
+Network IDs (`netId`) are varint-encoded (LEB128) — 1 byte for IDs < 128, 2 bytes for < 16K. Updates are grouped per entity to avoid repeating the netId for each dirty component. The wire protocol uses stable netIds instead of raw entity IDs; the client maintains a `netId → localEntityId` mapping.
+
+Only changed fields are sent per entity — if only `Position.x` changed, `Position.y` stays off the wire.
+
+---
+
+### Pluggable transport
+
+Default transport uses `ws`. You can provide your own `ServerTransport`:
+
+```ts
+import { createNetServer, createWsTransport } from 'archetype-ecs-net'
+
+// Default
+const server = createNetServer(em, registry, { port: 9001 })
+
+// Custom transport
+const server = createNetServer(em, registry, { port: 9001 }, myTransport)
+```
+
+```ts
+interface ServerTransport {
+  start(port: number, handlers: TransportHandlers): Promise<void>
+  stop(): Promise<void>
+  send(clientId: ClientId, data: ArrayBuffer): void
+  broadcast(data: ArrayBuffer): void
+}
+```
+
+---
+
+### Example
+
+**[RPG demo](example/)** — Full RPG with interest management, pathfinding, chunk-based visibility
+
+```bash
+npm run build                          # build dist/ for browser imports
+npx tsx example/server/main.ts         # start server
+# open example/client.html in browser (serve from project root)
+```
+
+---
+
+## Benchmarks
+
+1M entities across 4 archetypes (Players 50k/6c, Projectiles 250k/3c, NPCs 100k/5c, Static 600k/2c), 6 registered components, 3 game systems per tick. Termux/Android (aarch64):
+
+| Test | ms/frame | overhead | wire |
+|---|---:|---:|---:|
+| Raw game tick (1M, 4 archetypes) | 3.51 | baseline | |
+| + diffAndEncode (4k networked, 1%) | 5.59 | +2.08ms | 97 KB |
+| + diffAndEncode (40k networked, 10%) | 23.96 | +20.45ms | 995 KB |
+
+`diffAndEncode()` diffs and encodes in a single fused pass — no intermediate allocations, varint netIds, updates grouped per entity. At 1% networked (4k entities), the total overhead is 2.1ms — well within a 60fps budget.
+
+Run them yourself:
+
+```bash
+npx tsx bench/net-bench.ts
+```
+
+---
+
+## API reference
+
+### `createComponentRegistry(registrations)`
+
+Create a registry mapping components to wire IDs. Must be identical on server and client.
+
+### `Networked`
+
+Tag component. Add to any entity that should be synced over the network.
+
+### `createNetServer(em, registry, config, transport?)`
+
+Create a network server that diffs and broadcasts on every `tick()`.
+
+| Method / Property | Description |
+|---|---|
+| `start()` | Start listening on configured port |
+| `stop()` | Stop server, disconnect all clients |
+| `tick(filter?)` | Diff → encode → send. No filter = broadcast. With filter = per-client interest |
+| `send(clientId, data)` | Send a custom message to a specific client |
+| `clientCount` | Number of connected clients |
+| `entityNetIds` | `ReadonlyMap<EntityId, number>` — entity → netId mapping |
+| `onConnect` | Callback when client connects (receives full state) |
+| `onDisconnect` | Callback when client disconnects |
+| `onMessage` | Callback when client sends a message |
+
+The `filter` parameter is an `InterestFilter: (clientId) => ReadonlySet<number>` that returns the set of netIds visible to that client. Entities entering/leaving a client's interest set are sent as creates/destroys.
+
+### `createNetClient(em, registry)`
+
+Create a client that connects via WebSocket and auto-applies received state.
+
+| Method / Property | Description |
+|---|---|
+| `connect(url)` | Connect to server |
+| `disconnect()` | Close connection |
+| `connected` | Whether currently connected |
+| `onConnected` | Callback on successful connection |
+| `onDisconnected` | Callback on disconnect |
+
+---
+
+## License
+
+MIT

package/dist/ComponentRegistry.d.ts

@@ -0,0 +1,14 @@
+import type { ComponentRegistration, RegisteredComponent } from './types.js';
+export interface ComponentRegistry {
+    /** All registered components in wire ID order */
+    readonly components: readonly RegisteredComponent[];
+    /** Deterministic 32-bit hash of the registry schema (names + field names + types) */
+    readonly hash: number;
+    /** Look up by wire ID */
+    byWireId(id: number): RegisteredComponent | undefined;
+    /** Look up by component symbol */
+    bySymbol(sym: symbol): RegisteredComponent | undefined;
+    /** Look up by wire name */
+    byName(name: string): RegisteredComponent | undefined;
+}
+export declare function createComponentRegistry(registrations: ComponentRegistration[]): ComponentRegistry;

package/dist/ComponentRegistry.js

@@ -0,0 +1,90 @@
+import { componentSchemas } from 'archetype-ecs';
+// Maps TypedArray constructors back to wire type strings
+const CTOR_TO_TYPE = new Map([
+    [Float32Array, 'f32'],
+    [Float64Array, 'f64'],
+    [Int8Array, 'i8'],
+    [Int16Array, 'i16'],
+    [Int32Array, 'i32'],
+    [Uint8Array, 'u8'],
+    [Uint16Array, 'u16'],
+    [Uint32Array, 'u32'],
+    [Array, 'string'],
+]);
+const TYPE_BYTE_SIZE = {
+    f32: 4, f64: 8,
+    i8: 1, i16: 2, i32: 4,
+    u8: 1, u16: 2, u32: 4,
+    string: 0, // variable length
+};
+/** Simple FNV-1a 32-bit hash */
+function fnv1a(str) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < str.length; i++) {
+        h ^= str.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return h >>> 0;
+}
+export function createComponentRegistry(registrations) {
+    if (registrations.length > 255) {
+        throw new Error(`Max 255 networked components (got ${registrations.length})`);
+    }
+    const components = [];
+    const byWireIdMap = new Map();
+    const bySymbolMap = new Map();
+    const byNameMap = new Map();
+    for (let i = 0; i < registrations.length; i++) {
+        const reg = registrations[i];
+        const sym = reg.component._sym;
+        const schema = componentSchemas.get(sym);
+        const fields = [];
+        if (schema) {
+            for (const [fieldName, Ctor] of Object.entries(schema)) {
+                const wireType = CTOR_TO_TYPE.get(Ctor);
+                if (!wireType)
+                    throw new Error(`Unknown constructor for field "${fieldName}" in "${reg.name}"`);
+                fields.push({
+                    name: fieldName,
+                    type: wireType,
+                    byteSize: TYPE_BYTE_SIZE[wireType],
+                });
+            }
+        }
+        if (fields.length > 16) {
+            throw new Error(`Component "${reg.name}" has ${fields.length} fields (max 16 for u16 field bitmask)`);
+        }
+        const entry = {
+            wireId: i,
+            name: reg.name,
+            component: reg.component,
+            fields,
+        };
+        components.push(entry);
+        byWireIdMap.set(i, entry);
+        bySymbolMap.set(sym, entry);
+        byNameMap.set(reg.name, entry);
+    }
+    // Validate wireIds are sequential (defensive against future refactoring)
+    for (let i = 0; i < components.length; i++) {
+        if (components[i].wireId !== i) {
+            throw new Error(`Internal error: wireId mismatch at index ${i} (expected ${i}, got ${components[i].wireId})`);
+        }
+    }
+    // Build deterministic schema fingerprint: "name:field1:type1,field2:type2;..."
+    let schemaStr = '';
+    for (const c of components) {
+        schemaStr += c.name + ':';
+        for (const f of c.fields)
+            schemaStr += f.name + ':' + f.type + ',';
+        schemaStr += ';';
+    }
+    const hash = fnv1a(schemaStr);
+    return {
+        components,
+        hash,
+        byWireId: (id) => byWireIdMap.get(id),
+        bySymbol: (sym) => bySymbolMap.get(sym),
+        byName: (name) => byNameMap.get(name),
+    };
+}

package/dist/DirtyTracker.d.ts

@@ -0,0 +1,47 @@
+import type { EntityId, EntityManager, ComponentType } from 'archetype-ecs';
+import type { ComponentRegistry } from './ComponentRegistry.js';
+import { ProtocolEncoder } from './Protocol.js';
+import type { ClientDelta } from './InterestManager.js';
+/** Tag component — add to any entity that should be synced over the network */
+export declare const Networked: ComponentType;
+export interface CreatedEntry {
+    readonly netId: number;
+    readonly entityId: EntityId;
+}
+export interface DirtyEntry {
+    readonly netId: number;
+    readonly entityId: EntityId;
+    /** Per-wireId dirty field bitmask (copy, safe to read after compute) */
+    readonly dirtyMasks: Uint16Array;
+}
+export interface Changeset {
+    readonly created: readonly CreatedEntry[];
+    readonly destroyed: readonly number[];
+    readonly dirty: readonly DirtyEntry[];
+    /** Fast lookup sets for created/destroyed netIds */
+    readonly createdSet: ReadonlySet<number>;
+    readonly destroyedSet: ReadonlySet<number>;
+}
+export interface EntityCache {
+    /** Pre-encoded bytes for entity enters (varint netId + full component data) */
+    readonly enterSlices: ReadonlyMap<number, Uint8Array>;
+    /** Pre-encoded bytes for dirty entity updates (varint netId + dirty components) */
+    readonly updateSlices: ReadonlyMap<number, Uint8Array>;
+}
+export interface SnapshotDiffer {
+    /** Diff + encode in a single pass — avoids intermediate allocations (broadcast mode) */
+    diffAndEncode(encoder: ProtocolEncoder): ArrayBuffer;
+    /** Phase 1: compute what changed this tick (run once, then encode per client) */
+    computeChangeset(): Changeset;
+    /** Pre-encode all entities in a changeset into cached byte slices (1× per tick) */
+    preEncodeChangeset(encoder: ProtocolEncoder, changeset: Changeset, extraEnterNetIds: Iterable<number>): EntityCache;
+    /** Compose a per-client delta buffer from pre-encoded cache (fast memcpy path) */
+    composeFromCache(encoder: ProtocolEncoder, cache: EntityCache, clientDelta: ClientDelta): ArrayBuffer;
+    /** Flush snapshot buffers. Must call after all encoding is done when using computeChangeset(). */
+    flushSnapshots(): void;
+    /** Current mapping of entityId → netId for all tracked entities */
+    readonly entityNetIds: ReadonlyMap<EntityId, number>;
+    /** Reverse mapping of netId → entityId */
+    readonly netIdToEntity: ReadonlyMap<number, EntityId>;
+}
+export declare function createSnapshotDiffer(em: EntityManager, registry: ComponentRegistry): SnapshotDiffer;