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

## 当前实现

首版网页工具已建立：

```text
tools/map_editor/
├─ index.html
├─ styles.css
├─ app.js
└─ README.md
```

本地运行：

```powershell
python -m http.server 8787
```

打开：

```text
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` 记录。

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

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