7.6 KiB
地图编辑器工具文档
本文档说明 tools/map_editor/ 网页地图编辑器的用途、运行方式、操作流程和当前边界。该工具用于编辑游戏运行时读取的 .map 文本地图，不修改引擎源码，也不改变 StageMapLoader 的数据格式。
工具定位
地图编辑器服务第一关场景制作阶段，目标是让 .map 文件从手写配置变成可视化编辑：
- 可视化编辑世界范围、摄像机、玩家出生点、碰撞块、铺砖区、图形矩形、战斗区和敌人出生点。
- 生成兼容
StageMapLoader的.map文本。 - 保持静态网页形态，方便后续部署到服务器。
- 当前只负责地图数据，不负责直接运行游戏预览、不负责复制图片素材、不负责管理素材授权。
文件位置
tools/map_editor/
├─ index.html 网页结构
├─ styles.css 编辑器样式
├─ app.js 解析、绘制、编辑和导出逻辑
├─ README.md 快速说明
└─ DOCUMENTATION.md 本文档
默认编辑目标地图：
game/assets/map/stage_01.map
本地运行
在仓库根目录启动静态服务：
python -m http.server 8787
打开：
http://127.0.0.1:8787/tools/map_editor/
从仓库根目录启动时，工具会尝试自动加载：
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图形对象。
智能选择模式下，碰撞块被视为上层覆盖：
- 如果碰撞块和铺砖区/图形重叠，第一次点击会选中碰撞块。
- 不拖动，在同一区域再点一次，会切换到下层铺砖区或图形。
- 选中碰撞块后拖动，会移动碰撞块本身，不会误移动铺砖区。
- 如果想跳过分层点击，可以直接把“编辑目标”切到目标类型。
常用流程
编辑碰撞块
- 选择“智能选择”或“碰撞块”。
- 点击红色碰撞块。
- 拖动本体移动。
- 拖动右下角蓝色手柄调整宽高。
- 也可以在右侧属性面板直接修改
X / Y / W / H。
编辑铺砖区
- 选择“智能选择”或“铺砖区”。
- 如果和碰撞块重叠，智能选择下先点到碰撞块，再点一次切到铺砖区。
- 拖动铺砖区本体移动。
- 拖动右下角蓝色手柄调整列数和行数。
- 右侧属性面板可修改图块集、坐标、列数、行数、图块索引和 fallback 颜色。
导入图形素材
- 点击左侧“导入图形”。
- 选择图片文件。
- 编辑器会在
PropsBack图层创建一个rect_sprite。 - 同时自动创建同坐标、同尺寸的
collision。 - 选中图形后拖动或缩放，绑定碰撞块会同步移动或缩放。
导入后 .map 默认写入：
assets/stage/stage_01/props/<图片文件名>
静态网页不能自动复制图片到项目目录。实际运行游戏前，需要手动把对应图片素材放到该路径。
如果从仓库根目录启动静态服务，编辑器会把 .map 里的 assets/... 贴图路径映射到 game/assets/... 并自动加载预览。也就是说，项目内已经存在的 Mossy Cavern 等 PNG 会在重新打开地图后直接显示；只有文件没有放到对应目录时才会回退为颜色块。
rect_sprite_src 图形会在属性面板显示 源 X、源 Y、源 W、源 H，可以直接调整大图集的裁切区域。普通 rect_sprite 仍按整张图绘制，不会因为打开属性面板而自动变成 rect_sprite_src。
调整图层顺序
- 在对象列表中选择一个图层，或选择该图层下的图形/铺砖区。
- 点击右侧“图层上移”或“图层下移”。
- 编辑器预览和导出都会按当前
.map图层顺序处理。
运行时 StageRenderer 也按 .map 中 layer 出现顺序渲染，所以图层顺序会影响游戏内显示。
撤回操作
支持撤回以下操作：
- 新增对象。
- 删除对象。
- 移动对象。
- 调整对象尺寸。
- 修改属性。
- 导入图形。
- 图层上移/下移。
快捷键：
Ctrl+Z
打开或重新加载 .map 会清空撤回历史。当前未实现重做。
保存并下载
点击顶部“保存并下载”会下载：
<地图ID>.map
下载内容与右侧“导出文本”一致，并保持 StageMapLoader 兼容。
浏览器安全限制下，静态网页不能直接覆盖项目源文件。当前流程是：
- 保存并下载
.map。 - 手动替换项目内目标地图文件。
- 重新构建或运行游戏验证。
支持的 .map 数据
当前编辑器支持以下核心命令：
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。