cocos/extensions/level-map-editor/README.md

关卡地图编辑（level-map-editor）

对齐 Unity 平铺调色板（Tile Palette）：中间为关卡等距网格，右侧为可绘制的主题瓦片。

打开方式

1. 扩展管理器中启用本扩展，点击 刷新（版本应为 1.0.3）
2. 顶部菜单任选其一：
   • 面板 → level-map-editor → 关卡地图编辑（推荐）
   • 扩展 → 关卡地图编辑
3. 控制台应出现 [level-map-editor] extension loaded 与 Panel.open
4. 若仍无窗口：关闭扩展 → 再开启 → 或重启 Creator

使用步骤

1. 调色板 下拉选择主题（如 sanxing 三星堆）
2. 点 新建（自动分配下一个关卡 ID，从 91601 起，与 Unity / 主站 BEGINNING_REAL_LVID=91601 对齐）
   • 或输入已有 关卡 ID → 加载
3. 右侧点击瓦片（WallBlock / JumpBlock / Baseblock / kuai11 等）
4. 使用工具栏 画笔 / 框选 / 吸管 / 橡皮擦 / 填充（快捷键 B R I E F）
5. 选择 Ground 或 Border 层，在中间网格绘制
6. 绘制/改实体后 自动保存 levels-database.json 并 自动烘焙 Level{id}.prefab，同步 tools/level-prefab-index.json
7. 在 资源管理器 中编辑并 保存 Level{id}.prefab 后，扩展会 自动回写 JSON 并刷新本面板（当前关卡 ID 一致时）
8. 需要时 打开 Level 预制体 预览，或点 从预制体同步 手动触发回写

预制体 ↔ JSON 双向同步

方向	触发
JSON → prefab	面板改地图后自动烘焙，或点「烘焙预制体」
prefab → JSON	保存 level-prefabs/Level{id}.prefab 后自动导入；或点「从预制体同步」

回写内容：LevelMapData 的 groundJson / borderJson / theme；若 Ground/Border 子节点（g_x_y / b_x_y）与 JSON 不一致，以 场景瓦片节点 为准。spawns / boundary 仍由关卡控制器维护，不会被 prefab 覆盖。

场景内格子吸附

• GridSnapHelper 组件（挂在 Level 根节点）：拖动瓦片时自动吸附，可显示蓝色参考网格
• 面板 启用场景吸附助手：为当前 Level 添加该组件
• 面板 场景选中吸附：将场景中已选瓦片立即对齐到格子
• 画布鼠标移动时会 高亮 当前吸附格并显示坐标

数据与工具

路径	说明
assets/resources/level/levels-database.json	关卡逻辑数据
assets/resources/map-tiles/palettes/_index.json	主题调色板索引
assets/resources/level-prefabs/Level91601.prefab	烘焙后的关卡预制体（ID 与 Unity 一致，首关 91601）
tools/level-prefab-index.json	预制体路径索引（烘焙时自动重建）
tools/level_id.py / dist/level-id.js	关卡 ID 约定（91601 首关）

生成调色板（首次或 Unity 资源更新后）：

python3 tools/build_theme_palettes.py --unity-root "/path/to/主站"

详细说明见项目 tools/level-map-editor.md。

平台

• Cocos Creator 3.8.x
• macOS / Windows 编辑器