bulk

.dockerignore

@@ -0,0 +1,39 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+game/node_modules/
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+.env
+/.env.prod
+/fly.toml

.eslintignore

@@ -0,0 +1,7 @@
+webpack*
+.eslintrc.js
+next.config.js
+tailwind.config.js
+postcss.config.js
+convex/_generated/*
+dist/*

.eslintrc.js

@@ -0,0 +1,22 @@
+export default {
+  parser: '@typescript-eslint/parser', // Specifies the ESLint parser
+  plugins: ['@typescript-eslint'],
+  extends: [
+    'plugin:@typescript-eslint/recommended', // Uses the recommended rules from the @typescript-eslint/eslint-plugin
+    'plugin:@typescript-eslint/recommended-type-checked',
+  ],
+  parserOptions: {
+    project: './tsconfig.json',
+    ecmaVersion: 2018, // Allows for the parsing of modern ECMAScript features
+    sourceType: 'module', // Allows for the use of imports
+  },
+  rules: {
+    '@typescript-eslint/no-explicit-any': 'off',
+    '@typescript-eslint/explicit-function-return-type': 'off',
+    '@typescript-eslint/no-unused-vars': [
+      'warn',
+      { varsIgnorePattern: '^_', argsIgnorePattern: '^_' },
+    ],
+    '@typescript-eslint/no-non-null-assertion': 'off',
+  },
+};

.gitattributes

@@ -1,35 +0,0 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text

.github/workflows/hf-sync.yml

@@ -1,22 +0,0 @@
-name: Sync to Hugging Face Spaces
-on:
-  push:
-    branches:
-      - main
-jobs:
-  sync:
-    name: Sync
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v4
-        with:
-          lfs: true
-      - name: Sync to Hugging Face Spaces
-        uses: JacobLinCool/huggingface-sync@v1
-        with:
-          github: ${{ secrets.GITHUB_TOKEN }}
-          user: ${{ vars.HF_SPACE_OWNER }}
-          space: ${{ vars.HF_SPACE_NAME }}
-          token: ${{ secrets.HF_TOKEN }}
-          configuration: "README.md.yml"

.gitignore

@@ -0,0 +1,45 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+game/node_modules/
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+.env
+/.env.prod
+/fly.toml
+
+# Vite build
+dist
+convex-local-backend*
+convex_local_storage
+convex_local_backend.sqlite3

.prettierrc

@@ -0,0 +1,7 @@
+{
+  "trailingComma": "all",
+  "singleQuote": true,
+  "bracketSpacing": true,
+  "tabWidth": 2,
+  "printWidth": 100
+}

.vscode/convex.code-snippets

@@ -0,0 +1,102 @@
+{
+  "Convex Imports": {
+    "prefix": "convex:imports",
+    "body": [
+      "import { v } from \"convex/values\";",
+      "import { api, internal } from \"./_generated/api\";",
+      "import { Doc, Id } from \"./_generated/dataModel\";",
+      "import {",
+      "  action,",
+      "  internalAction,",
+      "  internalMutation,",
+      "  internalQuery,",
+      "  mutation,",
+      "  query,",
+      "} from \"./_generated/server\";"
+    ],
+    "scope": "javascript,typescript",
+    "isFileTemplate": true
+  },
+
+  "Convex Query": {
+    "prefix": "convex:query",
+    "body": [
+      "export const $1 = query({",
+      "  args: {},",
+      "  handler: async (ctx, args) => {",
+      "    $0",
+      "  },",
+      "});"
+    ],
+    "scope": "javascript,typescript"
+  },
+
+  "Convex Internal Query": {
+    "prefix": "convex:internalQuery",
+    "body": [
+      "export const $1 = internalQuery({",
+      "  args: {},",
+      "  handler: async (ctx, args) => {",
+      "    $0",
+      "  },",
+      "});"
+    ],
+    "scope": "javascript,typescript"
+  },
+
+  "Convex Mutation": {
+    "prefix": "convex:mutation",
+    "body": [
+      "export const $1 = mutation({",
+      "  args: {},",
+      "  handler: async (ctx, args) => {",
+      "    $0",
+      "  },",
+      "});"
+    ],
+    "scope": "javascript,typescript"
+  },
+
+  "Convex Internal Mutation": {
+    "prefix": "convex:internalMutation",
+    "body": [
+      "export const $1 = internalMutation({",
+      "  args: {},",
+      "  handler: async (ctx, args) => {",
+      "    $0",
+      "  },",
+      "});"
+    ],
+    "scope": "javascript,typescript"
+  },
+
+  "Convex Action": {
+    "prefix": "convex:action",
+    "body": [
+      "import { action } from \"./_generated/server\";",
+      "",
+      "export const $1 = action({",
+      "  args: {},",
+      "  handler: async (ctx, args) => {",
+      "    $0",
+      "  },",
+      "});"
+    ],
+    "scope": "javascript,typescript"
+  },
+
+  "Convex Internal Action": {
+    "prefix": "convex:internalAction",
+    "body": [
+      "import { internalAction } from \"./_generated/server\";",
+      "",
+      "export const $1 = internalAction({",
+      "  args: {},",
+      "  handler: async (ctx, args) => {",
+      "    $0",
+      "  },",
+      "});"
+    ],
+    "scope": "javascript,typescript"
+  }
+}

.vscode/settings.json

@@ -0,0 +1,21 @@
+{
+  "editor.formatOnSave": true,
+  "editor.tabSize": 2,
+  "[html]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[javascript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[jsonc]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[typescriptreact]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "typescript.preferences.importModuleSpecifierEnding": "auto",
+  "javascript.preferences.importModuleSpecifierEnding": "auto"
+}

ARCHITECTURE.md

@@ -0,0 +1,301 @@
+# Architecture
+
+This documents dives into the high-level architecture of AI Town and its different layers. We'll
+first start with a brief overview and then go in-depth on each component. The overview should
+be sufficient for forking AI Town and changing game or agent behavior. Read on to the deep dives
+if you're interested or running up against the engine's limitations.
+
+This doc assumes the reader has a working knowledge of Convex. If you're new to Convex, check out
+the [Convex tutorial](https://docs.convex.dev/get-started) to get started.
+
+## Overview
+
+AI Town is split into a few layers:
+
+- The server-side game logic in `convex/aiTown`: This layer defines what state AI Town maintains,
+  how it evolves over time, and how it reacts to user input. Both humans and agents submit inputs
+  that the game engine processes.
+- The client-side game UI in `src/`: AI Town uses `pixi-react` to render the game state to the
+  browser for human consumption.
+- The game engine in `convex/engine`: To make it easy to hack on the game rules, we've separated
+  out the game engine from the AI Town-specific game rules. The game engine is responsible for
+  saving and loading game state from the database, coordinating feeding inputs into the engine,
+  and actually running the game engine in Convex functions.
+- The agent in `convex/agent`: Agents run as part of the game loop, and can kick off asynchronous
+  Convex functions to do longer processing, such as talking to LLMs. Those functions can save state
+  in separate tables, or submit inputs to the game engine to modify game state. Internally, our
+  agents use a combination of simple rule-based systems and talking to an LLM.
+
+So, if you'd like to tweak agent behavior but keep the same game mechanics, check out `convex/agent`
+for the async work, and `convex/aiTown/agent.ts` for the game loop logic.
+If you would like to add new gameplay elements (that both humans and agents can interact with), add
+the feature to `convex/aiTown`, render it in the UI in `src/`, and respond to it in `convex/aiTown/agent.ts`.
+
+If you have parts of your game that are more latency sensitive, you can move them out of engine
+into regular Convex tables, queries, and mutations, only logging key bits into game state. See
+"Message data model" below for an example.
+
+## AI Town game logic (`convex/aiTown`)
+
+### Data model
+
+AI Town's data model has a few concepts:
+
+- Worlds (`convex/aiTown/world.ts`) represent a map with many players interacting together.
+- Players (`convex/aiTown/player.ts`) are the core characters in the game. Players have human readable names and
+  descriptions, and they may be associated with a human user. At any point in time, a player may be pathfinding
+  towards some destination and has a current location.
+- Conversations (`convex/aiTown/conversations.ts`) are created by a player and end at some point in time.
+- Conversation memberships (`convex/aiTown/conversationMembership.ts`) indicate that a player is a member
+  of a conversation. Players may only be in one conversation at any point in time, and conversations
+  currently have exactly two members. Memberships may be in one of three states:
+  - `invited`: The player has been invited to the conversation but hasn't accepted yet.
+  - `walkingOver`: The player has accepted the invite to the conversation but is too far away to talk. The
+    player will automatically join the conversation when they get close enough.
+  - `participating`: The player is actively participating in the conversation.
+
+### Schema
+
+There are three main categories of tables:
+
+1. Engine tables (`convex/engine/schema.ts`) for maintaining engine-internal state.
+2. Game tables (`convex/aiTown/schema.ts`) for game state. To keep game state small and efficient to
+   read and write, we store AI Town's data model across a few tables. See `convex/aiTown/schema.ts` for an overview.
+3. Agent tables (`convex/agent/schema.ts`) for agent state. Agents can freely read and write to these tables
+   within their actions.
+
+### Inputs (`convex/aiTown/inputs.ts`)
+
+AI Town modifies its data model by processing inputs. Inputs are submitted by players and agents and
+processed by the game engine. We specify inputs in the `inputs` object in `convex/aiTown/inputs.ts`.
+Use the `inputHandler` function to construct an input handler, specifying a Convex validator for
+arguments for end-to-end type-safety.
+
+- Joining (`join`) and leaving (`leave`) the game.
+- Moving a player to a particular location (`moveTo`): Movement in AI Town is similar to RTS games, where
+  the players specify where they want to go, and the engine figures out how to get there.
+- Starting a conversation (`startConversation`), accepting an invite (`acceptInvite`), rejecting an invite
+  (`rejectInvite`), and leaving a conversation (`leaveConversation`). To track typing indicators,
+  you use `startTyping` and `finishSendingMessage`. These are imported from `game/conversations.ts`.
+- Agent inputs are imported from `aiTown/agentInputs.ts` for things like remembering conversations,
+  deciding what to do, etc.
+
+Each of these inputs' implementation method checks invariants and updates game state as desired.
+For example, the `moveTo` input checks that the player isn't participating in a conversation,
+throwing an error telling them to leave the conversation first if so, and then updates their
+pathfinding state with the desired destination.
+
+### Simulation
+
+Other than when processing player inputs, the game state can change over time in the background as the
+simulation runs time forward. For example, if a player has decided to move along a path, their position
+will gradually update as time moves forward. Similarly, if two players collide into each other, they'll
+notice and replan their paths, trying to avoid obstacles.
+
+### Message data model
+
+We manage the tables for tracking chat messages in separate tables not affiliated
+with the game engine. This is for a few reasons:
+
+- The core simulation doesn't need to know about messages, so keeping them
+  out keeps game state small.
+- Messages are updated very frequently (when streamed out from OpenAI) and
+  benefit from lower input latency, so they're not a great fit for the engine.
+  See "Design goals and limitations" below.
+
+Messages (`convex/schema.ts`) are in a conversation and indicate an author and message text.
+Each conversation has a typing state in the conversations table that indicates that a player
+is currently typing. Players can still send messages while another player is typing, but
+having the indicator helps agents (and humans) not talk over each other.
+
+The separate tables are queried and modified with regular Convex queries and mutations
+that don't directly go through the simulation.
+
+## Game engine (`convex/engine`)
+
+Given the description of AI Town's game behavior in the previous section,
+the `AbstractGame` class in `convex/engine/abstractGame.ts` implements actually running the simulation.
+The game engine has a few responsibilities:
+
+- Coordinating incoming player inputs, feeding them into the simulation, and sending their
+  return values (or errors) to the client.
+- Running the simulation forward in time.
+- Saving and loading game state from the database.
+- Managing executing the game behavior, efficiently using Convex resources and minimizing input latency.
+
+AI Town's game behavior is implemented in the `Game` subclass.
+
+### Input handling
+
+Users submit inputs through the `insertInput` function, which inserts them into an `inputs` table, assigning a
+monotonically increasing unique input number and stamping the input with the time the server received it. The
+engine then processes inputs, writing their results back to the `inputs` row. Interested clients can subscribe
+on an input's status with the `inputStatus` query.
+
+`Game` provides an abstract method `handleInput` that `AiTown` implements with its specific behavior.
+
+### Running the simulation
+
+The `Game` class specifies how it simulates time forward with the `tick` method:
+
+- `tick(now)` runs the simulation forward until the given timestamp
+- Ticks are run at a high frequency, configurable with `tickDuration` (milliseconds). Since AI town has smooth motion
+  for player movement, it runs at 60 ticks per second.
+- It's generally a good idea to break up game logic into separate systems that can be ticked forward independently.
+  For example, AI Town's `tick` method advances pathfinding with `Player.tickPathfinding`, player positions with
+  `Player.tickPosition`, conversations with `Conversation.tick`, and `Agent.tick` for agent logic.
+
+To avoid running a Convex mutation 60 times per second (which would be expensive and slow), the engine batches up
+many ticks into a _step_. AI town runs steps at only 1 time per second. Here's how a step works:
+
+1. Load the game state into memory.
+2. Decide how long to run.
+3. Execute many ticks for our time interval, alternating between feeding in inputs with `handleInput` and advancing
+   the simulation with `tick`.
+4. Write the updated game state back to the database.
+
+One core invariant is that the game engine is fully "single-threaded" per world, so there are never two runs of
+an engine's step overlapping in time. Not having to think about race conditions or concurrency makes writing game
+engine code a lot easier.
+
+However, preserving this invariant is a little tricky. If the engine is idle for a minute and an
+input comes in, we want to run the engine immediately but then cancel its run after the minute's
+up. If we're not careful, a race condition may cause us to run multiple copies of the engine if an
+input comes in just as an idle timeout is expiring!
+
+Our approach is to store a generation number with the engine that monotonically increases over time.
+All scheduled runs of the engine contain their expected generation number as an argument. Then, if
+we'd like to cancel a future run of the engine, we can bump the generation number by one, and then
+we're guaranteed that the subsequent run will fail immediately as it'll notice that the engine's
+generation number does not match its expected one.
+
+### Engine state management
+
+The `World`, `Player`, `Conversation`, and `Agent` classes coordinate loading data into memory from the database,
+modifying it according to the game rules, and serializing it to write back out to the database. Here's the flow:
+
+1. The Convex scheduler calls the `convex/aiTown/main.ts:runStep` action.
+2. The `runStep` action calls `convex/aiTown/game.ts:loadWorld` to load the current game state. This query calls
+   `Game.load`, which loads all of a world's game state from the appropriate tables, and returns a
+   `GameState` object, which contains serialized versions of all of the players, agents, etc.
+3. The `runStep` action passes the `GameState` to the `Game` constructor, which parses the serialized versions
+   of all our game objects using their constructors. For example, `new Player(serializedPlayer)` parses the
+   database representation into the in-memory `Player` class.
+4. The engine runs the simulation, modifying the in-memory game objects.
+5. At the end of a step, the framework calls `Game.saveStep`, which computes a diff of the game state since
+   the beginning of the step and passes the diff to the `convex/aiTown/game.ts:saveWorld` mutation.
+6. The `saveWorld` mutation applies the diff to the database, notices if any deleted objects need to be archived,
+   updates the `participatedTogether` graph, and kicks off any scheduled jobs to run.
+7. Since the engine is the only mutator of game state, it continues to run steps for some amount of time
+   without repeating steps 1 to 3 again.
+
+Just as we assume that the game engine is "single threaded", we also assume that the game engine _exclusively_
+owns the tables that store game engine state. Only the game engine should programmatically modify these tables,
+so components outside the engine can only mutate them by sending inputs.
+
+### Historical tables
+
+If we're only writing updates out to the database at the end of the step, and steps are only running at once per
+second, continuous quantities like position will only update every second. This, then, defeats the whole purpose
+of having high-frequency ticks: Player positions will jump around and look choppy.
+
+To solve this, we track the historical values of quantities like position _within_ a step, storing the value
+at the end of each tick. Then, the client receives both the current value _and_ the past step's worth of
+history, and it can "replay" the history to make the motion smooth.
+
+The game tracks these quantities at the end of each tick by feeding them to a `HistoricalObject`. This object
+efficiently tracks its changes over time and serializes them into a buffer that clients can use for replaying
+its history. There are a few limitations on `HistoricalObject`:
+
+- Historical objects can only have numeric (floating point) values and can't have nested objects or optional fields.
+- Historical objects must declare which fields they'd like to track.
+
+We store each player's "location" (i.e. its position, orientation, and speed) in a `HistoricalObject` and
+write it to the `worlds` document at the end of a step when computing a diff.
+
+## Client-side game UI (`src/`)
+
+One guiding principle for AI Town's architecture is to keep the usage as close to "regular Convex" usage as possible. So,
+game state is stored in regular tables, and the UI just uses regular `useQuery` hooks to load that state and render
+it in the UI.
+
+The one exception is for historical tables, which feed in the latest state into a `useHistoricalValue` hook that parses
+the history buffer and replays time forward for smooth motion. To keep replayed time synchronized across multiple
+historical buffers, we provide a `useHistoricalTime` hook for the top of your app that keeps track of the current
+time and returns it for you to pass down into components.
+
+We also provide a `useSendInput` hook that wraps `useMutation` and automatically sends inputs to the server and
+waits for the engine to process them and return their outcome.
+
+## Agent architecture (`convex/agent`)
+
+### The agent loop (`convex/game/agents.ts`)
+
+Agents will execute any game state changes, and schedule operations to do anything that requires
+a long-lived request or accessing non-game tables. The flow generally is:
+
+1. Logic in `Agent.tick` can read and modify game state as time progresses, such as waiting until
+   the agent is near another player to start talking.
+2. When there is something that needs to talk to an LLM or read/write external data,
+   it calls `startOperation` with a reference to a Convex function: generally an `internalAction`.
+3. This function can read state from game tables and other tables via `internalQuery` functions.
+4. It executes long-running tasks, and can write data via `internalMutation`s.
+   Game state should not be written, but rather submitted via `inputs` (described in a previous section).
+5. Inputs are submitted from actions with `ctx.runMutation(api.game.main.sendInput, {...})` from actions
+   or via `insertInput` from mutations. They are referenced by their name as a string, like `moveTo`.
+6. Inputs are defined with `inputHandler` and are given an instance of the AiTown game to modify,
+   similar to the game loop. In fact, these are called as part of the game loop before `tickAgent`.
+7. When an operation is done, it deletes the `inProgressOperation`. This is to ensure an agent only
+   is trying to do one thing at a time.
+8. `Agent.tick` then can observe the new game state and continue to make decisions.
+
+### Conversations (`convex/agent/conversations.ts`)
+
+The agent code calls into the conversation layer which implements the prompt engineering for
+injecting personality and memories into the GPT responses. It has functions for starting a
+conversation (`startConversation`), continuing after the first message (`continueConversation`), and
+politely leaving a conversation (`leaveConversation`). Each function loads structured data from the
+database, queries the memory layer for the agent's opinion about the player they're talking with,
+and then calls into the OpenAI client (`convex/util/openai.ts`).
+
+### Memories (`convex/agent/memory.ts`)
+
+After each conversation, GPT summarizes its message history, and we compute an embedding of the
+summary text and write it into Convex's vector database. Then, when starting a new conversation
+with, Danny, we embed "What you think about Danny?", find the three most similar memories, and fetch
+their summary texts to inject into the conversation prompt.
+
+### Embeddings cache (`convex/agent/embeddingsCache.ts`)
+
+To avoid computing the same embedding over and over again, we cache embeddings by a hash of their
+text in a Convex table.
+
+## Design goals and limitations
+
+AI Town's game engine has a few design goals:
+
+- Try to be as close to a regular Convex app as possible. Use regular client hooks (like `useQuery`)
+  when possible, and store game state in regular tables.
+- Be as similar to existing engines as possible, so it's easy to change the behavior. We chose a
+  `tick()` based model for simulation since it's commonly used elsewhere and intuitive.
+- Decouple agent behavior from the game engine. It's nice to allow human players and AI agents to do
+  all the same things in the game.
+
+These design goals imply some inherent limitations:
+
+- All data is loaded into memory each step. The active game state loaded by the game should be small
+  enough to fit into memory and load and save frequently. Try to keep game state to less than a few dozen
+  kilobytes: Games that require tens of thousands of objects interacting together may not be a good
+  fit.
+- All inputs are fed through the database in the `inputs` table, so applications that require very
+  large or frequent inputs may not be a good fit.
+- Input latency will be around one RTT (time for the input to make it to the server and the response
+  to come back) plus half the step size (for expected server input delay when the input's waiting
+  for the next step). Historical values add another half step size of input latency since their
+  values are viewed slightly in the past. As configured, this will roughly be around 1.5s of input
+  latency, which won't be a good fit for competitive games. You can configure the step size to be
+  smaller (e.g. 250ms) which will decrease input latency at the cost of adding more Convex function
+  calls and database bandwidth.
+- The game engine is designed to be single threaded. JavaScript operating over plain objects
+  in-memory can be surprisingly fast, but if your simulation is very computationally expensive, it
+  may not be a good fit on AI Town's engine today.

Dockerfile

@@ -17,10 +17,6 @@ ENV HOME=/home/user \
     PATH=/home/user/.local/bin:$PATH
 
 WORKDIR $HOME/app
-
-RUN git clone https://github.com/a16z-infra/ai-town.git . && \
-    git checkout f005c46d1759b47bb3ade8d41952a713c4faf331 
-
 RUN npm install --include=dev @huggingface/inference
 RUN npm install --include=dev @huggingface/hub
 
@@ -28,17 +24,4 @@ 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 ./
-COPY ./patches/vite.config.ts ./
-COPY ./patches/characters.ts ./patches/gentle.js ./data/
-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"]

Justfile

@@ -0,0 +1,30 @@
+set fallback := true
+set shell := ["bash", "-uc"]
+set windows-shell := ["sh", "-uc"]
+
+# `just --list` (or just `just`) will print all the recipes in
+# the current Justfile. `just RECIPE` will run the macro/job.
+#
+# In several places there are recipes for running common scripts or commands.
+# Instead of `Makefile`s, Convex uses Justfiles, which are similar, but avoid
+# several footguns associated with Makefiles, since using make as a macro runner
+# can sometimes conflict with Makefiles desire to have some rudimentary
+# understanding of build artifacts and associated dependencies.
+#
+# Read up on just here: https://github.com/casey/just
+
+_default:
+  @just --list
+
+set positional-arguments
+
+# Uses an admin key from admin_key.txt for dev backends.
+# This uses the default admin key for local backends, which is safe as long as the backend is
+# running locally.
+# (*) Run convex CLI commands like `convex dev` against local backend from `just run-local-backend`.
+convex *ARGS:
+  cd {{invocation_directory()}}; npx convex "$@" --admin-key 0135d8598650f8f5cb0f30c34ec2e2bb62793bc28717c8eb6fb577996d50be5f4281b59181095065c5d0f86a2c31ddbe9b597ec62b47ded69782cd --url "http://127.0.0.1:3210"
+
+# Clears any data or stored files from the local backend.
+reset-local-backend:
+  rm -rf convex_local_storage && rm -f convex_local_backend.sqlite3

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 a16z-infra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,36 +1,445 @@
----
-title: AI Town on HuggingFace
-emoji: 🏠🐈‍⬛
-colorFrom: green
-colorTo: red
-sdk: docker
-app_port: 5173
-pinned: false
-disable_embedding: true
-# header: mini
-short_description: AI Town on HuggingFace
-hf_oauth: true
----
+# AI Town 🏠💻💌
 
-# AI Town 🏠💻💌 on Hugging Face 🤗
+[Live Demo](https://www.convex.dev/ai-town)
 
-[**Demo on Hugging Face Spaces**](https://huggingface.co/spaces/radames/ai-town)
+[Join our community Discord: AI Stack Devs](https://discord.gg/PQUmTBTGmT)
 
-AI Town is a very cool project by [Yoko](https://github.com/ykhli) et [al.](https://github.com/a16z-infra/ai-town), a virtual town with live AI characters where they can chat and socialize. You can also interact with them by sending them messages.
+<img width="1454" alt="Screen Shot 2023-08-14 at 10 01 00 AM" src="https://github.com/a16z-infra/ai-town/assets/3489963/a4c91f17-23ed-47ec-8c4e-9f9a8505057d">
 
-This repository contains a few code patches to make AI Town run on [Hugging Face 🤗 Spaces](https://huggingface.co/spaces), as well as a Dockerfile capable of running [Convex open-source backend](https://github.com/get-convex/convex-backend), the backend and frontend on a single container.
+AI Town is a virtual town where AI characters live, chat and socialize.
 
-## How to run locally
+This project is a deployable starter kit for easily building and customizing your own version of AI town.
+Inspired by the research paper [_Generative Agents: Interactive Simulacra of Human Behavior_](https://arxiv.org/pdf/2304.03442.pdf).
 
-Grab your Hugging Face API token from https://huggingface.co/settings/tokens
+The primary goal of this project, beyond just being a lot of fun to work on,
+is to provide a platform with a strong foundation that is meant to be extended.
+The back-end natively supports shared global state, transactions, and a simulation engine
+and should be suitable from everything from a simple project to play around with to a scalable, multi-player game.
+A secondary goal is to make a JS/TS framework available as most simulators in this space
+(including the original paper above) are written in Python.
+
+## Overview
+
+- 💻 [Stack](#stack)
+- 🧠 [Installation](#installation)
+- 👤 [Customize - run YOUR OWN simulated world](#customize-your-own-simulation)
+- 👩‍💻 [Deploying](#deploy-the-app)
+- 🏆 [Credits](#credits)
+
+## Stack
+
+- Game engine, database, and vector search: [Convex](https://convex.dev/)
+- Auth (Optional): [Clerk](https://clerk.com/)
+- Default chat model is `llama3` and embeddings with `mxbai-embed-large`.
+- Local inference: [Ollama](https://github.com/jmorganca/ollama)
+- Configurable for other cloud LLMs: [Together.ai](https://together.ai/) or anything
+  that speaks the [OpenAI API](https://platform.openai.com/).
+  PRs welcome to add more cloud provider support.
+- Pixel Art Generation: [Replicate](https://replicate.com/), [Fal.ai](https://serverless.fal.ai/lora)
+- Background Music Generation: [Replicate](https://replicate.com/) using [MusicGen](https://huggingface.co/spaces/facebook/MusicGen)
+
+## Installation
+
+**Note**: There is a one-click install of a fork of this project on
+[Pinokio](https://pinokio.computer/item?uri=https://github.com/cocktailpeanutlabs/aitown)
+for anyone interested in running but not modifying it 😎
+
+### 1. Clone repo and Install packages
+
+```bash
+git clone https://github.com/a16z-infra/ai-town.git
+cd ai-town
+npm install
+```
+
+### 2. To develop locally with [Convex](https://convex.dev):
+
+Either
+[download a pre-built binary(recommended)](https://github.com/get-convex/convex-backend/releases),
+or [build it from source and run it](https://stack.convex.dev/building-the-oss-backend).
+
+```sh
+# For new Macs:
+curl  -L -O https://github.com/get-convex/convex-backend/releases/latest/download/convex-local-backend-aarch64-apple-darwin.zip
+unzip convex-local-backend-aarch64-apple-darwin.zip
+
+brew install just
+
+# Runs the server
+./convex-local-backend
+```
+
+This also [installs `just`](https://github.com/casey/just?tab=readme-ov-file#installation)
+(e.g. `brew install just` or `cargo install just`).
+We use `just` like `make` to add extra params, so you run `just convex ...`
+instead of `npx convex ...` for local development.
+
+If you're running the pre-built binary on Mac and there's an Apple warning,
+go to the folder it's in and right-click it and select "Open" to bypass.
+From then on you can run it from the commandline.
+Or you can compile it from source and run it (see above).
+
+To develop against the cloud-hosted version, change the package.json scripts
+to use `convex ...` instead of `just convex ...`.
+
+### 3. To run a local LLM, download and run [Ollama](https://ollama.com/).
+
+You can leave the app running or run `ollama serve`.
+`ollama serve` will warn you if the app is already running.
+Run `ollama pull llama3` to have it download `llama3`.
+Test it out with `ollama run llama3`.
+If you want to customize which model to use, adjust convex/util/llm.ts or set
+`just convex env set LLM_MODEL # model`.
+Ollama model options can be found [here](https://ollama.ai/library).
+
+You might want to set `NUM_MEMORIES_TO_SEARCH` to `1` in constants.ts,
+to reduce the size of conversation prompts, if you see slowness.
+
+Check out `convex/config.ts` to configure which models to offer to the UI,
+or to set it up to talk to a cloud-hosted LLM.
+
+### 4. Adding background music with Replicate (Optional)
+
+For Daily background music generation, create a
+[Replicate](https://replicate.com/) account and create a token in your Profile's
+[API Token page](https://replicate.com/account/api-tokens).
+`npx convex env set REPLICATE_API_TOKEN # token`
+Specify `just` instead of `npx` if you're doing local development.
+
+### 5. Run the code
+
+To run both the front and and back end:
+
+```bash
+npm run dev
+```
+
+**Note**: If you encounter a node version error on the convex server upon application startup, please use node version 18, which is the most stable. One way to do this is by [installing nvm](https://nodejs.org/en/download/package-manager) and running `nvm install 18` or `nvm use 18`. Do this before both the `npm run dev` above and the `./convex-local-backend` in Step 2.
+
+You can now visit http://localhost:5173.
+
+If you'd rather run the frontend in a separate terminal from Convex (which syncs
+your backend functions as they're saved), you can run these two commands:
+
+```bash
+npm run dev:frontend
+npm run dev:backend
+```
+
+See package.json for details, but dev:backend runs `just convex dev`
+
+**Note**: The simulation will pause after 5 minutes if the window is idle.
+Loading the page will unpause it.
+You can also manually freeze & unfreeze the world with a button in the UI.
+If you want to run the world without the
+browser, you can comment-out the "stop inactive worlds" cron in `convex/crons.ts`.
+
+### Various commands to run / test / debug
+
+**To stop the back end, in case of too much activity**
+
+This will stop running the engine and agents. You can still run queries and
+run functions to debug.
+
+```bash
+just convex run testing:stop
+```
+
+**To restart the back end after stopping it**
+
+```bash
+just convex run testing:resume
+```
+
+**To kick the engine in case the game engine or agents aren't running**
+
+```bash
+just convex run testing:kick
+```
+
+**To archive the world**
+
+If you'd like to reset the world and start from scratch, you can archive the current world:
 
 ```bash
-export HF_TOKEN=hf_**********
-docker build -t ai-town -f Dockerfile .
-docker run -ti -p 5173:5173 -e LLM_API_KEY=$HF_TOKEN ai-town
+just convex run testing:archive
+```
+
+Then, you can still look at the world's data in the dashboard, but the engine and agents will
+no longer run.
+
+You can then create a fresh world with `init`.
+
+```bash
+just convex run init
+```
+
+**To clear all databases**
+
+You can wipe all tables with the `wipeAllTables` testing function.
+
+```bash
+just convex run testing:wipeAllTables
+```
+
+**To pause your backend deployment**
+
+You can go to the [dashboard](https://dashboard.convex.dev) to your deployment
+settings to pause and un-pause your deployment. This will stop all functions, whether invoked
+from the client, scheduled, or as a cron job. See this as a last resort, as
+there are gentler ways of stopping above. Once you
+
+## Customize your own simulation
+
+NOTE: every time you change character data, you should re-run
+`just convex run testing:wipeAllTables` and then
+`npm run dev` to re-upload everything to Convex.
+This is because character data is sent to Convex on the initial load.
+However, beware that `just convex run testing:wipeAllTables` WILL wipe all of your data.
+
+1. Create your own characters and stories: All characters and stories, as well as their spritesheet references are stored in [characters.ts](./data/characters.ts). You can start by changing character descriptions.
+
+2. Updating spritesheets: in `data/characters.ts`, you will see this code:
+
+```ts
+export const characters = [
+  {
+    name: 'f1',
+    textureUrl: '/assets/32x32folk.png',
+    spritesheetData: f1SpritesheetData,
+    speed: 0.1,
+  },
+  ...
+];
 ```
 
-## How to run on Hugging Face
+You should find a sprite sheet for your character, and define sprite motion / assets in the corresponding file (in the above example, `f1SpritesheetData` was defined in f1.ts)
+
+3. Update the Background (Environment): The map gets loaded in `convex/init.ts` from `data/gentle.js`. To update the map, follow these steps:
+
+   - Use [Tiled](https://www.mapeditor.org/) to export tilemaps as a JSON file (2 layers named bgtiles and objmap)
+   - Use the `convertMap.js` script to convert the JSON to a format that the engine can use.
+
+```console
+node data/convertMap.js <mapDataPath> <assetPath> <tilesetpxw> <tilesetpxh>
+```
+
+- `<mapDataPath>`: Path to the Tiled JSON file.
+- `<assetPath>`: Path to tileset images.
+- `<tilesetpxw>`: Tileset width in pixels.
+- `<tilesetpxh>`: Tileset height in pixels.
+  Generates `converted-map.js` that you can use like `gentle.js`
+
+4. Change the background music by modifying the prompt in `convex/music.ts`
+5. Change how often to generate new music at `convex/crons.ts` by modifying the `generate new background music` job
+
+## Using a cloud AI Provider
+
+Configure `convex/util/llm.ts` or set these env variables:
+
+```sh
+# Local Convex
+just convex env set LLM_API_HOST # url
+just convex env set LLM_MODEL # model
+# Cloud Convex
+npx convex env set LLM_API_HOST # url
+npx convex env set LLM_MODEL # model
+```
+
+The embeddings model config needs to be changed [in code](./convex/util/llm.ts),
+since you need to specify the embeddings dimension.
+
+### Keys
+
+For Together.ai, visit https://api.together.xyz/settings/api-keys
+For OpenAI, visit https://platform.openai.com/account/api-keys
+
+## Using hosted Convex
+
+You can run your Convex backend in the cloud by just running
+
+```sh
+npx convex dev --once --configure
+```
+
+And updating the `package.json` scripts to remove `just`:
+change `just convex ...` to `convex ...`.
+
+You'll then need to set any environment variables you had locally in the cloud
+environment with `npx convex env set` or on the dashboard:
+https://dashboard.convex.dev/deployment/settings/environment-variables
+
+To run commands, use `npx convex ...` where you used to run `just convex ...`.
+
+## Deploy the app
+
+### Deploy Convex functions to prod environment
+
+Before you can run the app, you will need to make sure the Convex functions are deployed to its production environment.
+
+1. Run `npx convex deploy` to deploy the convex functions to production
+2. Run `npx convex run init --prod`
+
+If you have existing data you want to clear, you can run `npx convex run testing:wipeAllTables --prod`
+
+### Adding Auth (Optional)
+
+You can add clerk auth back in with `git revert b44a436`.
+Or just look at that diff for what changed to remove it.
+
+**Make a Clerk account**
+
+- Go to https://dashboard.clerk.com/ and click on "Add Application"
+- Name your application and select the sign-in providers you would like to offer users
+- Create Application
+- Add `VITE_CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY` to `.env.local`
+
+```bash
+VITE_CLERK_PUBLISHABLE_KEY=pk_***
+CLERK_SECRET_KEY=sk_***
+```
+
+- Go to JWT Templates and create a new Convex Template.
+- Copy the JWKS endpoint URL for use below.
+
+```sh
+npx convex env set CLERK_ISSUER_URL # e.g. https://your-issuer-url.clerk.accounts.dev/
+```
+
+### Deploy to Vercel
+
+- Register an account on Vercel and then [install the Vercel CLI](https://vercel.com/docs/cli).
+- **If you are using Github Codespaces**: You will need to [install the Vercel CLI](https://vercel.com/docs/cli) and authenticate from your codespaces cli by running `vercel login`.
+- Deploy the app to Vercel with `vercel --prod`.
+
+## Using local inference from a cloud deployment.
+
+We support using [Ollama](https://github.com/jmorganca/ollama) for conversation generations.
+To have it accessible from the web, you can use Tunnelmole or Ngrok or similar.
+
+**Using Tunnelmole**
+
+[Tunnelmole](https://github.com/robbie-cahill/tunnelmole-client) is an open source tunneling tool.
+
+You can install Tunnelmole using one of the following options:
+
+- NPM: `npm install -g tunnelmole`
+- Linux: `curl -s https://tunnelmole.com/sh/install-linux.sh | sudo bash`
+- Mac: `curl -s https://tunnelmole.com/sh/install-mac.sh --output install-mac.sh && sudo bash install-mac.sh`
+- Windows: Install with NPM, or if you don't have NodeJS installed, download the `exe` file for Windows [here](https://tunnelmole.com/downloads/tmole.exe) and put it somewhere in your PATH.
+
+Once Tunnelmole is installed, run the following command:
+
+```
+tmole 11434
+```
+
+Tunnelmole should output a unique url once you run this command.
+
+**Using Ngrok**
+
+Ngrok is a popular closed source tunneling tool.
+
+- [Install Ngrok](https://ngrok.com/docs/getting-started/)
+
+Once ngrok is installed and authenticated, run the following command:
+
+```
+ngrok http http://localhost:11434
+```
+
+Ngrok should output a unique url once you run this command.
+
+**Add Ollama endpoint to Convex**
+
+```sh
+npx convex env set OLLAMA_HOST # your tunnelmole/ngrok unique url from the previous step
+```
+
+**Update Ollama domains**
+
+Ollama has a list of accepted domains. Add the ngrok domain so it won't reject
+traffic. see ollama.ai for more details.
+
+## Credits
+
+- All interactions, background music and rendering on the <Game/> component in the project are powered by [PixiJS](https://pixijs.com/).
+- Tilesheet:
+  - https://opengameart.org/content/16x16-game-assets by George Bailey
+  - https://opengameart.org/content/16x16-rpg-tileset by hilau
+- We used https://github.com/pierpo/phaser3-simple-rpg for the original POC of this project. We have since re-wrote the whole app, but appreciated the easy starting point
+- Original assets by [ansimuz](https://opengameart.org/content/tiny-rpg-forest)
+- The UI is based on original assets by [Mounir Tohami](https://mounirtohami.itch.io/pixel-art-gui-elements)
+
+# 🧑‍🏫 What is Convex?
+
+[Convex](https://convex.dev) is a hosted backend platform with a
+built-in database that lets you write your
+[database schema](https://docs.convex.dev/database/schemas) and
+[server functions](https://docs.convex.dev/functions) in
+[TypeScript](https://docs.convex.dev/typescript). Server-side database
+[queries](https://docs.convex.dev/functions/query-functions) automatically
+[cache](https://docs.convex.dev/functions/query-functions#caching--reactivity) and
+[subscribe](https://docs.convex.dev/client/react#reactivity) to data, powering a
+[realtime `useQuery` hook](https://docs.convex.dev/client/react#fetching-data) in our
+[React client](https://docs.convex.dev/client/react). There are also clients for
+[Python](https://docs.convex.dev/client/python),
+[Rust](https://docs.convex.dev/client/rust),
+[ReactNative](https://docs.convex.dev/client/react-native), and
+[Node](https://docs.convex.dev/client/javascript), as well as a straightforward
+[HTTP API](https://docs.convex.dev/http-api/).
+
+The database supports
+[NoSQL-style documents](https://docs.convex.dev/database/document-storage) with
+[opt-in schema validation](https://docs.convex.dev/database/schemas),
+[relationships](https://docs.convex.dev/database/document-ids) and
+[custom indexes](https://docs.convex.dev/database/indexes/)
+(including on fields in nested objects).
+
+The
+[`query`](https://docs.convex.dev/functions/query-functions) and
+[`mutation`](https://docs.convex.dev/functions/mutation-functions) server functions have transactional,
+low latency access to the database and leverage our
+[`v8` runtime](https://docs.convex.dev/functions/runtimes) with
+[determinism guardrails](https://docs.convex.dev/functions/runtimes#using-randomness-and-time-in-queries-and-mutations)
+to provide the strongest ACID guarantees on the market:
+immediate consistency,
+serializable isolation, and
+automatic conflict resolution via
+[optimistic multi-version concurrency control](https://docs.convex.dev/database/advanced/occ) (OCC / MVCC).
+
+The [`action` server functions](https://docs.convex.dev/functions/actions) have
+access to external APIs and enable other side-effects and non-determinism in
+either our
+[optimized `v8` runtime](https://docs.convex.dev/functions/runtimes) or a more
+[flexible `node` runtime](https://docs.convex.dev/functions/runtimes#nodejs-runtime).
+
+Functions can run in the background via
+[scheduling](https://docs.convex.dev/scheduling/scheduled-functions) and
+[cron jobs](https://docs.convex.dev/scheduling/cron-jobs).
+
+Development is cloud-first, with
+[hot reloads for server function](https://docs.convex.dev/cli#run-the-convex-dev-server) editing via the
+[CLI](https://docs.convex.dev/cli),
+[preview deployments](https://docs.convex.dev/production/hosting/preview-deployments),
+[logging and exception reporting integrations](https://docs.convex.dev/production/integrations/),
+There is a
+[dashboard UI](https://docs.convex.dev/dashboard) to
+[browse and edit data](https://docs.convex.dev/dashboard/deployments/data),
+[edit environment variables](https://docs.convex.dev/production/environment-variables),
+[view logs](https://docs.convex.dev/dashboard/deployments/logs),
+[run server functions](https://docs.convex.dev/dashboard/deployments/functions), and more.
+
+There are built-in features for
+[reactive pagination](https://docs.convex.dev/database/pagination),
+[file storage](https://docs.convex.dev/file-storage),
+[reactive text search](https://docs.convex.dev/text-search),
+[vector search](https://docs.convex.dev/vector-search),
+[https endpoints](https://docs.convex.dev/functions/http-actions) (for webhooks),
+[snapshot import/export](https://docs.convex.dev/database/import-export/),
+[streaming import/export](https://docs.convex.dev/production/integrations/streaming-import-export), and
+[runtime validation](https://docs.convex.dev/database/schemas#validators) for
+[function arguments](https://docs.convex.dev/functions/args-validation) and
+[database data](https://docs.convex.dev/database/schemas#schema-validation).
 
-You can duplicate this Space https://huggingface.co/spaces/radames/ai-town?duplicate=true, add your `HF_TOKEN`
-Then you can customize [patches/constants.ts](patches/constants.ts) and [patches/characters.ts](patches/characters.ts) as you wish, as well as the LLM model and embeddings model in [patches/llm.ts](patches/llm.ts).
+Everything scales automatically, and it’s [free to start](https://www.convex.dev/plans).

README.md.yml

@@ -1,18 +0,0 @@
-title: AI Town on HuggingFace
-emoji: 🏠💻💌🤗
-colorFrom: green
-colorTo: red
-sdk: docker
-app_port: 5173
-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