227 lines
7.6 KiB
Markdown
227 lines
7.6 KiB
Markdown
# 地图编辑器工具文档
|
|
|
|
本文档说明 `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/<图片文件名>
|
|
```
|
|
|
|
静态网页不能自动复制图片到项目目录。实际运行游戏前，需要手动把对应图片素材放到该路径。
|
|
|
|
如果从仓库根目录启动静态服务，编辑器会把 `.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` 会清空撤回历史。当前未实现重做。
|
|
|
|
### 保存并下载
|
|
|
|
点击顶部“保存并下载”会下载：
|
|
|
|
```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` 中存在于 `game/assets/...` 的 `assets/...` 贴图路径会自动预览。
|
|
- 如果导入图片后没有把真实文件放到 `game/assets/...` 对应路径，重新打开 `.map` 后会显示 fallback 色块。
|
|
- 暂未实现重做。
|
|
- 暂未实现多选和批量移动。
|
|
- 暂未实现 tile palette 和 tileset 图片预览。
|
|
- 暂未实现一键运行游戏预览。
|
|
|
|
## 后续扩展建议
|
|
|
|
- 增加服务端保存接口，部署后直接保存 `.map` 到服务器文件或数据库。
|
|
- 增加 tileset 图片预览和 tile palette。
|
|
- 增加多选、复制、粘贴、批量移动。
|
|
- 增加自动检查：视觉铺砖区与碰撞块错位提示。
|
|
- 增加一键打开 Windows 版游戏做快速预览。
|
|
- 增加导入素材落位检查，提示图片是否已经存在于 `game/assets`。
|