AI Town 是一个虚拟小镇，AI 角色在其中生活、聊天和社交。它是一个可部署的入门套件，方便你轻松构建和定制自己的 AI Town 版本，灵感来自研究论文《Generative Agents: Interactive Simulacra of Human Behavior》。
主要目标：除了开发过程本身很有趣之外，本项目旨在提供一个具有坚实基础、便于扩展的平台。后端原生支持共享全局状态、事务和模拟引擎，既适合简单的试验项目，也适合可扩展的多人游戏。次要目标是提供一个 JS/TS 框架，因为该领域的大多数模拟器（包括上述原始论文）都用 Python 编写。
技术架构：
- 游戏引擎、数据库和向量搜索：Convex
- 认证（可选）：Clerk
- 默认聊天模型为 llama3，嵌入模型为 mxbai-embed-large
- 本地推理：Ollama
- 可配置其他云端 LLM：Together.ai 或任何兼容 OpenAI API 的服务，欢迎提交 PR 增加更多云服务商支持
- 背景音乐生成：Replicate 使用 MusicGen
- 像素艺术生成：Replicate、Fal.ai
- 所有交互、背景音乐和组件渲染均由 PixiJS 驱动
安装方式（云端、本地、Docker、自托管、Fly.io 等）：
标准 Convex 设置（本地或云端开发）：需要 Convex 账户（免费），这是部署到云端并认真开发的最简单方式。运行后访问 http://localhost:5173。
Docker Compose 自托管 Convex：适合不想注册账户、接受 Docker 的用户。前端运行在 http://localhost:5173，后端运行在 http://localhost:3210（http api 为 3211），仪表盘运行在 http://localhost:6791。需要生成 admin key 并添加到 .env.local 文件。
还有社区分支提供 Pinokio 一键安装（适合只想运行而不修改的用户），也可部署到 Fly.io（参见 ./fly 说明）。
Windows 安装：需要 Windows 10/11 并安装 WSL2，推荐 Ubuntu 发行版。需安装 NVM 和 Node.js 18，安装 Python 和 Pip，然后按上述步骤操作。
配置 LLM：
- Ollama（默认）：下载安装 Ollama，运行 ollama serve，执行 ollama pull llama3 下载模型。可通过调整 convex/util/llm.ts 或设置 npx convex env set OLLAMA_MODEL 自定义模型。若需修改嵌入模型，更改 OLLAMA_EMBEDDING_DIMENSION 并设置 OLLAMA_EMBEDDING_MODEL。如遇速度慢，可在 constants.ts 中设置 NUM_MEMORIES_TO_SEARCH 为 1。
- OpenAI：设置 OPENAI_API_KEY 环境变量，可选通过 OPENAI_CHAT_MODEL 和 OPENAI_EMBEDDING_MODEL 选择模型。
- Together.ai：设置 TOGETHER_API_KEY，可选通过 TOGETHER_CHAT_MODEL、TOGETHER_EMBEDDING_MODEL 选择模型，嵌入模型维度需与 EMBEDDING_DIMENSION 匹配。
- 其他兼容 OpenAI 的 API（如 Anthropic、Groq、Azure）：更改 EMBEDDING_DIMENSION 以匹配嵌入模型维度，编辑 llm.ts 中的 getLLMConfig 或设置环境变量。 注意：更改 LLM 供应商或嵌入模型后，应删除数据并重新开始，因为记忆嵌入基于所选嵌入模型，向量数据库维度必须与嵌入模型维度一致。
自定义模拟世界：
- 每次更改角色数据后，应重新运行 npx convex run testing:wipeAllTables 然后 npm run dev 重新上传到 Convex。注意该命令会清除所有数据。
- 创建自己的角色和故事：所有角色、故事及其精灵表引用存储在 characters.ts 中。可先更改角色描述。
- 更新精灵表：在 data/characters.ts 中定义角色纹理和精灵数据，需为角色找到精灵表并在对应文件中定义精灵运动/资源。
- 更新背景（环境）：地图在 convex/init.ts 中从 data/gentle.js 加载。使用 Tiled 导出瓦片地图为 JSON（两个图层 bgtiles 和 objmap），再用 convertMap.js 脚本转换：node data/convertMap.js <mapDataPath> <assetPath> <tilesetpxw> <tilesetpxh>。生成 converted-map.js 后可像 gentle.js 一样使用。
- 添加背景音乐（可选）：使用 Replicate 生成每日背景音乐，需创建 Replicate 账户并获取 API token，设置 npx convex env set REPLICATE_API_TOKEN。需能接收 Replicate webhook。可通过 convex/music.ts 修改提示词调整音乐，通过 convex/crons.ts 调整生成频率。
运行/测试/调试命令：
- 停止后端（活动过多时）：停止引擎和代理运行，仍可运行查询和函数进行调试。
- 重启后端。
- 踢动引擎（引擎或代理未运行时）。
- 归档世界：重置世界并从头开始，归档当前世界后可在仪表盘查看数据，但引擎和代理不再运行，然后可用 init 创建新世界。
- 暂停后端部署：在仪表盘部署设置中暂停/取消暂停，将停止所有函数（客户端调用、调度或定时任务），作为最后手段。
部署到生产环境：
- 运行 npx convex deploy 部署 Convex 函数到生产环境
- 运行 npx convex run init --prod
- 转移本地数据：npx convex export 然后 npx convex import --prod
- 清除现有数据：npx convex run testing...
注意：若窗口空闲，模拟将在 5 分钟后暂停。加载页面可取消暂停，也可通过 UI 按钮手动冻结/解冻世界。若要在无浏览器情况下运行世界，可注释掉 convex/crons.ts 中的“stop inactive worlds”定时任务。
