# 关卡地图编辑（对齐 Unity Tile Palette）

## 布局（与 Unity 一致）

| 区域 | Unity | Cocos |
|------|-------|-------|
| 中间 | `Level2` 预制体（Ground + Border Tilemap） | 网格画布 = 当前关卡布局；烘焙后见 `level-prefabs/LevelN.prefab` |
| 右侧 | Tile Palette（Baseblock、JumpBlock、墙块…） | **地图模块** `map-tiles/MapTile_*.prefab` |
| 数据 | `Levels*.cs` + Addressables | `levels-database.json` |

## 1. 启用扩展

1. **扩展管理器** → 启用 `level-map-editor`
2. 菜单 **扩展 → 关卡地图编辑** 打开面板

## 2. 场景内格子吸附

### 自动吸附（推荐）

1. 打开 `level-prefabs/LevelN.prefab`
2. 选中 **LevelN 根节点** → 添加组件 **GridSnapHelper**
3. 在场景中拖动 Ground/Border 下瓦片时，会自动吸附到等距格子中心，并可显示蓝色参考网格

或在关卡地图编辑面板点击 **启用场景吸附助手**（会为当前 Level 根节点添加 `GridSnapHelper`）。

### 手动吸附

1. 在场景编辑器选中一个或多个瓦片节点
2. 面板点击 **场景选中吸附**，立即对齐到最近格子

### 面板画布吸附

鼠标在编辑画布上移动时，高亮当前吸附格子并显示坐标 `(x, y)`，点击/拖拽绘制时自动落在格子中心。

## 3. 绘制工具（对齐 Unity Tile Palette）

| 工具 | 快捷键 | 操作 |
|------|--------|------|
| **画笔** | `B` | 右侧选瓦片后，点击/拖拽在网格上绘制 |
| **框选** | `R` | 拖拽矩形，松开后用当前瓦片填满区域 |
| **吸管** | `I` | 点击已有格子，吸取瓦片并切换为画笔 |
| **橡皮擦** | `E` | 点击/拖拽删除当前层（Ground/Border）上的格子 |
| **填充** | `F` | 油漆桶：填充相连的同类型格子（需先选瓦片） |

1. 选择 **Ground** / **Border** 绘制层
2. 工具栏 **调色板** 下拉选择主题
3. 右侧点选瓦片（画笔/框选/填充需要；吸管/橡皮擦不需要）
4. 在中间等距网格上操作；鼠标移动会高亮吸附格并显示坐标
5. **保存 JSON** → **烘焙预制体** → **打开 Level 预制体**

生成主题调色板数据：

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

## 3. 地图模块预制体

路径：`assets/resources/map-tiles/`

| 预制体 | 用途 |
|--------|------|
| `MapTile_Baseblock` | 可走地面 |
| `MapTile_JumpBlock` | 跳跃格 |
| `MapTile_WallBlock` | 阻挡墙 |
| `MapTile_Decor23` | 装饰墙（Unity 素材切图-23） |

重新生成模块与调色板列表：

```bash
python3 tools/bake_map_tile_prefabs.py
```

首次使用前在 Creator 中 **刷新资源**，确保 `JumpBlock.png`、`WallBlock.png`、`Decor23.png` 已导入。

## 4. 在编辑器里看到砖块（与 Unity 一致）

烘焙后的 `LevelN.prefab` 每个格子带 **Sprite + UITransform**（丝路贴图）。

打开预制体后若场景是空的：

1. 场景编辑器左上角切到 **2D**
2. 按 **F** 聚焦到选中节点，或缩放到原点附近（格子约在 x,y ∈ [-200, 200]）
3. 展开 **Ground / Border**，应能看到等距砖块贴图

与 Unity 差异：Unity 用 **Tilemap** 绘制；Cocos 用 **子节点 + Sprite**（逻辑仍读 `levels-database.json`）。

## 5. 在场景中手动摆放（可选）

与 Unity 在 Scene 里拖 Tile 类似：

1. 在资源管理器打开 `level-prefabs/Level2.prefab`
2. 从 `map-tiles` 将 `MapTile_*` **拖到** `Ground` 或 `Border` 节点下
3. 设置节点位置为格子坐标 × **56**（`CELL_PIXEL`）
4. 保存后仍需同步 `levels-database.json`（用面板编辑或重新导出）

推荐以 **面板编辑 + 烘焙** 为主，保证 JSON 与预制体一致。

## 5. 从 Unity 重新同步

```bash
python3 tools/export_all_levels.py --unity-root "/path/to/主站" --output assets/resources/level/levels-database.json
python3 tools/bake_cocos_level_prefabs.py --db assets/resources/level/levels-database.json --out-dir assets/resources/level-prefabs
python3 tools/bake_map_tile_prefabs.py
```