push bulk 1

Dockerfile

@@ -24,16 +24,21 @@ RUN git clone https://github.com/a16z-infra/ai-town.git . && \
 RUN npm install --include=dev @huggingface/inference
 RUN npm install --include=dev @huggingface/hub
 
+
 RUN curl -L -O https://github.com/get-convex/convex-backend/releases/download/precompiled-2024-05-07-13337fd/convex-local-backend-x86_64-unknown-linux-gnu.zip && \
     unzip convex-local-backend-x86_64-unknown-linux-gnu.zip 
 
-COPY ./patches/llm.ts ./convex/util/
+COPY ./patches ./
 COPY ./patches/vite.config.ts ./
-COPY ./patches/constants.ts ./patches/music.ts ./convex/
 COPY ./patches/characters.ts ./patches/gentle.js ./data/
-COPY ./patches/PixiStaticMap.tsx ./src/components/
-COPY ./patches/Button.tsx ./src/components/buttons/Button.tsx
-COPY ./patches/App.tsx ./src/App.tsx
 COPY ./patches/run.sh ./
 
+COPY ./map.png ./assets/map.png
+COPY ./patches/assets/GrayCat.png ./assets/GrayCat.png
+COPY ./patches/assets/OrangeCat.png ./assets/OrangeCat.png
+COPY ./patches/assets/hf.svg ./assets/hf.svg
+COPY ./patches/data/spritesheets/c1.ts ./data/spritesheets/c1.ts
+
+
+
 CMD ["./run.sh"]

README.md

@@ -1,6 +1,6 @@
 ---
 title: AI Town on HuggingFace
-emoji: 🏠💻💌🤗
+emoji: 🏠🐈‍⬛
 colorFrom: green
 colorTo: red
 sdk: docker
@@ -9,6 +9,7 @@ pinned: false
 disable_embedding: true
 # header: mini
 short_description: AI Town on HuggingFace
+hf_oauth: true
 ---
 
 # AI Town 🏠💻💌 on Hugging Face 🤗

README.md.yml

@@ -8,3 +8,11 @@ pinned: false
 disable_embedding: true
 # header: mini
 short_description: AI Town on HuggingFace
+hf_oauth: true
+# optional, default duration is 8 hours/480 minutes. Max duration is 30 days/43200 minutes.
+hf_oauth_expiration_minutes: 480
+# optional, see "Scopes" below. "openid profile" is always included.
+hf_oauth_scopes:
+ - read-repos
+ - manage-repos
+ - inference-api

patches/PixiStaticMap.tsx

@@ -1,128 +0,0 @@
-import { PixiComponent, applyDefaultProps } from '@pixi/react';
-import * as PIXI from 'pixi.js';
-import { AnimatedSprite, WorldMap } from '../../convex/aiTown/worldMap';
-import * as campfire from '../../data/animations/campfire.json';
-import * as gentlesparkle from '../../data/animations/gentlesparkle.json';
-import * as gentlewaterfall from '../../data/animations/gentlewaterfall.json';
-import * as gentlesplash from '../../data/animations/gentlesplash.json';
-import * as windmill from '../../data/animations/windmill.json';
-
-const animations = {
-  'campfire.json': { spritesheet: campfire, url: '/assets/spritesheets/campfire.png' },
-  'gentlesparkle.json': {
-    spritesheet: gentlesparkle,
-    url: '/assets/spritesheets/gentlesparkle32.png',
-  },
-  'gentlewaterfall.json': {
-    spritesheet: gentlewaterfall,
-    url: '/assets/spritesheets/gentlewaterfall32.png',
-  },
-  'windmill.json': { spritesheet: windmill, url: '/assets/spritesheets/windmill.png' },
-  'gentlesplash.json': {
-    spritesheet: gentlesplash,
-    url: '/assets/spritesheets/gentlewaterfall32.png',
-  },
-};
-
-export const PixiStaticMap = PixiComponent('StaticMap', {
-  create: (props: { map: WorldMap; [k: string]: any }) => {
-    const map = props.map;
-    const numxtiles = Math.floor(map.tileSetDimX / map.tileDim);
-    const numytiles = Math.floor(map.tileSetDimY / map.tileDim);
-    const bt = PIXI.BaseTexture.from(map.tileSetUrl, {
-      scaleMode: PIXI.SCALE_MODES.NEAREST,
-    });
-
-    const tiles = [];
-    for (let x = 0; x < numxtiles; x++) {
-      for (let y = 0; y < numytiles; y++) {
-        tiles[x + y * numxtiles] = new PIXI.Texture(
-          bt,
-          new PIXI.Rectangle(x * map.tileDim, y * map.tileDim, map.tileDim, map.tileDim),
-        );
-      }
-    }
-    const screenxtiles = map.bgTiles[0].length;
-    const screenytiles = map.bgTiles[0][0].length;
-
-    const container = new PIXI.Container();
-    const allLayers = [...map.bgTiles, ...map.objectTiles];
-
-    // blit bg & object layers of map onto canvas
-    for (let i = 0; i < screenxtiles * screenytiles; i++) {
-      const x = i % screenxtiles;
-      const y = Math.floor(i / screenxtiles);
-      const xPx = x * map.tileDim;
-      const yPx = y * map.tileDim;
-
-      // Add all layers of backgrounds.
-      for (const layer of allLayers) {
-        const tileIndex = layer[x][y];
-        // Some layers may not have tiles at this location.
-        if (tileIndex === -1) continue;
-        const ctile = new PIXI.Sprite(tiles[tileIndex]);
-        ctile.x = xPx;
-        ctile.y = yPx;
-        container.addChild(ctile);
-      }
-    }
-
-    // TODO: Add layers.
-    const spritesBySheet = new Map<string, AnimatedSprite[]>();
-    for (const sprite of map.animatedSprites) {
-      const sheet = sprite.sheet;
-      if (!spritesBySheet.has(sheet)) {
-        spritesBySheet.set(sheet, []);
-      }
-      spritesBySheet.get(sheet)!.push(sprite);
-    }
-    for (const [sheet, sprites] of spritesBySheet.entries()) {
-      const animation = (animations as any)[sheet];
-      if (!animation) {
-        console.error('Could not find animation', sheet);
-        continue;
-      }
-      const { spritesheet, url } = animation;
-      const texture = PIXI.BaseTexture.from(url, {
-        scaleMode: PIXI.SCALE_MODES.NEAREST,
-      });
-      const spriteSheet = new PIXI.Spritesheet(texture, spritesheet);
-      spriteSheet.parse().then(() => {
-        for (const sprite of sprites) {
-          const pixiAnimation = spriteSheet.animations[sprite.animation];
-          if (!pixiAnimation) {
-            console.error('Failed to load animation', sprite);
-            continue;
-          }
-          const pixiSprite = new PIXI.AnimatedSprite(pixiAnimation);
-          pixiSprite.animationSpeed = 0.1;
-          pixiSprite.autoUpdate = true;
-          pixiSprite.x = sprite.x;
-          pixiSprite.y = sprite.y;
-          pixiSprite.width = sprite.w;
-          pixiSprite.height = sprite.h;
-          container.addChild(pixiSprite);
-          pixiSprite.play();
-        }
-      });
-    }
-
-    container.x = 0;
-    container.y = 0;
-
-    // Set the hit area manually to ensure `pointerdown` events are delivered to this container.
-    container.interactive = true;
-    container.hitArea = new PIXI.Rectangle(
-      0,
-      0,
-      screenxtiles * map.tileDim,
-      screenytiles * map.tileDim,
-    );
-
-    return container;
-  },
-
-  applyProps: (instance, oldProps, newProps) => {
-    applyDefaultProps(instance, oldProps, newProps);
-  },
-});

patches/characters.ts

@@ -6,7 +6,7 @@ import { data as f5SpritesheetData } from './spritesheets/f5';
 import { data as f6SpritesheetData } from './spritesheets/f6';
 import { data as f7SpritesheetData } from './spritesheets/f7';
 import { data as f8SpritesheetData } from './spritesheets/f8';
-
+import { data as c1SpritesheetData } from './spritesheets/c1';
 export const Descriptions = [
   // {
   //   name: 'Alex',
@@ -19,7 +19,7 @@ export const Descriptions = [
   // },
   {
     name: 'Lucky',
-    character: 'f1',
+    character: 'c1',
     identity: `Lucky is always happy and curious, and he loves cheese. He spends
       most of his time reading about the history of science and traveling
       through the galaxy on whatever ship will take him. He's very articulate and
@@ -30,7 +30,7 @@ export const Descriptions = [
   },
   {
     name: 'Bob',
-    character: 'f4',
+    character: 'c2',
     identity: `Bob is always grumpy and he loves trees. He spends
       most of his time gardening by himself. When spoken to he'll respond but try
       and get out of the conversation as quickly as possible. Secretly he resents
@@ -39,7 +39,7 @@ export const Descriptions = [
   },
   {
     name: 'Stella',
-    character: 'f6',
+    character: 'c1',
     identity: `Stella can never be trusted. she tries to trick people all the time. normally
       into giving her money, or doing things that will make her money. she's incredibly charming
       and not afraid to use her charm. she's a sociopath who has no empathy. but hides it well.`,
@@ -55,7 +55,7 @@ export const Descriptions = [
   // },
   {
     name: 'Alice',
-    character: 'f3',
+    character: 'c2',
     identity: `Alice is a famous scientist. She is smarter than everyone else and has
       discovered mysteries of the universe no one else can understand. As a result she often
       speaks in oblique riddles. She comes across as confused and forgetful.`,
@@ -85,51 +85,63 @@ export const characters = [
     name: 'f1',
     textureUrl: '/assets/32x32folk.png',
     spritesheetData: f1SpritesheetData,
-    speed: 0.1,
+    speed: 0.19,
   },
   {
     name: 'f2',
     textureUrl: '/assets/32x32folk.png',
     spritesheetData: f2SpritesheetData,
-    speed: 0.1,
+    speed: 0.19,
   },
   {
     name: 'f3',
     textureUrl: '/assets/32x32folk.png',
     spritesheetData: f3SpritesheetData,
-    speed: 0.1,
+    speed: 0.19,
   },
   {
     name: 'f4',
     textureUrl: '/assets/32x32folk.png',
     spritesheetData: f4SpritesheetData,
-    speed: 0.1,
+    speed: 0.19,
   },
   {
     name: 'f5',
     textureUrl: '/assets/32x32folk.png',
     spritesheetData: f5SpritesheetData,
-    speed: 0.1,
+    speed: 0.19,
   },
   {
     name: 'f6',
     textureUrl: '/assets/32x32folk.png',
     spritesheetData: f6SpritesheetData,
-    speed: 0.1,
+    speed: 0.19,
   },
   {
     name: 'f7',
     textureUrl: '/assets/32x32folk.png',
     spritesheetData: f7SpritesheetData,
-    speed: 0.1,
+    speed: 0.19,
   },
   {
     name: 'f8',
     textureUrl: '/assets/32x32folk.png',
     spritesheetData: f8SpritesheetData,
-    speed: 0.1,
+    speed: 0.19,
+  },
+  {
+    name: 'c1',
+    textureUrl: '/assets/GrayCat.png',
+    spritesheetData: c1SpritesheetData,
+    speed: 0.19,
+  },
+  {
+    name: 'c2',
+    textureUrl: '/assets/OrangeCat.png',
+    spritesheetData: c1SpritesheetData,
+    speed: 0.19,
   },
 ];
 
 // Characters move at 0.75 tiles per second.
-export const movementSpeed = 0.75;
+export const movementSpeed = 2;

patches/convex/agent/conversation.ts

@@ -0,0 +1,345 @@
+import { v } from 'convex/values';
+import { Id } from '../_generated/dataModel';
+import { ActionCtx, internalQuery } from '../_generated/server';
+import { LLMMessage, chatCompletion } from '../util/llm';
+import * as memory from './memory';
+import { api, internal } from '../_generated/api';
+import * as embeddingsCache from './embeddingsCache';
+import { GameId, conversationId, playerId } from '../aiTown/ids';
+import { NUM_MEMORIES_TO_SEARCH } from '../constants';
+
+const selfInternal = internal.agent.conversation;
+
+export async function startConversationMessage(
+  ctx: ActionCtx,
+  worldId: Id<'worlds'>,
+  conversationId: GameId<'conversations'>,
+  playerId: GameId<'players'>,
+  otherPlayerId: GameId<'players'>,
+) {
+  const { player, otherPlayer, agent, otherAgent, lastConversation } = await ctx.runQuery(
+    selfInternal.queryPromptData,
+    {
+      worldId,
+      playerId,
+      otherPlayerId,
+      conversationId,
+    },
+  );
+  const embedding = await embeddingsCache.fetch(
+    ctx,
+    `${player.name} is talking to ${otherPlayer.name}`,
+  );
+
+  const memories = await memory.searchMemories(
+    ctx,
+    player.id as GameId<'players'>,
+    embedding,
+    Number(process.env.NUM_MEMORIES_TO_SEARCH) || NUM_MEMORIES_TO_SEARCH,
+  );
+
+  const memoryWithOtherPlayer = memories.find(
+    (m) => m.data.type === 'conversation' && m.data.playerIds.includes(otherPlayerId),
+  );
+  const prompt = [
+    `You are ${player.name}, and you just started a conversation with ${otherPlayer.name}.`,
+  ];
+  prompt.push(...agentPrompts(otherPlayer, agent, otherAgent ?? null));
+  prompt.push(...previousConversationPrompt(otherPlayer, lastConversation));
+  prompt.push(...relatedMemoriesPrompt(memories));
+  if (memoryWithOtherPlayer) {
+    prompt.push(
+      `Be sure to include some detail or question about a previous conversation in your greeting.`,
+    );
+  }
+  prompt.push(`${player.name}:`);
+
+  const { content } = await chatCompletion({
+    messages: [
+      {
+        role: 'user',
+        content: prompt.join('\n'),
+      },
+    ],
+    max_tokens: 300,
+    stream: true,
+    stop: stopWords(otherPlayer.name, player.name),
+  });
+  return content;
+}
+
+export async function continueConversationMessage(
+  ctx: ActionCtx,
+  worldId: Id<'worlds'>,
+  conversationId: GameId<'conversations'>,
+  playerId: GameId<'players'>,
+  otherPlayerId: GameId<'players'>,
+) {
+  const { player, otherPlayer, conversation, agent, otherAgent } = await ctx.runQuery(
+    selfInternal.queryPromptData,
+    {
+      worldId,
+      playerId,
+      otherPlayerId,
+      conversationId,
+    },
+  );
+  const now = Date.now();
+  const started = new Date(conversation.created);
+  const embedding = await embeddingsCache.fetch(
+    ctx,
+    `What do you think about ${otherPlayer.name}?`,
+  );
+  const memories = await memory.searchMemories(ctx, player.id as GameId<'players'>, embedding, 3);
+  const prompt = [
+    `You are ${player.name}, and you're currently in a conversation with ${otherPlayer.name}.`,
+    `The conversation started at ${started.toLocaleString()}. It's now ${now.toLocaleString()}.`,
+  ];
+  prompt.push(...agentPrompts(otherPlayer, agent, otherAgent ?? null));
+  prompt.push(...relatedMemoriesPrompt(memories));
+  prompt.push(
+    `Below is the current chat history between you and ${otherPlayer.name}.`,
+    `DO NOT greet them again. Do NOT use the word "Hey" too often. Your response should be brief and within 200 characters.`,
+  );
+
+  const llmMessages: LLMMessage[] = [
+    {
+      role: 'user',
+      content: prompt.join('\n'),
+    },
+    ...(await previousMessages(
+      ctx,
+      worldId,
+      player,
+      otherPlayer,
+      conversation.id as GameId<'conversations'>,
+    )),
+  ];
+  llmMessages.push({ role: 'user', content: `${player.name}:` });
+
+  const { content } = await chatCompletion({
+    messages: llmMessages,
+    max_tokens: 300,
+    stream: true,
+    stop: stopWords(otherPlayer.name, player.name),
+  });
+  return content;
+}
+
+export async function leaveConversationMessage(
+  ctx: ActionCtx,
+  worldId: Id<'worlds'>,
+  conversationId: GameId<'conversations'>,
+  playerId: GameId<'players'>,
+  otherPlayerId: GameId<'players'>,
+) {
+  const { player, otherPlayer, conversation, agent, otherAgent } = await ctx.runQuery(
+    selfInternal.queryPromptData,
+    {
+      worldId,
+      playerId,
+      otherPlayerId,
+      conversationId,
+    },
+  );
+  const prompt = [
+    `You are ${player.name}, and you're currently in a conversation with ${otherPlayer.name}.`,
+    `You've decided to leave the question and would like to politely tell them you're leaving the conversation.`,
+  ];
+  prompt.push(...agentPrompts(otherPlayer, agent, otherAgent ?? null));
+  prompt.push(
+    `Below is the current chat history between you and ${otherPlayer.name}.`,
+    `How would you like to tell them that you're leaving? Your response should be brief and within 200 characters.`,
+  );
+  const llmMessages: LLMMessage[] = [
+    {
+      role: 'user',
+      content: prompt.join('\n'),
+    },
+    ...(await previousMessages(
+      ctx,
+      worldId,
+      player,
+      otherPlayer,
+      conversation.id as GameId<'conversations'>,
+    )),
+  ];
+  llmMessages.push({ role: 'user', content: `${player.name}:` });
+
+  const { content } = await chatCompletion({
+    messages: llmMessages,
+    max_tokens: 300,
+    stream: true,
+    stop: stopWords(otherPlayer.name, player.name),
+  });
+  return content;
+}
+
+function agentPrompts(
+  otherPlayer: { name: string },
+  agent: { identity: string; plan: string } | null,
+  otherAgent: { identity: string; plan: string } | null,
+): string[] {
+  const prompt = [];
+  if (agent) {
+    prompt.push(`About you: ${agent.identity}`);
+    prompt.push(`Your goals for the conversation: ${agent.plan}`);
+  }
+  if (otherAgent) {
+    prompt.push(`About ${otherPlayer.name}: ${otherAgent.identity}`);
+  }
+  return prompt;
+}
+
+function previousConversationPrompt(
+  otherPlayer: { name: string },
+  conversation: { created: number } | null,
+): string[] {
+  const prompt = [];
+  if (conversation) {
+    const prev = new Date(conversation.created);
+    const now = new Date();
+    prompt.push(
+      `Last time you chatted with ${
+        otherPlayer.name
+      } it was ${prev.toLocaleString()}. It's now ${now.toLocaleString()}.`,
+    );
+  }
+  return prompt;
+}
+
+function relatedMemoriesPrompt(memories: memory.Memory[]): string[] {
+  const prompt = [];
+  if (memories.length > 0) {
+    prompt.push(`Here are some related memories in decreasing relevance order:`);
+    for (const memory of memories) {
+      prompt.push(' - ' + memory.description);
+    }
+  }
+  return prompt;
+}
+
+async function previousMessages(
+  ctx: ActionCtx,
+  worldId: Id<'worlds'>,
+  player: { id: string; name: string },
+  otherPlayer: { id: string; name: string },
+  conversationId: GameId<'conversations'>,
+) {
+  const llmMessages: LLMMessage[] = [];
+  const prevMessages = await ctx.runQuery(api.messages.listMessages, { worldId, conversationId });
+  for (const message of prevMessages) {
+    const author = message.author === player.id ? player : otherPlayer;
+    const recipient = message.author === player.id ? otherPlayer : player;
+    llmMessages.push({
+      role: 'user',
+      content: `${author.name} to ${recipient.name}: ${message.text}`,
+    });
+  }
+  return llmMessages;
+}
+
+export const queryPromptData = internalQuery({
+  args: {
+    worldId: v.id('worlds'),
+    playerId,
+    otherPlayerId: playerId,
+    conversationId,
+  },
+  handler: async (ctx, args) => {
+    const world = await ctx.db.get(args.worldId);
+    if (!world) {
+      throw new Error(`World ${args.worldId} not found`);
+    }
+    const player = world.players.find((p) => p.id === args.playerId);
+    if (!player) {
+      throw new Error(`Player ${args.playerId} not found`);
+    }
+    const playerDescription = await ctx.db
+      .query('playerDescriptions')
+      .withIndex('worldId', (q) => q.eq('worldId', args.worldId).eq('playerId', args.playerId))
+      .first();
+    if (!playerDescription) {
+      throw new Error(`Player description for ${args.playerId} not found`);
+    }
+    const otherPlayer = world.players.find((p) => p.id === args.otherPlayerId);
+    if (!otherPlayer) {
+      throw new Error(`Player ${args.otherPlayerId} not found`);
+    }
+    const otherPlayerDescription = await ctx.db
+      .query('playerDescriptions')
+      .withIndex('worldId', (q) => q.eq('worldId', args.worldId).eq('playerId', args.otherPlayerId))
+      .first();
+    if (!otherPlayerDescription) {
+      throw new Error(`Player description for ${args.otherPlayerId} not found`);
+    }
+    const conversation = world.conversations.find((c) => c.id === args.conversationId);
+    if (!conversation) {
+      throw new Error(`Conversation ${args.conversationId} not found`);
+    }
+    const agent = world.agents.find((a) => a.playerId === args.playerId);
+    if (!agent) {
+      throw new Error(`Player ${args.playerId} not found`);
+    }
+    const agentDescription = await ctx.db
+      .query('agentDescriptions')
+      .withIndex('worldId', (q) => q.eq('worldId', args.worldId).eq('agentId', agent.id))
+      .first();
+    if (!agentDescription) {
+      throw new Error(`Agent description for ${agent.id} not found`);
+    }
+    const otherAgent = world.agents.find((a) => a.playerId === args.otherPlayerId);
+    let otherAgentDescription;
+    if (otherAgent) {
+      otherAgentDescription = await ctx.db
+        .query('agentDescriptions')
+        .withIndex('worldId', (q) => q.eq('worldId', args.worldId).eq('agentId', otherAgent.id))
+        .first();
+      if (!otherAgentDescription) {
+        throw new Error(`Agent description for ${otherAgent.id} not found`);
+      }
+    }
+    const lastTogether = await ctx.db
+      .query('participatedTogether')
+      .withIndex('edge', (q) =>
+        q
+          .eq('worldId', args.worldId)
+          .eq('player1', args.playerId)
+          .eq('player2', args.otherPlayerId),
+      )
+      // Order by conversation end time descending.
+      .order('desc')
+      .first();
+
+    let lastConversation = null;
+    if (lastTogether) {
+      lastConversation = await ctx.db
+        .query('archivedConversations')
+        .withIndex('worldId', (q) =>
+          q.eq('worldId', args.worldId).eq('id', lastTogether.conversationId),
+        )
+        .first();
+      if (!lastConversation) {
+        throw new Error(`Conversation ${lastTogether.conversationId} not found`);
+      }
+    }
+    return {
+      player: { name: playerDescription.name, ...player },
+      otherPlayer: { name: otherPlayerDescription.name, ...otherPlayer },
+      conversation,
+      agent: { identity: agentDescription.identity, plan: agentDescription.plan, ...agent },
+      otherAgent: otherAgent && {
+        identity: otherAgentDescription!.identity,
+        plan: otherAgentDescription!.plan,
+        ...otherAgent,
+      },
+      lastConversation,
+    };
+  },
+});
+
+function stopWords(otherPlayer: string, player: string) {
+  // These are the words we ask the LLM to stop on. OpenAI only supports 4.
+  const variants = [`${otherPlayer} to ${player}`];
+  return variants.flatMap((stop) => [stop + ':', stop.toLowerCase() + ':']);
+}

patches/convex/agent/embeddingsCache.ts

@@ -0,0 +1,110 @@
+import { v } from 'convex/values';
+import { ActionCtx, internalMutation, internalQuery } from '../_generated/server';
+import { internal } from '../_generated/api';
+import { Id } from '../_generated/dataModel';
+import { fetchEmbeddingBatch } from '../util/llm';
+
+const selfInternal = internal.agent.embeddingsCache;
+
+export async function fetch(ctx: ActionCtx, text: string) {
+  const result = await fetchBatch(ctx, [text]);
+  return result.embeddings[0];
+}
+
+export async function fetchBatch(ctx: ActionCtx, texts: string[]) {
+  const start = Date.now();
+
+  const textHashes = await Promise.all(texts.map((text) => hashText(text)));
+  const results = new Array<number[]>(texts.length);
+  const cacheResults = await ctx.runQuery(selfInternal.getEmbeddingsByText, {
+    textHashes,
+  });
+  for (const { index, embedding } of cacheResults) {
+    results[index] = embedding;
+  }
+  const toWrite = [];
+  if (cacheResults.length < texts.length) {
+    const missingIndexes = [...results.keys()].filter((i) => !results[i]);
+    const missingTexts = missingIndexes.map((i) => texts[i]);
+    const response = await fetchEmbeddingBatch(missingTexts);
+    if (response.embeddings.length !== missingIndexes.length) {
+      throw new Error(
+        `Expected ${missingIndexes.length} embeddings, got ${response.embeddings.length}`,
+      );
+    }
+    for (let i = 0; i < missingIndexes.length; i++) {
+      const resultIndex = missingIndexes[i];
+      toWrite.push({
+        textHash: textHashes[resultIndex],
+        embedding: response.embeddings[i],
+      });
+      results[resultIndex] = response.embeddings[i];
+    }
+  }
+  if (toWrite.length > 0) {
+    await ctx.runMutation(selfInternal.writeEmbeddings, { embeddings: toWrite });
+  }
+  return {
+    embeddings: results,
+    hits: cacheResults.length,
+    ms: Date.now() - start,
+  };
+}
+
+async function hashText(text: string) {
+  const textEncoder = new TextEncoder();
+  const buf = textEncoder.encode(text);
+  if (typeof crypto === 'undefined') {
+    // Ugly, ugly hax to get ESBuild to not try to bundle this node dependency.
+    const f = () => 'node:crypto';
+    const crypto = (await import(f())) as typeof import('crypto');
+    const hash = crypto.createHash('sha256');
+    hash.update(buf);
+    return hash.digest().buffer;
+  } else {
+    return await crypto.subtle.digest('SHA-256', buf);
+  }
+}
+
+export const getEmbeddingsByText = internalQuery({
+  args: { textHashes: v.array(v.bytes()) },
+  handler: async (
+    ctx,
+    args,
+  ): Promise<{ index: number; embeddingId: Id<'embeddingsCache'>; embedding: number[] }[]> => {
+    const out = [];
+    for (let i = 0; i < args.textHashes.length; i++) {
+      const textHash = args.textHashes[i];
+      const result = await ctx.db
+        .query('embeddingsCache')
+        .withIndex('text', (q) => q.eq('textHash', textHash))
+        .first();
+      if (result) {
+        out.push({
+          index: i,
+          embeddingId: result._id,
+          embedding: result.embedding,
+        });
+      }
+    }
+    return out;
+  },
+});
+
+export const writeEmbeddings = internalMutation({
+  args: {
+    embeddings: v.array(
+      v.object({
+        textHash: v.bytes(),
+        embedding: v.array(v.float64()),
+      }),
+    ),
+  },
+  handler: async (ctx, args): Promise<Id<'embeddingsCache'>[]> => {
+    const ids = [];
+    for (const embedding of args.embeddings) {
+      ids.push(await ctx.db.insert('embeddingsCache', embedding));
+    }
+    return ids;
+  },
+});

patches/convex/agent/memory.ts

@@ -0,0 +1,450 @@
+import { v } from 'convex/values';
+import { ActionCtx, DatabaseReader, internalMutation, internalQuery } from '../_generated/server';
+import { Doc, Id } from '../_generated/dataModel';
+import { internal } from '../_generated/api';
+import { LLMMessage, chatCompletion, fetchEmbedding } from '../util/llm';
+import { asyncMap } from '../util/asyncMap';
+import { GameId, agentId, conversationId, playerId } from '../aiTown/ids';
+import { SerializedPlayer } from '../aiTown/player';
+import { memoryFields } from './schema';
+
+// How long to wait before updating a memory's last access time.
+export const MEMORY_ACCESS_THROTTLE = 300_000; // In ms
+// We fetch 10x the number of memories by relevance, to have more candidates
+// for sorting by relevance + recency + importance.
+const MEMORY_OVERFETCH = 10;
+const selfInternal = internal.agent.memory;
+
+export type Memory = Doc<'memories'>;
+export type MemoryType = Memory['data']['type'];
+export type MemoryOfType<T extends MemoryType> = Omit<Memory, 'data'> & {
+  data: Extract<Memory['data'], { type: T }>;
+};
+
+export async function rememberConversation(
+  ctx: ActionCtx,
+  worldId: Id<'worlds'>,
+  agentId: GameId<'agents'>,
+  playerId: GameId<'players'>,
+  conversationId: GameId<'conversations'>,
+) {
+  const data = await ctx.runQuery(selfInternal.loadConversation, {
+    worldId,
+    playerId,
+    conversationId,
+  });
+  const { player, otherPlayer } = data;
+  const messages = await ctx.runQuery(selfInternal.loadMessages, { worldId, conversationId });
+  if (!messages.length) {
+    return;
+  }
+
+  const llmMessages: LLMMessage[] = [
+    {
+      role: 'user',
+      content: `You are ${player.name}, and you just finished a conversation with ${otherPlayer.name}. I would
+      like you to summarize the conversation from ${player.name}'s perspective, using first-person pronouns like
+      "I," and add if you liked or disliked this interaction.`,
+    },
+  ];
+  const authors = new Set<GameId<'players'>>();
+  for (const message of messages) {
+    const author = message.author === player.id ? player : otherPlayer;
+    authors.add(author.id as GameId<'players'>);
+    const recipient = message.author === player.id ? otherPlayer : player;
+    llmMessages.push({
+      role: 'user',
+      content: `${author.name} to ${recipient.name}: ${message.text}`,
+    });
+  }
+  llmMessages.push({ role: 'user', content: 'Summary:' });
+  const { content } = await chatCompletion({
+    messages: llmMessages,
+    max_tokens: 500,
+  });
+  const description = `Conversation with ${otherPlayer.name} at ${new Date(
+    data.conversation._creationTime,
+  ).toLocaleString()}: ${content}`;
+  const importance = await calculateImportance(description);
+  const { embedding } = await fetchEmbedding(description);
+  authors.delete(player.id as GameId<'players'>);
+  await ctx.runMutation(selfInternal.insertMemory, {
+    agentId,
+    playerId: player.id,
+    description,
+    importance,
+    lastAccess: messages[messages.length - 1]._creationTime,
+    data: {
+      type: 'conversation',
+      conversationId,
+      playerIds: [...authors],
+    },
+    embedding,
+  });
+  await reflectOnMemories(ctx, worldId, playerId);
+  return description;
+}
+
+export const loadConversation = internalQuery({
+  args: {
+    worldId: v.id('worlds'),
+    playerId,
+    conversationId,
+  },
+  handler: async (ctx, args) => {
+    const world = await ctx.db.get(args.worldId);
+    if (!world) {
+      throw new Error(`World ${args.worldId} not found`);
+    }
+    const player = world.players.find((p) => p.id === args.playerId);
+    if (!player) {
+      throw new Error(`Player ${args.playerId} not found`);
+    }
+    const playerDescription = await ctx.db
+      .query('playerDescriptions')
+      .withIndex('worldId', (q) => q.eq('worldId', args.worldId).eq('playerId', args.playerId))
+      .first();
+    if (!playerDescription) {
+      throw new Error(`Player description for ${args.playerId} not found`);
+    }
+    const conversation = await ctx.db
+      .query('archivedConversations')
+      .withIndex('worldId', (q) => q.eq('worldId', args.worldId).eq('id', args.conversationId))
+      .first();
+    if (!conversation) {
+      throw new Error(`Conversation ${args.conversationId} not found`);
+    }
+    const otherParticipator = await ctx.db
+      .query('participatedTogether')
+      .withIndex('conversation', (q) =>
+        q
+          .eq('worldId', args.worldId)
+          .eq('player1', args.playerId)
+          .eq('conversationId', args.conversationId),
+      )
+      .first();
+    if (!otherParticipator) {
+      throw new Error(
+        `Couldn't find other participant in conversation ${args.conversationId} with player ${args.playerId}`,
+      );
+    }
+    const otherPlayerId = otherParticipator.player2;
+    let otherPlayer: SerializedPlayer | Doc<'archivedPlayers'> | null =
+      world.players.find((p) => p.id === otherPlayerId) ?? null;
+    if (!otherPlayer) {
+      otherPlayer = await ctx.db
+        .query('archivedPlayers')
+        .withIndex('worldId', (q) => q.eq('worldId', world._id).eq('id', otherPlayerId))
+        .first();
+    }
+    if (!otherPlayer) {
+      throw new Error(`Conversation ${args.conversationId} other player not found`);
+    }
+    const otherPlayerDescription = await ctx.db
+      .query('playerDescriptions')
+      .withIndex('worldId', (q) => q.eq('worldId', args.worldId).eq('playerId', otherPlayerId))
+      .first();
+    if (!otherPlayerDescription) {
+      throw new Error(`Player description for ${otherPlayerId} not found`);
+    }
+    return {
+      player: { ...player, name: playerDescription.name },
+      conversation,
+      otherPlayer: { ...otherPlayer, name: otherPlayerDescription.name },
+    };
+  },
+});
+
+export async function searchMemories(
+  ctx: ActionCtx,
+  playerId: GameId<'players'>,
+  searchEmbedding: number[],
+  n: number = 3,
+) {
+  const candidates = await ctx.vectorSearch('memoryEmbeddings', 'embedding', {
+    vector: searchEmbedding,
+    filter: (q) => q.eq('playerId', playerId),
+    limit: n * MEMORY_OVERFETCH,
+  });
+  const rankedMemories = await ctx.runMutation(selfInternal.rankAndTouchMemories, {
+    candidates,
+    n,
+  });
+  return rankedMemories.map(({ memory }) => memory);
+}
+
+function makeRange(values: number[]) {
+  const min = Math.min(...values);
+  const max = Math.max(...values);
+  return [min, max] as const;
+}
+
+function normalize(value: number, range: readonly [number, number]) {
+  const [min, max] = range;
+  return (value - min) / (max - min);
+}
+
+export const rankAndTouchMemories = internalMutation({
+  args: {
+    candidates: v.array(v.object({ _id: v.id('memoryEmbeddings'), _score: v.number() })),
+    n: v.number(),
+  },
+  handler: async (ctx, args) => {
+    const ts = Date.now();
+    const relatedMemories = await asyncMap(args.candidates, async ({ _id }) => {
+      const memory = await ctx.db
+        .query('memories')
+        .withIndex('embeddingId', (q) => q.eq('embeddingId', _id))
+        .first();
+      if (!memory) throw new Error(`Memory for embedding ${_id} not found`);
+      return memory;
+    });
+
+    // TODO: fetch <count> recent memories and <count> important memories
+    // so we don't miss them in case they were a little less relevant.
+    const recencyScore = relatedMemories.map((memory) => {
+      const hoursSinceAccess = (ts - memory.lastAccess) / 1000 / 60 / 60;
+      return 0.99 ** Math.floor(hoursSinceAccess);
+    });
+    const relevanceRange = makeRange(args.candidates.map((c) => c._score));
+    const importanceRange = makeRange(relatedMemories.map((m) => m.importance));
+    const recencyRange = makeRange(recencyScore);
+    const memoryScores = relatedMemories.map((memory, idx) => ({
+      memory,
+      overallScore:
+        normalize(args.candidates[idx]._score, relevanceRange) +
+        normalize(memory.importance, importanceRange) +
+        normalize(recencyScore[idx], recencyRange),
+    }));
+    memoryScores.sort((a, b) => b.overallScore - a.overallScore);
+    const accessed = memoryScores.slice(0, args.n);
+    await asyncMap(accessed, async ({ memory }) => {
+      if (memory.lastAccess < ts - MEMORY_ACCESS_THROTTLE) {
+        await ctx.db.patch(memory._id, { lastAccess: ts });
+      }
+    });
+    return accessed;
+  },
+});
+
+export const loadMessages = internalQuery({
+  args: {
+    worldId: v.id('worlds'),
+    conversationId,
+  },
+  handler: async (ctx, args): Promise<Doc<'messages'>[]> => {
+    const messages = await ctx.db
+      .query('messages')
+      .withIndex('conversationId', (q) =>
+        q.eq('worldId', args.worldId).eq('conversationId', args.conversationId),
+      )
+      .collect();
+    return messages;
+  },
+});
+
+async function calculateImportance(description: string) {
+  const { content: importanceRaw } = await chatCompletion({
+    messages: [
+      {
+        role: 'user',
+        content: `On the scale of 0 to 9, where 0 is purely mundane (e.g., brushing teeth, making bed) and 9 is extremely poignant (e.g., a break up, college acceptance), rate the likely poignancy of the following piece of memory.
+      Memory: ${description}
+      Answer on a scale of 0 to 9. Respond with number only, e.g. "5"`,
+      },
+    ],
+    temperature: 0.0,
+    max_tokens: 1,
+  });
+
+  let importance = parseFloat(importanceRaw);
+  if (isNaN(importance)) {
+    importance = +(importanceRaw.match(/\d+/)?.[0] ?? NaN);
+  }
+  if (isNaN(importance)) {
+    console.debug('Could not parse memory importance from: ', importanceRaw);
+    importance = 5;
+  }
+  return importance;
+}
+
+const { embeddingId: _embeddingId, ...memoryFieldsWithoutEmbeddingId } = memoryFields;
+
+export const insertMemory = internalMutation({
+  args: {
+    agentId,
+    embedding: v.array(v.float64()),
+    ...memoryFieldsWithoutEmbeddingId,
+  },
+  handler: async (ctx, { agentId: _, embedding, ...memory }): Promise<void> => {
+    const embeddingId = await ctx.db.insert('memoryEmbeddings', {
+      playerId: memory.playerId,
+      embedding,
+    });
+    await ctx.db.insert('memories', {
+      ...memory,
+      embeddingId,
+    });
+  },
+});
+
+export const insertReflectionMemories = internalMutation({
+  args: {
+    worldId: v.id('worlds'),
+    playerId,
+    reflections: v.array(
+      v.object({
+        description: v.string(),
+        relatedMemoryIds: v.array(v.id('memories')),
+        importance: v.number(),
+        embedding: v.array(v.float64()),
+      }),
+    ),
+  },
+  handler: async (ctx, { playerId, reflections }) => {
+    const lastAccess = Date.now();
+    for (const { embedding, relatedMemoryIds, ...rest } of reflections) {
+      const embeddingId = await ctx.db.insert('memoryEmbeddings', {
+        playerId,
+        embedding,
+      });
+      await ctx.db.insert('memories', {
+        playerId,
+        embeddingId,
+        lastAccess,
+        ...rest,
+        data: {
+          type: 'reflection',
+          relatedMemoryIds,
+        },
+      });
+    }
+  },
+});
+
+async function reflectOnMemories(
+  ctx: ActionCtx,
+  worldId: Id<'worlds'>,
+  playerId: GameId<'players'>,
+) {
+  const { memories, lastReflectionTs, name } = await ctx.runQuery(
+    internal.agent.memory.getReflectionMemories,
+    {
+      worldId,
+      playerId,
+      numberOfItems: 100,
+    },
+  );
+
+  // should only reflect if lastest 100 items have importance score of >500
+  const sumOfImportanceScore = memories
+    .filter((m) => m._creationTime > (lastReflectionTs ?? 0))
+    .reduce((acc, curr) => acc + curr.importance, 0);
+  const shouldReflect = sumOfImportanceScore > 500;
+
+  if (!shouldReflect) {
+    return false;
+  }
+  console.debug('sum of importance score = ', sumOfImportanceScore);
+  console.debug('Reflecting...');
+  const prompt = ['[no prose]', '[Output only JSON]', `You are ${name}, statements about you:`];
+  memories.forEach((m, idx) => {
+    prompt.push(`Statement ${idx}: ${m.description}`);
+  });
+  prompt.push('What 3 high-level insights can you infer from the above statements?');
+  prompt.push(
+    'Return in JSON format, where the key is a list of input statements that contributed to your insights and value is your insight. Make the response parseable by Typescript JSON.parse() function. DO NOT escape characters or include "\n" or white space in response.',
+  );
+  prompt.push(
+    'Example: [{insight: "...", statementIds: [1,2]}, {insight: "...", statementIds: [1]}, ...]',
+  );
+
+  const { content: reflection } = await chatCompletion({
+    messages: [
+      {
+        role: 'user',
+        content: prompt.join('\n'),
+      },
+    ],
+  });
+
+  try {
+    const insights = JSON.parse(reflection) as { insight: string; statementIds: number[] }[];
+    const memoriesToSave = await asyncMap(insights, async (item) => {
+      const relatedMemoryIds = item.statementIds.map((idx: number) => memories[idx]._id);
+      const importance = await calculateImportance(item.insight);
+      const { embedding } = await fetchEmbedding(item.insight);
+      console.debug('adding reflection memory...', item.insight);
+      return {
+        description: item.insight,
+        embedding,
+        importance,
+        relatedMemoryIds,
+      };
+    });
+
+    await ctx.runMutation(selfInternal.insertReflectionMemories, {
+      worldId,
+      playerId,
+      reflections: memoriesToSave,
+    });
+  } catch (e) {
+    console.error('error saving or parsing reflection', e);
+    console.debug('reflection', reflection);
+    return false;
+  }
+  return true;
+}
+export const getReflectionMemories = internalQuery({
+  args: { worldId: v.id('worlds'), playerId, numberOfItems: v.number() },
+  handler: async (ctx, args) => {
+    const world = await ctx.db.get(args.worldId);
+    if (!world) {
+      throw new Error(`World ${args.worldId} not found`);
+    }
+    const player = world.players.find((p) => p.id === args.playerId);
+    if (!player) {
+      throw new Error(`Player ${args.playerId} not found`);
+    }
+    const playerDescription = await ctx.db
+      .query('playerDescriptions')
+      .withIndex('worldId', (q) => q.eq('worldId', args.worldId).eq('playerId', args.playerId))
+      .first();
+    if (!playerDescription) {
+      throw new Error(`Player description for ${args.playerId} not found`);
+    }
+    const memories = await ctx.db
+      .query('memories')
+      .withIndex('playerId', (q) => q.eq('playerId', player.id))
+      .order('desc')
+      .take(args.numberOfItems);
+
+    const lastReflection = await ctx.db
+      .query('memories')
+      .withIndex('playerId_type', (q) =>
+        q.eq('playerId', args.playerId).eq('data.type', 'reflection'),
+      )
+      .order('desc')
+      .first();
+
+    return {
+      name: playerDescription.name,
+      memories,
+      lastReflectionTs: lastReflection?._creationTime,
+    };
+  },
+});
+
+export async function latestMemoryOfType<T extends MemoryType>(
+  db: DatabaseReader,
+  playerId: GameId<'players'>,
+  type: T,
+) {
+  const entry = await db
+    .query('memories')
+    .withIndex('playerId_type', (q) => q.eq('playerId', playerId).eq('data.type', type))
+    .order('desc')
+    .first();
+  if (!entry) return null;
+  return entry as MemoryOfType<T>;
+}

patches/convex/agent/schema.ts

@@ -0,0 +1,53 @@
+import { v } from 'convex/values';
+import { playerId, conversationId } from '../aiTown/ids';
+import { defineTable } from 'convex/server';
+import { LLM_CONFIG } from '../util/llm';
+
+export const memoryFields = {
+  playerId,
+  description: v.string(),
+  embeddingId: v.id('memoryEmbeddings'),
+  importance: v.number(),
+  lastAccess: v.number(),
+  data: v.union(
+    // Setting up dynamics between players
+    v.object({
+      type: v.literal('relationship'),
+      // The player this memory is about, from the perspective of the player
+      // whose memory this is.
+      playerId,
+    }),
+    v.object({
+      type: v.literal('conversation'),
+      conversationId,
+      // The other player(s) in the conversation.
+      playerIds: v.array(playerId),
+    }),
+    v.object({
+      type: v.literal('reflection'),
+      relatedMemoryIds: v.array(v.id('memories')),
+    }),
+  ),
+};
+export const memoryTables = {
+  memories: defineTable(memoryFields)
+    .index('embeddingId', ['embeddingId'])
+    .index('playerId_type', ['playerId', 'data.type'])
+    .index('playerId', ['playerId']),
+  memoryEmbeddings: defineTable({
+    playerId,
+    embedding: v.array(v.float64()),
+  }).vectorIndex('embedding', {
+    vectorField: 'embedding',
+    filterFields: ['playerId'],
+    dimensions: LLM_CONFIG.embeddingDimension,
+  }),
+};
+
+export const agentTables = {
+  ...memoryTables,
+  embeddingsCache: defineTable({
+    textHash: v.bytes(),
+    embedding: v.array(v.float64()),
+  }).index('text', ['textHash']),
+};

patches/convex/aiTown/agent.ts

@@ -0,0 +1,368 @@
+import { ObjectType, v } from 'convex/values';
+import { GameId, parseGameId } from './ids';
+import { agentId, conversationId, playerId } from './ids';
+import { serializedPlayer } from './player';
+import { Game } from './game';
+import {
+  ACTION_TIMEOUT,
+  AWKWARD_CONVERSATION_TIMEOUT,
+  CONVERSATION_COOLDOWN,
+  CONVERSATION_DISTANCE,
+  INVITE_ACCEPT_PROBABILITY,
+  INVITE_TIMEOUT,
+  MAX_CONVERSATION_DURATION,
+  MAX_CONVERSATION_MESSAGES,
+  MESSAGE_COOLDOWN,
+  MIDPOINT_THRESHOLD,
+  PLAYER_CONVERSATION_COOLDOWN,
+} from '../constants';
+import { FunctionArgs } from 'convex/server';
+import { MutationCtx, internalMutation, internalQuery } from '../_generated/server';
+import { distance } from '../util/geometry';
+import { internal } from '../_generated/api';
+import { movePlayer } from './movement';
+import { insertInput } from './insertInput';
+
+export class Agent {
+  id: GameId<'agents'>;
+  playerId: GameId<'players'>;
+  toRemember?: GameId<'conversations'>;
+  lastConversation?: number;
+  lastInviteAttempt?: number;
+  inProgressOperation?: {
+    name: string;
+    operationId: string;
+    started: number;
+  };
+
+  constructor(serialized: SerializedAgent) {
+    const { id, lastConversation, lastInviteAttempt, inProgressOperation } = serialized;
+    const playerId = parseGameId('players', serialized.playerId);
+    this.id = parseGameId('agents', id);
+    this.playerId = playerId;
+    this.toRemember =
+      serialized.toRemember !== undefined
+        ? parseGameId('conversations', serialized.toRemember)
+        : undefined;
+    this.lastConversation = lastConversation;
+    this.lastInviteAttempt = lastInviteAttempt;
+    this.inProgressOperation = inProgressOperation;
+  }
+
+  tick(game: Game, now: number) {
+    const player = game.world.players.get(this.playerId);
+    if (!player) {
+      throw new Error(`Invalid player ID ${this.playerId}`);
+    }
+    if (this.inProgressOperation) {
+      if (now < this.inProgressOperation.started + ACTION_TIMEOUT) {
+        // Wait on the operation to finish.
+        return;
+      }
+      console.log(`Timing out ${JSON.stringify(this.inProgressOperation)}`);
+      delete this.inProgressOperation;
+    }
+    const conversation = game.world.playerConversation(player);
+    const member = conversation?.participants.get(player.id);
+
+    const recentlyAttemptedInvite =
+      this.lastInviteAttempt && now < this.lastInviteAttempt + CONVERSATION_COOLDOWN;
+    const doingActivity = player.activity && player.activity.until > now;
+    if (doingActivity && (conversation || player.pathfinding)) {
+      player.activity!.until = now;
+    }
+    // If we're not in a conversation, do something.
+    // If we aren't doing an activity or moving, do something.
+    // If we have been wandering but haven't thought about something to do for
+    // a while, do something.
+    if (!conversation && !doingActivity && (!player.pathfinding || !recentlyAttemptedInvite)) {
+      this.startOperation(game, now, 'agentDoSomething', {
+        worldId: game.worldId,
+        player: player.serialize(),
+        otherFreePlayers: [...game.world.players.values()]
+          .filter((p) => p.id !== player.id)
+          .filter(
+            (p) => ![...game.world.conversations.values()].find((c) => c.participants.has(p.id)),
+          )
+          .map((p) => p.serialize()),
+        agent: this.serialize(),
+        map: game.worldMap.serialize(),
+      });
+      return;
+    }
+    // Check to see if we have a conversation we need to remember.
+    if (this.toRemember) {
+      // Fire off the action to remember the conversation.
+      console.log(`Agent ${this.id} remembering conversation ${this.toRemember}`);
+      this.startOperation(game, now, 'agentRememberConversation', {
+        worldId: game.worldId,
+        playerId: this.playerId,
+        agentId: this.id,
+        conversationId: this.toRemember,
+      });
+      delete this.toRemember;
+      return;
+    }
+    if (conversation && member) {
+      const [otherPlayerId, otherMember] = [...conversation.participants.entries()].find(
+        ([id]) => id !== player.id,
+      )!;
+      const otherPlayer = game.world.players.get(otherPlayerId)!;
+      if (member.status.kind === 'invited') {
+        // Accept a conversation with another agent with some probability and with
+        // a human unconditionally.
+        if (otherPlayer.human || Math.random() < INVITE_ACCEPT_PROBABILITY) {
+          console.log(`Agent ${player.id} accepting invite from ${otherPlayer.id}`);
+          conversation.acceptInvite(game, player);
+          // Stop moving so we can start walking towards the other player.
+          if (player.pathfinding) {
+            delete player.pathfinding;
+          }
+        } else {
+          console.log(`Agent ${player.id} rejecting invite from ${otherPlayer.id}`);
+          conversation.rejectInvite(game, now, player);
+        }
+        return;
+      }
+      if (member.status.kind === 'walkingOver') {
+        // Leave a conversation if we've been waiting for too long.
+        if (member.invited + INVITE_TIMEOUT < now) {
+          console.log(`Giving up on invite to ${otherPlayer.id}`);
+          conversation.leave(game, now, player);
+          return;
+        }
+
+        // Don't keep moving around if we're near enough.
+        const playerDistance = distance(player.position, otherPlayer.position);
+        if (playerDistance < CONVERSATION_DISTANCE) {
+          return;
+        }
+
+        // Keep moving towards the other player.
+        // If we're close enough to the player, just walk to them directly.
+        if (!player.pathfinding) {
+          let destination;
+          if (playerDistance < MIDPOINT_THRESHOLD) {
+            destination = {
+              x: Math.floor(otherPlayer.position.x),
+              y: Math.floor(otherPlayer.position.y),
+            };
+          } else {
+            destination = {
+              x: Math.floor((player.position.x + otherPlayer.position.x) / 2),
+              y: Math.floor((player.position.y + otherPlayer.position.y) / 2),
+            };
+          }
+          console.log(`Agent ${player.id} walking towards ${otherPlayer.id}...`, destination);
+          movePlayer(game, now, player, destination);
+        }
+        return;
+      }
+      if (member.status.kind === 'participating') {
+        const started = member.status.started;
+        if (conversation.isTyping && conversation.isTyping.playerId !== player.id) {
+          // Wait for the other player to finish typing.
+          return;
+        }
+        if (!conversation.lastMessage) {
+          const isInitiator = conversation.creator === player.id;
+          const awkwardDeadline = started + AWKWARD_CONVERSATION_TIMEOUT;
+          // Send the first message if we're the initiator or if we've been waiting for too long.
+          if (isInitiator || awkwardDeadline < now) {
+            // Grab the lock on the conversation and send a "start" message.
+            console.log(`${player.id} initiating conversation with ${otherPlayer.id}.`);
+            const messageUuid = crypto.randomUUID();
+            conversation.setIsTyping(now, player, messageUuid);
+            this.startOperation(game, now, 'agentGenerateMessage', {
+              worldId: game.worldId,
+              playerId: player.id,
+              agentId: this.id,
+              conversationId: conversation.id,
+              otherPlayerId: otherPlayer.id,
+              messageUuid,
+              type: 'start',
+            });
+            return;
+          } else {
+            // Wait on the other player to say something up to the awkward deadline.
+            return;
+          }
+        }
+        // See if the conversation has been going on too long and decide to leave.
+        const tooLongDeadline = started + MAX_CONVERSATION_DURATION;
+        if (tooLongDeadline < now || conversation.numMessages > MAX_CONVERSATION_MESSAGES) {
+          console.log(`${player.id} leaving conversation with ${otherPlayer.id}.`);
+          const messageUuid = crypto.randomUUID();
+          conversation.setIsTyping(now, player, messageUuid);
+          this.startOperation(game, now, 'agentGenerateMessage', {
+            worldId: game.worldId,
+            playerId: player.id,
+            agentId: this.id,
+            conversationId: conversation.id,
+            otherPlayerId: otherPlayer.id,
+            messageUuid,
+            type: 'leave',
+          });
+          return;
+        }
+        // Wait for the awkward deadline if we sent the last message.
+        if (conversation.lastMessage.author === player.id) {
+          const awkwardDeadline = conversation.lastMessage.timestamp + AWKWARD_CONVERSATION_TIMEOUT;
+          if (now < awkwardDeadline) {
+            return;
+          }
+        }
+        // Wait for a cooldown after the last message to simulate "reading" the message.
+        const messageCooldown = conversation.lastMessage.timestamp + MESSAGE_COOLDOWN;
+        if (now < messageCooldown) {
+          return;
+        }
+        // Grab the lock and send a message!
+        console.log(`${player.id} continuing conversation with ${otherPlayer.id}.`);
+        const messageUuid = crypto.randomUUID();
+        conversation.setIsTyping(now, player, messageUuid);
+        this.startOperation(game, now, 'agentGenerateMessage', {
+          worldId: game.worldId,
+          playerId: player.id,
+          agentId: this.id,
+          conversationId: conversation.id,
+          otherPlayerId: otherPlayer.id,
+          messageUuid,
+          type: 'continue',
+        });
+        return;
+      }
+    }
+  }
+
+  startOperation<Name extends keyof AgentOperations>(
+    game: Game,
+    now: number,
+    name: Name,
+    args: Omit<FunctionArgs<AgentOperations[Name]>, 'operationId'>,
+  ) {
+    if (this.inProgressOperation) {
+      throw new Error(
+        `Agent ${this.id} already has an operation: ${JSON.stringify(this.inProgressOperation)}`,
+      );
+    }
+    const operationId = game.allocId('operations');
+    console.log(`Agent ${this.id} starting operation ${name} (${operationId})`);
+    game.scheduleOperation(name, { operationId, ...args } as any);
+    this.inProgressOperation = {
+      name,
+      operationId,
+      started: now,
+    };
+  }
+
+  serialize(): SerializedAgent {
+    return {
+      id: this.id,
+      playerId: this.playerId,
+      toRemember: this.toRemember,
+      lastConversation: this.lastConversation,
+      lastInviteAttempt: this.lastInviteAttempt,
+      inProgressOperation: this.inProgressOperation,
+    };
+  }
+}
+
+export const serializedAgent = {
+  id: agentId,
+  playerId: playerId,
+  toRemember: v.optional(conversationId),
+  lastConversation: v.optional(v.number()),
+  lastInviteAttempt: v.optional(v.number()),
+  inProgressOperation: v.optional(
+    v.object({
+      name: v.string(),
+      operationId: v.string(),
+      started: v.number(),
+    }),
+  ),
+};
+export type SerializedAgent = ObjectType<typeof serializedAgent>;
+
+type AgentOperations = typeof internal.aiTown.agentOperations;
+
+export async function runAgentOperation(ctx: MutationCtx, operation: string, args: any) {
+  let reference;
+  switch (operation) {
+    case 'agentRememberConversation':
+      reference = internal.aiTown.agentOperations.agentRememberConversation;
+      break;
+    case 'agentGenerateMessage':
+      reference = internal.aiTown.agentOperations.agentGenerateMessage;
+      break;
+    case 'agentDoSomething':
+      reference = internal.aiTown.agentOperations.agentDoSomething;
+      break;
+    default:
+      throw new Error(`Unknown operation: ${operation}`);
+  }
+  await ctx.scheduler.runAfter(0, reference, args);
+}
+
+export const agentSendMessage = internalMutation({
+  args: {
+    worldId: v.id('worlds'),
+    conversationId,
+    agentId,
+    playerId,
+    text: v.string(),
+    messageUuid: v.string(),
+    leaveConversation: v.boolean(),
+    operationId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    await ctx.db.insert('messages', {
+      conversationId: args.conversationId,
+      author: args.playerId,
+      text: args.text,
+      messageUuid: args.messageUuid,
+      worldId: args.worldId,
+    });
+    await insertInput(ctx, args.worldId, 'agentFinishSendingMessage', {
+      conversationId: args.conversationId,
+      agentId: args.agentId,
+      timestamp: Date.now(),
+      leaveConversation: args.leaveConversation,
+      operationId: args.operationId,
+    });
+  },
+});
+
+export const findConversationCandidate = internalQuery({
+  args: {
+    now: v.number(),
+    worldId: v.id('worlds'),
+    player: v.object(serializedPlayer),
+    otherFreePlayers: v.array(v.object(serializedPlayer)),
+  },
+  handler: async (ctx, { now, worldId, player, otherFreePlayers }) => {
+    const { position } = player;
+    const candidates = [];
+
+    for (const otherPlayer of otherFreePlayers) {
+      // Find the latest conversation we're both members of.
+      const lastMember = await ctx.db
+        .query('participatedTogether')
+        .withIndex('edge', (q) =>
+          q.eq('worldId', worldId).eq('player1', player.id).eq('player2', otherPlayer.id),
+        )
+        .order('desc')
+        .first();
+      if (lastMember) {
+        if (now < lastMember.ended + PLAYER_CONVERSATION_COOLDOWN) {
+          continue;
+        }
+      }
+      candidates.push({ id: otherPlayer.id, position });
+    }
+
+    // Sort by distance and take the nearest candidate.
+    candidates.sort((a, b) => distance(a.position, position) - distance(b.position, position));
+    return candidates[0]?.id;
+  },
+});

patches/convex/aiTown/agentDescription.ts

@@ -0,0 +1,27 @@
+import { ObjectType, v } from 'convex/values';
+import { GameId, agentId, parseGameId } from './ids';
+
+export class AgentDescription {
+  agentId: GameId<'agents'>;
+  identity: string;
+  plan: string;
+
+  constructor(serialized: SerializedAgentDescription) {
+    const { agentId, identity, plan } = serialized;
+    this.agentId = parseGameId('agents', agentId);
+    this.identity = identity;
+    this.plan = plan;
+  }
+
+  serialize(): SerializedAgentDescription {
+    const { agentId, identity, plan } = this;
+    return { agentId, identity, plan };
+  }
+}
+
+export const serializedAgentDescription = {
+  agentId,
+  identity: v.string(),
+  plan: v.string(),
+};
+export type SerializedAgentDescription = ObjectType<typeof serializedAgentDescription>;

patches/convex/aiTown/agentInputs.ts

@@ -0,0 +1,155 @@
+import { v } from 'convex/values';
+import { agentId, conversationId, parseGameId } from './ids';
+import { Player, activity } from './player';
+import { Conversation, conversationInputs } from './conversation';
+import { movePlayer } from './movement';
+import { inputHandler } from './inputHandler';
+import { point } from '../util/types';
+import { Descriptions } from '../../data/characters';
+import { AgentDescription } from './agentDescription';
+import { Agent } from './agent';
+
+export const agentInputs = {
+  finishRememberConversation: inputHandler({
+    args: {
+      operationId: v.string(),
+      agentId,
+    },
+    handler: (game, now, args) => {
+      const agentId = parseGameId('agents', args.agentId);
+      const agent = game.world.agents.get(agentId);
+      if (!agent) {
+        throw new Error(`Couldn't find agent: ${agentId}`);
+      }
+      if (
+        !agent.inProgressOperation ||
+        agent.inProgressOperation.operationId !== args.operationId
+      ) {
+        console.debug(`Agent ${agentId} isn't remembering ${args.operationId}`);
+      } else {
+        delete agent.inProgressOperation;
+        delete agent.toRemember;
+      }
+      return null;
+    },
+  }),
+  finishDoSomething: inputHandler({
+    args: {
+      operationId: v.string(),
+      agentId: v.id('agents'),
+      destination: v.optional(point),
+      invitee: v.optional(v.id('players')),
+      activity: v.optional(activity),
+    },
+    handler: (game, now, args) => {
+      const agentId = parseGameId('agents', args.agentId);
+      const agent = game.world.agents.get(agentId);
+      if (!agent) {
+        throw new Error(`Couldn't find agent: ${agentId}`);
+      }
+      if (
+        !agent.inProgressOperation ||
+        agent.inProgressOperation.operationId !== args.operationId
+      ) {
+        console.debug(`Agent ${agentId} didn't have ${args.operationId} in progress`);
+        return null;
+      }
+      delete agent.inProgressOperation;
+      const player = game.world.players.get(agent.playerId)!;
+      if (args.invitee) {
+        const inviteeId = parseGameId('players', args.invitee);
+        const invitee = game.world.players.get(inviteeId);
+        if (!invitee) {
+          throw new Error(`Couldn't find player: ${inviteeId}`);
+        }
+        Conversation.start(game, now, player, invitee);
+        agent.lastInviteAttempt = now;
+      }
+      if (args.destination) {
+        movePlayer(game, now, player, args.destination);
+      }
+      if (args.activity) {
+        player.activity = args.activity;
+      }
+      return null;
+    },
+  }),
+  agentFinishSendingMessage: inputHandler({
+    args: {
+      agentId,
+      conversationId,
+      timestamp: v.number(),
+      operationId: v.string(),
+      leaveConversation: v.boolean(),
+    },
+    handler: (game, now, args) => {
+      const agentId = parseGameId('agents', args.agentId);
+      const agent = game.world.agents.get(agentId);
+      if (!agent) {
+        throw new Error(`Couldn't find agent: ${agentId}`);
+      }
+      const player = game.world.players.get(agent.playerId);
+      if (!player) {
+        throw new Error(`Couldn't find player: ${agent.playerId}`);
+      }
+      const conversationId = parseGameId('conversations', args.conversationId);
+      const conversation = game.world.conversations.get(conversationId);
+      if (!conversation) {
+        throw new Error(`Couldn't find conversation: ${conversationId}`);
+      }
+      if (
+        !agent.inProgressOperation ||
+        agent.inProgressOperation.operationId !== args.operationId
+      ) {
+        console.debug(`Agent ${agentId} wasn't sending a message ${args.operationId}`);
+        return null;
+      }
+      delete agent.inProgressOperation;
+      conversationInputs.finishSendingMessage.handler(game, now, {
+        playerId: agent.playerId,
+        conversationId: args.conversationId,
+        timestamp: args.timestamp,
+      });
+      if (args.leaveConversation) {
+        conversation.leave(game, now, player);
+      }
+      return null;
+    },
+  }),
+  createAgent: inputHandler({
+    args: {
+      descriptionIndex: v.number(),
+    },
+    handler: (game, now, args) => {
+      const description = Descriptions[args.descriptionIndex];
+      const playerId = Player.join(
+        game,
+        now,
+        description.name,
+        description.character,
+        description.identity,
+      );
+      const agentId = game.allocId('agents');
+      game.world.agents.set(
+        agentId,
+        new Agent({
+          id: agentId,
+          playerId: playerId,
+          inProgressOperation: undefined,
+          lastConversation: undefined,
+          lastInviteAttempt: undefined,
+          toRemember: undefined,
+        }),
+      );
+      game.agentDescriptions.set(
+        agentId,
+        new AgentDescription({
+          agentId: agentId,
+          identity: description.identity,
+          plan: description.plan,
+        }),
+      );
+      return { agentId };
+    },
+  }),
+};

patches/convex/aiTown/agentOperations.ts

@@ -0,0 +1,182 @@
+'use node';
+
+import { v } from 'convex/values';
+import { internalAction } from '../_generated/server';
+import { WorldMap, serializedWorldMap } from './worldMap';
+import { rememberConversation } from '../agent/memory';
+import { GameId, agentId, conversationId, playerId } from './ids';
+import {
+  continueConversationMessage,
+  leaveConversationMessage,
+  startConversationMessage,
+} from '../agent/conversation';
+import { assertNever } from '../util/assertNever';
+import { serializedAgent } from './agent';
+import { ACTIVITIES, ACTIVITY_COOLDOWN, CONVERSATION_COOLDOWN } from '../constants';
+import { api, internal } from '../_generated/api';
+import { sleep } from '../util/sleep';
+import { serializedPlayer } from './player';
+
+export const agentRememberConversation = internalAction({
+  args: {
+    worldId: v.id('worlds'),
+    playerId,
+    agentId,
+    conversationId,
+    operationId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    await rememberConversation(
+      ctx,
+      args.worldId,
+      args.agentId as GameId<'agents'>,
+      args.playerId as GameId<'players'>,
+      args.conversationId as GameId<'conversations'>,
+    );
+    await sleep(Math.random() * 1000);
+    await ctx.runMutation(api.aiTown.main.sendInput, {
+      worldId: args.worldId,
+      name: 'finishRememberConversation',
+      args: {
+        agentId: args.agentId,
+        operationId: args.operationId,
+      },
+    });
+  },
+});
+
+export const agentGenerateMessage = internalAction({
+  args: {
+    worldId: v.id('worlds'),
+    playerId,
+    agentId,
+    conversationId,
+    otherPlayerId: playerId,
+    operationId: v.string(),
+    type: v.union(v.literal('start'), v.literal('continue'), v.literal('leave')),
+    messageUuid: v.string(),
+  },
+  handler: async (ctx, args) => {
+    let completionFn;
+    switch (args.type) {
+      case 'start':
+        completionFn = startConversationMessage;
+        break;
+      case 'continue':
+        completionFn = continueConversationMessage;
+        break;
+      case 'leave':
+        completionFn = leaveConversationMessage;
+        break;
+      default:
+        assertNever(args.type);
+    }
+    const completion = await completionFn(
+      ctx,
+      args.worldId,
+      args.conversationId as GameId<'conversations'>,
+      args.playerId as GameId<'players'>,
+      args.otherPlayerId as GameId<'players'>,
+    );
+    // TODO: stream in the text instead of reading it all at once.
+    const text = await completion.readAll();
+
+    await ctx.runMutation(internal.aiTown.agent.agentSendMessage, {
+      worldId: args.worldId,
+      conversationId: args.conversationId,
+      agentId: args.agentId,
+      playerId: args.playerId,
+      text,
+      messageUuid: args.messageUuid,
+      leaveConversation: args.type === 'leave',
+      operationId: args.operationId,
+    });
+  },
+});
+
+export const agentDoSomething = internalAction({
+  args: {
+    worldId: v.id('worlds'),
+    player: v.object(serializedPlayer),
+    agent: v.object(serializedAgent),
+    map: v.object(serializedWorldMap),
+    otherFreePlayers: v.array(v.object(serializedPlayer)),
+    operationId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const { player, agent } = args;
+    const map = new WorldMap(args.map);
+    const now = Date.now();
+    // Don't try to start a new conversation if we were just in one.
+    const justLeftConversation =
+      agent.lastConversation && now < agent.lastConversation + CONVERSATION_COOLDOWN;
+    // Don't try again if we recently tried to find someone to invite.
+    const recentlyAttemptedInvite =
+      agent.lastInviteAttempt && now < agent.lastInviteAttempt + CONVERSATION_COOLDOWN;
+    const recentActivity = player.activity && now < player.activity.until + ACTIVITY_COOLDOWN;
+    // Decide whether to do an activity or wander somewhere.
+    if (!player.pathfinding) {
+      if (recentActivity || justLeftConversation) {
+        await sleep(Math.random() * 1000);
+        await ctx.runMutation(api.aiTown.main.sendInput, {
+          worldId: args.worldId,
+          name: 'finishDoSomething',
+          args: {
+            operationId: args.operationId,
+            agentId: agent.id,
+            destination: wanderDestination(map),
+          },
+        });
+        return;
+      } else {
+        // TODO: have LLM choose the activity & emoji
+        const activity = ACTIVITIES[Math.floor(Math.random() * ACTIVITIES.length)];
+        await sleep(Math.random() * 1000);
+        await ctx.runMutation(api.aiTown.main.sendInput, {
+          worldId: args.worldId,
+          name: 'finishDoSomething',
+          args: {
+            operationId: args.operationId,
+            agentId: agent.id,
+            activity: {
+              description: activity.description,
+              emoji: activity.emoji,
+              until: Date.now() + activity.duration,
+            },
+          },
+        });
+        return;
+      }
+    }
+    const invitee =
+      justLeftConversation || recentlyAttemptedInvite
+        ? undefined
+        : await ctx.runQuery(internal.aiTown.agent.findConversationCandidate, {
+            now,
+            worldId: args.worldId,
+            player: args.player,
+            otherFreePlayers: args.otherFreePlayers,
+          });
+
+    // TODO: We hit a lot of OCC errors on sending inputs in this file. It's
+    // easy for them to get scheduled at the same time and line up in time.
+    await sleep(Math.random() * 1000);
+    await ctx.runMutation(api.aiTown.main.sendInput, {
+      worldId: args.worldId,
+      name: 'finishDoSomething',
+      args: {
+        operationId: args.operationId,
+        agentId: args.agent.id,
+        invitee,
+      },
+    });
+  },
+});
+
+function wanderDestination(worldMap: WorldMap) {
+  // Wander someonewhere at least one tile away from the edge.
+  return {
+    x: 1 + Math.floor(Math.random() * (worldMap.width - 2)),
+    y: 1 + Math.floor(Math.random() * (worldMap.height - 2)),
+  };
+}

patches/convex/aiTown/conversation.ts

@@ -0,0 +1,395 @@
+import { ObjectType, v } from 'convex/values';
+import { GameId, parseGameId } from './ids';
+import { conversationId, playerId } from './ids';
+import { Player } from './player';
+import { inputHandler } from './inputHandler';
+
+import { TYPING_TIMEOUT, CONVERSATION_DISTANCE } from '../constants';
+import { distance, normalize, vector } from '../util/geometry';
+import { Point } from '../util/types';
+import { Game } from './game';
+import { stopPlayer, blocked, movePlayer } from './movement';
+import { ConversationMembership, serializedConversationMembership } from './conversationMembership';
+import { parseMap, serializeMap } from '../util/object';
+
+export class Conversation {
+  id: GameId<'conversations'>;
+  creator: GameId<'players'>;
+  created: number;
+  isTyping?: {
+    playerId: GameId<'players'>;
+    messageUuid: string;
+    since: number;
+  };
+  lastMessage?: {
+    author: GameId<'players'>;
+    timestamp: number;
+  };
+  numMessages: number;
+  participants: Map<GameId<'players'>, ConversationMembership>;
+
+  constructor(serialized: SerializedConversation) {
+    const { id, creator, created, isTyping, lastMessage, numMessages, participants } = serialized;
+    this.id = parseGameId('conversations', id);
+    this.creator = parseGameId('players', creator);
+    this.created = created;
+    this.isTyping = isTyping && {
+      playerId: parseGameId('players', isTyping.playerId),
+      messageUuid: isTyping.messageUuid,
+      since: isTyping.since,
+    };
+    this.lastMessage = lastMessage && {
+      author: parseGameId('players', lastMessage.author),
+      timestamp: lastMessage.timestamp,
+    };
+    this.numMessages = numMessages;
+    this.participants = parseMap(participants, ConversationMembership, (m) => m.playerId);
+  }
+
+  tick(game: Game, now: number) {
+    if (this.isTyping && this.isTyping.since + TYPING_TIMEOUT < now) {
+      delete this.isTyping;
+    }
+    if (this.participants.size !== 2) {
+      console.warn(`Conversation ${this.id} has ${this.participants.size} participants`);
+      return;
+    }
+    const [playerId1, playerId2] = [...this.participants.keys()];
+    const member1 = this.participants.get(playerId1)!;
+    const member2 = this.participants.get(playerId2)!;
+
+    const player1 = game.world.players.get(playerId1)!;
+    const player2 = game.world.players.get(playerId2)!;
+
+    const playerDistance = distance(player1?.position, player2?.position);
+
+    // If the players are both in the "walkingOver" state and they're sufficiently close, transition both
+    // of them to "participating" and stop their paths.
+    if (member1.status.kind === 'walkingOver' && member2.status.kind === 'walkingOver') {
+      if (playerDistance < CONVERSATION_DISTANCE) {
+        console.log(`Starting conversation between ${player1.id} and ${player2.id}`);
+
+        // First, stop the two players from moving.
+        stopPlayer(player1);
+        stopPlayer(player2);
+
+        member1.status = { kind: 'participating', started: now };
+        member2.status = { kind: 'participating', started: now };
+
+        // Try to move the first player to grid point nearest the other player.
+        const neighbors = (p: Point) => [
+          { x: p.x + 1, y: p.y },
+          { x: p.x - 1, y: p.y },
+          { x: p.x, y: p.y + 1 },
+          { x: p.x, y: p.y - 1 },
+        ];
+        const floorPos1 = { x: Math.floor(player1.position.x), y: Math.floor(player1.position.y) };
+        const p1Candidates = neighbors(floorPos1).filter((p) => !blocked(game, now, p, player1.id));
+        p1Candidates.sort((a, b) => distance(a, player2.position) - distance(b, player2.position));
+        if (p1Candidates.length > 0) {
+          const p1Candidate = p1Candidates[0];
+
+          // Try to move the second player to the grid point nearest the first player's
+          // destination.
+          const p2Candidates = neighbors(p1Candidate).filter(
+            (p) => !blocked(game, now, p, player2.id),
+          );
+          p2Candidates.sort(
+            (a, b) => distance(a, player2.position) - distance(b, player2.position),
+          );
+          if (p2Candidates.length > 0) {
+            const p2Candidate = p2Candidates[0];
+            movePlayer(game, now, player1, p1Candidate, true);
+            movePlayer(game, now, player2, p2Candidate, true);
+          }
+        }
+      }
+    }
+
+    // Orient the two players towards each other if they're not moving.
+    if (member1.status.kind === 'participating' && member2.status.kind === 'participating') {
+      const v = normalize(vector(player1.position, player2.position));
+      if (!player1.pathfinding && v) {
+        player1.facing = v;
+      }
+      if (!player2.pathfinding && v) {
+        player2.facing.dx = -v.dx;
+        player2.facing.dy = -v.dy;
+      }
+    }
+  }
+
+  static start(game: Game, now: number, player: Player, invitee: Player) {
+    if (player.id === invitee.id) {
+      throw new Error(`Can't invite yourself to a conversation`);
+    }
+    // Ensure the players still exist.
+    if ([...game.world.conversations.values()].find((c) => c.participants.has(player.id))) {
+      const reason = `Player ${player.id} is already in a conversation`;
+      console.log(reason);
+      return { error: reason };
+    }
+    if ([...game.world.conversations.values()].find((c) => c.participants.has(invitee.id))) {
+      const reason = `Player ${player.id} is already in a conversation`;
+      console.log(reason);
+      return { error: reason };
+    }
+    const conversationId = game.allocId('conversations');
+    console.log(`Creating conversation ${conversationId}`);
+    game.world.conversations.set(
+      conversationId,
+      new Conversation({
+        id: conversationId,
+        created: now,
+        creator: player.id,
+        numMessages: 0,
+        participants: [
+          { playerId: player.id, invited: now, status: { kind: 'walkingOver' } },
+          { playerId: invitee.id, invited: now, status: { kind: 'invited' } },
+        ],
+      }),
+    );
+    return { conversationId };
+  }
+
+  setIsTyping(now: number, player: Player, messageUuid: string) {
+    if (this.isTyping) {
+      if (this.isTyping.playerId !== player.id) {
+        throw new Error(`Player ${this.isTyping.playerId} is already typing in ${this.id}`);
+      }
+      return;
+    }
+    this.isTyping = { playerId: player.id, messageUuid, since: now };
+  }
+
+  acceptInvite(game: Game, player: Player) {
+    const member = this.participants.get(player.id);
+    if (!member) {
+      throw new Error(`Player ${player.id} not in conversation ${this.id}`);
+    }
+    if (member.status.kind !== 'invited') {
+      throw new Error(
+        `Invalid membership status for ${player.id}:${this.id}: ${JSON.stringify(member)}`,
+      );
+    }
+    member.status = { kind: 'walkingOver' };
+  }
+
+  rejectInvite(game: Game, now: number, player: Player) {
+    const member = this.participants.get(player.id);
+    if (!member) {
+      throw new Error(`Player ${player.id} not in conversation ${this.id}`);
+    }
+    if (member.status.kind !== 'invited') {
+      throw new Error(
+        `Rejecting invite in wrong membership state: ${this.id}:${player.id}: ${JSON.stringify(
+          member,
+        )}`,
+      );
+    }
+    this.stop(game, now);
+  }
+
+  stop(game: Game, now: number) {
+    delete this.isTyping;
+    for (const [playerId, member] of this.participants.entries()) {
+      const agent = [...game.world.agents.values()].find((a) => a.playerId === playerId);
+      if (agent) {
+        agent.lastConversation = now;
+        agent.toRemember = this.id;
+      }
+    }
+    game.world.conversations.delete(this.id);
+  }
+
+  leave(game: Game, now: number, player: Player) {
+    const member = this.participants.get(player.id);
+    if (!member) {
+      throw new Error(`Couldn't find membership for ${this.id}:${player.id}`);
+    }
+    this.stop(game, now);
+  }
+
+  serialize(): SerializedConversation {
+    const { id, creator, created, isTyping, lastMessage, numMessages } = this;
+    return {
+      id,
+      creator,
+      created,
+      isTyping,
+      lastMessage,
+      numMessages,
+      participants: serializeMap(this.participants),
+    };
+  }
+}
+
+export const serializedConversation = {
+  id: conversationId,
+  creator: playerId,
+  created: v.number(),
+  isTyping: v.optional(
+    v.object({
+      playerId,
+      messageUuid: v.string(),
+      since: v.number(),
+    }),
+  ),
+  lastMessage: v.optional(
+    v.object({
+      author: playerId,
+      timestamp: v.number(),
+    }),
+  ),
+  numMessages: v.number(),
+  participants: v.array(v.object(serializedConversationMembership)),
+};
+export type SerializedConversation = ObjectType<typeof serializedConversation>;
+
+export const conversationInputs = {
+  // Start a conversation, inviting the specified player.
+  // Conversations can only have two participants for now,
+  // so we don't have a separate "invite" input.
+  startConversation: inputHandler({
+    args: {
+      playerId,
+      invitee: playerId,
+    },
+    handler: (game: Game, now: number, args): GameId<'conversations'> => {
+      const playerId = parseGameId('players', args.playerId);
+      const player = game.world.players.get(playerId);
+      if (!player) {
+        throw new Error(`Invalid player ID: ${playerId}`);
+      }
+      const inviteeId = parseGameId('players', args.invitee);
+      const invitee = game.world.players.get(inviteeId);
+      if (!invitee) {
+        throw new Error(`Invalid player ID: ${inviteeId}`);
+      }
+      console.log(`Starting ${playerId} ${inviteeId}...`);
+      const { conversationId, error } = Conversation.start(game, now, player, invitee);
+      if (!conversationId) {
+        // TODO: pass it back to the client for them to show an error.
+        throw new Error(error);
+      }
+      return conversationId;
+    },
+  }),
+
+  startTyping: inputHandler({
+    args: {
+      playerId,
+      conversationId,
+      messageUuid: v.string(),
+    },
+    handler: (game: Game, now: number, args): null => {
+      const playerId = parseGameId('players', args.playerId);
+      const player = game.world.players.get(playerId);
+      if (!player) {
+        throw new Error(`Invalid player ID: ${playerId}`);
+      }
+      const conversationId = parseGameId('conversations', args.conversationId);
+      const conversation = game.world.conversations.get(conversationId);
+      if (!conversation) {
+        throw new Error(`Invalid conversation ID: ${conversationId}`);
+      }
+      if (conversation.isTyping && conversation.isTyping.playerId !== playerId) {
+        throw new Error(
+          `Player ${conversation.isTyping.playerId} is already typing in ${conversationId}`,
+        );
+      }
+      conversation.isTyping = { playerId, messageUuid: args.messageUuid, since: now };
+      return null;
+    },
+  }),
+
+  finishSendingMessage: inputHandler({
+    args: {
+      playerId,
+      conversationId,
+      timestamp: v.number(),
+    },
+    handler: (game: Game, now: number, args): null => {
+      const playerId = parseGameId('players', args.playerId);
+      const conversationId = parseGameId('conversations', args.conversationId);
+      const conversation = game.world.conversations.get(conversationId);
+      if (!conversation) {
+        throw new Error(`Invalid conversation ID: ${conversationId}`);
+      }
+      if (conversation.isTyping && conversation.isTyping.playerId === playerId) {
+        delete conversation.isTyping;
+      }
+      conversation.lastMessage = { author: playerId, timestamp: args.timestamp };
+      conversation.numMessages++;
+      return null;
+    },
+  }),
+
+  // Accept an invite to a conversation, which puts the
+  // player in the "walkingOver" state until they're close
+  // enough to the other participant.
+  acceptInvite: inputHandler({
+    args: {
+      playerId,
+      conversationId,
+    },
+    handler: (game: Game, now: number, args): null => {
+      const playerId = parseGameId('players', args.playerId);
+      const player = game.world.players.get(playerId);
+      if (!player) {
+        throw new Error(`Invalid player ID ${playerId}`);
+      }
+      const conversationId = parseGameId('conversations', args.conversationId);
+      const conversation = game.world.conversations.get(conversationId);
+      if (!conversation) {
+        throw new Error(`Invalid conversation ID ${conversationId}`);
+      }
+      conversation.acceptInvite(game, player);
+      return null;
+    },
+  }),
+
+  // Reject the invite. Eventually we might add a message
+  // that explains why!
+  rejectInvite: inputHandler({
+    args: {
+      playerId,
+      conversationId,
+    },
+    handler: (game: Game, now: number, args): null => {
+      const playerId = parseGameId('players', args.playerId);
+      const player = game.world.players.get(playerId);
+      if (!player) {
+        throw new Error(`Invalid player ID ${playerId}`);
+      }
+      const conversationId = parseGameId('conversations', args.conversationId);
+      const conversation = game.world.conversations.get(conversationId);
+      if (!conversation) {
+        throw new Error(`Invalid conversation ID ${conversationId}`);
+      }
+      conversation.rejectInvite(game, now, player);
+      return null;
+    },
+  }),
+  // Leave a conversation.
+  leaveConversation: inputHandler({
+    args: {
+      playerId,
+      conversationId,
+    },
+    handler: (game: Game, now: number, args): null => {
+      const playerId = parseGameId('players', args.playerId);
+      const player = game.world.players.get(playerId);
+      if (!player) {
+        throw new Error(`Invalid player ID ${playerId}`);
+      }
+      const conversationId = parseGameId('conversations', args.conversationId);
+      const conversation = game.world.conversations.get(conversationId);
+      if (!conversation) {
+        throw new Error(`Invalid conversation ID ${conversationId}`);
+      }
+      conversation.leave(game, now, player);
+      return null;
+    },
+  }),
+};

patches/convex/aiTown/conversationMembership.ts

@@ -0,0 +1,38 @@
+import { ObjectType, v } from 'convex/values';
+import { GameId, parseGameId, playerId } from './ids';
+
+export const serializedConversationMembership = {
+  playerId,
+  invited: v.number(),
+  status: v.union(
+    v.object({ kind: v.literal('invited') }),
+    v.object({ kind: v.literal('walkingOver') }),
+    v.object({ kind: v.literal('participating'), started: v.number() }),
+  ),
+};
+export type SerializedConversationMembership = ObjectType<typeof serializedConversationMembership>;
+
+export class ConversationMembership {
+  playerId: GameId<'players'>;
+  invited: number;
+  status:
+    | { kind: 'invited' }
+    | { kind: 'walkingOver' }
+    | { kind: 'participating'; started: number };
+
+  constructor(serialized: SerializedConversationMembership) {
+    const { playerId, invited, status } = serialized;
+    this.playerId = parseGameId('players', playerId);
+    this.invited = invited;
+    this.status = status;
+  }
+
+  serialize(): SerializedConversationMembership {
+    const { playerId, invited, status } = this;
+    return {
+      playerId,
+      invited,
+      status,
+    };
+  }
+}

patches/convex/aiTown/dayNightCycle.ts

@@ -0,0 +1,71 @@
+import { v, Infer, ObjectType } from 'convex/values';
+import { Game } from './game';
+
+// Define the schema for DayNightCycle
+export const dayNightCycleSchema = {
+  currentTime: v.number(),
+  isDay: v.boolean(),
+  dayDuration: v.number(),
+  nightDuration: v.number(),
+};
+export type SerializedDayNightCycle = ObjectType<typeof dayNightCycleSchema>;
+
+export class DayNightCycle {
+  currentTime: number;
+  isDay: boolean;
+  dayDuration: number;
+  nightDuration: number;
+
+  constructor(serialized: SerializedDayNightCycle) {
+    const { currentTime, isDay, dayDuration, nightDuration } = serialized;
+    this.currentTime = currentTime;
+    this.isDay = isDay;
+    this.dayDuration = dayDuration;
+    this.nightDuration = nightDuration;
+  }
+
+  // Tick method to increment the counter
+  tick(game: Game, tickDuration: number) {
+    this.currentTime += tickDuration;
+
+    if (this.isDay && this.currentTime >= this.dayDuration) {
+      this.isDay = false;
+      this.currentTime = 0;
+      this.onNightStart(game);
+    } else if (!this.isDay && this.currentTime >= this.nightDuration) {
+      this.isDay = true;
+      this.currentTime = 0;
+      this.onDayStart(game);
+    }
+  }
+
+  onDayStart(game: Game) {
+    console.log("Day has started!");
+    for (const player of game.world.players.values()) {
+      // player.onDayStart(game);
+    }
+    for (const agent of game.world.agents.values()) {
+      // agent.onDayStart(game);
+    }
+  }
+
+  onNightStart(game: Game) {
+    console.log("Night has started!");
+    for (const player of game.world.players.values()) {
+      // player.onNightStart(game);
+    }
+    for (const agent of game.world.agents.values()) {
+      // agent.onNightStart(game);
+    }
+  }
+
+  serialize(): SerializedDayNightCycle {
+    const { currentTime, isDay, dayDuration, nightDuration } = this;
+    return {
+      currentTime,
+      isDay,
+      dayDuration,
+      nightDuration,
+    };
+  }
+}

patches/convex/aiTown/game.ts

@@ -0,0 +1,374 @@
+import { Infer, v } from 'convex/values';
+import { Doc, Id } from '../_generated/dataModel';
+import {
+  ActionCtx,
+  DatabaseReader,
+  MutationCtx,
+  internalMutation,
+  internalQuery,
+} from '../_generated/server';
+import { World, serializedWorld } from './world';
+import { WorldMap, serializedWorldMap } from './worldMap';
+import { PlayerDescription, serializedPlayerDescription } from './playerDescription';
+import { Location, locationFields, playerLocation } from './location';
+import { runAgentOperation } from './agent';
+import { GameId, IdTypes, allocGameId } from './ids';
+import { InputArgs, InputNames, inputs } from './inputs';
+import {
+  AbstractGame,
+  EngineUpdate,
+  applyEngineUpdate,
+  engineUpdate,
+  loadEngine,
+} from '../engine/abstractGame';
+import { internal } from '../_generated/api';
+import { HistoricalObject } from '../engine/historicalObject';
+import { AgentDescription, serializedAgentDescription } from './agentDescription';
+import { parseMap, serializeMap } from '../util/object';
+
+const gameState = v.object({
+  world: v.object(serializedWorld),
+  playerDescriptions: v.array(v.object(serializedPlayerDescription)),
+  agentDescriptions: v.array(v.object(serializedAgentDescription)),
+  worldMap: v.object(serializedWorldMap),
+});
+type GameState = Infer<typeof gameState>;
+
+const gameStateDiff = v.object({
+  world: v.object(serializedWorld),
+  playerDescriptions: v.optional(v.array(v.object(serializedPlayerDescription))),
+  agentDescriptions: v.optional(v.array(v.object(serializedAgentDescription))),
+  worldMap: v.optional(v.object(serializedWorldMap)),
+  agentOperations: v.array(v.object({ name: v.string(), args: v.any() })),
+});
+type GameStateDiff = Infer<typeof gameStateDiff>;
+
+export class Game extends AbstractGame {
+  tickDuration = 16;
+  stepDuration = 1000;
+  maxTicksPerStep = 600;
+  maxInputsPerStep = 32;
+
+  world: World;
+
+  historicalLocations: Map<GameId<'players'>, HistoricalObject<Location>>;
+
+  descriptionsModified: boolean;
+  worldMap: WorldMap;
+  playerDescriptions: Map<GameId<'players'>, PlayerDescription>;
+  agentDescriptions: Map<GameId<'agents'>, AgentDescription>;
+
+  pendingOperations: Array<{ name: string; args: any }> = [];
+
+  numPathfinds: number;
+
+  constructor(
+    engine: Doc<'engines'>,
+    public worldId: Id<'worlds'>,
+    state: GameState,
+  ) {
+    super(engine);
+
+    this.world = new World(state.world);
+    delete this.world.historicalLocations;
+
+    this.descriptionsModified = false;
+    this.worldMap = new WorldMap(state.worldMap);
+    this.agentDescriptions = parseMap(state.agentDescriptions, AgentDescription, (a) => a.agentId);
+    this.playerDescriptions = parseMap(
+      state.playerDescriptions,
+      PlayerDescription,
+      (p) => p.playerId,
+    );
+
+    this.historicalLocations = new Map();
+
+    this.numPathfinds = 0;
+  }
+
+  static async load(
+    db: DatabaseReader,
+    worldId: Id<'worlds'>,
+    generationNumber: number,
+  ): Promise<{ engine: Doc<'engines'>; gameState: GameState }> {
+    const worldDoc = await db.get(worldId);
+    if (!worldDoc) {
+      throw new Error(`No world found with id ${worldId}`);
+    }
+    const worldStatus = await db
+      .query('worldStatus')
+      .withIndex('worldId', (q) => q.eq('worldId', worldId))
+      .unique();
+    if (!worldStatus) {
+      throw new Error(`No engine found for world ${worldId}`);
+    }
+    const engine = await loadEngine(db, worldStatus.engineId, generationNumber);
+    const playerDescriptionsDocs = await db
+      .query('playerDescriptions')
+      .withIndex('worldId', (q) => q.eq('worldId', worldId))
+      .collect();
+    const agentDescriptionsDocs = await db
+      .query('agentDescriptions')
+      .withIndex('worldId', (q) => q.eq('worldId', worldId))
+      .collect();
+    const worldMapDoc = await db
+      .query('maps')
+      .withIndex('worldId', (q) => q.eq('worldId', worldId))
+      .unique();
+    if (!worldMapDoc) {
+      throw new Error(`No map found for world ${worldId}`);
+    }
+    // Discard the system fields and historicalLocations from the world state.
+    const { _id, _creationTime, historicalLocations: _, ...world } = worldDoc;
+    const playerDescriptions = playerDescriptionsDocs
+      // Discard player descriptions for players that no longer exist.
+      .filter((d) => !!world.players.find((p) => p.id === d.playerId))
+      .map(({ _id, _creationTime, worldId: _, ...doc }) => doc);
+    const agentDescriptions = agentDescriptionsDocs
+      .filter((a) => !!world.agents.find((p) => p.id === a.agentId))
+      .map(({ _id, _creationTime, worldId: _, ...doc }) => doc);
+    const {
+      _id: _mapId,
+      _creationTime: _mapCreationTime,
+      worldId: _mapWorldId,
+      ...worldMap
+    } = worldMapDoc;
+    return {
+      engine,
+      gameState: {
+        world,
+        playerDescriptions,
+        agentDescriptions,
+        worldMap,
+      },
+    };
+  }
+
+  allocId<T extends IdTypes>(idType: T): GameId<T> {
+    const id = allocGameId(idType, this.world.nextId);
+    this.world.nextId += 1;
+    return id;
+  }
+
+  scheduleOperation(name: string, args: unknown) {
+    this.pendingOperations.push({ name, args });
+  }
+
+  handleInput<Name extends InputNames>(now: number, name: Name, args: InputArgs<Name>) {
+    const handler = inputs[name]?.handler;
+    if (!handler) {
+      throw new Error(`Invalid input: ${name}`);
+    }
+    return handler(this, now, args as any);
+  }
+
+  beginStep(_now: number) {
+    // Store the current location of all players in the history tracking buffer.
+    this.historicalLocations.clear();
+    for (const player of this.world.players.values()) {
+      this.historicalLocations.set(
+        player.id,
+        new HistoricalObject(locationFields, playerLocation(player)),
+      );
+    }
+    this.numPathfinds = 0;
+  }
+
+  tick(now: number) {
+    // update day&nigth cycle counter
+    this.world.dayNightCycle.tick(this, this.tickDuration);
+
+    for (const player of this.world.players.values()) {
+      player.tick(this, now);
+    }
+    for (const player of this.world.players.values()) {
+      player.tickPathfinding(this, now);
+    }
+    for (const player of this.world.players.values()) {
+      player.tickPosition(this, now);
+    }
+    for (const conversation of this.world.conversations.values()) {
+      conversation.tick(this, now);
+    }
+    for (const agent of this.world.agents.values()) {
+      agent.tick(this, now);
+    }
+
+    // Save each player's location into the history buffer at the end of
+    // each tick.
+    for (const player of this.world.players.values()) {
+      let historicalObject = this.historicalLocations.get(player.id);
+      if (!historicalObject) {
+        historicalObject = new HistoricalObject(locationFields, playerLocation(player));
+        this.historicalLocations.set(player.id, historicalObject);
+      }
+      historicalObject.update(now, playerLocation(player));
+    }
+  }
+
+  async saveStep(ctx: ActionCtx, engineUpdate: EngineUpdate): Promise<void> {
+    const diff = this.takeDiff();
+    await ctx.runMutation(internal.aiTown.game.saveWorld, {
+      engineId: this.engine._id,
+      engineUpdate,
+      worldId: this.worldId,
+      worldDiff: diff,
+    });
+  }
+
+  takeDiff(): GameStateDiff {
+    const historicalLocations = [];
+    let bufferSize = 0;
+    for (const [id, historicalObject] of this.historicalLocations.entries()) {
+      const buffer = historicalObject.pack();
+      if (!buffer) {
+        continue;
+      }
+      historicalLocations.push({ playerId: id, location: buffer });
+      bufferSize += buffer.byteLength;
+    }
+    if (bufferSize > 0) {
+      console.debug(
+        `Packed ${Object.entries(historicalLocations).length} history buffers in ${(
+          bufferSize / 1024
+        ).toFixed(2)}KiB.`,
+      );
+    }
+    this.historicalLocations.clear();
+
+    const result: GameStateDiff = {
+      world: { ...this.world.serialize(), historicalLocations },
+      agentOperations: this.pendingOperations,
+    };
+    this.pendingOperations = [];
+    if (this.descriptionsModified) {
+      result.playerDescriptions = serializeMap(this.playerDescriptions);
+      result.agentDescriptions = serializeMap(this.agentDescriptions);
+      result.worldMap = this.worldMap.serialize();
+      this.descriptionsModified = false;
+    }
+    return result;
+  }
+
+  static async saveDiff(ctx: MutationCtx, worldId: Id<'worlds'>, diff: GameStateDiff) {
+    const existingWorld = await ctx.db.get(worldId);
+    if (!existingWorld) {
+      throw new Error(`No world found with id ${worldId}`);
+    }
+    const newWorld = diff.world;
+    // Archive newly deleted players, conversations, and agents.
+    for (const player of existingWorld.players) {
+      if (!newWorld.players.some((p) => p.id === player.id)) {
+        await ctx.db.insert('archivedPlayers', { worldId, ...player });
+      }
+    }
+    for (const conversation of existingWorld.conversations) {
+      if (!newWorld.conversations.some((c) => c.id === conversation.id)) {
+        const participants = conversation.participants.map((p) => p.playerId);
+        const archivedConversation = {
+          worldId,
+          id: conversation.id,
+          created: conversation.created,
+          creator: conversation.creator,
+          ended: Date.now(),
+          lastMessage: conversation.lastMessage,
+          numMessages: conversation.numMessages,
+          participants,
+        };
+        await ctx.db.insert('archivedConversations', archivedConversation);
+        for (let i = 0; i < participants.length; i++) {
+          for (let j = 0; j < participants.length; j++) {
+            if (i == j) {
+              continue;
+            }
+            const player1 = participants[i];
+            const player2 = participants[j];
+            await ctx.db.insert('participatedTogether', {
+              worldId,
+              conversationId: conversation.id,
+              player1,
+              player2,
+              ended: Date.now(),
+            });
+          }
+        }
+      }
+    }
+    for (const conversation of existingWorld.agents) {
+      if (!newWorld.agents.some((a) => a.id === conversation.id)) {
+        await ctx.db.insert('archivedAgents', { worldId, ...conversation });
+      }
+    }
+    // Update the world state.
+    await ctx.db.replace(worldId, newWorld);
+
+    // Update the larger description tables if they changed.
+    const { playerDescriptions, agentDescriptions, worldMap } = diff;
+    if (playerDescriptions) {
+      for (const description of playerDescriptions) {
+        const existing = await ctx.db
+          .query('playerDescriptions')
+          .withIndex('worldId', (q) =>
+            q.eq('worldId', worldId).eq('playerId', description.playerId),
+          )
+          .unique();
+        if (existing) {
+          await ctx.db.replace(existing._id, { worldId, ...description });
+        } else {
+          await ctx.db.insert('playerDescriptions', { worldId, ...description });
+        }
+      }
+    }
+    if (agentDescriptions) {
+      for (const description of agentDescriptions) {
+        const existing = await ctx.db
+          .query('agentDescriptions')
+          .withIndex('worldId', (q) => q.eq('worldId', worldId).eq('agentId', description.agentId))
+          .unique();
+        if (existing) {
+          await ctx.db.replace(existing._id, { worldId, ...description });
+        } else {
+          await ctx.db.insert('agentDescriptions', { worldId, ...description });
+        }
+      }
+    }
+    if (worldMap) {
+      const existing = await ctx.db
+        .query('maps')
+        .withIndex('worldId', (q) => q.eq('worldId', worldId))
+        .unique();
+      if (existing) {
+        await ctx.db.replace(existing._id, { worldId, ...worldMap });
+      } else {
+        await ctx.db.insert('maps', { worldId, ...worldMap });
+      }
+    }
+    // Start the desired agent operations.
+    for (const operation of diff.agentOperations) {
+      await runAgentOperation(ctx, operation.name, operation.args);
+    }
+  }
+}
+
+export const loadWorld = internalQuery({
+  args: {
+    worldId: v.id('worlds'),
+    generationNumber: v.number(),
+  },
+  handler: async (ctx, args) => {
+    return await Game.load(ctx.db, args.worldId, args.generationNumber);
+  },
+});
+
+export const saveWorld = internalMutation({
+  args: {
+    engineId: v.id('engines'),
+    engineUpdate,
+    worldId: v.id('worlds'),
+    worldDiff: gameStateDiff,
+  },
+  handler: async (ctx, args) => {
+    await applyEngineUpdate(ctx, args.engineId, args.engineUpdate);
+    await Game.saveDiff(ctx, args.worldId, args.worldDiff);
+  },
+});

patches/convex/aiTown/ids.ts

@@ -0,0 +1,32 @@
+import { v } from 'convex/values';
+
+const IdShortCodes = { agents: 'a', conversations: 'c', players: 'p', operations: 'o' };
+export type IdTypes = keyof typeof IdShortCodes;
+
+export type GameId<T extends IdTypes> = string & { __type: T };
+
+export function parseGameId<T extends IdTypes>(idType: T, gameId: string): GameId<T> {
+  const type = gameId[0];
+  const match = Object.entries(IdShortCodes).find(([_, value]) => value === type);
+  if (!match || match[0] !== idType) {
+    throw new Error(`Invalid game ID type: ${type}`);
+  }
+  const number = parseInt(gameId.slice(2), 10);
+  if (isNaN(number) || !Number.isInteger(number) || number < 0) {
+    throw new Error(`Invalid game ID number: ${gameId}`);
+  }
+  return gameId as GameId<T>;
+}
+
+export function allocGameId<T extends IdTypes>(idType: T, idNumber: number): GameId<T> {
+  const type = IdShortCodes[idType];
+  if (!type) {
+    throw new Error(`Invalid game ID type: ${idType}`);
+  }
+  return `${type}:${idNumber}` as GameId<T>;
+}
+
+export const conversationId = v.string();
+export const playerId = v.string();
+export const agentId = v.string();
+export const operationId = v.string();

patches/convex/aiTown/inputHandler.ts

@@ -0,0 +1,9 @@
+import { ObjectType, PropertyValidators, Value } from 'convex/values';
+import type { Game } from './game';
+
+export function inputHandler<ArgsValidator extends PropertyValidators, Return extends Value>(def: {
+  args: ArgsValidator;
+  handler: (game: Game, now: number, args: ObjectType<ArgsValidator>) => Return;
+}) {
+  return def;
+}

patches/convex/aiTown/inputs.ts

@@ -0,0 +1,25 @@
+import { ObjectType } from 'convex/values';
+import { playerInputs } from './player';
+import { conversationInputs } from './conversation';
+import { agentInputs } from './agentInputs';
+
+// It's easy to hit circular dependencies with these imports,
+// so assert at module scope so we hit errors when analyzing.
+if (playerInputs === undefined || conversationInputs === undefined || agentInputs === undefined) {
+  throw new Error("Input map is undefined, check if there's a circular import.");
+}
+export const inputs = {
+  ...playerInputs,
+  // Inputs for the messaging layer.
+  ...conversationInputs,
+  // Inputs for the agent layer.
+  ...agentInputs,
+};
+export type Inputs = typeof inputs;
+export type InputNames = keyof Inputs;
+export type InputArgs<Name extends InputNames> = ObjectType<Inputs[Name]['args']>;
+export type InputReturnValue<Name extends InputNames> = ReturnType<
+  Inputs[Name]['handler']
+> extends Promise<infer T>
+  ? T
+  : never;

patches/convex/aiTown/insertInput.ts

@@ -0,0 +1,20 @@
+import { MutationCtx } from '../_generated/server';
+import { Id } from '../_generated/dataModel';
+import { engineInsertInput } from '../engine/abstractGame';
+import { InputNames, InputArgs } from './inputs';
+
+export async function insertInput<Name extends InputNames>(
+  ctx: MutationCtx,
+  worldId: Id<'worlds'>,
+  name: Name,
+  args: InputArgs<Name>,
+): Promise<Id<'inputs'>> {
+  const worldStatus = await ctx.db
+    .query('worldStatus')
+    .withIndex('worldId', (q) => q.eq('worldId', worldId))
+    .unique();
+  if (!worldStatus) {
+    throw new Error(`World for engine ${worldId} not found`);
+  }
+  return await engineInsertInput(ctx, worldStatus.engineId, name, args);
+}

patches/convex/aiTown/location.ts

@@ -0,0 +1,32 @@
+import { FieldConfig } from '../engine/historicalObject';
+import { Player } from './player';
+
+export type Location = {
+  // Unpacked player position.
+  x: number;
+  y: number;
+
+  // Normalized facing vector.
+  dx: number;
+  dy: number;
+
+  speed: number;
+};
+
+export const locationFields: FieldConfig = [
+  { name: 'x', precision: 8 },
+  { name: 'y', precision: 8 },
+  { name: 'dx', precision: 8 },
+  { name: 'dy', precision: 8 },
+  { name: 'speed', precision: 16 },
+];
+
+export function playerLocation(player: Player): Location {
+  return {
+    x: player.position.x,
+    y: player.position.y,
+    dx: player.facing.dx,
+    dy: player.facing.dy,
+    speed: player.speed,
+  };
+}

patches/convex/aiTown/main.ts

@@ -0,0 +1,154 @@
+import { ConvexError, v } from 'convex/values';
+import { DatabaseReader, MutationCtx, internalAction, mutation, query } from '../_generated/server';
+import { insertInput } from './insertInput';
+import { Game } from './game';
+import { internal } from '../_generated/api';
+import { sleep } from '../util/sleep';
+import { Id } from '../_generated/dataModel';
+import { ENGINE_ACTION_DURATION } from '../constants';
+
+export async function createEngine(ctx: MutationCtx) {
+  const now = Date.now();
+  const engineId = await ctx.db.insert('engines', {
+    currentTime: now,
+    generationNumber: 0,
+    running: true,
+  });
+  return engineId;
+}
+
+async function loadWorldStatus(db: DatabaseReader, worldId: Id<'worlds'>) {
+  const worldStatus = await db
+    .query('worldStatus')
+    .withIndex('worldId', (q) => q.eq('worldId', worldId))
+    .unique();
+  if (!worldStatus) {
+    throw new Error(`No engine found for world ${worldId}`);
+  }
+  return worldStatus;
+}
+
+export async function startEngine(ctx: MutationCtx, worldId: Id<'worlds'>) {
+  const { engineId } = await loadWorldStatus(ctx.db, worldId);
+  const engine = await ctx.db.get(engineId);
+  if (!engine) {
+    throw new Error(`Invalid engine ID: ${engineId}`);
+  }
+  if (engine.running) {
+    throw new Error(`Engine ${engineId} isn't currently stopped`);
+  }
+  const now = Date.now();
+  const generationNumber = engine.generationNumber + 1;
+  await ctx.db.patch(engineId, {
+    // Forcibly advance time to the present. This does mean we'll skip
+    // simulating the time the engine was stopped, but we don't want
+    // to have to simulate a potentially large stopped window and send
+    // it down to clients.
+    lastStepTs: engine.currentTime,
+    currentTime: now,
+    running: true,
+    generationNumber,
+  });
+  await ctx.scheduler.runAfter(0, internal.aiTown.main.runStep, {
+    worldId: worldId,
+    generationNumber,
+    maxDuration: ENGINE_ACTION_DURATION,
+  });
+}
+
+export async function kickEngine(ctx: MutationCtx, worldId: Id<'worlds'>) {
+  const { engineId } = await loadWorldStatus(ctx.db, worldId);
+  const engine = await ctx.db.get(engineId);
+  if (!engine) {
+    throw new Error(`Invalid engine ID: ${engineId}`);
+  }
+  if (!engine.running) {
+    throw new Error(`Engine ${engineId} isn't currently running`);
+  }
+  const generationNumber = engine.generationNumber + 1;
+  await ctx.db.patch(engineId, { generationNumber });
+  await ctx.scheduler.runAfter(0, internal.aiTown.main.runStep, {
+    worldId: worldId,
+    generationNumber,
+    maxDuration: ENGINE_ACTION_DURATION,
+  });
+}
+
+export async function stopEngine(ctx: MutationCtx, worldId: Id<'worlds'>) {
+  const { engineId } = await loadWorldStatus(ctx.db, worldId);
+  const engine = await ctx.db.get(engineId);
+  if (!engine) {
+    throw new Error(`Invalid engine ID: ${engineId}`);
+  }
+  if (!engine.running) {
+    throw new Error(`Engine ${engineId} isn't currently running`);
+  }
+  await ctx.db.patch(engineId, { running: false });
+}
+
+export const runStep = internalAction({
+  args: {
+    worldId: v.id('worlds'),
+    generationNumber: v.number(),
+    maxDuration: v.number(),
+  },
+  handler: async (ctx, args) => {
+    try {
+      const { engine, gameState } = await ctx.runQuery(internal.aiTown.game.loadWorld, {
+        worldId: args.worldId,
+        generationNumber: args.generationNumber,
+      });
+      const game = new Game(engine, args.worldId, gameState);
+
+      let now = Date.now();
+      const deadline = now + args.maxDuration;
+      while (now < deadline) {
+        await game.runStep(ctx, now);
+        const sleepUntil = Math.min(now + game.stepDuration, deadline);
+        await sleep(sleepUntil - now);
+        now = Date.now();
+      }
+      await ctx.scheduler.runAfter(0, internal.aiTown.main.runStep, {
+        worldId: args.worldId,
+        generationNumber: game.engine.generationNumber,
+        maxDuration: args.maxDuration,
+      });
+    } catch (e: unknown) {
+      if (e instanceof ConvexError) {
+        if (e.data.kind === 'engineNotRunning') {
+          console.debug(`Engine is not running: ${e.message}`);
+          return;
+        }
+        if (e.data.kind === 'generationNumber') {
+          console.debug(`Generation number mismatch: ${e.message}`);
+          return;
+        }
+      }
+      throw e;
+    }
+  },
+});
+
+export const sendInput = mutation({
+  args: {
+    worldId: v.id('worlds'),
+    name: v.string(),
+    args: v.any(),
+  },
+  handler: async (ctx, args) => {
+    return await insertInput(ctx, args.worldId, args.name as any, args.args);
+  },
+});
+
+export const inputStatus = query({
+  args: {
+    inputId: v.id('inputs'),
+  },
+  handler: async (ctx, args) => {
+    const input = await ctx.db.get(args.inputId);
+    if (!input) {
+      throw new Error(`Invalid input ID: ${args.inputId}`);
+    }
+    return input.returnValue ?? null;
+  },
+});

patches/convex/aiTown/movement.ts

@@ -0,0 +1,189 @@
+import { movementSpeed } from '../../data/characters';
+import { COLLISION_THRESHOLD } from '../constants';
+import { compressPath, distance, manhattanDistance, pointsEqual } from '../util/geometry';
+import { MinHeap } from '../util/minheap';
+import { Point, Vector } from '../util/types';
+import { Game } from './game';
+import { GameId } from './ids';
+import { Player } from './player';
+import { WorldMap } from './worldMap';
+
+type PathCandidate = {
+  position: Point;
+  facing?: Vector;
+  t: number;
+  length: number;
+  cost: number;
+  prev?: PathCandidate;
+};
+
+export function stopPlayer(player: Player) {
+  delete player.pathfinding;
+  player.speed = 0;
+}
+
+export function movePlayer(
+  game: Game,
+  now: number,
+  player: Player,
+  destination: Point,
+  allowInConversation?: boolean,
+) {
+  if (Math.floor(destination.x) !== destination.x || Math.floor(destination.y) !== destination.y) {
+    throw new Error(`Non-integral destination: ${JSON.stringify(destination)}`);
+  }
+  const { position } = player;
+  // Close enough to current position or destination => no-op.
+  if (pointsEqual(position, destination)) {
+    return;
+  }
+  // Don't allow players in a conversation to move.
+  const inConversation = [...game.world.conversations.values()].some(
+    (c) => c.participants.get(player.id)?.status.kind === 'participating',
+  );
+  if (inConversation && !allowInConversation) {
+    throw new Error(`Can't move when in a conversation. Leave the conversation first!`);
+  }
+  player.pathfinding = {
+    destination: destination,
+    started: now,
+    state: {
+      kind: 'needsPath',
+    },
+  };
+  return;
+}
+
+export function findRoute(game: Game, now: number, player: Player, destination: Point) {
+  const minDistances: PathCandidate[][] = [];
+  const explore = (current: PathCandidate): Array<PathCandidate> => {
+    const { x, y } = current.position;
+    const neighbors = [];
+
+    // If we're not on a grid point, first try to move horizontally
+    // or vertically to a grid point. Note that this can create very small
+    // deltas between the current position and the nearest grid point so
+    // be careful to preserve the `facing` vectors rather than trying to
+    // derive them anew.
+    if (x !== Math.floor(x)) {
+      neighbors.push(
+        { position: { x: Math.floor(x), y }, facing: { dx: -1, dy: 0 } },
+        { position: { x: Math.floor(x) + 1, y }, facing: { dx: 1, dy: 0 } },
+      );
+    }
+    if (y !== Math.floor(y)) {
+      neighbors.push(
+        { position: { x, y: Math.floor(y) }, facing: { dx: 0, dy: -1 } },
+        { position: { x, y: Math.floor(y) + 1 }, facing: { dx: 0, dy: 1 } },
+      );
+    }
+    // Otherwise, just move to adjacent grid points.
+    if (x == Math.floor(x) && y == Math.floor(y)) {
+      neighbors.push(
+        { position: { x: x + 1, y }, facing: { dx: 1, dy: 0 } },
+        { position: { x: x - 1, y }, facing: { dx: -1, dy: 0 } },
+        { position: { x, y: y + 1 }, facing: { dx: 0, dy: 1 } },
+        { position: { x, y: y - 1 }, facing: { dx: 0, dy: -1 } },
+      );
+    }
+    const next = [];
+    for (const { position, facing } of neighbors) {
+      const segmentLength = distance(current.position, position);
+      const length = current.length + segmentLength;
+      if (blocked(game, now, position, player.id)) {
+        continue;
+      }
+      const remaining = manhattanDistance(position, destination);
+      const path = {
+        position,
+        facing,
+        // Movement speed is in tiles per second.
+        t: current.t + (segmentLength / movementSpeed) * 1000,
+        length,
+        cost: length + remaining,
+        prev: current,
+      };
+      const existingMin = minDistances[position.y]?.[position.x];
+      if (existingMin && existingMin.cost <= path.cost) {
+        continue;
+      }
+      minDistances[position.y] ??= [];
+      minDistances[position.y][position.x] = path;
+      next.push(path);
+    }
+    return next;
+  };
+
+  const startingLocation = player.position;
+  const startingPosition = { x: startingLocation.x, y: startingLocation.y };
+  let current: PathCandidate | undefined = {
+    position: startingPosition,
+    facing: player.facing,
+    t: now,
+    length: 0,
+    cost: manhattanDistance(startingPosition, destination),
+    prev: undefined,
+  };
+  let bestCandidate = current;
+  const minheap = MinHeap<PathCandidate>((p0, p1) => p0.cost > p1.cost);
+  while (current) {
+    if (pointsEqual(current.position, destination)) {
+      break;
+    }
+    if (
+      manhattanDistance(current.position, destination) <
+      manhattanDistance(bestCandidate.position, destination)
+    ) {
+      bestCandidate = current;
+    }
+    for (const candidate of explore(current)) {
+      minheap.push(candidate);
+    }
+    current = minheap.pop();
+  }
+  let newDestination = null;
+  if (!current) {
+    if (bestCandidate.length === 0) {
+      return null;
+    }
+    current = bestCandidate;
+    newDestination = current.position;
+  }
+  const densePath = [];
+  let facing = current.facing!;
+  while (current) {
+    densePath.push({ position: current.position, t: current.t, facing });
+    facing = current.facing!;
+    current = current.prev;
+  }
+  densePath.reverse();
+
+  return { path: compressPath(densePath), newDestination };
+}
+
+export function blocked(game: Game, now: number, pos: Point, playerId?: GameId<'players'>) {
+  const otherPositions = [...game.world.players.values()]
+    .filter((p) => p.id !== playerId)
+    .map((p) => p.position);
+  return blockedWithPositions(pos, otherPositions, game.worldMap);
+}
+
+export function blockedWithPositions(position: Point, otherPositions: Point[], map: WorldMap) {
+  if (isNaN(position.x) || isNaN(position.y)) {
+    throw new Error(`NaN position in ${JSON.stringify(position)}`);
+  }
+  if (position.x < 0 || position.y < 0 || position.x >= map.width || position.y >= map.height) {
+    return 'out of bounds';
+  }
+  for (const layer of map.objectTiles) {
+    if (layer[Math.floor(position.x)][Math.floor(position.y)] !== -1) {
+      return 'world blocked';
+    }
+  }
+  for (const otherPosition of otherPositions) {
+    if (distance(otherPosition, position) < COLLISION_THRESHOLD) {
+      return 'player';
+    }
+  }
+  return null;
+}

patches/convex/aiTown/player.ts

@@ -0,0 +1,310 @@
+import { Infer, ObjectType, v } from 'convex/values';
+import { Point, Vector, path, point, vector } from '../util/types';
+import { GameId, parseGameId } from './ids';
+import { playerId } from './ids';
+import {
+  PATHFINDING_TIMEOUT,
+  PATHFINDING_BACKOFF,
+  HUMAN_IDLE_TOO_LONG,
+  MAX_HUMAN_PLAYERS,
+  MAX_PATHFINDS_PER_STEP,
+} from '../constants';
+import { pointsEqual, pathPosition } from '../util/geometry';
+import { Game } from './game';
+import { stopPlayer, findRoute, blocked, movePlayer } from './movement';
+import { inputHandler } from './inputHandler';
+import { characters } from '../../data/characters';
+import { PlayerDescription } from './playerDescription';
+
+const pathfinding = v.object({
+  destination: point,
+  started: v.number(),
+  state: v.union(
+    v.object({
+      kind: v.literal('needsPath'),
+    }),
+    v.object({
+      kind: v.literal('waiting'),
+      until: v.number(),
+    }),
+    v.object({
+      kind: v.literal('moving'),
+      path,
+    }),
+  ),
+});
+export type Pathfinding = Infer<typeof pathfinding>;
+
+export const activity = v.object({
+  description: v.string(),
+  emoji: v.optional(v.string()),
+  until: v.number(),
+});
+export type Activity = Infer<typeof activity>;
+
+export const serializedPlayer = {
+  id: playerId,
+  human: v.optional(v.string()),
+  pathfinding: v.optional(pathfinding),
+  activity: v.optional(activity),
+
+  // The last time they did something.
+  lastInput: v.number(),
+
+  position: point,
+  facing: vector,
+  speed: v.number(),
+};
+export type SerializedPlayer = ObjectType<typeof serializedPlayer>;
+
+export class Player {
+  id: GameId<'players'>;
+  human?: string;
+  pathfinding?: Pathfinding;
+  activity?: Activity;
+
+  lastInput: number;
+
+  position: Point;
+  facing: Vector;
+  speed: number;
+
+  constructor(serialized: SerializedPlayer) {
+    const { id, human, pathfinding, activity, lastInput, position, facing, speed } = serialized;
+    this.id = parseGameId('players', id);
+    this.human = human;
+    this.pathfinding = pathfinding;
+    this.activity = activity;
+    this.lastInput = lastInput;
+    this.position = position;
+    this.facing = facing;
+    this.speed = speed;
+  }
+
+  tick(game: Game, now: number) {
+    if (this.human && this.lastInput < now - HUMAN_IDLE_TOO_LONG) {
+      this.leave(game, now);
+    }
+  }
+
+  tickPathfinding(game: Game, now: number) {
+    // There's nothing to do if we're not moving.
+    const { pathfinding, position } = this;
+    if (!pathfinding) {
+      return;
+    }
+
+    // Stop pathfinding if we've reached our destination.
+    if (pathfinding.state.kind === 'moving' && pointsEqual(pathfinding.destination, position)) {
+      stopPlayer(this);
+    }
+
+    // Stop pathfinding if we've timed out.
+    if (pathfinding.started + PATHFINDING_TIMEOUT < now) {
+      console.warn(`Timing out pathfinding for ${this.id}`);
+      stopPlayer(this);
+    }
+
+    // Transition from "waiting" to "needsPath" if we're past the deadline.
+    if (pathfinding.state.kind === 'waiting' && pathfinding.state.until < now) {
+      pathfinding.state = { kind: 'needsPath' };
+    }
+
+    // Perform pathfinding if needed.
+    if (pathfinding.state.kind === 'needsPath' && game.numPathfinds < MAX_PATHFINDS_PER_STEP) {
+      game.numPathfinds++;
+      if (game.numPathfinds === MAX_PATHFINDS_PER_STEP) {
+        console.warn(`Reached max pathfinds for this step`);
+      }
+      const route = findRoute(game, now, this, pathfinding.destination);
+      if (route === null) {
+        console.log(`Failed to route to ${JSON.stringify(pathfinding.destination)}`);
+        stopPlayer(this);
+      } else {
+        if (route.newDestination) {
+          console.warn(
+            `Updating destination from ${JSON.stringify(
+              pathfinding.destination,
+            )} to ${JSON.stringify(route.newDestination)}`,
+          );
+          pathfinding.destination = route.newDestination;
+        }
+        pathfinding.state = { kind: 'moving', path: route.path };
+      }
+    }
+  }
+
+  tickPosition(game: Game, now: number) {
+    // There's nothing to do if we're not moving.
+    if (!this.pathfinding || this.pathfinding.state.kind !== 'moving') {
+      this.speed = 0;
+      return;
+    }
+
+    // Compute a candidate new position and check if it collides
+    // with anything.
+    const candidate = pathPosition(this.pathfinding.state.path as any, now);
+    if (!candidate) {
+      console.warn(`Path out of range of ${now} for ${this.id}`);
+      return;
+    }
+    const { position, facing, velocity } = candidate;
+    const collisionReason = blocked(game, now, position, this.id);
+    if (collisionReason !== null) {
+      const backoff = Math.random() * PATHFINDING_BACKOFF;
+      console.warn(`Stopping path for ${this.id}, waiting for ${backoff}ms: ${collisionReason}`);
+      this.pathfinding.state = {
+        kind: 'waiting',
+        until: now + backoff,
+      };
+      return;
+    }
+    // Update the player's location.
+    this.position = position;
+    this.facing = facing;
+    this.speed = velocity;
+  }
+
+  static join(
+    game: Game,
+    now: number,
+    name: string,
+    character: string,
+    description: string,
+    tokenIdentifier?: string,
+  ) {
+    if (tokenIdentifier) {
+      let numHumans = 0;
+      for (const player of game.world.players.values()) {
+        if (player.human) {
+          numHumans++;
+        }
+        if (player.human === tokenIdentifier) {
+          throw new Error(`You are already in this game!`);
+        }
+      }
+      if (numHumans >= MAX_HUMAN_PLAYERS) {
+        throw new Error(`Only ${MAX_HUMAN_PLAYERS} human players allowed at once.`);
+      }
+    }
+    let position;
+    for (let attempt = 0; attempt < 10; attempt++) {
+      const candidate = {
+        x: Math.floor(Math.random() * game.worldMap.width),
+        y: Math.floor(Math.random() * game.worldMap.height),
+      };
+      if (blocked(game, now, candidate)) {
+        continue;
+      }
+      position = candidate;
+      break;
+    }
+    if (!position) {
+      throw new Error(`Failed to find a free position!`);
+    }
+    const facingOptions = [
+      { dx: 1, dy: 0 },
+      { dx: -1, dy: 0 },
+      { dx: 0, dy: 1 },
+      { dx: 0, dy: -1 },
+    ];
+    const facing = facingOptions[Math.floor(Math.random() * facingOptions.length)];
+    if (!characters.find((c) => c.name === character)) {
+      throw new Error(`Invalid character: ${character}`);
+    }
+    const playerId = game.allocId('players');
+    game.world.players.set(
+      playerId,
+      new Player({
+        id: playerId,
+        human: tokenIdentifier,
+        lastInput: now,
+        position,
+        facing,
+        speed: 0,
+      }),
+    );
+    game.playerDescriptions.set(
+      playerId,
+      new PlayerDescription({
+        playerId,
+        character,
+        description,
+        name,
+      }),
+    );
+    game.descriptionsModified = true;
+    return playerId;
+  }
+
+  leave(game: Game, now: number) {
+    // Stop our conversation if we're leaving the game.
+    const conversation = [...game.world.conversations.values()].find((c) =>
+      c.participants.has(this.id),
+    );
+    if (conversation) {
+      conversation.stop(game, now);
+    }
+    game.world.players.delete(this.id);
+  }
+
+  serialize(): SerializedPlayer {
+    const { id, human, pathfinding, activity, lastInput, position, facing, speed } = this;
+    return {
+      id,
+      human,
+      pathfinding,
+      activity,
+      lastInput,
+      position,
+      facing,
+      speed,
+    };
+  }
+}
+
+export const playerInputs = {
+  join: inputHandler({
+    args: {
+      name: v.string(),
+      character: v.string(),
+      description: v.string(),
+      tokenIdentifier: v.optional(v.string()),
+    },
+    handler: (game, now, args) => {
+      Player.join(game, now, args.name, args.character, args.description, args.tokenIdentifier);
+      return null;
+    },
+  }),
+  leave: inputHandler({
+    args: { playerId },
+    handler: (game, now, args) => {
+      const playerId = parseGameId('players', args.playerId);
+      const player = game.world.players.get(playerId);
+      if (!player) {
+        throw new Error(`Invalid player ID ${playerId}`);
+      }
+      player.leave(game, now);
+      return null;
+    },
+  }),
+  moveTo: inputHandler({
+    args: {
+      playerId,
+      destination: v.union(point, v.null()),
+    },
+    handler: (game, now, args) => {
+      const playerId = parseGameId('players', args.playerId);
+      const player = game.world.players.get(playerId);
+      if (!player) {
+        throw new Error(`Invalid player ID ${playerId}`);
+      }
+      if (args.destination) {
+        movePlayer(game, now, player, args.destination);
+      } else {
+        stopPlayer(player);
+      }
+      return null;
+    },
+  }),
+};

patches/convex/aiTown/playerDescription.ts

@@ -0,0 +1,35 @@
+import { ObjectType, v } from 'convex/values';
+import { GameId, parseGameId, playerId } from './ids';
+
+export const serializedPlayerDescription = {
+  playerId,
+  name: v.string(),
+  description: v.string(),
+  character: v.string(),
+};
+export type SerializedPlayerDescription = ObjectType<typeof serializedPlayerDescription>;
+
+export class PlayerDescription {
+  playerId: GameId<'players'>;
+  name: string;
+  description: string;
+  character: string;
+
+  constructor(serialized: SerializedPlayerDescription) {
+    const { playerId, name, description, character } = serialized;
+    this.playerId = parseGameId('players', playerId);
+    this.name = name;
+    this.description = description;
+    this.character = character;
+  }
+
+  serialize(): SerializedPlayerDescription {
+    const { playerId, name, description, character } = this;
+    return {
+      playerId,
+      name,
+      description,
+      character,
+    };
+  }
+}

patches/convex/aiTown/schema.ts

@@ -0,0 +1,79 @@
+import { v } from 'convex/values';
+import { defineTable } from 'convex/server';
+import { serializedPlayer } from './player';
+import { serializedPlayerDescription } from './playerDescription';
+import { serializedAgent } from './agent';
+import { serializedAgentDescription } from './agentDescription';
+import { serializedWorld } from './world';
+import { serializedWorldMap } from './worldMap';
+import { serializedConversation } from './conversation';
+import { conversationId, playerId } from './ids';
+
+export const aiTownTables = {
+  // This table has a single document that stores all players, conversations, and agents. This
+  // data is small and changes regularly over time.
+  worlds: defineTable({ ...serializedWorld }),
+
+  // Worlds can be started or stopped by the developer or paused for inactivity, and this
+  // infrequently changing document tracks this world state.
+  worldStatus: defineTable({
+    worldId: v.id('worlds'),
+    isDefault: v.boolean(),
+    engineId: v.id('engines'),
+    lastViewed: v.number(),
+    status: v.union(v.literal('running'), v.literal('stoppedByDeveloper'), v.literal('inactive')),
+  }).index('worldId', ['worldId']),
+
+  // This table contains the map data for a given world. Since it's a bit larger than the player
+  // state and infrequently changes, we store it in a separate table.
+  maps: defineTable({
+    worldId: v.id('worlds'),
+    ...serializedWorldMap,
+  }).index('worldId', ['worldId']),
+
+  // Human readable text describing players and agents that's stored in separate tables, just like `maps`.
+  playerDescriptions: defineTable({
+    worldId: v.id('worlds'),
+    ...serializedPlayerDescription,
+  }).index('worldId', ['worldId', 'playerId']),
+  agentDescriptions: defineTable({
+    worldId: v.id('worlds'),
+    ...serializedAgentDescription,
+  }).index('worldId', ['worldId', 'agentId']),
+
+  //The game engine doesn't want to track players that have left or conversations that are over, since
+  // it wants to keep its managed state small. However, we may want to look at old conversations in the
+  // UI or from the agent code. So, whenever we delete an entry from within the world's document, we
+  // "archive" it within these tables.
+  archivedPlayers: defineTable({ worldId: v.id('worlds'), ...serializedPlayer }).index('worldId', [
+    'worldId',
+    'id',
+  ]),
+  archivedConversations: defineTable({
+    worldId: v.id('worlds'),
+    id: conversationId,
+    creator: playerId,
+    created: v.number(),
+    ended: v.number(),
+    lastMessage: serializedConversation.lastMessage,
+    numMessages: serializedConversation.numMessages,
+    participants: v.array(playerId),
+  }).index('worldId', ['worldId', 'id']),
+  archivedAgents: defineTable({ worldId: v.id('worlds'), ...serializedAgent }).index('worldId', [
+    'worldId',
+    'id',
+  ]),
+
+  // The agent layer wants to know what the last (completed) conversation was between two players,
+  // so this table represents a labelled graph indicating which players have talked to each other.
+  participatedTogether: defineTable({
+    worldId: v.id('worlds'),
+    conversationId,
+    player1: playerId,
+    player2: playerId,
+    ended: v.number(),
+  })
+    .index('edge', ['worldId', 'player1', 'player2', 'ended'])
+    .index('conversation', ['worldId', 'player1', 'conversationId'])
+    .index('playerHistory', ['worldId', 'player1', 'ended']),
+};

patches/convex/aiTown/world.ts

@@ -0,0 +1,70 @@
+import { ObjectType, v } from 'convex/values';
+import { Conversation, serializedConversation } from './conversation';
+import { Player, serializedPlayer } from './player';
+import { Agent, serializedAgent } from './agent';
+import { GameId, parseGameId, playerId } from './ids';
+import { parseMap } from '../util/object';
+import { DayNightCycle, SerializedDayNightCycle, dayNightCycleSchema } from './dayNightCycle';
+
+export const historicalLocations = v.array(
+  v.object({
+    playerId,
+    location: v.bytes(),
+  }),
+);
+
+export const serializedWorld = {
+  nextId: v.number(),
+  conversations: v.array(v.object(serializedConversation)),
+  players: v.array(v.object(serializedPlayer)),
+  agents: v.array(v.object(serializedAgent)),
+  historicalLocations: v.optional(historicalLocations),
+  dayNightCycle: v.object(dayNightCycleSchema),
+};
+export type SerializedWorld = ObjectType<typeof serializedWorld>;
+
+export class World {
+  nextId: number;
+  conversations: Map<GameId<'conversations'>, Conversation>;
+  players: Map<GameId<'players'>, Player>;
+  agents: Map<GameId<'agents'>, Agent>;
+  historicalLocations?: Map<GameId<'players'>, ArrayBuffer>;
+  dayNightCycle: DayNightCycle;
+
+  constructor(serialized: SerializedWorld) {
+    const { nextId, historicalLocations } = serialized;
+
+    this.nextId = nextId;
+    this.conversations = parseMap(serialized.conversations, Conversation, (c) => c.id);
+    this.players = parseMap(serialized.players, Player, (p) => p.id);
+    this.agents = parseMap(serialized.agents, Agent, (a) => a.id);
+    this.dayNightCycle = new DayNightCycle(serialized.dayNightCycle);
+
+    if (historicalLocations) {
+      this.historicalLocations = new Map();
+      for (const { playerId, location } of historicalLocations) {
+        this.historicalLocations.set(parseGameId('players', playerId), location);
+      }
+    }
+  }
+
+  playerConversation(player: Player): Conversation | undefined {
+    return [...this.conversations.values()].find((c) => c.participants.has(player.id));
+  }
+
+  serialize(): SerializedWorld {
+    return {
+      nextId: this.nextId,
+      conversations: [...this.conversations.values()].map((c) => c.serialize()),
+      players: [...this.players.values()].map((p) => p.serialize()),
+      agents: [...this.agents.values()].map((a) => a.serialize()),
+      historicalLocations:
+        this.historicalLocations &&
+        [...this.historicalLocations.entries()].map(([playerId, location]) => ({
+          playerId,
+          location,
+        })),
+      dayNightCycle: this.dayNightCycle.serialize(),
+    };
+  }
+}

patches/convex/aiTown/worldMap.ts

@@ -0,0 +1,94 @@
+import { Infer, ObjectType, v } from 'convex/values';
+
+// `layer[position.x][position.y]` is the tileIndex or -1 if empty.
+const tileLayer = v.array(v.array(v.number()));
+export type TileLayer = Infer<typeof tileLayer>;
+
+const animatedSprite = {
+  x: v.number(),
+  y: v.number(),
+  w: v.number(),
+  h: v.number(),
+  layer: v.number(),
+  sheet: v.string(),
+  animation: v.string(),
+};
+export type AnimatedSprite = ObjectType<typeof animatedSprite>;
+
+export const serializedWorldMap = {
+  width: v.number(),
+  height: v.number(),
+
+  tileSetUrl: v.string(),
+  tileSetAlternateUrl: v.string(),
+  //  Width & height of tileset image, px.
+  tileSetDimX: v.number(),
+  tileSetDimY: v.number(),
+
+  // Tile size in pixels (assume square)
+  tileDim: v.number(),
+  bgTiles: v.array(v.array(v.array(v.number()))),
+  decorTiles: v.array(v.array(v.array(v.number()))),
+  objectTiles: v.array(tileLayer),
+  bgTilesN: v.array(v.array(v.array(v.number()))),
+  decorTilesN: v.array(v.array(v.array(v.number()))),
+  objectTilesN: v.array(tileLayer),
+  animatedSprites: v.array(v.object(animatedSprite)),
+};
+export type SerializedWorldMap = ObjectType<typeof serializedWorldMap>;
+
+export class WorldMap {
+  width: number;
+  height: number;
+
+  tileSetUrl: string;
+  tileSetAlternateUrl: string;
+  tileSetDimX: number;
+  tileSetDimY: number;
+
+  tileDim: number;
+
+  bgTiles: TileLayer[];
+  decorTiles: TileLayer[];
+  objectTiles: TileLayer[];
+  bgTilesN: TileLayer[];
+  decorTilesN: TileLayer[];
+  objectTilesN: TileLayer[];
+  animatedSprites: AnimatedSprite[];
+
+  constructor(serialized: SerializedWorldMap) {
+    this.width = serialized.width;
+    this.height = serialized.height;
+    this.tileSetUrl = serialized.tileSetUrl;
+    this.tileSetAlternateUrl = serialized.tileSetAlternateUrl;
+    this.tileSetDimX = serialized.tileSetDimX;
+    this.tileSetDimY = serialized.tileSetDimY;
+    this.tileDim = serialized.tileDim;
+    this.bgTiles = serialized.bgTiles;
+    this.decorTiles = serialized.decorTiles;
+    this.objectTiles = serialized.objectTiles;
+    this.bgTilesN = serialized.bgTilesN;
+    this.decorTilesN = serialized.decorTilesN;
+    this.objectTilesN = serialized.objectTilesN;
+    this.animatedSprites = serialized.animatedSprites;
+  }
+
+  serialize(): SerializedWorldMap {
+    return {
+      width: this.width,
+      height: this.height,
+      tileSetUrl: this.tileSetUrl,
+      tileSetAlternateUrl: this.tileSetAlternateUrl,
+      tileSetDimX: this.tileSetDimX,
+      tileSetDimY: this.tileSetDimY,
+      tileDim: this.tileDim,
+      bgTiles: this.bgTiles,
+      objectTiles: this.objectTiles,
+      decorTiles:this.decorTiles,
+      bgTilesN: this.bgTilesN,
+      objectTilesN: this.objectTilesN,
+      decorTilesN:this.decorTilesN,
+      animatedSprites: this.animatedSprites,
+    };
+  }
+}

patches/{constants.ts → convex/constants.ts}

@@ -1,78 +1,81 @@
-// export const ACTION_TIMEOUT = 120_000; // more time for local dev
-export const ACTION_TIMEOUT = 60_000; // normally fine
-
-export const IDLE_WORLD_TIMEOUT = 5 * 60 * 1000;
-export const WORLD_HEARTBEAT_INTERVAL = 60 * 1000;
-
-export const MAX_STEP = 10 * 60 * 1000;
-export const TICK = 16;
-export const STEP_INTERVAL = 1000;
-
-export const PATHFINDING_TIMEOUT = 60 * 1000;
-export const PATHFINDING_BACKOFF = 1000;
-export const CONVERSATION_DISTANCE = 1.3;
-export const MIDPOINT_THRESHOLD = 4;
-export const TYPING_TIMEOUT = 15 * 1000;
-export const COLLISION_THRESHOLD = 0.75;
-
-// How many human players can be in a world at once.
-export const MAX_HUMAN_PLAYERS = 8;
-
-// Don't talk to anyone for 15s after having a conversation.
-export const CONVERSATION_COOLDOWN = 15000;
-
-// Don't do another activity for 10s after doing one.
-export const ACTIVITY_COOLDOWN = 10_000;
-
-// Don't talk to a player within 60s of talking to them.
-export const PLAYER_CONVERSATION_COOLDOWN = 60000;
-
-// Invite 80% of invites that come from other agents.
-export const INVITE_ACCEPT_PROBABILITY = 0.8;
-
-// Wait for 1m for invites to be accepted.
-export const INVITE_TIMEOUT = 60000;
-
-// Wait for another player to say something before jumping in.
-export const AWKWARD_CONVERSATION_TIMEOUT = 60_000; // more time locally
-// export const AWKWARD_CONVERSATION_TIMEOUT = 20_000;
-
-// Leave a conversation after participating too long.
-export const MAX_CONVERSATION_DURATION = 10 * 60_000; // more time locally
-// export const MAX_CONVERSATION_DURATION = 2 * 60_000;
-
-// Leave a conversation if it has more than 8 messages;
-export const MAX_CONVERSATION_MESSAGES = 8;
-
-// Wait for 1s after sending an input to the engine. We can remove this
-// once we can await on an input being processed.
-export const INPUT_DELAY = 1000;
-
-// How many memories to get from the agent's memory.
-// This is over-fetched by 10x so we can prioritize memories by more than relevance.
-export const NUM_MEMORIES_TO_SEARCH = 1;
-
-// Wait for at least two seconds before sending another message.
-export const MESSAGE_COOLDOWN = 2000;
-
-// Don't run a turn of the agent more than once a second.
-export const AGENT_WAKEUP_THRESHOLD = 1000;
-
-// How old we let memories be before we vacuum them
-export const VACUUM_MAX_AGE = 2 * 7 * 24 * 60 * 60 * 1000;
-export const DELETE_BATCH_SIZE = 64;
-
-export const HUMAN_IDLE_TOO_LONG = 5 * 60 * 1000;
-
-export const ACTIVITIES = [
-  { description: 'reading a book', emoji: '📖', duration: 60_000 },
-  { description: 'daydreaming', emoji: '🤔', duration: 60_000 },
-  { description: 'gardening', emoji: '🥕', duration: 60_000 },
-];
-
-export const ENGINE_ACTION_DURATION = 30000;
-
-// Bound the number of pathfinding searches we do per game step.
-export const MAX_PATHFINDS_PER_STEP = 16;
-
-export const DEFAULT_NAME = 'Me';
+// export const ACTION_TIMEOUT = 120_000; // more time for local dev
+export const ACTION_TIMEOUT = 60_000; // normally fine
+
+export const IDLE_WORLD_TIMEOUT = 5 * 60 * 1000;
+export const WORLD_HEARTBEAT_INTERVAL = 60 * 1000;
+
+export const MAX_STEP = 10 * 60 * 1000;
+export const TICK = 16;
+export const STEP_INTERVAL = 1000;
+
+export const PATHFINDING_TIMEOUT = 60 * 1000;
+export const PATHFINDING_BACKOFF = 1000;
+export const CONVERSATION_DISTANCE = 1.3;
+export const MIDPOINT_THRESHOLD = 4;
+export const TYPING_TIMEOUT = 15 * 1000;
+export const COLLISION_THRESHOLD = 0.75;
+
+// How many human players can be in a world at once.
+export const MAX_HUMAN_PLAYERS = 8;
+
+// Don't talk to anyone for 15s after having a conversation.
+export const CONVERSATION_COOLDOWN = 15000;
+
+// Don't do another activity for 10s after doing one.
+export const ACTIVITY_COOLDOWN = 10_000;
+
+// Don't talk to a player within 60s of talking to them.
+export const PLAYER_CONVERSATION_COOLDOWN = 60000;
+
+// Invite 80% of invites that come from other agents.
+export const INVITE_ACCEPT_PROBABILITY = 0.8;
+
+// Wait for 1m for invites to be accepted.
+export const INVITE_TIMEOUT = 60000;
+
+// Wait for another player to say something before jumping in.
+export const AWKWARD_CONVERSATION_TIMEOUT = 60_000; // more time locally
+// export const AWKWARD_CONVERSATION_TIMEOUT = 20_000;
+
+// Leave a conversation after participating too long.
+export const MAX_CONVERSATION_DURATION = 10 * 60_000; // more time locally
+// export const MAX_CONVERSATION_DURATION = 2 * 60_000;
+
+// Leave a conversation if it has more than 8 messages;
+export const MAX_CONVERSATION_MESSAGES = 8;
+
+// Wait for 1s after sending an input to the engine. We can remove this
+// once we can await on an input being processed.
+export const INPUT_DELAY = 1000;
+
+// How many memories to get from the agent's memory.
+// This is over-fetched by 10x so we can prioritize memories by more than relevance.
+export const NUM_MEMORIES_TO_SEARCH = 1;
+
+// Wait for at least two seconds before sending another message.
+export const MESSAGE_COOLDOWN = 2000;
+
+// Don't run a turn of the agent more than once a second.
+export const AGENT_WAKEUP_THRESHOLD = 1000;
+
+// How old we let memories be before we vacuum them
+export const VACUUM_MAX_AGE = 2 * 7 * 24 * 60 * 60 * 1000;
+export const DELETE_BATCH_SIZE = 64;
+
+export const HUMAN_IDLE_TOO_LONG = 5 * 60 * 1000;
+
+export const ACTIVITIES = [
+  { description: 'reading a book', emoji: '📖', duration: 60_000 },
+  { description: 'daydreaming', emoji: '🤔', duration: 60_000 },
+  { description: 'gardening', emoji: '🥕', duration: 60_000 },
+];
+
+export const ENGINE_ACTION_DURATION = 30000;
+
+export const DAY_DURATION = 120000;
+export const NIGHT_DURATION = 30000;
+
+// Bound the number of pathfinding searches we do per game step.
+export const MAX_PATHFINDS_PER_STEP = 16;
+
+export const DEFAULT_NAME = 'Me';

patches/convex/crons.ts

@@ -0,0 +1,89 @@
+import { cronJobs } from 'convex/server';
+import { DELETE_BATCH_SIZE, IDLE_WORLD_TIMEOUT, VACUUM_MAX_AGE } from './constants';
+import { internal } from './_generated/api';
+import { internalMutation } from './_generated/server';
+import { TableNames } from './_generated/dataModel';
+import { v } from 'convex/values';
+
+const crons = cronJobs();
+
+crons.interval(
+  'stop inactive worlds',
+  { seconds: IDLE_WORLD_TIMEOUT / 1000 },
+  internal.world.stopInactiveWorlds,
+);
+
+crons.interval('restart dead worlds', { seconds: 60 }, internal.world.restartDeadWorlds);
+
+crons.daily('vacuum old entries', { hourUTC: 4, minuteUTC: 20 }, internal.crons.vacuumOldEntries);
+
+export default crons;
+
+const TablesToVacuum: TableNames[] = [
+  // Un-comment this to also clean out old conversations.
+  // 'conversationMembers', 'conversations', 'messages',
+
+  // Inputs aren't useful unless you're trying to replay history.
+  // If you want to support that, you should add a snapshot table, so you can
+  // replay from a certain time period. Or stop vacuuming inputs and replay from
+  // the beginning of time
+  'inputs',
+
+  // We can keep memories without their embeddings for inspection, but we won't
+  // retrieve them when searching memories via vector search.
+  'memories',
+  // We can vacuum fewer tables without serious consequences, but the only
+  // one that will cause issues over time is having >>100k vectors.
+  'memoryEmbeddings',
+];
+
+export const vacuumOldEntries = internalMutation({
+  args: {},
+  handler: async (ctx, args) => {
+    const before = Date.now() - VACUUM_MAX_AGE;
+    for (const tableName of TablesToVacuum) {
+      console.log(`Checking ${tableName}...`);
+      const exists = await ctx.db
+        .query(tableName)
+        .withIndex('by_creation_time', (q) => q.lt('_creationTime', before))
+        .first();
+      if (exists) {
+        console.log(`Vacuuming ${tableName}...`);
+        await ctx.scheduler.runAfter(0, internal.crons.vacuumTable, {
+          tableName,
+          before,
+          cursor: null,
+          soFar: 0,
+        });
+      }
+    }
+  },
+});
+
+export const vacuumTable = internalMutation({
+  args: {
+    tableName: v.string(),
+    before: v.number(),
+    cursor: v.union(v.string(), v.null()),
+    soFar: v.number(),
+  },
+  handler: async (ctx, { tableName, before, cursor, soFar }) => {
+    const results = await ctx.db
+      .query(tableName as TableNames)
+      .withIndex('by_creation_time', (q) => q.lt('_creationTime', before))
+      .paginate({ cursor, numItems: DELETE_BATCH_SIZE });
+    for (const row of results.page) {
+      await ctx.db.delete(row._id);
+    }
+    if (!results.isDone) {
+      await ctx.scheduler.runAfter(0, internal.crons.vacuumTable, {
+        tableName,
+        before,
+        soFar: results.page.length + soFar,
+        cursor: results.continueCursor,
+      });
+    } else {
+      console.log(`Vacuumed ${soFar + results.page.length} entries from ${tableName}`);
+    }
+  },
+});

patches/convex/engine/abstractGame.ts

@@ -0,0 +1,199 @@
+import { ConvexError, Infer, Value, v } from 'convex/values';
+import { Doc, Id } from '../_generated/dataModel';
+import { ActionCtx, DatabaseReader, MutationCtx, internalQuery } from '../_generated/server';
+import { engine } from '../engine/schema';
+import { internal } from '../_generated/api';
+
+export abstract class AbstractGame {
+  abstract tickDuration: number;
+  abstract stepDuration: number;
+  abstract maxTicksPerStep: number;
+  abstract maxInputsPerStep: number;
+
+  constructor(public engine: Doc<'engines'>) {}
+
+  abstract handleInput(now: number, name: string, args: object): Value;
+  abstract tick(now: number): void;
+
+  // Optional callback at the beginning of each step.
+  beginStep(now: number) {}
+  abstract saveStep(ctx: ActionCtx, engineUpdate: EngineUpdate): Promise<void>;
+
+  async runStep(ctx: ActionCtx, now: number) {
+    const inputs = await ctx.runQuery(internal.engine.abstractGame.loadInputs, {
+      engineId: this.engine._id,
+      processedInputNumber: this.engine.processedInputNumber,
+      max: this.maxInputsPerStep,
+    });
+
+    const lastStepTs = this.engine.currentTime;
+    const startTs = lastStepTs ? lastStepTs + this.tickDuration : now;
+    let currentTs = startTs;
+    let inputIndex = 0;
+    let numTicks = 0;
+    let processedInputNumber = this.engine.processedInputNumber;
+    const completedInputs = [];
+
+    this.beginStep(currentTs);
+
+    while (numTicks < this.maxTicksPerStep) {
+      numTicks += 1;
+
+      // Collect all of the inputs for this tick.
+      const tickInputs = [];
+      while (inputIndex < inputs.length) {
+        const input = inputs[inputIndex];
+        if (input.received > currentTs) {
+          break;
+        }
+        inputIndex += 1;
+        processedInputNumber = input.number;
+        tickInputs.push(input);
+      }
+
+      // Feed the inputs to the game.
+      for (const input of tickInputs) {
+        let returnValue;
+        try {
+          const value = this.handleInput(currentTs, input.name, input.args);
+          returnValue = { kind: 'ok' as const, value };
+        } catch (e: any) {
+          console.error(`Input ${input._id} failed: ${e.message}`);
+          returnValue = { kind: 'error' as const, message: e.message };
+        }
+        completedInputs.push({ inputId: input._id, returnValue });
+      }
+
+      // Simulate the game forward one tick.
+      this.tick(currentTs);
+
+      const candidateTs = currentTs + this.tickDuration;
+      if (now < candidateTs) {
+        break;
+      }
+      currentTs = candidateTs;
+    }
+
+    // Commit the step by moving time forward, consuming our inputs, and saving the game's state.
+    const expectedGenerationNumber = this.engine.generationNumber;
+    this.engine.currentTime = currentTs;
+    this.engine.lastStepTs = lastStepTs;
+    this.engine.generationNumber += 1;
+    this.engine.processedInputNumber = processedInputNumber;
+    const { _id, _creationTime, ...engine } = this.engine;
+    const engineUpdate = { engine, completedInputs, expectedGenerationNumber };
+    await this.saveStep(ctx, engineUpdate);
+
+    console.debug(`Simulated from ${startTs} to ${currentTs} (${currentTs - startTs}ms)`);
+  }
+}
+
+const completedInput = v.object({
+  inputId: v.id('inputs'),
+  returnValue: v.union(
+    v.object({
+      kind: v.literal('ok'),
+      value: v.any(),
+    }),
+    v.object({
+      kind: v.literal('error'),
+      message: v.string(),
+    }),
+  ),
+});
+
+export const engineUpdate = v.object({
+  engine,
+  expectedGenerationNumber: v.number(),
+  completedInputs: v.array(completedInput),
+});
+export type EngineUpdate = Infer<typeof engineUpdate>;
+
+export async function loadEngine(
+  db: DatabaseReader,
+  engineId: Id<'engines'>,
+  generationNumber: number,
+) {
+  const engine = await db.get(engineId);
+  if (!engine) {
+    throw new Error(`No engine found with id ${engineId}`);
+  }
+  if (!engine.running) {
+    throw new ConvexError({
+      kind: 'engineNotRunning',
+      message: `Engine ${engineId} is not running`,
+    });
+  }
+  if (engine.generationNumber !== generationNumber) {
+    throw new ConvexError({ kind: 'generationNumber', message: 'Generation number mismatch' });
+  }
+  return engine;
+}
+
+export async function engineInsertInput(
+  ctx: MutationCtx,
+  engineId: Id<'engines'>,
+  name: string,
+  args: any,
+): Promise<Id<'inputs'>> {
+  const now = Date.now();
+  const prevInput = await ctx.db
+    .query('inputs')
+    .withIndex('byInputNumber', (q) => q.eq('engineId', engineId))
+    .order('desc')
+    .first();
+  const number = prevInput ? prevInput.number + 1 : 0;
+  const inputId = await ctx.db.insert('inputs', {
+    engineId,
+    number,
+    name,
+    args,
+    received: now,
+  });
+  return inputId;
+}
+
+export const loadInputs = internalQuery({
+  args: {
+    engineId: v.id('engines'),
+    processedInputNumber: v.optional(v.number()),
+    max: v.number(),
+  },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query('inputs')
+      .withIndex('byInputNumber', (q) =>
+        q.eq('engineId', args.engineId).gt('number', args.processedInputNumber ?? -1),
+      )
+      .order('asc')
+      .take(args.max);
+  },
+});
+
+export async function applyEngineUpdate(
+  ctx: MutationCtx,
+  engineId: Id<'engines'>,
+  update: EngineUpdate,
+) {
+  const engine = await loadEngine(ctx.db, engineId, update.expectedGenerationNumber);
+  if (
+    engine.currentTime &&
+    update.engine.currentTime &&
+    update.engine.currentTime < engine.currentTime
+  ) {
+    throw new Error('Time moving backwards');
+  }
+  await ctx.db.replace(engine._id, update.engine);
+
+  for (const completedInput of update.completedInputs) {
+    const input = await ctx.db.get(completedInput.inputId);
+    if (!input) {
+      throw new Error(`Input ${completedInput.inputId} not found`);
+    }
+    if (input.returnValue) {
+      throw new Error(`Input ${completedInput.inputId} already completed`);
+    }
+    input.returnValue = completedInput.returnValue;
+    await ctx.db.replace(input._id, input);
+  }
+}

patches/convex/engine/historicalObject.test.ts

@@ -0,0 +1,47 @@
+import { History, packSampleRecord, unpackSampleRecord } from './historicalObject';
+
+describe('HistoricalObject', () => {
+  test('pack sample record roundtrips', () => {
+    let data: Record<string, History> = {
+      x: {
+        initialValue: 0,
+        samples: [
+          { time: 1696021246740, value: 1 },
+          { time: 1696021246756, value: 2 },
+          { time: 1696021246772, value: 3 },
+          { time: 1696021246788, value: 4 },
+        ],
+      },
+      y: {
+        initialValue: 140.2,
+        samples: [
+          { time: 1696021246740, value: 169.7 },
+          { time: 1696021246756, value: 237.59 },
+          { time: 1696021246772, value: 344.44 },
+          { time: 1696021246788, value: 489.13 },
+        ],
+      },
+    };
+    const fields = [
+      { name: 'x', precision: 4 },
+      { name: 'y', precision: 4 },
+    ];
+    const packed = packSampleRecord(fields, data);
+    const unpacked = unpackSampleRecord(fields, packed);
+    const maxError = Math.max(1 / (1 << 4), 1e-8);
+
+    expect(Object.keys(data)).toEqual(Object.keys(unpacked));
+    for (const key of Object.keys(data)) {
+      const { initialValue, samples } = data[key];
+      const { initialValue: unpackedInitialValue, samples: unpackedSamples } = unpacked[key];
+      expect(Math.abs(initialValue - unpackedInitialValue)).toBeLessThanOrEqual(maxError);
+      expect(samples.length).toEqual(unpackedSamples.length);
+      for (let i = 0; i < samples.length; i++) {
+        const sample = samples[i];
+        const unpackedSample = unpackedSamples[i];
+        expect(sample.time).toEqual(unpackedSample.time);
+        expect(Math.abs(sample.value - unpackedSample.value)).toBeLessThanOrEqual(maxError);
+      }
+    }
+  });
+});

patches/convex/engine/historicalObject.ts

@@ -0,0 +1,355 @@
+import { xxHash32 } from '../util/xxhash';
+import { compressSigned, uncompressSigned } from '../util/FastIntegerCompression';
+import {
+  runLengthEncode,
+  deltaEncode,
+  quantize,
+  deltaDecode,
+  runLengthDecode,
+  unquantize,
+} from '../util/compression';
+
+// `HistoricalObject`s require the developer to pass in the
+// field names that'll be tracked and sent down to the client.
+//
+// By default, the historical tracking will round each floating point
+// value to an integer. The developer can specify more or less precision
+// via the `precision` parameter: the table's quantization will maintain
+// less than `1 / 2^precision` error. Note that higher precision values
+// imply less error.
+export type FieldConfig = Array<string | { name: string; precision: number }>;
+
+// `HistoricalObject`s support at most 16 fields.
+const MAX_FIELDS = 16;
+
+const PACKED_VERSION = 1;
+
+type NormalizedFieldConfig = Array<{
+  name: string;
+  precision: number;
+}>;
+
+// The `History` structure represents the history of a continuous
+// value over all bounded time. Each sample represents a line
+// segment that's extends to the previous sample's time inclusively
+// and to the sample's time non-inclusively. We track an `initialValue`
+// that goes to `-\infty` up until the first sample, and the final
+// sample persists out to `+\infty`.
+// ```
+//                    ^
+//                 position
+//                    |
+// samples[0].value - |         x---------------o
+//                    |
+// samples[1].value - |                         x-------->
+//                    |
+// initialValue     - <---------o
+//                    |
+//                     ------------------------------> time
+//                              |               |
+//                      samples[0].time  samples[1].time
+// ```
+export type History = {
+  initialValue: number;
+  samples: Sample[];
+};
+
+export type Sample = {
+  time: number;
+  value: number;
+};
+
+// `HistoricalObject` tracks a set of numeric fields over time and
+// supports compressing the fields' histories into a binary buffer.
+// This can be useful for continuous properties like position, where
+// we'd want to smoothly replay their tick-by-tick progress at a high
+// frame rate on the client.
+//
+// `HistoricalObject`s have a few limitations:
+// - Documents in a historical can only have up to 16 fields.
+// - The historical tracking only applies to a specified list of fields,
+//   and these fields must match between the client and server.
+export class HistoricalObject<T extends Record<string, number>> {
+  startTs?: number;
+
+  fieldConfig: NormalizedFieldConfig;
+
+  data: T;
+  history: Record<string, History> = {};
+
+  constructor(fields: FieldConfig, initialValue: T) {
+    if (fields.length >= MAX_FIELDS) {
+      throw new Error(`HistoricalObject can have at most ${MAX_FIELDS} fields.`);
+    }
+    this.fieldConfig = normalizeFieldConfig(fields);
+    this.checkShape(initialValue);
+    this.data = initialValue;
+  }
+
+  historyLength() {
+    return Object.values(this.history)
+      .map((h) => h.samples.length)
+      .reduce((a, b) => a + b, 0);
+  }
+
+  checkShape(data: any) {
+    for (const [key, value] of Object.entries(data)) {
+      if (!this.fieldConfig.find((f) => f.name === key)) {
+        throw new Error(`Cannot set undeclared field '${key}'`);
+      }
+      if (typeof value !== 'number') {
+        throw new Error(
+          `HistoricalObject only supports numeric values, found: ${JSON.stringify(value)}`,
+        );
+      }
+    }
+  }
+
+  update(now: number, data: T) {
+    this.checkShape(data);
+    for (const [key, value] of Object.entries(data)) {
+      const currentValue = this.data[key];
+      if (currentValue !== value) {
+        let history = this.history[key];
+        if (!history) {
+          this.history[key] = history = { initialValue: currentValue, samples: [] };
+        }
+        const { samples } = history;
+        let inserted = false;
+        if (samples.length > 0) {
+          const last = samples[samples.length - 1];
+          if (now < last.time) {
+            throw new Error(`Server time moving backwards: ${now} < ${last.time}`);
+          }
+          if (now === last.time) {
+            last.value = value;
+            inserted = true;
+          }
+        }
+        if (!inserted) {
+          samples.push({ time: now, value });
+        }
+      }
+    }
+    this.data = data;
+  }
+
+  pack(): ArrayBuffer | null {
+    if (this.historyLength() === 0) {
+      return null;
+    }
+    return packSampleRecord(this.fieldConfig, this.history);
+  }
+}
+
+// Pack (normalized) field configuration into a binary buffer.
+//
+// Format:
+// ```
+// [ u8 version ]
+// for each field config:
+//   [ u8 field name length ]
+//   [ UTF8 encoded field name ]
+//   [ u8 precision ]
+// ```
+function packFieldConfig(fields: NormalizedFieldConfig) {
+  const out = new ArrayBuffer(1024);
+  const outView = new DataView(out);
+  let pos = 0;
+
+  outView.setUint8(pos, PACKED_VERSION);
+  pos += 1;
+
+  const encoder = new TextEncoder();
+  for (const fieldConfig of fields) {
+    const name = encoder.encode(fieldConfig.name);
+
+    outView.setUint8(pos, name.length);
+    pos += 1;
+
+    new Uint8Array(out, pos, name.length).set(name);
+    pos += name.length;
+
+    outView.setUint8(pos, fieldConfig.precision);
+    pos += 1;
+  }
+  return out.slice(0, pos);
+}
+
+// Pack a document's sample record into a binary buffer.
+//
+// We encode each field's history with a few layered forms of
+// compression:
+// 1. Quantization: Turn each floating point number into an integer
+//    by multiplying by 2^precision and then `Math.floor()`.
+// 2. Delta encoding: Assume that values are continuous and don't
+//    abruptly change over time, so their differences will be small.
+//    This step turns the large integers from (1) into small ones.
+// 3. Run length encoding (optional): Assume that some quantities
+//    in the system will have constant velocity, so encode `k`
+//    repetitions of `n` as `[k, n]`. If run length encoding doesn't
+//    make (2) smaller, we skip it.
+// 4. Varint encoding: Using FastIntegerCompression.js, we use a
+//    variable length integer encoding that uses fewer bytes for
+//    smaller numbers.
+//
+// Format:
+// ```
+// [ 4 byte xxhash of packed field config ]
+//
+// for each set field:
+//   [ 0 0 0 useRLE? ]
+//   [ u4 field number ]
+//
+//   Sample timestamps:
+//   [ u64le initial timestamp ]
+//   [ u16le timestamp buffer length ]
+//   [ vint(RLE(delta(remaining timestamps)))]
+//
+//   Sample values:
+//   [ u16le value buffer length ]
+//   [ vint(RLE?(delta([initialValue, ...values])))]
+// ```
+export function packSampleRecord(
+  fields: NormalizedFieldConfig,
+  sampleRecord: Record<string, History>,
+): ArrayBuffer {
+  const out = new ArrayBuffer(65536);
+  const outView = new DataView(out);
+  let pos = 0;
+
+  const configHash = xxHash32(new Uint8Array(packFieldConfig(fields)));
+  outView.setUint32(pos, configHash, true);
+  pos += 4;
+
+  for (let fieldNumber = 0; fieldNumber < fields.length; fieldNumber += 1) {
+    const { name, precision } = fields[fieldNumber];
+    const history = sampleRecord[name];
+    if (!history || history.samples.length === 0) {
+      continue;
+    }
+
+    const timestamps = history.samples.map((s) => Math.floor(s.time));
+    const initialTimestamp = timestamps[0];
+    const encodedTimestamps = runLengthEncode(deltaEncode(timestamps.slice(1), initialTimestamp));
+    const compressedTimestamps = compressSigned(encodedTimestamps);
+    if (compressedTimestamps.byteLength >= 1 << 16) {
+      throw new Error(`Compressed buffer too long: ${compressedTimestamps.byteLength}`);
+    }
+
+    const values = [history.initialValue, ...history.samples.map((s) => s.value)];
+    const quantized = quantize(values, precision);
+    const deltaEncoded = deltaEncode(quantized);
+    const runLengthEncoded = runLengthEncode(deltaEncoded);
+
+    // Decide if we're going to run length encode the values based on whether
+    // it actually made the encoded buffer smaller.
+    const useRLE = runLengthEncoded.length < deltaEncoded.length;
+    let fieldHeader = fieldNumber;
+    if (useRLE) {
+      fieldHeader |= 1 << 4;
+    }
+
+    const encoded = useRLE ? runLengthEncoded : deltaEncoded;
+    const compressed = compressSigned(encoded);
+    if (compressed.byteLength >= 1 << 16) {
+      throw new Error(`Compressed buffer too long: ${compressed.byteLength}`);
+    }
+
+    outView.setUint8(pos, fieldHeader);
+    pos += 1;
+
+    outView.setBigUint64(pos, BigInt(initialTimestamp), true);
+    pos += 8;
+
+    outView.setUint16(pos, compressedTimestamps.byteLength, true);
+    pos += 2;
+
+    new Uint8Array(out, pos, compressedTimestamps.byteLength).set(
+      new Uint8Array(compressedTimestamps),
+    );
+    pos += compressedTimestamps.byteLength;
+
+    outView.setUint16(pos, compressed.byteLength, true);
+    pos += 2;
+
+    new Uint8Array(out, pos, compressed.byteLength).set(new Uint8Array(compressed));
+    pos += compressed.byteLength;
+  }
+
+  return out.slice(0, pos);
+}
+
+export function unpackSampleRecord(fields: FieldConfig, buffer: ArrayBuffer) {
+  const view = new DataView(buffer);
+  let pos = 0;
+
+  const normalizedFields = normalizeFieldConfig(fields);
+  const expectedConfigHash = xxHash32(new Uint8Array(packFieldConfig(normalizedFields)));
+
+  const configHash = view.getUint32(pos, true);
+  pos += 4;
+
+  if (configHash !== expectedConfigHash) {
+    throw new Error(`Config hash mismatch: ${configHash} !== ${expectedConfigHash}`);
+  }
+
+  const out = {} as Record<string, History>;
+  while (pos < buffer.byteLength) {
+    const fieldHeader = view.getUint8(pos);
+    pos += 1;
+
+    const fieldNumber = fieldHeader & 0b00001111;
+    const useRLE = (fieldHeader & (1 << 4)) !== 0;
+    const fieldConfig = normalizedFields[fieldNumber];
+    if (!fieldConfig) {
+      throw new Error(`Invalid field number: ${fieldNumber}`);
+    }
+
+    const initialTimestamp = Number(view.getBigUint64(pos, true));
+    pos += 8;
+
+    const compressedTimestampLength = view.getUint16(pos, true);
+    pos += 2;
+
+    const compressedTimestampBuffer = buffer.slice(pos, pos + compressedTimestampLength);
+    pos += compressedTimestampLength;
+
+    const timestamps = [
+      initialTimestamp,
+      ...deltaDecode(
+        runLengthDecode(uncompressSigned(compressedTimestampBuffer)),
+        initialTimestamp,
+      ),
+    ];
+
+    const compressedLength = view.getUint16(pos, true);
+    pos += 2;
+
+    const compressedBuffer = buffer.slice(pos, pos + compressedLength);
+    pos += compressedLength;
+
+    const encoded = uncompressSigned(compressedBuffer);
+    const deltaEncoded = useRLE ? runLengthDecode(encoded) : encoded;
+    const quantized = deltaDecode(deltaEncoded);
+    const values = unquantize(quantized, fieldConfig.precision);
+
+    if (timestamps.length + 1 !== values.length) {
+      throw new Error(`Invalid sample record: ${timestamps.length} + 1 !== ${values.length}`);
+    }
+    const initialValue = values[0];
+    const samples = [];
+    for (let i = 0; i < timestamps.length; i++) {
+      const time = timestamps[i];
+      const value = values[i + 1];
+      samples.push({ value, time });
+    }
+    const history = { initialValue, samples };
+    out[fieldConfig.name] = history;
+  }
+  return out;
+}
+
+function normalizeFieldConfig(fields: FieldConfig): NormalizedFieldConfig {
+  return fields.map((f) => (typeof f === 'string' ? { name: f, precision: 0 } : f));
+}

patches/convex/engine/schema.ts

@@ -0,0 +1,56 @@
+import { defineTable } from 'convex/server';
+import { Infer, v } from 'convex/values';
+
+const input = v.object({
+  // Inputs are scoped to a single engine.
+  engineId: v.id('engines'),
+
+  // Monotonically increasing input number within a world starting at 0.
+  number: v.number(),
+
+  // Name of the input handler to run.
+  name: v.string(),
+  // Dynamically typed arguments and return value for the input handler. We'll
+  // provide type safety at a higher layer.
+  args: v.any(),
+  returnValue: v.optional(
+    v.union(
+      v.object({
+        kind: v.literal('ok'),
+        value: v.any(),
+      }),
+      v.object({
+        kind: v.literal('error'),
+        message: v.string(),
+      }),
+    ),
+  ),
+
+  // Timestamp when the server received the input. This timestamp is best-effort,
+  // since we don't guarantee strict monotonicity here. So, an input may not get
+  // assigned to the engine step whose time interval contains this timestamp.
+  received: v.number(),
+});
+
+export const engine = v.object({
+  // What is the current simulation time for the engine? Monotonically increasing.
+  currentTime: v.optional(v.number()),
+  // What was `currentTime` for the preceding step of the engine?
+  lastStepTs: v.optional(v.number()),
+
+  // How far has the engine processed in the input queue?
+  processedInputNumber: v.optional(v.number()),
+
+  running: v.boolean(),
+
+  // Monotonically increasing counter that serializes all engine runs. If we ever
+  // end up with two steps overlapping in time, this counter will force them to
+  // conflict.
+  generationNumber: v.number(),
+});
+export type Engine = Infer<typeof engine>;
+
+export const engineTables = {
+  inputs: defineTable(input).index('byInputNumber', ['engineId', 'number']),
+  engines: defineTable(engine),
+};

patches/convex/http.ts

@@ -0,0 +1,10 @@
+import { httpRouter } from 'convex/server';
+import { handleReplicateWebhook } from './music';
+
+const http = httpRouter();
+http.route({
+  path: '/replicate_webhook',
+  method: 'POST',
+  handler: handleReplicateWebhook,
+});
+export default http;

patches/convex/init.ts

@@ -0,0 +1,125 @@
+import { v } from 'convex/values';
+import { internal } from './_generated/api';
+import { DatabaseReader, MutationCtx, mutation } from './_generated/server';
+import { Descriptions } from '../data/characters';
+import * as map from '../data/gentle';
+import { insertInput } from './aiTown/insertInput';
+import { Id } from './_generated/dataModel';
+import { createEngine } from './aiTown/main';
+import { ENGINE_ACTION_DURATION, DAY_DURATION, NIGHT_DURATION } from './constants';
+import { assertApiKey } from './util/llm';
+
+const init = mutation({
+  args: {
+    numAgents: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    assertApiKey();
+    const { worldStatus, engine } = await getOrCreateDefaultWorld(ctx);
+    if (worldStatus.status !== 'running') {
+      console.warn(
+        `Engine ${engine._id} is not active! Run "npx convex run testing:resume" to restart it.`,
+      );
+      return;
+    }
+    const shouldCreate = await shouldCreateAgents(
+      ctx.db,
+      worldStatus.worldId,
+      worldStatus.engineId,
+    );
+    if (shouldCreate) {
+      const toCreate = args.numAgents !== undefined ? args.numAgents : Descriptions.length;
+      for (let i = 0; i < toCreate; i++) {
+        await insertInput(ctx, worldStatus.worldId, 'createAgent', {
+          descriptionIndex: i % Descriptions.length,
+        });
+      }
+    }
+  },
+});
+export default init;
+
+async function getOrCreateDefaultWorld(ctx: MutationCtx) {
+  const now = Date.now();
+
+  let worldStatus = await ctx.db
+    .query('worldStatus')
+    .filter((q) => q.eq(q.field('isDefault'), true))
+    .unique();
+  if (worldStatus) {
+    const engine = (await ctx.db.get(worldStatus.engineId))!;
+    return { worldStatus, engine };
+  }
+
+  const engineId = await createEngine(ctx);
+  const engine = (await ctx.db.get(engineId))!;
+  const worldId = await ctx.db.insert('worlds', {
+    nextId: 0,
+    agents: [],
+    conversations: [],
+    players: [],
+    // initialize day & night cycle counter
+    dayNightCycle: {
+      currentTime: 0,
+      isDay: true,
+      dayDuration: DAY_DURATION,
+      nightDuration: NIGHT_DURATION,
+    },
+  });
+  const worldStatusId = await ctx.db.insert('worldStatus', {
+    engineId: engineId,
+    isDefault: true,
+    lastViewed: now,
+    status: 'running',
+    worldId: worldId,
+  });
+  worldStatus = (await ctx.db.get(worldStatusId))!;
+  await ctx.db.insert('maps', {
+    worldId,
+    width: map.mapwidth,
+    height: map.mapheight,
+    tileSetUrl: map.tilesetpath,
+    tileSetAlternateUrl: map.tilesetalternatepath,
+    tileSetDimX: map.tilesetpxw,
+    tileSetDimY: map.tilesetpxh,
+    tileDim: map.tiledim,
+    bgTiles: map.bgtiles,
+    objectTiles: map.objmap,
+    decorTiles: map.decors,
+    bgTilesN: map.bgtilesN,
+    objectTilesN: map.objmapN,
+    decorTilesN: map.decorsN,
+    animatedSprites: map.animatedsprites,
+  });
+  await ctx.scheduler.runAfter(0, internal.aiTown.main.runStep, {
+    worldId,
+    generationNumber: engine.generationNumber,
+    maxDuration: ENGINE_ACTION_DURATION,
+  });
+  return { worldStatus, engine };
+}
+
+async function shouldCreateAgents(
+  db: DatabaseReader,
+  worldId: Id<'worlds'>,
+  engineId: Id<'engines'>,
+) {
+  const world = await db.get(worldId);
+  if (!world) {
+    throw new Error(`Invalid world ID: ${worldId}`);
+  }
+  if (world.agents.length > 0) {
+    return false;
+  }
+  const unactionedJoinInputs = await db
+    .query('inputs')
+    .withIndex('byInputNumber', (q) => q.eq('engineId', engineId))
+    .order('asc')
+    .filter((q) => q.eq(q.field('name'), 'createAgent'))
+    .filter((q) => q.eq(q.field('returnValue'), undefined))
+    .collect();
+  if (unactionedJoinInputs.length > 0) {
+    return false;
+  }
+  return true;
+}

patches/convex/messages.ts

@@ -0,0 +1,53 @@
+import { v } from 'convex/values';
+import { mutation, query } from './_generated/server';
+import { insertInput } from './aiTown/insertInput';
+import { conversationId, playerId } from './aiTown/ids';
+
+export const listMessages = query({
+  args: {
+    worldId: v.id('worlds'),
+    conversationId,
+  },
+  handler: async (ctx, args) => {
+    const messages = await ctx.db
+      .query('messages')
+      .withIndex('conversationId', (q) => q.eq('worldId', args.worldId).eq('conversationId', args.conversationId))
+      .collect();
+    const out = [];
+    for (const message of messages) {
+      const playerDescription = await ctx.db
+        .query('playerDescriptions')
+        .withIndex('worldId', (q) => q.eq('worldId', args.worldId).eq('playerId', message.author))
+        .first();
+      if (!playerDescription) {
+        throw new Error(`Invalid author ID: ${message.author}`);
+      }
+      out.push({ ...message, authorName: playerDescription.name });
+    }
+    return out;
+  },
+});
+
+export const writeMessage = mutation({
+  args: {
+    worldId: v.id('worlds'),
+    conversationId,
+    messageUuid: v.string(),
+    playerId,
+    text: v.string(),
+  },
+  handler: async (ctx, args) => {
+    await ctx.db.insert('messages', {
+      conversationId: args.conversationId,
+      author: args.playerId,
+      messageUuid: args.messageUuid,
+      text: args.text,
+      worldId: args.worldId,
+    });
+    await insertInput(ctx, args.worldId, 'finishSendingMessage', {
+      conversationId: args.conversationId,
+      playerId: args.playerId,
+      timestamp: Date.now(),
+    });
+  },
+});

patches/{music.ts → convex/music.ts}

@@ -1,135 +1,135 @@
-import { v } from 'convex/values';
-import { query, internalMutation } from './_generated/server';
-import Replicate, { WebhookEventType } from 'replicate';
-import { httpAction, internalAction } from './_generated/server';
-import { internal, api } from './_generated/api';
-
-function client(): Replicate {
-  const replicate = new Replicate({
-    auth: process.env.REPLICATE_API_TOKEN || '',
-  });
-  return replicate;
-}
-
-function replicateAvailable(): boolean {
-  return !!process.env.REPLICATE_API_TOKEN;
-}
-
-export const insertMusic = internalMutation({
-  args: { storageId: v.string(), type: v.union(v.literal('background'), v.literal('player')) },
-  handler: async (ctx, args) => {
-    await ctx.db.insert('music', {
-      storageId: args.storageId,
-      type: args.type,
-    });
-  },
-});
-
-export const getBackgroundMusic = query({
-  handler: async (ctx) => {
-    const music = await ctx.db
-      .query('music')
-      .filter((entry) => entry.eq(entry.field('type'), 'background'))
-      .order('desc')
-      .first();
-    if (!music) {
-      return '/assets/background.mp3';
-    }
-    const url = await ctx.storage.getUrl(music.storageId);
-    if (!url) {
-      throw new Error(`Invalid storage ID: ${music.storageId}`);
-    }
-    return url;
-  },
-});
-
-export const enqueueBackgroundMusicGeneration = internalAction({
-  handler: async (ctx): Promise<void> => {
-    if (!replicateAvailable()) {
-      return;
-    }
-    const worldStatus = await ctx.runQuery(api.world.defaultWorldStatus);
-    if (!worldStatus) {
-      console.log('No active default world, returning.');
-      return;
-    }
-    // TODO: MusicGen-Large on Replicate only allows 30 seconds. Use MusicGen-Small for longer?
-    await generateMusic('16-bit RPG adventure game with wholesome vibe', 30);
-  },
-});
-
-export const handleReplicateWebhook = httpAction(async (ctx, request) => {
-  const req = await request.json();
-  if (req.id) {
-    const prediction = await client().predictions.get(req.id);
-    const response = await fetch(prediction.output);
-    const music = await response.blob();
-    const storageId = await ctx.storage.store(music);
-    await ctx.runMutation(internal.music.insertMusic, { type: 'background', storageId });
-  }
-  return new Response();
-});
-
-enum MusicGenNormStrategy {
-  Clip = 'clip',
-  Loudness = 'loudness',
-  Peak = 'peak',
-  Rms = 'rms',
-}
-
-enum MusicGenFormat {
-  wav = 'wav',
-  mp3 = 'mp3',
-}
-
-/**
- *
- * @param prompt A description of the music you want to generate.
- * @param duration Duration of the generated audio in seconds.
- * @param webhook webhook URL for Replicate to call when @param webhook_events_filter is triggered
- * @param webhook_events_filter Array of event names to filter the webhook. See https://replicate.com/docs/reference/http#predictions.create--webhook_events_filter
- * @param normalization_strategy Strategy for normalizing audio.
- * @param top_k Reduces sampling to the k most likely tokens.
- * @param top_p Reduces sampling to tokens with cumulative probability of p. When set to `0` (default), top_k sampling is used.
- * @param temperature Controls the 'conservativeness' of the sampling process. Higher temperature means more diversity.
- * @param classifer_free_gudance Increases the influence of inputs on the output. Higher values produce lower-varience outputs that adhere more closely to inputs.
- * @param output_format Output format for generated audio. See @
- * @param seed Seed for random number generator. If None or -1, a random seed will be used.
- * @returns object containing metadata of the prediction with ID to fetch once result is completed
- */
-export async function generateMusic(
-  prompt: string,
-  duration: number,
-  webhook: string = process.env.CONVEX_SITE_URL + '/replicate_webhook' || '',
-  webhook_events_filter: [WebhookEventType] = ['completed'],
-  normalization_strategy: MusicGenNormStrategy = MusicGenNormStrategy.Peak,
-  output_format: MusicGenFormat = MusicGenFormat.mp3,
-  top_k = 250,
-  top_p = 0,
-  temperature = 1,
-  classifer_free_gudance = 3,
-  seed = -1,
-  model_version = 'large',
-) {
-  if (!replicateAvailable()) {
-    throw new Error('Replicate API token not set');
-  }
-  return await client().predictions.create({
-    // https://replicate.com/facebookresearch/musicgen/versions/7a76a8258b23fae65c5a22debb8841d1d7e816b75c2f24218cd2bd8573787906
-    version: '7a76a8258b23fae65c5a22debb8841d1d7e816b75c2f24218cd2bd8573787906',
-    input: {
-      model_version,
-      prompt,
-      duration,
-      normalization_strategy,
-      top_k,
-      top_p,
-      temperature,
-      classifer_free_gudance,
-      output_format,
-      seed,
-    },
-    webhook,
-    webhook_events_filter,
-  });
-}
+import { v } from 'convex/values';
+import { query, internalMutation } from './_generated/server';
+import Replicate, { WebhookEventType } from 'replicate';
+import { httpAction, internalAction } from './_generated/server';
+import { internal, api } from './_generated/api';
+
+function client(): Replicate {
+  const replicate = new Replicate({
+    auth: process.env.REPLICATE_API_TOKEN || '',
+  });
+  return replicate;
+}
+
+function replicateAvailable(): boolean {
+  return !!process.env.REPLICATE_API_TOKEN;
+}
+
+export const insertMusic = internalMutation({
+  args: { storageId: v.string(), type: v.union(v.literal('background'), v.literal('player')) },
+  handler: async (ctx, args) => {
+    await ctx.db.insert('music', {
+      storageId: args.storageId,
+      type: args.type,
+    });
+  },
+});
+
+export const getBackgroundMusic = query({
+  handler: async (ctx) => {
+    const music = await ctx.db
+      .query('music')
+      .filter((entry) => entry.eq(entry.field('type'), 'background'))
+      .order('desc')
+      .first();
+    if (!music) {
+      return '/assets/background.mp3';
+    }
+    const url = await ctx.storage.getUrl(music.storageId);
+    if (!url) {
+      throw new Error(`Invalid storage ID: ${music.storageId}`);
+    }
+    return url;
+  },
+});
+
+export const enqueueBackgroundMusicGeneration = internalAction({
+  handler: async (ctx): Promise<void> => {
+    if (!replicateAvailable()) {
+      return;
+    }
+    const worldStatus = await ctx.runQuery(api.world.defaultWorldStatus);
+    if (!worldStatus) {
+      console.log('No active default world, returning.');
+      return;
+    }
+    // TODO: MusicGen-Large on Replicate only allows 30 seconds. Use MusicGen-Small for longer?
+    await generateMusic('16-bit RPG adventure game with wholesome vibe', 30);
+  },
+});
+
+export const handleReplicateWebhook = httpAction(async (ctx, request) => {
+  const req = await request.json();
+  if (req.id) {
+    const prediction = await client().predictions.get(req.id);
+    const response = await fetch(prediction.output);
+    const music = await response.blob();
+    const storageId = await ctx.storage.store(music);
+    await ctx.runMutation(internal.music.insertMusic, { type: 'background', storageId });
+  }
+  return new Response();
+});
+
+enum MusicGenNormStrategy {
+  Clip = 'clip',
+  Loudness = 'loudness',
+  Peak = 'peak',
+  Rms = 'rms',
+}
+
+enum MusicGenFormat {
+  wav = 'wav',
+  mp3 = 'mp3',
+}
+
+/**
+ *
+ * @param prompt A description of the music you want to generate.
+ * @param duration Duration of the generated audio in seconds.
+ * @param webhook webhook URL for Replicate to call when @param webhook_events_filter is triggered
+ * @param webhook_events_filter Array of event names to filter the webhook. See https://replicate.com/docs/reference/http#predictions.create--webhook_events_filter
+ * @param normalization_strategy Strategy for normalizing audio.
+ * @param top_k Reduces sampling to the k most likely tokens.
+ * @param top_p Reduces sampling to tokens with cumulative probability of p. When set to `0` (default), top_k sampling is used.
+ * @param temperature Controls the 'conservativeness' of the sampling process. Higher temperature means more diversity.
+ * @param classifer_free_gudance Increases the influence of inputs on the output. Higher values produce lower-varience outputs that adhere more closely to inputs.
+ * @param output_format Output format for generated audio. See @
+ * @param seed Seed for random number generator. If None or -1, a random seed will be used.
+ * @returns object containing metadata of the prediction with ID to fetch once result is completed
+ */
+export async function generateMusic(
+  prompt: string,
+  duration: number,
+  webhook: string = process.env.CONVEX_SITE_URL + '/replicate_webhook' || '',
+  webhook_events_filter: [WebhookEventType] = ['completed'],
+  normalization_strategy: MusicGenNormStrategy = MusicGenNormStrategy.Peak,
+  output_format: MusicGenFormat = MusicGenFormat.mp3,
+  top_k = 250,
+  top_p = 0,
+  temperature = 1,
+  classifer_free_gudance = 3,
+  seed = -1,
+  model_version = 'large',
+) {
+  if (!replicateAvailable()) {
+    throw new Error('Replicate API token not set');
+  }
+  return await client().predictions.create({
+    // https://replicate.com/facebookresearch/musicgen/versions/7a76a8258b23fae65c5a22debb8841d1d7e816b75c2f24218cd2bd8573787906
+    version: '7a76a8258b23fae65c5a22debb8841d1d7e816b75c2f24218cd2bd8573787906',
+    input: {
+      model_version,
+      prompt,
+      duration,
+      normalization_strategy,
+      top_k,
+      top_p,
+      temperature,
+      classifer_free_gudance,
+      output_format,
+      seed,
+    },
+    webhook,
+    webhook_events_filter,
+  });
+}

patches/convex/schema.ts

@@ -0,0 +1,27 @@
+import { defineSchema, defineTable } from 'convex/server';
+import { v } from 'convex/values';
+import { agentTables } from './agent/schema';
+import { aiTownTables } from './aiTown/schema';
+import { conversationId, playerId } from './aiTown/ids';
+import { engineTables } from './engine/schema';
+
+export default defineSchema({
+  music: defineTable({
+    storageId: v.string(),
+    type: v.union(v.literal('background'), v.literal('player')),
+  }),
+
+  messages: defineTable({
+    conversationId,
+    messageUuid: v.string(),
+    author: playerId,
+    text: v.string(),
+    worldId: v.optional(v.id('worlds')),
+  })
+    .index('conversationId', ['worldId', 'conversationId'])
+    .index('messageUuid', ['conversationId', 'messageUuid']),
+
+  ...agentTables,
+  ...aiTownTables,
+  ...engineTables,
+});

patches/convex/testing.ts

@@ -0,0 +1,202 @@
+import { Id, TableNames } from './_generated/dataModel';
+import { internal } from './_generated/api';
+import {
+  DatabaseReader,
+  internalAction,
+  internalMutation,
+  mutation,
+  query,
+} from './_generated/server';
+import { v } from 'convex/values';
+import schema from './schema';
+import { DELETE_BATCH_SIZE } from './constants';
+import { kickEngine, startEngine, stopEngine } from './aiTown/main';
+import { insertInput } from './aiTown/insertInput';
+import { fetchEmbedding, LLM_CONFIG } from './util/llm';
+import { chatCompletion } from './util/llm';
+import { startConversationMessage } from './agent/conversation';
+import { GameId } from './aiTown/ids';
+
+// Clear all of the tables except for the embeddings cache.
+const excludedTables: Array<TableNames> = ['embeddingsCache'];
+
+export const wipeAllTables = internalMutation({
+  handler: async (ctx) => {
+    for (const tableName of Object.keys(schema.tables)) {
+      if (excludedTables.includes(tableName as TableNames)) {
+        continue;
+      }
+      await ctx.scheduler.runAfter(0, internal.testing.deletePage, { tableName, cursor: null });
+    }
+  },
+});
+
+export const deletePage = internalMutation({
+  args: {
+    tableName: v.string(),
+    cursor: v.union(v.string(), v.null()),
+  },
+  handler: async (ctx, args) => {
+    const results = await ctx.db
+      .query(args.tableName as TableNames)
+      .paginate({ cursor: args.cursor, numItems: DELETE_BATCH_SIZE });
+    for (const row of results.page) {
+      await ctx.db.delete(row._id);
+    }
+    if (!results.isDone) {
+      await ctx.scheduler.runAfter(0, internal.testing.deletePage, {
+        tableName: args.tableName,
+        cursor: results.continueCursor,
+      });
+    }
+  },
+});
+
+export const kick = internalMutation({
+  handler: async (ctx) => {
+    const { worldStatus } = await getDefaultWorld(ctx.db);
+    await kickEngine(ctx, worldStatus.worldId);
+  },
+});
+
+export const stopAllowed = query({
+  handler: async () => {
+    return !process.env.STOP_NOT_ALLOWED;
+  },
+});
+
+export const stop = mutation({
+  handler: async (ctx) => {
+    if (process.env.STOP_NOT_ALLOWED) throw new Error('Stop not allowed');
+    const { worldStatus, engine } = await getDefaultWorld(ctx.db);
+    if (worldStatus.status === 'inactive' || worldStatus.status === 'stoppedByDeveloper') {
+      if (engine.running) {
+        throw new Error(`Engine ${engine._id} isn't stopped?`);
+      }
+      console.debug(`World ${worldStatus.worldId} is already inactive`);
+      return;
+    }
+    console.log(`Stopping engine ${engine._id}...`);
+    await ctx.db.patch(worldStatus._id, { status: 'stoppedByDeveloper' });
+    await stopEngine(ctx, worldStatus.worldId);
+  },
+});
+
+export const resume = mutation({
+  handler: async (ctx) => {
+    const { worldStatus, engine } = await getDefaultWorld(ctx.db);
+    if (worldStatus.status === 'running') {
+      if (!engine.running) {
+        throw new Error(`Engine ${engine._id} isn't running?`);
+      }
+      console.debug(`World ${worldStatus.worldId} is already running`);
+      return;
+    }
+    console.log(
+      `Resuming engine ${engine._id} for world ${worldStatus.worldId} (state: ${worldStatus.status})...`,
+    );
+    await ctx.db.patch(worldStatus._id, { status: 'running' });
+    await startEngine(ctx, worldStatus.worldId);
+  },
+});
+
+export const archive = internalMutation({
+  handler: async (ctx) => {
+    const { worldStatus, engine } = await getDefaultWorld(ctx.db);
+    if (engine.running) {
+      throw new Error(`Engine ${engine._id} is still running!`);
+    }
+    console.log(`Archiving world ${worldStatus.worldId}...`);
+    await ctx.db.patch(worldStatus._id, { isDefault: false });
+  },
+});
+
+async function getDefaultWorld(db: DatabaseReader) {
+  const worldStatus = await db
+    .query('worldStatus')
+    .filter((q) => q.eq(q.field('isDefault'), true))
+    .first();
+  if (!worldStatus) {
+    throw new Error('No default world found');
+  }
+  const engine = await db.get(worldStatus.engineId);
+  if (!engine) {
+    throw new Error(`Engine ${worldStatus.engineId} not found`);
+  }
+  return { worldStatus, engine };
+}
+
+export const debugCreatePlayers = internalMutation({
+  args: {
+    numPlayers: v.number(),
+  },
+  handler: async (ctx, args) => {
+    const { worldStatus } = await getDefaultWorld(ctx.db);
+    for (let i = 0; i < args.numPlayers; i++) {
+      const inputId = await insertInput(ctx, worldStatus.worldId, 'join', {
+        name: `Robot${i}`,
+        description: `This player is a robot.`,
+        character: `f${1 + (i % 8)}`,
+      });
+    }
+  },
+});
+
+export const randomPositions = internalMutation({
+  handler: async (ctx) => {
+    const { worldStatus } = await getDefaultWorld(ctx.db);
+    const map = await ctx.db
+      .query('maps')
+      .withIndex('worldId', (q) => q.eq('worldId', worldStatus.worldId))
+      .unique();
+    if (!map) {
+      throw new Error(`No map for world ${worldStatus.worldId}`);
+    }
+    const world = await ctx.db.get(worldStatus.worldId);
+    if (!world) {
+      throw new Error(`No world for world ${worldStatus.worldId}`);
+    }
+    for (const player of world.players) {
+      await insertInput(ctx, world._id, 'moveTo', {
+        playerId: player.id,
+        destination: {
+          x: 1 + Math.floor(Math.random() * (map.width - 2)),
+          y: 1 + Math.floor(Math.random() * (map.height - 2)),
+        },
+      });
+    }
+  },
+});
+
+export const testEmbedding = internalAction({
+  args: { input: v.string() },
+  handler: async (_ctx, args) => {
+    return await fetchEmbedding(args.input);
+  },
+});
+
+export const testCompletion = internalAction({
+  args: {},
+  handler: async (ctx, args) => {
+    return await chatCompletion({
+      messages: [
+        { content: 'You are helpful', role: 'system' },
+        { content: 'Where is pizza?', role: 'user' },
+      ],
+    });
+  },
+});
+
+export const testConvo = internalAction({
+  args: {},
+  handler: async (ctx, args) => {
+    const a: any = (await startConversationMessage(
+      ctx,
+      'm1707m46wmefpejw1k50rqz7856qw3ew' as Id<'worlds'>,
+      'c:115' as GameId<'conversations'>,
+      'p:0' as GameId<'players'>,
+      'p:6' as GameId<'players'>,
+    )) as any;
+    return await a.readAll();
+  },
+});

patches/convex/util/FastIntegerCompression.ts

@@ -0,0 +1,221 @@
+/**
+ * FastIntegerCompression.js : a fast integer compression library in JavaScript.
+ * From https://github.com/lemire/FastIntegerCompression.js/
+ * (c) the authors
+ * Licensed under the Apache License, Version 2.0.
+ *
+ *FastIntegerCompression
+ * Simple usage :
+ *  // var FastIntegerCompression = require("fastintcompression");// if you use node
+ *  var array = [10,100000,65999,10,10,0,1,1,2000];
+ *  var buf = FastIntegerCompression.compress(array);
+ *  var back = FastIntegerCompression.uncompress(buf); // gets back [10,100000,65999,10,10,0,1,1,2000]
+ *
+ *
+ * You can install the library under node with the command line
+ *   npm install fastintcompression
+ */
+
+function bytelog(val: number) {
+  if (val < 1 << 7) {
+    return 1;
+  } else if (val < 1 << 14) {
+    return 2;
+  } else if (val < 1 << 21) {
+    return 3;
+  } else if (val < 1 << 28) {
+    return 4;
+  }
+  return 5;
+}
+
+function zigzag_encode(val: number) {
+  return (val + val) ^ (val >> 31);
+}
+
+function zigzag_decode(val: number) {
+  return (val >> 1) ^ -(val & 1);
+}
+
+// Compute how many bytes an array of integers would use once compressed.
+// The input is expected to be an array of non-negative integers.
+export function computeCompressedSizeInBytes(input: number[]) {
+  var c = input.length;
+  var answer = 0;
+  for (var i = 0; i < c; i++) {
+    answer += bytelog(input[i]);
+  }
+  return answer;
+}
+
+// Compute how many bytes an array of integers would use once compressed.
+// The input is expected to be an array of integers, some of them can be negative.
+export function computeCompressedSizeInBytesSigned(input: number[]) {
+  var c = input.length;
+  var answer = 0;
+  for (var i = 0; i < c; i++) {
+    answer += bytelog(zigzag_encode(input[i]));
+  }
+  return answer;
+}
+
+// Compress an array of integers, return a compressed buffer (as an ArrayBuffer).
+// It is expected that the integers are non-negative: the caller is responsible
+// for making this check. Floating-point numbers are not supported.
+export function compress(input: number[]) {
+  var c = input.length;
+  var buf = new ArrayBuffer(computeCompressedSizeInBytes(input));
+  var view = new Int8Array(buf);
+  var pos = 0;
+  for (var i = 0; i < c; i++) {
+    var val = input[i];
+    if (val < 1 << 7) {
+      view[pos++] = val;
+    } else if (val < 1 << 14) {
+      view[pos++] = (val & 0x7f) | 0x80;
+      view[pos++] = val >>> 7;
+    } else if (val < 1 << 21) {
+      view[pos++] = (val & 0x7f) | 0x80;
+      view[pos++] = ((val >>> 7) & 0x7f) | 0x80;
+      view[pos++] = val >>> 14;
+    } else if (val < 1 << 28) {
+      view[pos++] = (val & 0x7f) | 0x80;
+      view[pos++] = ((val >>> 7) & 0x7f) | 0x80;
+      view[pos++] = ((val >>> 14) & 0x7f) | 0x80;
+      view[pos++] = val >>> 21;
+    } else {
+      view[pos++] = (val & 0x7f) | 0x80;
+      view[pos++] = ((val >>> 7) & 0x7f) | 0x80;
+      view[pos++] = ((val >>> 14) & 0x7f) | 0x80;
+      view[pos++] = ((val >>> 21) & 0x7f) | 0x80;
+      view[pos++] = val >>> 28;
+    }
+  }
+  return buf;
+}
+
+// From a compressed array of integers stored ArrayBuffer,
+// compute the number of compressed integers by scanning the input.
+export function computeHowManyIntegers(input: ArrayBuffer) {
+  var view = new Uint8Array(input);
+  var c = view.length;
+  var count = 0;
+  for (var i = 0; i < c; i++) {
+    count += view[i] >>> 7;
+  }
+  return c - count;
+}
+// Uncompress an array of integer from an ArrayBuffer, return the array.
+// It is assumed that they were compressed using the compress function, the caller
+// is responsible for ensuring that it is the case.
+export function uncompress(input: ArrayBuffer) {
+  var array = []; // The size of the output is not yet known.
+  var inbyte = new Int8Array(input);
+  var end = inbyte.length;
+  var pos = 0;
+  while (end > pos) {
+    var c = inbyte[pos++];
+    var v = c & 0x7f;
+    if (c >= 0) {
+      array.push(v);
+      continue;
+    }
+    c = inbyte[pos++];
+    v |= (c & 0x7f) << 7;
+    if (c >= 0) {
+      array.push(v);
+      continue;
+    }
+    c = inbyte[pos++];
+    v |= (c & 0x7f) << 14;
+    if (c >= 0) {
+      array.push(v);
+      continue;
+    }
+    c = inbyte[pos++];
+    v |= (c & 0x7f) << 21;
+    if (c >= 0) {
+      array.push(v);
+      continue;
+    }
+    c = inbyte[pos++];
+    v |= c << 28;
+    v >>>= 0; // make positive
+    array.push(v);
+  }
+  return array;
+}
+
+// Compress an array of integers, return a compressed buffer (as an ArrayBuffer).
+// The integers can be signed (negative), but floating-point values are not supported.
+export function compressSigned(input: number[]) {
+  var c = input.length;
+  var buf = new ArrayBuffer(computeCompressedSizeInBytesSigned(input));
+  var view = new Int8Array(buf);
+  var pos = 0;
+  for (var i = 0; i < c; i++) {
+    var val = zigzag_encode(input[i]);
+    if (val < 1 << 7) {
+      view[pos++] = val;
+    } else if (val < 1 << 14) {
+      view[pos++] = (val & 0x7f) | 0x80;
+      view[pos++] = val >>> 7;
+    } else if (val < 1 << 21) {
+      view[pos++] = (val & 0x7f) | 0x80;
+      view[pos++] = ((val >>> 7) & 0x7f) | 0x80;
+      view[pos++] = val >>> 14;
+    } else if (val < 1 << 28) {
+      view[pos++] = (val & 0x7f) | 0x80;
+      view[pos++] = ((val >>> 7) & 0x7f) | 0x80;
+      view[pos++] = ((val >>> 14) & 0x7f) | 0x80;
+      view[pos++] = val >>> 21;
+    } else {
+      view[pos++] = (val & 0x7f) | 0x80;
+      view[pos++] = ((val >>> 7) & 0x7f) | 0x80;
+      view[pos++] = ((val >>> 14) & 0x7f) | 0x80;
+      view[pos++] = ((val >>> 21) & 0x7f) | 0x80;
+      view[pos++] = val >>> 28;
+    }
+  }
+  return buf;
+}
+
+// Uncompress an array of integer from an ArrayBuffer, return the array.
+// It is assumed that they were compressed using the compressSigned function, the caller
+// is responsible for ensuring that it is the case.
+export function uncompressSigned(input: ArrayBuffer) {
+  var array = []; // The size of the output is not yet known.
+  var inbyte = new Int8Array(input);
+  var end = inbyte.length;
+  var pos = 0;
+  while (end > pos) {
+    var c = inbyte[pos++];
+    var v = c & 0x7f;
+    if (c >= 0) {
+      array.push(zigzag_decode(v));
+      continue;
+    }
+    c = inbyte[pos++];
+    v |= (c & 0x7f) << 7;
+    if (c >= 0) {
+      array.push(zigzag_decode(v));
+      continue;
+    }
+    c = inbyte[pos++];
+    v |= (c & 0x7f) << 14;
+    if (c >= 0) {
+      array.push(zigzag_decode(v));
+      continue;
+    }
+    c = inbyte[pos++];
+    v |= (c & 0x7f) << 21;
+    if (c >= 0) {
+      array.push(zigzag_decode(v));
+      continue;
+    }
+    c = inbyte[pos++];
+    v |= c << 28;
+    array.push(zigzag_decode(v));
+  }
+  return array;
+}

patches/convex/util/assertNever.ts

@@ -0,0 +1,4 @@
+// From https://www.typescriptlang.org/docs/handbook/unions-and-intersections.html#union-exhaustiveness-checking
+export function assertNever(x: never): never {
+  throw new Error(`Unexpected object: ${JSON.stringify(x)}`);
+}

patches/convex/util/asyncMap.test.ts

@@ -0,0 +1,15 @@
+import { asyncMap } from './asyncMap';
+
+describe('asyncMap', () => {
+  it('should map over a list asynchronously', async () => {
+    const list = [1, 2, 3];
+    const result = await asyncMap(list, async (item: number) => item * 2);
+    expect(result).toEqual([2, 4, 6]);
+  });
+
+  it('should handle empty list input', async () => {
+    const list: number[] = [];
+    const result = await asyncMap(list, async (item: number) => item * 2);
+    expect(result).toEqual([]);
+  });
+});