263 lines
8.9 KiB
Markdown
263 lines
8.9 KiB
Markdown
# 地图编辑器工具文档
|
|
|
|
本文档说明 `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`。
|