@voicethere/agent 0.5.3 → 0.5.5

package/templates/game-sync.ts

@@ -2,393 +2,575 @@
  * Multiplayer object-sync template with ownership checks.
  *
  * World layout:
- * - one global Float32Array
+ * - one global Float32Array (fixed MAX_LIVE_OBJECTS slots when Redis is enabled)
  * - each tracked object uses exactly 9 floats:
  *   [objectId, posX, posY, posZ, posW, dirX, dirY, dirZ, dirW]
  *
+ * With project Redis (`AGENT_REDIS_URL`), the world blob is shared across runner
+ * workers (key `game-sync:world`). World writes (allocate/release Lua, sim SET)
+ * serialize on `game-sync:sim-lock`; one holder runs physics per tick.
+ *
  * Control messages:
  * - `{ type: "register" }` -> allocates (or reuses) one 9-float slot
  * - server replies `{ type: "register_ack", objectId }`
+ * - `{ type: "register_nack", reason: "world_full", maxObjects: 25 }` when cap reached
+ * - `{ type: "remove", objectId }` or `{ type: "unregister", objectId?: number }` ->
+ *   zeros that live slot (objectId required for click-to-remove; omit objectId on
+ *   unregister to drop the highest object owned by this session)
+ * - `{ type: "unregister_ack", objectId }` or `{ type: "unregister_nack", reason }`
  *
  * Simulation:
  * - server-authoritative movement at 60Hz
  * - wall bounce + object-object elastic collisions on server
  * - clients render server snapshots; client binary writes are ignored
+ * - with project Redis, the sim loop keeps running with zero connected clients so
+ *   objects persist and keep moving after everyone disconnects
  *
  * Broadcast:
- * - 60Hz world-state broadcast starts when at least 1 client is connected
- * - stops when connected client count drops below 1
+ * - 60Hz world-state broadcast while the sim loop runs (no-op send when 0 sessions)
  *
  * Build:
  *   npx @voicethere/agent build --entry templates/game-sync.ts
  */
+import Redis from "ioredis";
 import {
-    agentLog,
-    defineAgent,
-    sendBinaryToClient,
-    sendToClient,
+  agentLog,
+  defineAgent,
+  sendBinaryToClient,
+  sendToClient,
 } from "@voicethere/agent";
 
-const OBJECT_STRIDE = 9;
+import {
+  MAX_LIVE_OBJECTS,
+  parseChatCommand,
+  parseRegisterCommand,
+  parseUnregisterCommand,
+  resolveRemoveTarget,
+  REGISTER_NACK_REASON_WORLD_FULL,
+  UNREGISTER_NACK_REASON_NOT_FOUND,
+} from "./game-sync-protocol.js";
+import {
+  LUA_ALLOCATE_OBJECT,
+  LUA_RELEASE_OBJECT,
+  REDIS_EVAL_KEYS,
+} from "./game-sync-redis.js";
+import {
+  BOARD_HEIGHT,
+  BOARD_WIDTH,
+  OBJECT_RADIUS,
+  simulateWorldStep,
+} from "./game-sync-sim.js";
+import {
+  collectActiveObjectIds,
+  commitSimulatedWorld,
+  countLiveObjects,
+  createEmptyWorldBuffer,
+  findFirstEmptySlot,
+  markSlotFree,
+  normalizeWorldBuffer,
+  objectIdToSlot,
+  OBJECT_SLOT_BYTE_LENGTH,
+  REDIS_SIM_LOCK_KEY,
+  REDIS_WORLD_KEY,
+  slotToObjectId,
+  writeObjectSlot,
+} from "./game-sync-world-layout.js";
+
 const BROADCAST_HZ = 60;
 const BROADCAST_INTERVAL_MS = Math.floor(1000 / BROADCAST_HZ);
-const BOARD_WIDTH = 1280;
-const BOARD_HEIGHT = 720;
-const OBJECT_RADIUS = 25;
+const SIM_LOCK_TTL_MS = BROADCAST_INTERVAL_MS * 2;
+const SIM_LOCK_RETRY_MS = 5;
 const MIN_SPEED = 90;
 const MAX_SPEED = 180;
-const COLLISION_RESTITUTION = 1.0;
 
 const connectedSessions = new Set<string>();
-const objectOwners = new Map<number, string>(); // objectId -> sessionId
-const sessionObjects = new Map<string, Set<number>>(); // sessionId -> owned objectIds
-// Slots we can recycle. Keeping a free-list avoids unbounded array growth when
-// clients churn (join/leave repeatedly).
+const objectOwners = new Map<number, string>();
+const sessionObjects = new Map<string, Set<number>>();
 const freeSlots: number[] = [];
 
-let worldState = new Float32Array(0);
+let worldState = createEmptyWorldBuffer();
+let redis: Redis | null = null;
 let broadcastTimer: NodeJS.Timeout | null = null;
+let worldMutationChain: Promise<void> = Promise.resolve();
+
+function withWorldMutation<T>(fn: () => Promise<T>): Promise<T> {
+  const run = worldMutationChain.then(fn);
+  worldMutationChain = run.then(
+    () => undefined,
+    () => undefined,
+  );
+  return run;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+async function withRedisSimLock<T>(
+  fn: () => Promise<T>,
+  options?: { retryUntilAcquired?: boolean },
+): Promise<T | null> {
+  if (!redis) {
+    return fn();
+  }
+
+  const retryUntilAcquired = options?.retryUntilAcquired ?? true;
+
+  while (true) {
+    const lockAcquired = await redis.set(
+      REDIS_SIM_LOCK_KEY,
+      "1",
+      "PX",
+      SIM_LOCK_TTL_MS,
+      "NX",
+    );
+    if (lockAcquired === "OK") {
+      try {
+        return await fn();
+      } finally {
+        await redis.del(REDIS_SIM_LOCK_KEY);
+      }
+    }
+    if (!retryUntilAcquired) {
+      return null;
+    }
+    await sleep(SIM_LOCK_RETRY_MS);
+  }
+}
 
 interface TrackedObjectInfo {
-    objectId: number;
-    ownerSessionId: string;
+  objectId: number;
+  ownerSessionId: string;
 }
 
 function rand(min: number, max: number): number {
-    return min + Math.random() * (max - min);
+  return min + Math.random() * (max - min);
 }
 
 function randomVelocity(): number {
-    return (Math.random() < 0.5 ? -1 : 1) * rand(MIN_SPEED, MAX_SPEED);
+  return (Math.random() < 0.5 ? -1 : 1) * rand(MIN_SPEED, MAX_SPEED);
 }
 
-function slotToObjectId(slot: number): number {
-    // Object ids are 1-based so 0 can represent "unused".
-    return slot + 1;
+function randomInitialTail(): Buffer {
+  const floats = new Float32Array([
+    rand(OBJECT_RADIUS, BOARD_WIDTH - OBJECT_RADIUS),
+    rand(OBJECT_RADIUS, BOARD_HEIGHT - OBJECT_RADIUS),
+    0,
+    1,
+    randomVelocity(),
+    randomVelocity(),
+    0,
+    0,
+  ]);
+  return Buffer.from(floats.buffer, floats.byteOffset, floats.byteLength);
 }
 
-function objectIdToSlot(objectId: number): number {
-    // Inverse of slotToObjectId().
-    return objectId - 1;
+function attachObjectToSession(sessionId: string, objectId: number): void {
+  let owned = sessionObjects.get(sessionId);
+  if (!owned) {
+    owned = new Set<number>();
+    sessionObjects.set(sessionId, owned);
+  }
+  owned.add(objectId);
+  objectOwners.set(objectId, sessionId);
 }
 
-function markSlotFree(slot: number): void {
-    // Zero the entire record. Slot is still allocated in array length terms,
-    // but logically available for reuse.
-    const start = slot * OBJECT_STRIDE;
-    for (let i = 0; i < OBJECT_STRIDE; i += 1) {
-        worldState[start + i] = 0;
+function detachObjectFromSession(objectId: number): void {
+  const owner = objectOwners.get(objectId);
+  if (owner) {
+    const owned = sessionObjects.get(owner);
+    owned?.delete(objectId);
+    if (owned && owned.size === 0) {
+      sessionObjects.delete(owner);
     }
+  }
+  objectOwners.delete(objectId);
 }
 
-function allocateSlot(): number {
-    // Prefer recycling old slots before growing worldState.
-    const reused = freeSlots.shift();
-    if (reused !== undefined) return reused;
+function allocateSlotInMemory(): number | null {
+  if (countLiveObjects(worldState) >= MAX_LIVE_OBJECTS) {
+    return null;
+  }
 
-    // Grow by exactly one object record (9 floats).
-    const next = new Float32Array(worldState.length + OBJECT_STRIDE);
-    next.set(worldState);
-    worldState = next;
-    return worldState.length / OBJECT_STRIDE - 1;
-}
+  const reused = freeSlots.shift();
+  if (reused !== undefined) {
+    return reused;
+  }
 
-function attachObjectToSession(sessionId: string, objectId: number): void {
-    // Tracks ownership in both directions so validation and cleanup are O(1).
-    let owned = sessionObjects.get(sessionId);
-    if (!owned) {
-        owned = new Set<number>();
-        sessionObjects.set(sessionId, owned);
-    }
-    owned.add(objectId);
-    objectOwners.set(objectId, sessionId);
+  return findFirstEmptySlot(worldState);
 }
 
-function releaseObject(objectId: number): void {
-    // Remove reverse-ownership references first.
-    const owner = objectOwners.get(objectId);
-    if (owner) {
-        const owned = sessionObjects.get(owner);
-        owned?.delete(objectId);
-        if (owned && owned.size === 0) {
-            sessionObjects.delete(owner);
-        }
-    }
-
-    objectOwners.delete(objectId);
+function releaseObjectInMemory(objectId: number): void {
+  const slot = objectIdToSlot(objectId);
+  if (slot < 0 || slot >= MAX_LIVE_OBJECTS) return;
 
-    const slot = objectIdToSlot(objectId);
-    if (slot < 0) return;
-    if (slot >= worldState.length / OBJECT_STRIDE) return;
+  markSlotFree(worldState, slot);
+  if (!freeSlots.includes(slot)) {
+    freeSlots.push(slot);
+    freeSlots.sort((a, b) => a - b);
+  }
+}
 
-    // Free slot contents and push slot into free-list for future register() calls.
-    markSlotFree(slot);
-    if (!freeSlots.includes(slot)) {
-        freeSlots.push(slot);
-        freeSlots.sort((a, b) => a - b);
-    }
+function registerObjectInMemory(sessionId: string): number | null {
+  const slot = allocateSlotInMemory();
+  if (slot === null) {
+    return null;
+  }
+
+  const objectId = slotToObjectId(slot);
+  writeObjectSlot(
+    worldState,
+    slot,
+    objectId,
+    rand(OBJECT_RADIUS, BOARD_WIDTH - OBJECT_RADIUS),
+    rand(OBJECT_RADIUS, BOARD_HEIGHT - OBJECT_RADIUS),
+    0,
+    1,
+    randomVelocity(),
+    randomVelocity(),
+    0,
+    0,
+  );
+  attachObjectToSession(sessionId, objectId);
+  return objectId;
 }
 
-function registerObject(sessionId: string): number {
-    // Allocate (or reuse) one slot and stamp object id plus initial state.
-    const slot = allocateSlot();
-    const objectId = slotToObjectId(slot);
-    const start = slot * OBJECT_STRIDE;
-    worldState[start] = objectId;
-    worldState[start + 1] = rand(OBJECT_RADIUS, BOARD_WIDTH - OBJECT_RADIUS);
-    worldState[start + 2] = rand(OBJECT_RADIUS, BOARD_HEIGHT - OBJECT_RADIUS);
-    worldState[start + 3] = 0;
-    worldState[start + 4] = 1;
-    worldState[start + 5] = randomVelocity();
-    worldState[start + 6] = randomVelocity();
-    worldState[start + 7] = 0;
-    worldState[start + 8] = 0;
-    attachObjectToSession(sessionId, objectId);
-    return objectId;
+async function registerObjectInRedis(
+  sessionId: string,
+): Promise<number | null> {
+  if (!redis) {
+    return registerObjectInMemory(sessionId);
+  }
+
+  const result = await redis.eval(
+    LUA_ALLOCATE_OBJECT,
+    1,
+    REDIS_EVAL_KEYS.worldKey,
+    REDIS_EVAL_KEYS.worldByteLength,
+    REDIS_EVAL_KEYS.slotByteLength,
+    REDIS_EVAL_KEYS.maxSlots,
+    randomInitialTail(),
+    REDIS_EVAL_KEYS.headers,
+  );
+
+  const objectId = Number(result);
+  if (!Number.isFinite(objectId) || objectId < 1) {
+    return null;
+  }
+
+  attachObjectToSession(sessionId, objectId);
+  worldState = await loadWorldFromRedis();
+  return objectId;
 }
 
-function parseRegisterCommand(message: unknown): boolean {
-    if (!message || typeof message !== "object") return false;
-    const record = message as { type?: unknown };
-    return record.type === "register";
+async function releaseObjectInRedis(objectId: number): Promise<boolean> {
+  detachObjectFromSession(objectId);
+  if (!redis) {
+    releaseObjectInMemory(objectId);
+    return true;
+  }
+
+  const released = await redis.eval(
+    LUA_RELEASE_OBJECT,
+    1,
+    REDIS_EVAL_KEYS.worldKey,
+    REDIS_EVAL_KEYS.worldByteLength,
+    REDIS_EVAL_KEYS.slotByteLength,
+    REDIS_EVAL_KEYS.maxSlots,
+    String(objectId),
+    REDIS_EVAL_KEYS.headers,
+  );
+  if (Number(released) === 1) {
+    worldState = await loadWorldFromRedis();
+  }
+  return Number(released) === 1;
 }
 
-function parseChatCommand(
-    message: unknown,
-): { text: string } | null {
-    if (!message || typeof message !== "object") return null;
-    const record = message as { type?: unknown; text?: unknown };
-    if (record.type !== "chat" || typeof record.text !== "string") return null;
-    const text = record.text.trim();
-    if (!text) return null;
-    return {text};
+async function unregisterObject(
+  sessionId: string,
+  objectId?: number,
+): Promise<{ ok: true; objectId: number } | { ok: false; reason: string }> {
+  const owned = sessionObjects.get(sessionId);
+  const target = resolveRemoveTarget(objectId, owned);
+  if (!target.ok) {
+    return target;
+  }
+
+  const previousOwner = objectOwners.get(target.objectId) ?? sessionId;
+  notifyObjectReleased(target.objectId, previousOwner);
+  const released = await withWorldMutation(async () => {
+    if (!redis) {
+      return releaseObjectInRedis(target.objectId);
+    }
+    const result = await withRedisSimLock(() =>
+      releaseObjectInRedis(target.objectId),
+    );
+    return result === true;
+  });
+  if (!released) {
+    return { ok: false, reason: UNREGISTER_NACK_REASON_NOT_FOUND };
+  }
+  return { ok: true, objectId: target.objectId };
 }
 
 function trackedObjectsSnapshot(): TrackedObjectInfo[] {
-    const objects: TrackedObjectInfo[] = [];
-    for (const [objectId, ownerSessionId] of objectOwners) {
-        objects.push({objectId, ownerSessionId});
-    }
-    objects.sort((a, b) => a.objectId - b.objectId);
-    return objects;
+  const objects: TrackedObjectInfo[] = [];
+  for (const [objectId, ownerSessionId] of objectOwners) {
+    objects.push({ objectId, ownerSessionId });
+  }
+  objects.sort((a, b) => a.objectId - b.objectId);
+  return objects;
 }
 
-function notifyObjectRegistered(objectId: number, ownerSessionId: string): void {
-    for (const sessionId of connectedSessions) {
-        if (sessionId === ownerSessionId) continue;
-        sendToClient(sessionId, {
-            type: "object_registered",
-            objectId,
-            ownerSessionId,
-        });
-    }
+function notifyObjectRegistered(
+  objectId: number,
+  ownerSessionId: string,
+): void {
+  for (const sessionId of connectedSessions) {
+    if (sessionId === ownerSessionId) continue;
+    sendToClient(sessionId, {
+      type: "object_registered",
+      objectId,
+      ownerSessionId,
+    });
+  }
 }
 
 function notifyObjectReleased(objectId: number, ownerSessionId: string): void {
-    for (const sessionId of connectedSessions) {
-        if (sessionId === ownerSessionId) continue;
-        sendToClient(sessionId, {
-            type: "object_released",
-            objectId,
-            ownerSessionId,
-        });
-    }
+  for (const sessionId of connectedSessions) {
+    if (sessionId === ownerSessionId) continue;
+    sendToClient(sessionId, {
+      type: "object_released",
+      objectId,
+      ownerSessionId,
+    });
+  }
 }
 
-function broadcastWorldState(): void {
-    if (connectedSessions.size === 0) return;
-    // Copy to a detached buffer so downstream sends cannot observe mutations
-    // from subsequent writes in the same event loop tick.
-    const payload = Buffer.from(worldState.buffer.slice(0));
-    for (const sessionId of connectedSessions) {
-        sendBinaryToClient(sessionId, payload, "sync");
-    }
+function copyWorldBuffer(world: Float32Array): Buffer {
+  return Buffer.from(world.buffer, world.byteOffset, world.byteLength);
 }
 
-function simulateWorldStep(dtSec: number): void {
-    const activeObjectIds = [...objectOwners.keys()];
-    for (const objectId of activeObjectIds) {
-        const slot = objectIdToSlot(objectId);
-        const start = slot * OBJECT_STRIDE;
-        if (start < 0 || start + OBJECT_STRIDE > worldState.length) continue;
-
-        let x = worldState[start + 1] ?? 0;
-        let y = worldState[start + 2] ?? 0;
-        let vx = worldState[start + 5] ?? 0;
-        let vy = worldState[start + 6] ?? 0;
-
-        x += vx * dtSec;
-        y += vy * dtSec;
+function broadcastWorldBuffer(world: Float32Array): void {
+  if (connectedSessions.size === 0) return;
+  const payload = copyWorldBuffer(world);
+  for (const sessionId of connectedSessions) {
+    sendBinaryToClient(sessionId, payload, "sync");
+  }
+}
 
-        if (x < OBJECT_RADIUS || x > BOARD_WIDTH - OBJECT_RADIUS) {
-            vx *= -1;
-            x = Math.max(OBJECT_RADIUS, Math.min(BOARD_WIDTH - OBJECT_RADIUS, x));
-        }
-        if (y < OBJECT_RADIUS || y > BOARD_HEIGHT - OBJECT_RADIUS) {
-            vy *= -1;
-            y = Math.max(OBJECT_RADIUS, Math.min(BOARD_HEIGHT - OBJECT_RADIUS, y));
-        }
+async function loadWorldFromRedis(): Promise<Float32Array> {
+  if (!redis) {
+    return new Float32Array(worldState);
+  }
+  const raw = await redis.getBuffer(REDIS_WORLD_KEY);
+  return normalizeWorldBuffer(raw);
+}
 
-        worldState[start + 1] = x;
-        worldState[start + 2] = y;
-        worldState[start + 5] = vx;
-        worldState[start + 6] = vy;
-    }
+async function saveWorldToRedis(world: Float32Array): Promise<void> {
+  if (!redis) return;
+  await redis.setBuffer(REDIS_WORLD_KEY, copyWorldBuffer(world));
+}
 
-    for (let i = 0; i < activeObjectIds.length; i += 1) {
-        const aId = activeObjectIds[i];
-        const aSlot = objectIdToSlot(aId);
-        const aStart = aSlot * OBJECT_STRIDE;
-        if (aStart < 0 || aStart + OBJECT_STRIDE > worldState.length) continue;
-        for (let j = i + 1; j < activeObjectIds.length; j += 1) {
-            const bId = activeObjectIds[j];
-            const bSlot = objectIdToSlot(bId);
-            const bStart = bSlot * OBJECT_STRIDE;
-            if (bStart < 0 || bStart + OBJECT_STRIDE > worldState.length) continue;
-
-            let ax = worldState[aStart + 1] ?? 0;
-            let ay = worldState[aStart + 2] ?? 0;
-            let avx = worldState[aStart + 5] ?? 0;
-            let avy = worldState[aStart + 6] ?? 0;
-            let bx = worldState[bStart + 1] ?? 0;
-            let by = worldState[bStart + 2] ?? 0;
-            let bvx = worldState[bStart + 5] ?? 0;
-            let bvy = worldState[bStart + 6] ?? 0;
-
-            let dx = bx - ax;
-            let dy = by - ay;
-            let distSq = dx * dx + dy * dy;
-            const minDist = OBJECT_RADIUS * 2;
-            const minDistSq = minDist * minDist;
-            if (!(distSq > 0 && distSq < minDistSq)) continue;
-
-            let dist = Math.sqrt(distSq);
-            if (dist === 0) {
-                // Deterministic fallback axis when centers overlap exactly.
-                dx = 1;
-                dy = 0;
-                dist = 1;
-                distSq = 1;
-            }
-            const nx = dx / dist;
-            const ny = dy / dist;
-
-            // Positional correction prevents objects from remaining overlapped.
-            const overlap = minDist - dist;
-            const half = overlap * 0.5;
-            ax -= nx * half;
-            ay -= ny * half;
-            bx += nx * half;
-            by += ny * half;
-
-            const rvx = bvx - avx;
-            const rvy = bvy - avy;
-            const velAlongNormal = rvx * nx + rvy * ny;
-            if (velAlongNormal < 0) {
-                const impulse = (-(1 + COLLISION_RESTITUTION) * velAlongNormal) / 2;
-                avx -= impulse * nx;
-                avy -= impulse * ny;
-                bvx += impulse * nx;
-                bvy += impulse * ny;
-            }
-
-            worldState[aStart + 1] = Math.max(OBJECT_RADIUS, Math.min(BOARD_WIDTH - OBJECT_RADIUS, ax));
-            worldState[aStart + 2] = Math.max(OBJECT_RADIUS, Math.min(BOARD_HEIGHT - OBJECT_RADIUS, ay));
-            worldState[aStart + 5] = avx;
-            worldState[aStart + 6] = avy;
-            worldState[bStart + 1] = Math.max(OBJECT_RADIUS, Math.min(BOARD_WIDTH - OBJECT_RADIUS, bx));
-            worldState[bStart + 2] = Math.max(OBJECT_RADIUS, Math.min(BOARD_HEIGHT - OBJECT_RADIUS, by));
-            worldState[bStart + 5] = bvx;
-            worldState[bStart + 6] = bvy;
-        }
-    }
+async function runSimulationTick(): Promise<void> {
+  if (!redis) {
+    await withWorldMutation(async () => {
+      const activeObjectIds = [...objectOwners.keys()];
+      simulateWorldStep(worldState, 1 / BROADCAST_HZ, activeObjectIds);
+    });
+    broadcastWorldBuffer(worldState);
+    return;
+  }
+
+  await withWorldMutation(async () => {
+    await withRedisSimLock(
+      async () => {
+        const world = await loadWorldFromRedis();
+        const activeObjectIds = collectActiveObjectIds(world);
+        simulateWorldStep(world, 1 / BROADCAST_HZ, activeObjectIds);
+        const latestRedis = await loadWorldFromRedis();
+        commitSimulatedWorld(world, latestRedis);
+        await saveWorldToRedis(world);
+        worldState = world;
+      },
+      { retryUntilAcquired: false },
+    );
+  });
+
+  const world = await loadWorldFromRedis();
+  worldState = world;
+  broadcastWorldBuffer(world);
 }
 
 function startBroadcastLoopIfNeeded(): void {
-    if (broadcastTimer) return;
-    if (connectedSessions.size < 1) return;
-
-    broadcastTimer = setInterval(() => {
-        if (connectedSessions.size < 1) {
-            if (broadcastTimer) {
-                clearInterval(broadcastTimer);
-                broadcastTimer = null;
-            }
-            return;
-        }
-        simulateWorldStep(1 / BROADCAST_HZ);
-        broadcastWorldState();
-    }, BROADCAST_INTERVAL_MS);
+  if (broadcastTimer) return;
+  if (!redis && connectedSessions.size < 1) return;
+
+  broadcastTimer = setInterval(() => {
+    if (!redis && connectedSessions.size < 1) {
+      if (broadcastTimer) {
+        clearInterval(broadcastTimer);
+        broadcastTimer = null;
+      }
+      return;
+    }
+    void runSimulationTick().catch((error: unknown) => {
+      const detail = error instanceof Error ? error.message : String(error);
+      agentLog("error", `world tick failed: ${detail}`);
+    });
+  }, BROADCAST_INTERVAL_MS);
 
-    agentLog("info", `world loop started (${BROADCAST_HZ}Hz)`);
+  agentLog("info", `world loop started (${BROADCAST_HZ}Hz)`);
 }
 
 function stopBroadcastLoopIfNeeded(): void {
-    if (connectedSessions.size >= 1) return;
-    if (!broadcastTimer) return;
-    clearInterval(broadcastTimer);
-    broadcastTimer = null;
-    agentLog("info", "world loop stopped");
+  if (redis) return;
+  if (connectedSessions.size >= 1) return;
+  if (!broadcastTimer) return;
+  clearInterval(broadcastTimer);
+  broadcastTimer = null;
+  agentLog("info", "world loop stopped");
+}
+
+async function ensureRedisWorldInitialized(): Promise<void> {
+  if (!redis) return;
+  const existing = await redis.getBuffer(REDIS_WORLD_KEY);
+  if (!existing || existing.byteLength === 0) {
+    const empty = createEmptyWorldBuffer();
+    await redis.setBuffer(REDIS_WORLD_KEY, copyWorldBuffer(empty));
+  }
 }
 
 defineAgent({
-    onClientJoin({sessionId}) {
-        connectedSessions.add(sessionId);
-        startBroadcastLoopIfNeeded();
-        // New client receives the current ownership map so it can assign stable
-        // colors per owner and immediately render known tracked objects.
-        sendToClient(sessionId, {
-            type: "world_snapshot",
-            objects: trackedObjectsSnapshot(),
-        });
-        agentLog("info", `join ${sessionId} connected=${connectedSessions.size}`);
-    },
-
-    onClientLeave({sessionId}) {
-        connectedSessions.delete(sessionId);
-
-        const owned = sessionObjects.get(sessionId);
-        if (owned) {
-            for (const objectId of [...owned]) {
-                notifyObjectReleased(objectId, sessionId);
-                releaseObject(objectId);
-            }
-            sessionObjects.delete(sessionId);
+  async onAgentStart({ env }) {
+    const redisUrl = env.AGENT_REDIS_URL ?? process.env.AGENT_REDIS_URL;
+    if (!redisUrl?.trim()) {
+      agentLog(
+        "warn",
+        "AGENT_REDIS_URL unset — game-sync uses per-worker in-memory world only",
+      );
+      worldState = createEmptyWorldBuffer();
+      return;
+    }
+
+    redis = new Redis(redisUrl, {
+      maxRetriesPerRequest: 3,
+      lazyConnect: true,
+    });
+    await redis.connect();
+    await ensureRedisWorldInitialized();
+    worldState = await loadWorldFromRedis();
+    startBroadcastLoopIfNeeded();
+    agentLog("info", "game-sync agent connected to project Redis world buffer");
+  },
+
+  onClientJoin({ sessionId }) {
+    connectedSessions.add(sessionId);
+    startBroadcastLoopIfNeeded();
+    sendToClient(sessionId, {
+      type: "world_snapshot",
+      objects: trackedObjectsSnapshot(),
+    });
+    agentLog("info", `join ${sessionId} connected=${connectedSessions.size}`);
+  },
+
+  async onClientLeave({ sessionId }) {
+    connectedSessions.delete(sessionId);
+    for (const [objectId, ownerSessionId] of objectOwners) {
+      if (ownerSessionId === sessionId) {
+        objectOwners.delete(objectId);
+      }
+    }
+    sessionObjects.delete(sessionId);
+    stopBroadcastLoopIfNeeded();
+    agentLog(
+      "info",
+      `leave ${sessionId} connected=${connectedSessions.size} live=${countLiveObjects(worldState)}`,
+    );
+  },
+
+  async onDataChannelMessage(ctx) {
+    if (parseRegisterCommand(ctx.message)) {
+      const objectId = await withWorldMutation(async () => {
+        if (!redis) {
+          return registerObjectInMemory(ctx.sessionId);
         }
+        const result = await withRedisSimLock(() =>
+          registerObjectInRedis(ctx.sessionId),
+        );
+        return result;
+      });
+      if (objectId === null) {
+        sendToClient(ctx.sessionId, {
+          type: "register_nack",
+          reason: REGISTER_NACK_REASON_WORLD_FULL,
+          maxObjects: MAX_LIVE_OBJECTS,
+        });
+        agentLog(
+          "info",
+          `register_nack world_full session=${ctx.sessionId} redis=${Boolean(redis)}`,
+        );
+        return;
+      }
+      sendToClient(ctx.sessionId, { type: "register_ack", objectId });
+      notifyObjectRegistered(objectId, ctx.sessionId);
+      agentLog(
+        "info",
+        `register session=${ctx.sessionId} objectId=${objectId}`,
+      );
+      return;
+    }
 
-        stopBroadcastLoopIfNeeded();
+    const unregister = parseUnregisterCommand(ctx.message);
+    if (unregister) {
+      const result = await unregisterObject(ctx.sessionId, unregister.objectId);
+      if (!result.ok) {
+        sendToClient(ctx.sessionId, {
+          type: "unregister_nack",
+          reason: result.reason,
+        });
         agentLog(
-            "info",
-            `leave ${sessionId} connected=${connectedSessions.size} worldFloats=${worldState.length} freeSlots=${freeSlots.length}`,
+          "info",
+          `unregister_nack session=${ctx.sessionId} reason=${result.reason}`,
         );
-    },
-
-    onDataChannelMessage(ctx) {
-        // Register is a control-plane message over JSON data channel.
-        // Binary channel is reserved for high-frequency state deltas.
-        if (parseRegisterCommand(ctx.message)) {
-            const objectId = registerObject(ctx.sessionId);
-            sendToClient(ctx.sessionId, {type: "register_ack", objectId});
-            notifyObjectRegistered(objectId, ctx.sessionId);
-            agentLog("info", `register session=${ctx.sessionId} objectId=${objectId}`);
-            return;
-        }
+        return;
+      }
+      sendToClient(ctx.sessionId, {
+        type: "unregister_ack",
+        objectId: result.objectId,
+      });
+      agentLog(
+        "info",
+        `unregister_ack session=${ctx.sessionId} objectId=${result.objectId}`,
+      );
+      return;
+    }
 
-        // Optional chat mode for debugging/coordinating live test sessions.
-        const chat = parseChatCommand(ctx.message);
-        if (!chat) return;
-        for (const sessionId of connectedSessions) {
-            sendToClient(sessionId, {
-                type: "chat_broadcast",
-                senderSessionId: ctx.sessionId,
-                text: chat.text,
-            });
-        }
-    },
+    const chat = parseChatCommand(ctx.message);
+    if (!chat) return;
+    for (const sessionId of connectedSessions) {
+      sendToClient(sessionId, {
+        type: "chat_broadcast",
+        senderSessionId: ctx.sessionId,
+        text: chat.text,
+      });
+    }
+  },
 
-    onDataChannelBinary(ctx) {
-        // Server-authoritative simulation: ignore client binary state writes.
-        // Keeping the hook makes intent-based controls easy to add later.
-        void ctx;
-    },
+  onDataChannelBinary(ctx) {
+    void ctx;
+  },
 });
+
+// Re-export layout helpers for unit tests.
+export {
+  countLiveObjects,
+  findFirstEmptySlot,
+  markSlotFree,
+  readSlotObjectId,
+  slotToObjectId,
+  writeObjectSlot,
+} from "./game-sync-world-layout.js";
+export { simulateWorldStep } from "./game-sync-sim.js";