刘宇飞
d393302388
Adds level prefabs, theme assets, audio, extensions, and deployment scripts for the Unity WebGL migration. Co-authored-by: Cursor <cursoragent@cursor.com>
106 lines
4.0 KiB
Markdown
106 lines
4.0 KiB
Markdown
# 关卡地图编辑（对齐 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
|
||
```
|