Document map editor tool

tools/map_editor/DOCUMENTATION.md

@@ -0,0 +1,221 @@
+# 地图编辑器工具文档
+
+本文档说明 `tools/map_editor/` 网页地图编辑器的用途、运行方式、操作流程和当前边界。该工具用于编辑游戏运行时读取的 `.map` 文本地图，不修改引擎源码，也不改变 `StageMapLoader` 的数据格式。
+
+## 工具定位
+
+地图编辑器服务第一关场景制作阶段，目标是让 `.map` 文件从手写配置变成可视化编辑：
+
+- 可视化编辑世界范围、摄像机、玩家出生点、碰撞块、铺砖区、图形矩形、战斗区和敌人出生点。
+- 生成兼容 `StageMapLoader` 的 `.map` 文本。
+- 保持静态网页形态，方便后续部署到服务器。
+- 当前只负责地图数据，不负责直接运行游戏预览、不负责复制图片素材、不负责管理素材授权。
+
+## 文件位置
+
+```text
+tools/map_editor/
+├─ index.html          网页结构
+├─ styles.css          编辑器样式
+├─ app.js              解析、绘制、编辑和导出逻辑
+├─ README.md           快速说明
+└─ DOCUMENTATION.md    本文档
+```
+
+默认编辑目标地图：
+
+```text
+game/assets/map/stage_01.map
+```
+
+## 本地运行
+
+在仓库根目录启动静态服务：
+
+```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` 文本文件。
+- `保存并下载`：下载当前导出的 `<地图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/<图片文件名>
+```
+
+静态网页不能自动复制图片到项目目录。实际运行游戏前，需要手动把对应图片素材放到该路径。
+
+### 调整图层顺序
+
+1. 在对象列表中选择一个图层，或选择该图层下的图形/铺砖区。
+2. 点击右侧“图层上移”或“图层下移”。
+3. 编辑器预览和导出都会按当前 `.map` 图层顺序处理。
+
+运行时 `StageRenderer` 也按 `.map` 中 `layer` 出现顺序渲染，所以图层顺序会影响游戏内显示。
+
+### 撤回操作
+
+支持撤回以下操作：
+
+- 新增对象。
+- 删除对象。
+- 移动对象。
+- 调整对象尺寸。
+- 修改属性。
+- 导入图形。
+- 图层上移/下移。
+
+快捷键：
+
+```text
+Ctrl+Z
+```
+
+打开或重新加载 `.map` 会清空撤回历史。当前未实现重做。
+
+### 保存并下载
+
+点击顶部“保存并下载”会下载：
+
+```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`。
+- 导入图片的真实文件仍需手动放入项目资源目录。
+- 已导入图片的浏览器预览只在当前会话有效；重新打开 `.map` 后，如果没有重新选择图片，会显示 fallback 色块。
+- 暂未实现重做。
+- 暂未实现多选和批量移动。
+- 暂未实现 tile palette 和 tileset 图片预览。
+- 暂未实现一键运行游戏预览。
+
+## 后续扩展建议
+
+- 增加服务端保存接口，部署后直接保存 `.map` 到服务器文件或数据库。
+- 增加 tileset 图片预览和 tile palette。
+- 增加多选、复制、粘贴、批量移动。
+- 增加自动检查：视觉铺砖区与碰撞块错位提示。
+- 增加一键打开 Windows 版游戏做快速预览。
+- 增加导入素材落位检查，提示图片是否已经存在于 `game/assets`。

tools/map_editor/README.md

@@ -2,6 +2,12 @@
 
 这是一个静态网页地图编辑器，用来编辑游戏使用的 `.map` 文本文件。
 
+完整工具说明见：
+
+```text
+tools/map_editor/DOCUMENTATION.md
+```
+
 ## 本地运行
 
 在仓库根目录执行：