docs(skill): 白模关卡自动生成工具 Skill 文档
This commit is contained in:
@@ -0,0 +1,256 @@
|
||||
---
|
||||
name: "level-builder"
|
||||
description: >
|
||||
白模关卡自动生成工具。当需要"搭建白模关卡"、"生成白模"、"Level Builder"、
|
||||
"白模搭建"、"自动摆放 Actor"、"解析搭建指南"、"parse build guide"时使用。
|
||||
从搭建指南 Markdown 自动解析、验证、在 UE5 编辑器中构建白模关卡并生成搭建报告。
|
||||
---
|
||||
|
||||
# 白模关卡自动生成工具 (Level Builder)
|
||||
|
||||
> 从搭建指南 Markdown → JSON 中间数据 → UE5 Actor 自动构建 + 搭建报告生成
|
||||
|
||||
## 触发条件
|
||||
|
||||
- **game-dev 白模搭建任务**：收到步骤⑥子任务 6a（白模搭建）时使用
|
||||
- **用户手动触发**：用户说"搭建白模"、"生成白模关卡"、"Level Builder"等
|
||||
- **修改关卡后重新生成**：搭建指南有更新，需要重新生成白模
|
||||
|
||||
---
|
||||
|
||||
## 工具位置
|
||||
|
||||
```
|
||||
tools/level-builder/
|
||||
main.py # CLI 入口
|
||||
parsers/
|
||||
markdown_table.py # 通用 Markdown 表格解析
|
||||
build_guide_parser.py # 搭建指南解析器（核心）
|
||||
config/
|
||||
asset_mapping.py # 37 种 BSP 资产 → UE5 路径
|
||||
material_mapping.py # 13 种标识色材质路径
|
||||
zone_config.py # 7 区域定义 + Outliner 结构
|
||||
substitution_rules.py # Primitives 替代规则
|
||||
builder/
|
||||
scene_builder.py # UE5 Python API Actor 构建
|
||||
validation/
|
||||
asset_validator.py # 离线资产验证
|
||||
report/
|
||||
report_generator.py # 搭建报告生成
|
||||
output/ # 生成物目录
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 前置条件
|
||||
|
||||
1. **PythonScriptPlugin 已启用** — `ChildHood.uproject` 中已配置
|
||||
2. **BlockingStarterPack 已导入** — `Content/BlockingStarterPack/` 目录存在
|
||||
3. **搭建指南已就绪** — `docs/technical/关卡-v<XX>-搭建指南.md` 存在
|
||||
|
||||
---
|
||||
|
||||
## 使用流程
|
||||
|
||||
### 第一步：解析搭建指南（离线，Claude 可执行）
|
||||
|
||||
将搭建指南 Markdown 解析为 JSON 中间数据：
|
||||
|
||||
```bash
|
||||
cd tools/level-builder
|
||||
python main.py parse -i ../../docs/technical/关卡-v01-搭建指南.md -o output/level_v01.json
|
||||
```
|
||||
|
||||
**预期输出**：
|
||||
```
|
||||
[INFO] level_builder: 解析搭建指南: ...
|
||||
[INFO] level_builder: 解析完成: 265 个 Actor
|
||||
[INFO] level_builder: 按类别: {'STR': 123, 'PROP': 53, ...}
|
||||
[INFO] level_builder: 唯一资产数: 37
|
||||
```
|
||||
|
||||
**生成文件**: `output/level_v01.json`
|
||||
|
||||
### 第二步：验证（离线，Claude 可执行）
|
||||
|
||||
验证 JSON 中所有资产引用是否有效：
|
||||
|
||||
```bash
|
||||
python main.py validate -i output/level_v01.json
|
||||
```
|
||||
|
||||
**预期输出**：
|
||||
```
|
||||
[INFO] level_builder: ✅ 验证通过!
|
||||
[INFO] level_builder: 有效 Actor: 265/265
|
||||
```
|
||||
|
||||
**生成文件**: `output/validation_result.json`
|
||||
|
||||
### 第三步：UE5 编辑器内构建（需要 UE5 编辑器运行）
|
||||
|
||||
在 UE5 编辑器 Python 控制台中执行：
|
||||
|
||||
```
|
||||
方式 A — Output Log Python 控制台:
|
||||
exec(open(r"tools/level-builder/main.py").read())
|
||||
main(["build", "-i", "output/level_v01.json"])
|
||||
|
||||
方式 B — 仅构建指定区域:
|
||||
main(["build", "-i", "output/level_v01.json", "--zones", "Z1,Z3"])
|
||||
|
||||
方式 C — 增量构建（不清除已有 Actor）:
|
||||
main(["build", "-i", "output/level_v01.json", "--no-clear"])
|
||||
```
|
||||
|
||||
**预期输出**：
|
||||
```
|
||||
[LevelBuilder] 加载 265 个 Actor 定义
|
||||
[LevelBuilder] 清除 0 个已有 LVL_* Actor...
|
||||
进度: 20/265 (20 成功, 0 失败)
|
||||
...
|
||||
[LevelBuilder] 构建完成!
|
||||
成功: 265
|
||||
失败: 0
|
||||
日志: output/build_log.json
|
||||
```
|
||||
|
||||
**生成文件**: `output/build_log.json`
|
||||
|
||||
### 第四步：生成搭建报告（离线，Claude 可执行）
|
||||
|
||||
```bash
|
||||
python main.py report -i output/level_v01.json -l output/build_log.json -o output/搭建报告.md
|
||||
```
|
||||
|
||||
**生成文件**: `output/搭建报告.md`（Markdown 格式，含逐区域对照表）
|
||||
|
||||
---
|
||||
|
||||
## 输出说明
|
||||
|
||||
### JSON 中间数据结构
|
||||
|
||||
每个 Actor 的数据格式：
|
||||
|
||||
```json
|
||||
{
|
||||
"actor_name": "LVL_Z1_STR_SouthWall_01",
|
||||
"asset_key": "Wall_400x300",
|
||||
"asset_type": "static_mesh",
|
||||
"category": "STR",
|
||||
"zone_id": "Z1",
|
||||
"location": [200, 0, 0],
|
||||
"rotation": [0, 0, 0],
|
||||
"scale": [1, 1, 1],
|
||||
"material": "MI_DevRed",
|
||||
"folder": "LVL_SuburbanV01/Z1_家/Structure",
|
||||
"note": ""
|
||||
}
|
||||
```
|
||||
|
||||
特殊 asset_type：
|
||||
- `player_start` — PlayerStart（重生点）
|
||||
- `directional_light` — DirectionalLight（太阳光）
|
||||
- `sky_light` — SkyLight（天空光）
|
||||
- `point_light` — PointLight（点光源）
|
||||
|
||||
### Actor 命名规范
|
||||
|
||||
`LVL_<ZoneID>_<Category>_<Description>`
|
||||
|
||||
| Category | 含义 | 示例 |
|
||||
|----------|------|------|
|
||||
| STR | 结构体 | `LVL_Z1_STR_SouthWall_01` |
|
||||
| PROP | 布景 | `LVL_Z3_PROP_StreetLamp_01` |
|
||||
| INTR | 交互物 | `LVL_Z1_INTR_Fridge_01` |
|
||||
| COLL | 收集品 | `LVL_Z3_COLL_GlassBead_01` |
|
||||
| BND | 边界 | `LVL_BND_East_01` |
|
||||
| LGT | 光源 | `LVL_LGT_DirectionalLight` |
|
||||
|
||||
### Outliner 文件夹结构
|
||||
|
||||
```
|
||||
LVL_SuburbanV01/
|
||||
Z1_家/
|
||||
Structure/
|
||||
Props/
|
||||
Interactables/
|
||||
Collectibles/
|
||||
Z2_小卖部/
|
||||
...
|
||||
Global/
|
||||
Boundaries/
|
||||
Lighting/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 新版本适配
|
||||
|
||||
当有新版本的关卡执行案时，需要：
|
||||
|
||||
1. **策划产出执行案** → `docs/design/<stage>/关卡-v<XX>-<名称>-执行案.md`
|
||||
2. **程序产出搭建指南** → `docs/technical/关卡-v<XX>-搭建指南.md`
|
||||
- 搭建指南格式参照 `docs/technical/关卡-v01-搭建指南.md`
|
||||
- 包含：资产映射表 + Phase A(地面) + Phase B(边界) + Phase C(逐区域) + Phase D(光照)
|
||||
3. **运行 Level Builder** → 按上述四步流程执行
|
||||
|
||||
### 如果需要添加新 BSP 资产
|
||||
|
||||
编辑 `config/asset_mapping.py`，添加条目：
|
||||
|
||||
```python
|
||||
"新资产名": {
|
||||
"path": f"{MESH_ROOT}/分类目录/SM_资产名.SM_资产名",
|
||||
"default_size": (宽, 深, 高), # cm
|
||||
"category": "wall|floor|stair|door|primitive|...",
|
||||
},
|
||||
```
|
||||
|
||||
### 如果需要添加新区域
|
||||
|
||||
编辑 `config/zone_config.py`，在 `ZONES` 字典中添加区域定义。
|
||||
|
||||
---
|
||||
|
||||
## 故障排查
|
||||
|
||||
| 问题 | 原因 | 解决 |
|
||||
|------|------|------|
|
||||
| `No module named 'unreal'` | Stage 2 在编辑器外运行 | 只在 UE5 编辑器 Python 控制台中执行 build 命令 |
|
||||
| 资产加载失败 (spawn returned None) | BSP 资产未导入或路径错误 | 检查 `Content/BlockingStarterPack/` 是否存在 |
|
||||
| Actor 数量与预期不符 | 搭建指南格式变化 | 检查 `parsers/build_guide_parser.py` 的解析逻辑 |
|
||||
| PythonScriptPlugin 未加载 | .uproject 修改后未重启编辑器 | 重启 UE5 编辑器 |
|
||||
| 坐标表达式解析失败 | `200+400n` 格式的范围行 | 检查 `_expand_range_row` 和 `_eval_coord_expr` |
|
||||
|
||||
---
|
||||
|
||||
## 配置参考
|
||||
|
||||
### 区域一览
|
||||
|
||||
| Zone ID | 名称 | 原点 | 尺寸 | 标识色 |
|
||||
|---------|------|------|------|--------|
|
||||
| Z1 | 家 | (0,0,0) | 1000×800 | Red |
|
||||
| Z2 | 小卖部 | (1000,200,0) | 600×600 | Orange |
|
||||
| Z3 | 主街道 | (0,800,0) | 5000×500 | Gray |
|
||||
| Z4 | 空地 | (3500,1300,0) | 1500×1200 | Brown |
|
||||
| Z5 | 巷子 | (2000,0,0) | 600×800 | Green |
|
||||
| Z6 | 水塘边 | (5500,0,0) | 1500×1000 | Blue |
|
||||
| Z7 | 老居民楼 | (5000,1300,0) | 1500×1200 | Yellow |
|
||||
|
||||
### 搭建报告发布
|
||||
|
||||
搭建报告需要双轨发布：
|
||||
1. **本地文件**: `docs/technical/关卡-v<XX>-搭建报告.md`
|
||||
2. **Issue 评论**: 在对应任务 Issue 下以评论形式发布（供 PM 和策划直接查看）
|
||||
|
||||
---
|
||||
|
||||
## 未来扩展
|
||||
|
||||
- **执行案解析器** — 直接从 `关卡-v<XX>-<名称>-执行案.md` 解析，跳过手动搭建指南
|
||||
- **蓝图支持** — 除 StaticMesh 外支持 Blueprint Actor 放置
|
||||
- **碰撞预设** — 自动为不同 Category 设置碰撞 Profile
|
||||
- **LOD 标记** — 为远距离布景标记 LOD 策略
|
||||
Reference in New Issue
Block a user