AI Town is a virtual town where AI characters live, chat, and socialize. The project is a deployable starter kit that makes it easy to build and customize your own version of an AI town. It is inspired by the research paper "Generative Agents: Interactive Simulacra of Human Behavior."
Main goals: Besides being fun, to provide a platform with a robust foundation designed to be extensible. The backend natively supports shared global state, transactions, and a simulation engine, making it suitable for everything from simple projects to scalable multiplayer games. A secondary goal is to provide a JS/TS framework, since most simulators in this field (including the original paper) are written in Python.
Main capabilities: AI character simulation, chat, and socialization; backend support for shared state, transactions, and a simulation engine; configurable multiple LLMs (Ollama, OpenAI, Together.ai, etc.); background music generation (Replicate); pixel art generation (Replicate, Fal.ai); rendering uses PixiJS.
Usage: Installation (cloud, local, Docker, self-hosted, Fly.io, etc.). The standard Convex setup requires a free Convex account and is the easiest way to deploy and develop in the cloud. The Docker Compose setup can run self-contained. A community fork supports one-click installation with Pinokio. It can also be deployed to Fly.io. On Windows, you must first install WSL2, update packages, install NVM and Node.js 18, and install Python and Pip. LLM configuration uses Ollama locally by default, and OpenAI, Together.ai, or other OpenAI-compatible APIs can also be used. Custom simulation: modify the characters and story in characters.ts, update the sprite sheet, export the map JSON with Tiled and convert it, and add background music via Replicate. Deploying to production: run npx convex deploy to deploy functions, npx convex run init --prod, and you can export local data and import it.
Use cases: From simple projects to scalable multiplayer games, suitable for developers who want to extend and customize an AI virtual town.
Limitations: The materials do not provide specific pricing or cost information. When changing the LLM provider or embedding model, the data must be deleted and started over, because memory embeddings are based on the selectedembedding model, and the vector database dimensions must match. The simulation pauses after the window is idle for 5 minutes, and loading the page unpauses it.
