cocos/tools/level-map-editor.md

关卡地图编辑（对齐 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 预制体

生成主题调色板数据：

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）

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

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 重新同步

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