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