30 分钟画出一张能跑的小镇地图：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 角色在小镇里醒来、散步、凑在一起聊天，还会记住昨天发生的事——这就是 AI Town 的日常。而角色住哪儿、往哪儿走，取决于你给小镇的地图。这篇教程带你打开 AI Town 地图编辑器，从零画出一张 30 分钟内就能跑进游戏的小镇地图。
01 跑起来 🚀：3 条命令启动本地小镇和编辑器
这节能拿到什么：本地同时跑起游戏和地图编辑器，后面所有操作都有地方验证。
克隆仓库并安装依赖：
git clone https://gitcode.com/gh_mirrors/ai/ai-town cd ai-town && npm install做完后你会看到：终端无报错，项目根目录多出 node_modules。
然后启动游戏（标准方式需要一个免费 Convex 账号）：
npm run dev做完后你会看到：浏览器打开 http://localhost:5173，AI 角色已经在小镇里走动。
再开一个终端启动地图编辑器：
npm run le做完后你会看到：localhost:5174 出现编辑器页面，顶部有 edit / map / config 三个标签页。
02 认识画布 🖼️：7 套内置图块与取用方式
这节能拿到什么：搞清楚右侧面板里的图块来自哪个文件，以及怎么取一块图开始画。
编辑器的默认图块集由 leconfig.js 里的DEFAULTTILESETPATH指定，默认是 gentle.png。src/editor/tilesets/目录里共 7 套可选：
| 文件 | 风格定位 | 适用场景 |
|---|---|---|
| gentle.png | 柔和手绘田园（默认） | 第一张地图的地面与背景 |
| gentle-obj.png | 同风格物块层 | 碰撞层上的树、房屋、围栏 |
| Serene.png | 宁静冷调 | 安静的居民区 |
| Modern.png | 现代都市 | 建筑、街道、设施 |
| forest.png | 像素森林 | 野外、公园、林地 |
| magecity.png | 法师之城 | 奇幻主题小镇 |
| phantasy2.png | 复古幻想 | 实验性风格地图 |
取图按动手顺序来：打开 edit 页，右侧面板就是图块集，点一下等于选中一支"画笔"；左上画板是背景层（无碰撞），点画板即可落笔；第二行左侧画板是物块层（有碰撞），树和建筑都放这里；右下 composite 面板是两层叠加后的实时预览。想换图块集，直接改 leconfig.js 里那行路径即可，也可以在 config 页用 Load Tileset 加载本地文件。
03 第一张地图 🗺️：从空白画布到保存
这节能拿到什么：按 5 步画出第一张图，并存成游戏可加载的 .js 文件。想知道 AI Town 地图编辑器怎么新建地图，就是下面这条链路。
定尺寸。默认画布 2048×1536 像素、每格 32 像素（约 64×48 格），由 leconfig.js 的levelwidth/levelheight控制；按p键可在 16px 与 32px 格子间切换。
铺地形。在右侧图块集选中地面图块，在背景层点击绘制；大面积统一地面选中图块后按f，整层一次填充完成。
放建筑。换到第二行的物块层画树、房子。这一层有碰撞，AI 角色和玩家都会被挡住；画错了按住d点击图块删除。
点缀植被。继续用物块层补花草和装饰；拿不准对齐就按g叠加 32×32 网格，误操作用 Ctrl+z 撤销。
保存并接进游戏。AI Town 地图保存这一步很简单：按s键生成地图 .js 文件（含 tilesetpath、bgtiles、objmap 等字段，可对照 src/editor/maps/ 里的 gentle.js 等示例），config 页的 Save Composite 还能导出 PNG 预览图。想让它真正跑起来：把 .js 放进项目，把convex/init.ts里的地图导入从data/gentle改为你的新文件，然后依次执行npx convex run testing:wipeAllTables和npx convex run init清掉旧世界、重建世界，刷新页面就能看到自己的地图。
04 进阶玩法 ✨：自定义图块与动态元素
这节能拿到什么：换上自己的图块，再给地图加上会动的元素。
换自己的图块（AI Town 自定义图块）。把你按 32×32 对齐切好的图片放进src/editor/tilesets/，把 leconfig.js 的DEFAULTTILESETPATH指过去，重启编辑器即可；不想改代码，用 config 页的 Load Tileset 加载本地 png 也可以。
加动态元素。仓库自带data/animations/下 5 组动画定义（windmill、campfire、gentlesparkle、gentlewaterfall、gentlesplash）及对应帧图；在 config 页用 Load Sprite 加载动画再摆上画布——默认地图里的风车和篝火就是这么来的。
导入外部地图。如果你熟悉 Tiled 编辑器，可导出两层（bgtiles、objmap）的 JSON，用 convertMap.js 脚本转成引擎能用的地图文件。
换一批居民。角色定义集中在 data/characters.ts，改完角色数据后同样要清库重建世界。
05 避坑速查 ⚠️
| 现象 | 原因 | 解法 |
|---|---|---|
| 选中的图块"消失"、位置画偏 | 图块完全透明，或没对齐网格 | 按m叠红色遮罩找隐形图块，按g叠网格辅助对齐 |
| 图块错位、被切断 | 16px 与 32px 格长选错 | p键或 config 页的 16/32 选项切换 |
| 保存了地图，游戏里还是旧小镇 | 只生成了 .js，没接进后端 | 改 convex/init.ts 的导入路径，再清库重建世界 |
| 启动时提示 node 版本错误 | Node 版本不兼容 | 换到 Node 18（README 推荐的最稳定版本） |
画完之后：3 件值得做的事
- 用 Modern.png 图块集重画一张同样大小的地图，直观感受图块风格的差别。
- 把自己切的 32×32 png 换成默认图块集，完整走一遍 AI Town 自定义图块流程。
- 加载 windmill 或 campfire 动画摆进地图，看看世界启动后的动态效果。
【免费下载链接】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辅助生成（AIGC），仅供参考