企业官网建设流程全解析

如何 5 分钟在本地跑通 AI Town：安装、场景与角色定制指南

【免费下载链接】ai-townA MIT-licensed, deployable starter kit for building and customizing your own version of AI town - a virtual town where AI characters live, chat and socialize.项目地址: https://gitcode.com/gh_mirrors/ai/ai-town

AI Town 是一个 MIT 许可的虚拟小镇启动工具包，AI 角色在里面生活、走动、聊天和社交。这篇 AI Town 教程带你完成 AI 虚拟小镇安装与场景搭建：先跑通，再学会把小镇改成自己的样子。

跑起来之后，你看到什么

执行完下文全部命令，浏览器里会出现一座像素风小镇：居民按各自设定四处走动、停下来对话，你点进聊天框也能插话。整座城市跑在 Convex 后端上，共享一份全局状态，所有客户端看到的小镇行为保持一致。

五分钟完成 AI 虚拟小镇安装

环境只需两样：Git 和 Node.js。

1. 克隆仓库：

git clone https://gitcode.com/gh_mirrors/ai/ai-town

2. 进入项目并装依赖：

cd ai-town npm install

3. 启动开发服务：

npm run dev

该命令并行拉起 Convex 后端与 Vite 前端，首次启动会执行一次初始化，稍等片刻即可在浏览器访问页面。

两点提示：

• 角色对话依赖 LLM，默认用本地 Ollama 跑 llama3，也可接 OpenAI、Together.ai 等支持 OpenAI API 的服务，在 Convex 环境变量里配置对应 key。
• 页面闲置 5 分钟后模拟会暂停，点界面上的冻结按钮可随时恢复。

换一个地图文件，换一整套场景

AI Town 的场景由两部分拼成：tileset（tileset 是一张像素素材图集，地面、树木、建筑都从里面切格子取用）加上一份地图数据文件，后者记录每个格子的摆放位置。

想换整张地图，最短路径是改convex/init.ts的地图引用。仓库自带多套现成地图，都在 src/editor/maps/ 下：gentle.js、serene.js、mage3.js等，对应 src/editor/tilesets/ 里的不同风格图集，如像素风的gentle.png、都市感的Modern.png，前端渲染用的素材集中在 public/assets/（含rpg-tileset.png与tilemap.json）。

从零画地图则走工具链：用 Tiled 导出 JSON（需bgtiles与objmap两层），再跑node data/convertMap.js生成新地图文件，用法同gentle.js。

把角色改成你自己的

所有 AI 角色的名字、贴图与背景设定集中在 data/characters.ts，改完描述，角色开口说话的内容就会跟着变。行为层逻辑在 convex/aiTown/ 下，agent.ts管代理运转，player.ts管玩家与角色的交互入口。

改完角色数据需要清库重传：

npx convex run testing:wipeAllTables npm run dev

注意wipeAllTables会清空 Convex 中的全部数据，确认后再执行。

值得翻的三个目录

• src/editor/：内置关卡编辑器，npm run le单独启动
• data/：地图、动画与角色素材源文件
• convex/aiTown/：世界、移动、会话、代理等核心逻辑

下一步：复制一张现成地图的 JSON，用 Tiled 重排几个格子，给小镇盖第一栋你自己的房子。

【免费下载链接】ai-townA MIT-licensed, deployable starter kit for building and customizing your own version of AI town - a virtual town where AI characters live, chat and socialize.项目地址: https://gitcode.com/gh_mirrors/ai/ai-town