Document map editor plan

game/docs/README.md

@@ -22,6 +22,7 @@
 - `modules/core_services.md`：启动、服务、配置、资源路径。
 - `modules/assets.md`：资源槽位和素材落位。
 - `modules/data_map.md`：地图数据和 `LevelDefinition`。
+- `modules/map_editor.md`：简易 `.map` 地图编辑器计划。
 - `modules/stage_rendering.md`：场景分层和渲染。
 - `modules/scene_camera.md`：场景流程、摄像机、battle zone。
 - `modules/movement_collision.md`：横版移动和平台碰撞。

game/docs/modules/README.md

@@ -7,6 +7,7 @@
 - `core_services.md`：游戏启动、`GameServices`、资源路径、基础配置。
 - `assets.md`：全局资源槽位、角色资源优先级、地图和 stage 资源落位。
 - `data_map.md`：`LevelDefinition`、`.map` 加载、地图数据格式。
+- `map_editor.md`：简易 `.map` 地图编辑器目标、范围和验收标准。
 - `stage_rendering.md`：`StageRenderer`、场景分层、贴图/色块 fallback。
 - `scene_camera.md`：`WhiteboxScene`、摄像机跟随、battle zone 锁镜头。
 - `movement_collision.md`：`PlatformWorld`、`PlatformMover`、横版基础碰撞。

game/docs/modules/data_map.md

@@ -76,6 +76,7 @@ endbattle_zone
 
 ## 下一步
 
+- 下一阶段开始正式做地图场景，优先建设简易 `.map` 编辑器，详见 `map_editor.md`。
 - 把 `tile_rect` 扩展成可表达 tile row/column 或 tile id。
 - 增加空 layer、battle zone 无 spawn、tile texture 不存在等更严格错误日志。
 - 保留 `whitebox_level.cpp` 作为 fallback，不再把主地图写死在 C++。

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 版做快速预览。

game/docs/planning/scene_build_plan.md

@@ -292,15 +292,19 @@ game/assets/stage/stage_01/
 4. 已完成：给 map loader 增加重复 tileset、未知 tileset、非法 tile rect 等错误日志。
 5. 已完成：补轻量 map 验收流程：启动时日志确认加载 `.map`，Windows/Switch 产物确认存在 `assets/map/stage_01.map` 和全局素材槽位。
 
+### 当前阶段：地图场景制作
+
+从现在开始，重点从“场景骨架”切到“地图场景制作”。因为 `.map` 已经成为第一关主数据源，继续手写地图会拖慢制作效率，所以下一步先做一个简易 `.map` 地图编辑器。编辑器计划见 `../modules/map_editor.md`。
+
 ### 下一轮建议任务
 
-继续围绕地图视觉骨架，不进入战斗玩法：
+继续围绕地图制作工具和地图视觉骨架，不进入战斗玩法：
 
-1. 给 `tile_rect` 增加二维 source index 或 tile id，避免只支持 tileset 第一行。
+1. 建立 `tools/map_editor/`，实现能打开/保存 `stage_01.map` 的最小编辑器。
-2. 按正式素材规格整理 `stage_01_tileset.png` 的格子约定。
+2. 编辑器首版先支持 world、camera、player spawn、collision、tileset、tile_rect、battle zone、spawn point。
-3. 用一个临时 tileset PNG 替换当前 fallback 色块，验证 source rect 对齐。
+3. 在编辑器中提供网格吸附、视图平移、缩放和对象选择。
-4. 增加 tile texture 缺失的日志去重，避免大量 tile 重复报同一个资源。
+4. 保存后的 `.map` 必须能被 `StageMapLoader` 直接读取。
-5. 手动跑图确认所有平台视觉和碰撞误差不超过 4 像素。
+5. 编辑器稳定后，再给 `tile_rect` 增加二维 source index 或 tile id，接正式 tileset。
 
 ### Debug 快捷键