# 关卡地图编辑（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 资源更新后）：

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

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

## 平台

- Cocos Creator **3.8.x**
- macOS / Windows 编辑器
