murow 0.0.1

package/src/protocol/intent/intent.ts

@@ -0,0 +1,12 @@
+/**
+ * Base interface for all game intents.
+ *
+ * Intents represent player or AI actions that need to be processed by the game simulation.
+ * They are timestamped with a tick number for deterministic replay and synchronization.
+ */
+export interface Intent {
+  /** The game tick at which this intent should be processed */
+  tick: number;
+  /** Numeric identifier for the intent type (used for codec lookup) */
+  kind: number;
+}

package/src/protocol/snapshot/index.ts

@@ -0,0 +1,45 @@
+/**
+ * Snapshot system for server-to-client state updates.
+ *
+ * Snapshots are delta updates that contain:
+ * 1. Server tick number
+ * 2. Partial state updates (only what changed)
+ *
+ * They need to be:
+ * 1. Encoded efficiently (binary)
+ * 2. Sent over network
+ * 3. Decoded on the client
+ * 4. Merged into client state
+ *
+ * @example
+ * ```ts
+ * import { Snapshot, SnapshotCodec, applySnapshot } from './protocol/snapshot';
+ * import { PooledCodec } from '../core/pooled-codec';
+ * import { BinaryCodec } from '../core/binary-codec';
+ *
+ * interface GameState {
+ *   players: Record<number, { x: number; y: number }>;
+ * }
+ *
+ * // 1. Create codec once (reuse this instance)
+ * const snapshotCodec = new SnapshotCodec<GameState>(
+ *   new PooledCodec({ players: // ... your schema })
+ * );
+ *
+ * // 2. Server: Encode snapshot
+ * const snapshot: Snapshot<GameState> = {
+ *   tick: 100,
+ *   updates: { players: { 1: { x: 5, y: 10 } } }
+ * };
+ * const buf = snapshotCodec.encode(snapshot);
+ *
+ * // 3. Client: Decode and apply
+ * const snapshot = snapshotCodec.decode(buf);
+ * applySnapshot(clientState, snapshot);
+ * ```
+ */
+
+export type { Snapshot } from "./snapshot";
+export { applySnapshot } from "./snapshot";
+export { SnapshotCodec } from "./snapshot-codec";
+export { SnapshotRegistry } from "./snapshot-registry";

package/src/protocol/snapshot/snapshot-codec.test.ts

@@ -0,0 +1,138 @@
+import { describe, it, expect } from "bun:test";
+import { SnapshotCodec } from "./snapshot-codec";
+import { Snapshot } from "./snapshot";
+import { Codec } from "./snapshot-codec";
+
+// Simple mock codec for testing
+class MockCodec<T> implements Codec<T> {
+  encode(value: T): Uint8Array {
+    const json = JSON.stringify(value);
+    return new TextEncoder().encode(json);
+  }
+
+  decode(buf: Uint8Array): T {
+    const json = new TextDecoder().decode(buf);
+    return JSON.parse(json);
+  }
+}
+
+interface TestState {
+  x: number;
+  y: number;
+  health?: number;
+}
+
+describe("SnapshotCodec", () => {
+  it("should encode and decode a snapshot", () => {
+    const codec = new SnapshotCodec<TestState>(new MockCodec());
+    const snapshot: Snapshot<TestState> = {
+      tick: 100,
+      updates: { x: 10, y: 20 },
+    };
+
+    const buf = codec.encode(snapshot);
+    const decoded = codec.decode(buf);
+
+    expect(decoded.tick).toBe(100);
+    expect(decoded.updates.x).toBe(10);
+    expect(decoded.updates.y).toBe(20);
+  });
+
+  it("should handle partial updates", () => {
+    const codec = new SnapshotCodec<TestState>(new MockCodec());
+    const snapshot: Snapshot<TestState> = {
+      tick: 50,
+      updates: { x: 5 },
+    };
+
+    const buf = codec.encode(snapshot);
+    const decoded = codec.decode(buf);
+
+    expect(decoded.tick).toBe(50);
+    expect(decoded.updates.x).toBe(5);
+    expect(decoded.updates.y).toBeUndefined();
+  });
+
+  it("should handle large tick numbers", () => {
+    const codec = new SnapshotCodec<TestState>(new MockCodec());
+    const snapshot: Snapshot<TestState> = {
+      tick: 4294967295, // Max u32
+      updates: { x: 1, y: 2 },
+    };
+
+    const buf = codec.encode(snapshot);
+    const decoded = codec.decode(buf);
+
+    expect(decoded.tick).toBe(4294967295);
+  });
+
+  it("should preserve tick in binary format", () => {
+    const codec = new SnapshotCodec<TestState>(new MockCodec());
+    const snapshot: Snapshot<TestState> = {
+      tick: 12345,
+      updates: { x: 1 },
+    };
+
+    const buf = codec.encode(snapshot);
+
+    // First 4 bytes should be the tick (little-endian)
+    const tick = new DataView(buf.buffer, buf.byteOffset).getUint32(0, true);
+    expect(tick).toBe(12345);
+  });
+
+  it("should handle empty updates", () => {
+    const codec = new SnapshotCodec<TestState>(new MockCodec());
+    const snapshot: Snapshot<TestState> = {
+      tick: 100,
+      updates: {},
+    };
+
+    const buf = codec.encode(snapshot);
+    const decoded = codec.decode(buf);
+
+    expect(decoded.tick).toBe(100);
+    expect(decoded.updates).toEqual({});
+  });
+
+  it("should handle nested state", () => {
+    interface NestedState {
+      player: {
+        position: { x: number; y: number };
+        health: number;
+      };
+    }
+
+    const codec = new SnapshotCodec<NestedState>(new MockCodec());
+    const snapshot: Snapshot<NestedState> = {
+      tick: 200,
+      updates: {
+        player: {
+          position: { x: 10, y: 20 },
+          health: 80,
+        },
+      },
+    };
+
+    const buf = codec.encode(snapshot);
+    const decoded = codec.decode(buf);
+
+    expect(decoded.tick).toBe(200);
+    expect(decoded.updates.player?.position.x).toBe(10);
+    expect(decoded.updates.player?.position.y).toBe(20);
+    expect(decoded.updates.player?.health).toBe(80);
+  });
+
+  it("should round-trip multiple times", () => {
+    const codec = new SnapshotCodec<TestState>(new MockCodec());
+    const original: Snapshot<TestState> = {
+      tick: 999,
+      updates: { x: 123, y: 456, health: 78 },
+    };
+
+    for (let i = 0; i < 10; i++) {
+      const buf = codec.encode(original);
+      const decoded = codec.decode(buf);
+      expect(decoded).toEqual(original);
+    }
+  });
+});

package/src/protocol/snapshot/snapshot-codec.ts

@@ -0,0 +1,71 @@
+import type { Snapshot } from "./snapshot";
+
+/**
+ * Generic codec interface (users import from core/pooled-codec)
+ */
+export interface Codec<T> {
+  encode(value: T): Uint8Array;
+  decode(buf: Uint8Array): T;
+}
+
+/**
+ * Codec for encoding/decoding snapshots with binary serialization.
+ *
+ * Users instantiate this once with a PooledCodec for their state schema.
+ *
+ * @example
+ * ```ts
+ * import { SnapshotCodec } from './protocol/snapshot';
+ * import { PooledCodec } from './core/pooled-codec';
+ * import { BinaryCodec } from './core/binary-codec';
+ *
+ * interface GameState {
+ *   players: Record<number, { x: number; y: number }>;
+ * }
+ *
+ * const snapshotCodec = new SnapshotCodec<GameState>(
+ *   new PooledCodec({ players: // schema })
+ * );
+ *
+ * // Encode/decode
+ * const buf = snapshotCodec.encode(snapshot);
+ * const decoded = snapshotCodec.decode(buf);
+ * ```
+ */
+export class SnapshotCodec<T> {
+  /**
+   * @param updatesCodec Codec for encoding/decoding the state updates
+   */
+  constructor(private updatesCodec: Codec<Partial<T>>) {}
+
+  /**
+   * Encode a snapshot into binary format.
+   * Format: [tick: u32][updates: encoded by updatesCodec]
+   */
+  encode(snapshot: Snapshot<T>): Uint8Array {
+    const updatesBytes = this.updatesCodec.encode(snapshot.updates);
+    const buf = new Uint8Array(4 + updatesBytes.length);
+
+    // Encode tick (4 bytes, little-endian)
+    new DataView(buf.buffer).setUint32(0, snapshot.tick, true);
+
+    // Encode updates
+    buf.set(updatesBytes, 4);
+
+    return buf;
+  }
+
+  /**
+   * Decode binary data into a snapshot.
+   */
+  decode(buf: Uint8Array): Snapshot<T> {
+    // Decode tick (first 4 bytes)
+    const tick = new DataView(buf.buffer, buf.byteOffset).getUint32(0, true);
+
+    // Decode updates (remaining bytes)
+    const updatesBytes = buf.subarray(4);
+    const updates = this.updatesCodec.decode(updatesBytes);
+
+    return { tick, updates };
+  }
+}

package/src/protocol/snapshot/snapshot-registry.test.ts

@@ -0,0 +1,302 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { SnapshotRegistry } from "./snapshot-registry";
+import { Snapshot } from "./snapshot";
+
+// Mock codec for testing
+class MockCodec<T> {
+  encode(value: T): Uint8Array {
+    const json = JSON.stringify(value);
+    return new TextEncoder().encode(json);
+  }
+
+  decode(buf: Uint8Array): T {
+    const json = new TextDecoder().decode(buf);
+    return JSON.parse(json);
+  }
+}
+
+// Test update types
+interface PlayerUpdate {
+  players: Array<{ entityId: number; x: number; y: number }>;
+}
+
+interface ScoreUpdate {
+  score: number;
+}
+
+interface ProjectileUpdate {
+  projectiles: Array<{ id: number; x: number; y: number }>;
+}
+
+type GameUpdate = PlayerUpdate | ScoreUpdate | ProjectileUpdate;
+
+describe("SnapshotRegistry", () => {
+  let registry: SnapshotRegistry<GameUpdate>;
+
+  beforeEach(() => {
+    registry = new SnapshotRegistry<GameUpdate>();
+  });
+
+  describe("register", () => {
+    it("should register a codec for a snapshot type", () => {
+      registry.register("players", new MockCodec<PlayerUpdate>());
+      expect(registry.has("players")).toBe(true);
+    });
+
+    it("should throw error when registering duplicate type", () => {
+      registry.register("players", new MockCodec<PlayerUpdate>());
+      expect(() => registry.register("players", new MockCodec<PlayerUpdate>())).toThrow(
+        'Snapshot type "players" is already registered'
+      );
+    });
+
+    it("should allow registering multiple types", () => {
+      registry.register("players", new MockCodec<PlayerUpdate>());
+      registry.register("score", new MockCodec<ScoreUpdate>());
+      registry.register("projectiles", new MockCodec<ProjectileUpdate>());
+
+      expect(registry.has("players")).toBe(true);
+      expect(registry.has("score")).toBe(true);
+      expect(registry.has("projectiles")).toBe(true);
+    });
+  });
+
+  describe("encode", () => {
+    beforeEach(() => {
+      registry.register("players", new MockCodec<PlayerUpdate>());
+      registry.register("score", new MockCodec<ScoreUpdate>());
+    });
+
+    it("should encode a snapshot with type ID", () => {
+      const snapshot: Snapshot<PlayerUpdate> = {
+        tick: 100,
+        updates: {
+          players: [
+            { entityId: 1, x: 10, y: 20 },
+          ],
+        },
+      };
+
+      const buf = registry.encode("players", snapshot);
+
+      expect(buf).toBeInstanceOf(Uint8Array);
+      expect(buf.length).toBeGreaterThan(5); // type(1) + tick(4) + data
+      expect(buf[0]).toBe(0); // First registered type gets ID 0
+    });
+
+    it("should encode different types with different type IDs", () => {
+      const playerSnapshot: Snapshot<PlayerUpdate> = {
+        tick: 100,
+        updates: { players: [{ entityId: 1, x: 10, y: 20 }] },
+      };
+
+      const scoreSnapshot: Snapshot<ScoreUpdate> = {
+        tick: 101,
+        updates: { score: 50 },
+      };
+
+      const buf1 = registry.encode("players", playerSnapshot);
+      const buf2 = registry.encode("score", scoreSnapshot);
+
+      expect(buf1[0]).toBe(0); // players = ID 0
+      expect(buf2[0]).toBe(1); // score = ID 1
+    });
+
+    it("should throw error when encoding unregistered type", () => {
+      const snapshot: Snapshot<ProjectileUpdate> = {
+        tick: 100,
+        updates: { projectiles: [] },
+      };
+
+      expect(() => registry.encode("projectiles", snapshot)).toThrow(
+        'No codec registered for snapshot type "projectiles"'
+      );
+    });
+
+    it("should preserve tick number in encoding", () => {
+      const snapshot: Snapshot<ScoreUpdate> = {
+        tick: 12345,
+        updates: { score: 100 },
+      };
+
+      const buf = registry.encode("score", snapshot);
+
+      // Tick is at bytes 1-4 (after type ID)
+      const tick = new DataView(buf.buffer, buf.byteOffset + 1).getUint32(0, true);
+      expect(tick).toBe(12345);
+    });
+  });
+
+  describe("decode", () => {
+    beforeEach(() => {
+      registry.register("players", new MockCodec<PlayerUpdate>());
+      registry.register("score", new MockCodec<ScoreUpdate>());
+    });
+
+    it("should decode a snapshot and return type", () => {
+      const original: Snapshot<PlayerUpdate> = {
+        tick: 100,
+        updates: {
+          players: [
+            { entityId: 1, x: 10, y: 20 },
+          ],
+        },
+      };
+
+      const buf = registry.encode("players", original);
+      const { type, snapshot } = registry.decode(buf);
+
+      expect(type).toBe("players");
+      expect(snapshot.tick).toBe(100);
+      expect(snapshot.updates).toEqual(original.updates);
+    });
+
+    it("should decode different snapshot types correctly", () => {
+      const playerSnapshot: Snapshot<PlayerUpdate> = {
+        tick: 100,
+        updates: { players: [{ entityId: 1, x: 10, y: 20 }] },
+      };
+
+      const scoreSnapshot: Snapshot<ScoreUpdate> = {
+        tick: 101,
+        updates: { score: 50 },
+      };
+
+      const buf1 = registry.encode("players", playerSnapshot);
+      const buf2 = registry.encode("score", scoreSnapshot);
+
+      const decoded1 = registry.decode(buf1);
+      const decoded2 = registry.decode(buf2);
+
+      expect(decoded1.type).toBe("players");
+      expect(decoded1.snapshot.updates).toEqual(playerSnapshot.updates);
+
+      expect(decoded2.type).toBe("score");
+      expect(decoded2.snapshot.updates).toEqual(scoreSnapshot.updates);
+    });
+
+    it("should throw error when decoding unknown type ID", () => {
+      const buf = new Uint8Array([99, 0, 0, 0, 100]); // Unknown type ID 99
+
+      expect(() => registry.decode(buf)).toThrow("Unknown snapshot type ID: 99");
+    });
+  });
+
+  describe("round-trip encoding/decoding", () => {
+    beforeEach(() => {
+      registry.register("players", new MockCodec<PlayerUpdate>());
+      registry.register("score", new MockCodec<ScoreUpdate>());
+      registry.register("projectiles", new MockCodec<ProjectileUpdate>());
+    });
+
+    it("should preserve data through encode/decode cycle", () => {
+      const original: Snapshot<PlayerUpdate> = {
+        tick: 500,
+        updates: {
+          players: [
+            { entityId: 1, x: 100, y: 200 },
+            { entityId: 2, x: 300, y: 400 },
+          ],
+        },
+      };
+
+      const buf = registry.encode("players", original);
+      const { type, snapshot } = registry.decode(buf);
+
+      expect(type).toBe("players");
+      expect(snapshot).toEqual(original);
+    });
+
+    it("should handle multiple round-trips", () => {
+      const original: Snapshot<ScoreUpdate> = {
+        tick: 1000,
+        updates: { score: 99999 },
+      };
+
+      for (let i = 0; i < 10; i++) {
+        const buf = registry.encode("score", original);
+        const { type, snapshot } = registry.decode(buf);
+        expect(type).toBe("score");
+        expect(snapshot).toEqual(original);
+      }
+    });
+
+    it("should handle arrays in updates", () => {
+      const original: Snapshot<ProjectileUpdate> = {
+        tick: 250,
+        updates: {
+          projectiles: [
+            { id: 1, x: 10, y: 20 },
+            { id: 2, x: 30, y: 40 },
+            { id: 3, x: 50, y: 60 },
+          ],
+        },
+      };
+
+      const buf = registry.encode("projectiles", original);
+      const { type, snapshot } = registry.decode(buf);
+
+      expect(type).toBe("projectiles");
+      expect(snapshot.updates).toEqual(original.updates);
+    });
+  });
+
+  describe("getTypes", () => {
+    it("should return empty array when no types registered", () => {
+      expect(registry.getTypes()).toEqual([]);
+    });
+
+    it("should return all registered types", () => {
+      registry.register("players", new MockCodec<PlayerUpdate>());
+      registry.register("score", new MockCodec<ScoreUpdate>());
+
+      const types = registry.getTypes();
+      expect(types).toContain("players");
+      expect(types).toContain("score");
+      expect(types.length).toBe(2);
+    });
+  });
+
+  describe("integration scenarios", () => {
+    beforeEach(() => {
+      registry.register("players", new MockCodec<PlayerUpdate>());
+      registry.register("score", new MockCodec<ScoreUpdate>());
+    });
+
+    it("should allow sending only specific updates", () => {
+      // Server only sends player updates this tick
+      const playerBuf = registry.encode("players", {
+        tick: 100,
+        updates: { players: [{ entityId: 1, x: 5, y: 10 }] },
+      });
+
+      // Next tick, only send score
+      const scoreBuf = registry.encode("score", {
+        tick: 101,
+        updates: { score: 100 },
+      });
+
+      // Client can decode both
+      const decoded1 = registry.decode(playerBuf);
+      const decoded2 = registry.decode(scoreBuf);
+
+      expect(decoded1.type).toBe("players");
+      expect(decoded2.type).toBe("score");
+    });
+
+    it("should maintain type safety with unions", () => {
+      const snapshot: Snapshot<PlayerUpdate> = {
+        tick: 100,
+        updates: { players: [{ entityId: 1, x: 5, y: 10 }] },
+      };
+
+      const buf = registry.encode("players", snapshot);
+      const { type, snapshot: decoded } = registry.decode(buf);
+
+      // Type narrowing based on type field
+      if (type === "players") {
+        expect(decoded.updates.players).toBeDefined();
+      }
+    });
+  });
+});