NS_unknown_game/game/docs/modules/map_editor.md

Map Editor

目标

下一阶段开始正式做地图场景。为了避免手写 .map 文件效率太低，需要先做一个简易地图编辑器，用来编辑和保存当前游戏使用的 .map 数据。

首版编辑器目标不是完整关卡编辑器，而是服务第一关灰盒/素材替换阶段：

• 能打开 game/assets/map/stage_01.map。
• 能可视化编辑地图基础对象。
• 能保存回当前 .map 文本格式。
• 保存后的 .map 必须能被 StageMapLoader 直接读取。
• 不改变游戏运行时主流程。

首版范围

必须支持

• 打开/保存 .map。
• 显示世界尺寸、摄像机范围和玩家出生点。
• 显示并编辑 collision 矩形。
• 显示并编辑 layer。
• 显示并编辑 tileset。
• 显示并编辑 tile_rect。
• 显示并编辑 battle_zone。
• 显示并编辑 spawn。
• 网格吸附，默认以 tile size 或 10px 为单位。
• 基础缩放和平移视图。

可以暂缓

• 重做。
• 多选批量操作。
• 自动铺边缘 tile。
• 地图对象属性面板的高级校验。
• 直接预览游戏运行效果。
• PVF 二进制脚本导入/导出。

推荐形态

优先做项目内工具，而不是改游戏本体：

tools/map_editor/

推荐首版技术路线：

• 桌面本地工具或轻量网页工具均可。
• 数据层必须读写当前 .map 文本格式。
• 编辑器内部可以有自己的 UI 状态，但导出文件必须保持 StageMapLoader 兼容。

如果做网页工具，首版可以使用：

• 单页 HTML/JS。
• Canvas 绘制地图。
• 文件打开/保存走浏览器 File API。

如果做原生工具，首版可以使用：

• C++/SDL + ImGui。
• 或 C#/.NET 简易桌面工具。

当前优先推荐轻量网页工具，因为它能更快完成 .map 可视化编辑，且不影响引擎编译链路。

当前实现

首版网页工具已建立：

tools/map_editor/
├─ index.html
├─ styles.css
├─ app.js
├─ server.js
└─ README.md

推荐本地运行：

node tools/map_editor/server.js

打开：

http://127.0.0.1:8787/tools/map_editor/

这种模式下支持顶部 保存 和 一键部署：

• 保存：写入 game/assets/map/stage_01.map。
• 一键部署：写入项目资源目录，并同步到已存在的 PC/Switch build 资源目录。

只需要下载 .map 时，也可以使用普通静态服务：

python -m http.server 8787

打开：

http://127.0.0.1:8787/tools/map_editor/

当前能力：

• 从仓库静态服务加载 game/assets/map/stage_01.map。
• 通过文件选择打开任意 .map。
• Canvas 可视化 world、camera、player spawn、collision、rect、tile_rect、battle zone、spawn。
• 对象列表选择和画布点击选择。
• 网格吸附拖动对象。
• 通过“编辑目标”过滤画布命中目标，默认“智能选择”把 collision 当作上层覆盖；重叠位置第一次点选碰撞块，再点一次切到下层 tile_rect 或图形。
• 矩形对象支持右下角手柄缩放。
• 属性面板编辑选中对象的数值或文本。
• 新增/删除 tileset、layer、collision、tile_rect、battle zone、spawn。
• 支持撤回最近编辑操作，包含新增、删除、拖动、缩放、属性修改、导入图形和图层移动。
• 支持 Ctrl+Z 快捷撤回。
• 支持保存并下载 .map 文本。
• 使用 server.js 启动时，支持直接保存到项目资源目录。
• 使用 server.js 启动时，支持一键部署到项目资源目录和已存在的 PC/Switch build 资源目录。
• 支持选择图层或图层内对象后，对对应图层上移/下移；预览和导出都按当前 .map 图层顺序处理。
• 通过“导入图形”创建 rect_sprite，并自动追加一个同坐标、同尺寸的 collision。
• 导入图形在当前浏览器会话内支持图片预览；图形移动和缩放时，同步更新绑定碰撞块。
• 从仓库根目录启动静态服务时，.map 内 assets/... 贴图路径会自动映射到 game/assets/... 并加载项目内已有图片预览。
• rect_sprite_src 图形支持在属性面板编辑源图裁切区域。
• 重新打开 .map 时，如果 rect_sprite 与某个 collision 坐标尺寸一致，编辑器会自动恢复二者的编辑绑定。
• 导出兼容 StageMapLoader 的 .map 文本。

浏览器安全限制下，纯静态网页不能直接覆盖本地源文件；当前通过“保存并下载”导出 .map。本地开发时可通过 tools/map_editor/server.js 启动带写入 API 的服务，直接写回项目文件和已有 build 资源目录。

数据边界

编辑器只负责编辑 .map 数据，不负责：

• 修改 WhiteboxScene。
• 修改 StageRenderer。
• 修改碰撞运行逻辑。
• 修改角色、战斗或 AI。
• 管理素材授权。

素材路径仍由 .map 和 game/assets/stage/stage_01/ASSETS.md 记录。

导入图形时，静态网页不能直接复制图片文件到仓库。编辑器默认把贴图路径写为：

assets/stage/stage_01/props/<图片文件名>

实际运行游戏前，需要把对应图片素材放到该目录。编辑器内的图形-碰撞绑定是工具层能力，导出的 .map 仍保持运行时兼容格式，不额外写入私有字段。

项目内已有素材预览规则：

• assets/... 会映射到仓库内 game/assets/...。
• game/assets/... 会直接映射到仓库同名路径。
• 如果文件存在，编辑器重新打开 .map 后也会自动预览。
• 如果文件不存在，编辑器使用颜色块 fallback。

首版验收

完成时应达到：

1. 已完成：能载入当前 stage_01.map。
2. 已完成：能看到地面、平台、battle zone、spawn point。
3. 已完成：能新增/移动/删除一个 collision。
4. 已完成：能新增/移动/删除一个 tile_rect。
5. 已完成：tile_rect 与 collision 重叠时，默认智能选择先选中并移动碰撞块，再次点击同一区域可切到铺砖区。
6. 已完成：能导入图形，生成 rect_sprite 和同尺寸 collision。
7. 已完成：导入图形支持移动、缩放和同步调整绑定碰撞块。
8. 已完成：能撤回最近编辑操作。
9. 已完成：能保存并下载 .map。
10. 已完成：能上移/下移图层，并按当前图层顺序预览和导出。
11. 已完成：编辑器 parser/serializer 烟测通过，保存格式保持 StageMapLoader 兼容。
12. 待后续地图修改后复测：Windows 构建通过，短启动通过。
13. 待后续地图修改后复测：Switch 构建能把保存后的 .map 打进 RomFS。

后续增强

• tile palette。
• tileset 图片预览。
• 保存接口：部署到服务器后，把 .map 文本写回服务端文件或数据库。
• battle zone 清场出口配置。
• props 图层编辑。
• 自动检查视觉 tile 与碰撞误差。
• 一键运行 Windows 版做快速预览。