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
└─ README.md

本地运行：

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。
• 矩形对象支持右下角手柄缩放。
• 属性面板编辑选中对象的数值或文本。
• 新增/删除 tileset、layer、collision、tile_rect、battle zone、spawn。
• 通过“导入图形”创建 rect_sprite，并自动追加一个同坐标、同尺寸的 collision。
• 导入图形在当前浏览器会话内支持图片预览；图形移动和缩放时，同步更新绑定碰撞块。
• 重新打开 .map 时，如果 rect_sprite 与某个 collision 坐标尺寸一致，编辑器会自动恢复二者的编辑绑定。
• 导出兼容 StageMapLoader 的 .map 文本。

浏览器安全限制下，纯静态网页不能直接覆盖本地源文件；当前通过 Download 导出 .map。后续部署到服务器时，可以增加一个保存接口，把编辑器导出的文本写回服务端文件或数据库。

数据边界

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

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

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

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

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

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

首版验收

完成时应达到：

1. 已完成：能载入当前 stage_01.map。
2. 已完成：能看到地面、平台、battle zone、spawn point。
3. 已完成：能新增/移动/删除一个 collision。
4. 已完成：能新增/移动/删除一个 tile_rect。
5. 已完成：能导入图形，生成 rect_sprite 和同尺寸 collision。
6. 已完成：导入图形支持移动、缩放和同步调整绑定碰撞块。
7. 已完成：能导出 .map。
8. 已完成：编辑器 parser/serializer 烟测通过，保存格式保持 StageMapLoader 兼容。
9. 待后续地图修改后复测：Windows 构建通过，短启动通过。
10. 待后续地图修改后复测：Switch 构建能把保存后的 .map 打进 RomFS。

后续增强

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