Document map editor plan

game/docs/modules/map_editor.md

@@ -0,0 +1,98 @@
+# 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 二进制脚本导入/导出。
+
+## 推荐形态
+
+优先做项目内工具，而不是改游戏本体：
+
+```text
+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 版做快速预览。