# 地图编辑器工具文档

本文档说明 `tools/map_editor/` 网页地图编辑器的用途、运行方式、操作流程和当前边界。该工具用于编辑游戏运行时读取的 `.map` 文本地图，不修改引擎源码，也不改变 `StageMapLoader` 的数据格式。

## 工具定位

地图编辑器服务第一关场景制作阶段，目标是让 `.map` 文件从手写配置变成可视化编辑：

- 可视化编辑世界范围、摄像机、玩家出生点、碰撞块、铺砖区、图形矩形、战斗区和敌人出生点。
- 生成兼容 `StageMapLoader` 的 `.map` 文本。
- 保持静态网页形态，方便后续部署到服务器。
- 当前只负责地图数据，不负责直接运行游戏预览、不负责复制图片素材、不负责管理素材授权。

## 文件位置

```text
tools/map_editor/
├─ index.html          网页结构
├─ styles.css          编辑器样式
├─ app.js              解析、绘制、编辑和导出逻辑
├─ server.js           本地可写服务，用于保存和部署 .map
├─ README.md           快速说明
└─ DOCUMENTATION.md    本文档
```

默认编辑目标地图：

```text
game/assets/map/stage_01.map
```

## 本地运行

推荐在仓库根目录启动本地可写服务：

```powershell
node tools/map_editor/server.js
```

打开：

```text
http://127.0.0.1:8787/tools/map_editor/
```

这种模式下，顶部工具栏的 `保存` 和 `一键部署` 会启用。

也可以启动普通静态服务：

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

打开：

```text
http://127.0.0.1:8787/tools/map_editor/
```

静态模式可以编辑和下载，但不能直接写回项目文件。无论哪种模式，从仓库根目录启动时，工具都会尝试自动加载：

```text
game/assets/map/stage_01.map
```

也可以通过顶部“打开 .map”选择其他 `.map` 文件。

## 界面区域

### 顶部工具栏

- `撤回`：撤回最近一次编辑操作。
- `加载 stage_01.map`：重新加载项目默认地图。
- `打开 .map`：从本地选择一个 `.map` 文本文件。
- `保存`：写入项目资源目录的 `game/assets/map/stage_01.map`，需要本地可写服务。
- `一键部署`：保存并同步到项目资源目录和已存在的 PC/Switch build 资源目录，需本地可写服务。
- `保存并下载`：下载当前导出的 `<地图ID>.map`。

### 左侧菜单

- `地图设置`：地图 ID、世界宽高、网格大小、编辑目标。
- `新增对象`：新增图块集、图层、碰撞块、铺砖区、导入图形、战斗区、出生点。
- `对象列表`：列出当前地图中的可编辑对象，点击后选中对象。

### 中间画布

- 显示世界范围、网格、摄像机范围、图层内容、碰撞块、战斗区和出生点。
- 鼠标滚轮缩放。
- 空白区域拖拽可以平移视图。
- 选中对象后拖动本体可以移动。
- 选中矩形类对象后拖动右下角蓝色手柄可以调整尺寸。

### 右侧面板

- `选中对象`：显示当前对象属性。
- `图层上移 / 图层下移`：调整选中图层或选中对象所在图层的顺序。
- `删除选中对象`：删除当前对象。
- `图块集`：显示已有 tileset。
- `导出文本`：实时显示将要保存的 `.map` 文本。

## 编辑目标和命中规则

左侧“编辑目标”用于控制画布点击优先命中的对象类型：

- `智能选择`：默认模式。
- `碰撞块`：只选择 `collision`。
- `铺砖区`：只选择 `tile_rect`。
- `战斗区`：选择 battle zone 触发范围和镜头范围。
- `出生点`：选择玩家或敌人出生点。
- `场景矩形`：选择 `rect` / `rect_sprite` 图形对象。

智能选择模式下，碰撞块被视为上层覆盖：

1. 如果碰撞块和铺砖区/图形重叠，第一次点击会选中碰撞块。
2. 不拖动，在同一区域再点一次，会切换到下层铺砖区或图形。
3. 选中碰撞块后拖动，会移动碰撞块本身，不会误移动铺砖区。
4. 如果想跳过分层点击，可以直接把“编辑目标”切到目标类型。

## 常用流程

### 编辑碰撞块

1. 选择“智能选择”或“碰撞块”。
2. 点击红色碰撞块。
3. 拖动本体移动。
4. 拖动右下角蓝色手柄调整宽高。
5. 也可以在右侧属性面板直接修改 `X / Y / W / H`。

### 编辑铺砖区

1. 选择“智能选择”或“铺砖区”。
2. 如果和碰撞块重叠，智能选择下先点到碰撞块，再点一次切到铺砖区。
3. 拖动铺砖区本体移动。
4. 拖动右下角蓝色手柄调整列数和行数。
5. 右侧属性面板可修改图块集、坐标、列数、行数、图块索引和 fallback 颜色。

### 导入图形素材

1. 点击左侧“导入图形”。
2. 选择图片文件。
3. 编辑器会在 `PropsBack` 图层创建一个 `rect_sprite`。
4. 同时自动创建同坐标、同尺寸的 `collision`。
5. 选中图形后拖动或缩放，绑定碰撞块会同步移动或缩放。

导入后 `.map` 默认写入：

```text
assets/stage/stage_01/props/<图片文件名>
```

静态网页不能自动复制图片到项目目录。实际运行游戏前，需要手动把对应图片素材放到该路径。

如果从仓库根目录启动静态服务，编辑器会把 `.map` 里的 `assets/...` 贴图路径映射到 `game/assets/...` 并自动加载预览。也就是说，项目内已经存在的 Mossy Cavern 等 PNG 会在重新打开地图后直接显示；只有文件没有放到对应目录时才会回退为颜色块。

`rect_sprite_src` 图形会在属性面板显示 `源 X`、`源 Y`、`源 W`、`源 H`，可以直接调整大图集的裁切区域。普通 `rect_sprite` 仍按整张图绘制，不会因为打开属性面板而自动变成 `rect_sprite_src`。

### 调整图层顺序

1. 在对象列表中选择一个图层，或选择该图层下的图形/铺砖区。
2. 点击右侧“图层上移”或“图层下移”。
3. 编辑器预览和导出都会按当前 `.map` 图层顺序处理。

运行时 `StageRenderer` 也按 `.map` 中 `layer` 出现顺序渲染，所以图层顺序会影响游戏内显示。

### 撤回操作

支持撤回以下操作：

- 新增对象。
- 删除对象。
- 移动对象。
- 调整对象尺寸。
- 修改属性。
- 导入图形。
- 图层上移/下移。

快捷键：

```text
Ctrl+Z
```

打开或重新加载 `.map` 会清空撤回历史。当前未实现重做。

### 保存和部署

使用本地可写服务启动时：

```powershell
node tools/map_editor/server.js
```

顶部按钮会启用：

- `保存`：写入 `game/assets/map/stage_01.map`。
- `一键部署`：写入 `game/assets/map/stage_01.map`，并同步到已存在的构建资源目录：
  - `build/windows/x64/release/assets/map/stage_01.map`
  - `build/switch/aarch64/release/switch_game/assets/map/stage_01.map`
  - `build/switch/aarch64/release/switch_game/romfs/assets/map/stage_01.map`

如果某个 build 目录不存在，一键部署会跳过该目标，不会创建完整 build 结构。

### 保存并下载

点击顶部“保存并下载”会下载：

```text
<地图ID>.map
```

下载内容与右侧“导出文本”一致，并保持 `StageMapLoader` 兼容。

普通静态服务模式下，浏览器安全限制不允许直接覆盖项目源文件。当前流程是：

1. 保存并下载 `.map`。
2. 手动替换项目内目标地图文件。
3. 重新构建或运行游戏验证。

## 支持的 .map 数据

当前编辑器支持以下核心命令：

```text
map
world
camera
player_spawn
collision
tileset
layer / endlayer
rect
rect_sprite
rect_sprite_src
tile_rect
battle_zone / endbattle_zone
spawn
```

导出的文本不会写入编辑器私有字段。例如图形和碰撞块的绑定关系只存在于编辑器内存中；导出后仍然是普通 `rect_sprite` 和普通 `collision`。

重新打开 `.map` 时，如果 `rect_sprite` 和某个 `collision` 坐标尺寸完全一致，编辑器会尝试恢复二者的编辑绑定。

## 当前限制

- 普通静态服务模式不能直接覆盖本地源文件，只能下载 `.map`。
- `保存` / `一键部署` 需要使用 `node tools/map_editor/server.js` 启动本地可写服务。
- 导入图片的真实文件仍需手动放入项目资源目录。
- `.map` 中存在于 `game/assets/...` 的 `assets/...` 贴图路径会自动预览。
- 如果导入图片后没有把真实文件放到 `game/assets/...` 对应路径，重新打开 `.map` 后会显示 fallback 色块。
- 暂未实现重做。
- 暂未实现多选和批量移动。
- 暂未实现 tile palette 和 tileset 图片预览。
- 暂未实现一键运行游戏预览。

## 后续扩展建议

- 增加正式服务器保存接口，部署后直接保存 `.map` 到服务器文件或数据库。
- 增加 tileset 图片预览和 tile palette。
- 增加多选、复制、粘贴、批量移动。
- 增加自动检查：视觉铺砖区与碰撞块错位提示。
- 增加一键打开 Windows 版游戏做快速预览。
- 增加导入素材落位检查，提示图片是否已经存在于 `game/assets`。