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 可视化编辑，且不影响引擎编译链路。

数据边界

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

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

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

首版验收

完成时应达到：

1. 能载入当前 stage_01.map。
2. 能看到地面、平台、battle zone、spawn point。
3. 能新增/移动/删除一个 collision。
4. 能新增/移动/删除一个 tile_rect。
5. 能保存 .map。
6. 保存后的 .map 用游戏启动不报解析错误。
7. Windows 构建通过，短启动通过。
8. Switch 构建能把保存后的 .map 打进 RomFS。

后续增强

• tile palette。
• tileset 图片预览。
• battle zone 清场出口配置。
• props 图层编辑。
• 自动检查视觉 tile 与碰撞误差。
• 一键运行 Windows 版做快速预览。