Code Map: Understanding the AI Town Architecture

Welcome to the code deep dive for AI Town! To navigate this project effectively, it’s essential to first understand its high-level architecture. This code map provides a bird’s-eye view of the repository, breaking down the roles and responsibilities of key directories and files.

AI Town is architecturally split into two main parts:

A Convex Backend (convex/): This is the “brain” of the simulation. It runs all the AI logic, manages the game state, and handles all data persistence.
A React + Pixi.js Frontend (src/): This is the “face” of the simulation. It renders the virtual world and characters and provides the user interface for interaction.

🎯 Navigate the Codebase:

🧠 AI Agent Behavior (agent.ts) - How characters make decisions

💭 Agent Memory System - How characters remember and learn

💬 Conversation Manager - How characters chat with each other

⚙️ Engine Controller - The world’s heartbeat system

💡

This map is designed to give you a foundational understanding before we dive into specific files. Refer back to it anytime you need to orient yourself within the codebase.

Project Structure Overview

Here is the annotated file tree that outlines the core components of the AI Town project.

ai-town/
├── convex/                     # [Role: Backend] All backend logic, data models, and AI integration for the Convex platform.
│   ├── aiTown/                 # [Role: Core Game Logic] Manages the specific simulation rules for AI Town.
│   │   ├── main.ts             # [Role: Simulation Engine Loop] The main 'tick' function that drives the entire simulation forward.
│   │   ├── game.ts             # [Role: Game State Manager] Defines the core game state and rules for how it can change.
│   │   ├── agent.ts            # [Role: AI Agent Behavior] Governs how individual AI agents think, plan, and act in the world.
│   │   ├── inputHandler.ts     # [Role: Input Processor] Handles all inputs from players and agents to update the game state.
│   │   ├── world.ts            # [Role: World State] Manages the state of the game world, including all players and agents within it.
│   │   ├── player.ts           # [Role: Player Logic] Defines the backend logic associated with a human-controlled player.
│   │   ├── movement.ts         # [Role: Character Movement] Calculates and validates character movement within the game world.
│   │   └── schema.ts           # [Role: Game Data Schema] Defines the database tables specific to the AI Town game module.
│   ├── agent/                  # [Role: Generative Agent Framework] Contains the core AI logic for memory, conversation, and embeddings.
│   │   ├── conversation.ts     # [Role: AI Conversation Manager] Orchestrates conversations between AI agents, including starting and ending them.
│   │   ├── memory.ts           # [Role: Agent Memory System] Implements the AI's memory, using vector embeddings for retrieval (RAG).
│   │   ├── embeddingsCache.ts  # [Role: Embeddings Cache] Caches vector embeddings to reduce cost and latency of LLM calls.
│   │   └── schema.ts           # [Role: Agent Data Schema] Defines the database tables for the generic agent framework.
│   ├── engine/                 # [Role: Abstract Game Engine] Provides a generic, reusable game engine structure.
│   │   └── abstractGame.ts     # [Role: Game Interface] Defines the abstract class that any game simulation must implement.
│   ├── util/                   # [Role: Backend Utilities] Shared helper functions for the backend.
│   │   └── llm.ts              # [Role: LLM Client] A wrapper for making calls to various LLM providers like OpenAI or Ollama.
│   ├── schema.ts               # [Role: Master Database Schema] Defines the entire database structure for the Convex backend.
│   ├── crons.ts                # [Role: Scheduled Tasks] Defines cron jobs that run periodically, like advancing the game simulation.
│   └── http.ts                 # [Role: HTTP Endpoints] Exposes backend functionality over standard HTTP for external services.
├── src/                        # [Role: Frontend] All React-based frontend code, including UI components and rendering logic.
│   ├── components/             # [Role: UI Components] Reusable React components that make up the user interface.
│   │   ├── Game.tsx            # [Role: Main Game Component] The top-level component that assembles all game UI and rendering surfaces.
│   │   ├── PixiGame.tsx        # [Role: Game Renderer] Manages the Pixi.js canvas, rendering the game world, sprites, and animations.
│   │   ├── Player.tsx          # [Role: Player Character Component] Renders the user's avatar and handles its client-side representation.
│   │   ├── Messages.tsx        # [Role: Chat UI] Displays the conversation bubbles and message history for players and agents.
│   │   └── ConvexClientProvider.tsx # [Role: Backend Connector] Connects the React application to the Convex backend.
│   ├── hooks/                  # [Role: React Hooks] Custom hooks for managing state and side effects, especially for server communication.
│   │   ├── useWorldHeartbeat.ts# [Role: World State Sync] Keeps the client's view of the world synchronized with the backend.
│   │   └── sendInput.ts        # [Role: Action Sender] A function to send user inputs (like movement or chat) to the backend.
│   ├── App.tsx                 # [Role: Root Application Component] The main React component that sets up providers and routing.
│   └── main.tsx                # [Role: Frontend Entrypoint] The file that initializes and mounts the React application into the DOM.
├── data/                       # [Role: Initial Game Data] Contains static data used to initialize the game world.
│   └── characters.ts           # [Role: Character Definitions] Defines the initial set of AI characters, their personalities, and starting positions.
├── public/                     # [Role: Static Assets] Publicly served assets like images, fonts, and sounds.
├── index.html                  # [Role: HTML Entrypoint] The main HTML file that the browser loads to start the application.
└── package.json                # [Role: Project Configuration] Defines project metadata, dependencies, and scripts.

AI Prompt Library Engine Controller