275 lines
8.2 KiB
Markdown
275 lines
8.2 KiB
Markdown
---
|
||
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 构建
|
||
|
||
有两种方式，**推荐使用命令行方式**（全自动，无需手动操作编辑器）：
|
||
|
||
#### 方式 A：命令行一键构建（推荐）
|
||
|
||
```bat
|
||
REM 从项目根目录运行
|
||
tools\level-builder\build_level.bat
|
||
```
|
||
|
||
**高级用法**：
|
||
```bat
|
||
build_level.bat --json output/v02.json --map LVL_SuburbanV02 # 指定 JSON 和关卡名
|
||
build_level.bat --no-quit # 构建后保留编辑器
|
||
build_level.bat --no-null-rhi # 显示编辑器窗口（调试）
|
||
build_level.bat --dry-run # 只打印命令不执行
|
||
```
|
||
|
||
**环境变量**：
|
||
- `UE5_ROOT` — UE5 安装目录（未设置时自动检测 5.7/5.6 常见路径）
|
||
|
||
**预期输出**：
|
||
```
|
||
[LevelBuilder] 加载 265 个 Actor 定义
|
||
[LevelBuilder] SUCCESS: 265 | FAILED: 0 | TOTAL: 265
|
||
[LevelBuilder] ✅ 关卡已保存: /Game/Maps/LVL_SuburbanV01
|
||
```
|
||
|
||
**生成文件**：
|
||
- `Content/Maps/LVL_SuburbanV01.umap` — UE5 关卡文件
|
||
- `tools/level-builder/output/build_log.json` — 构建日志
|
||
|
||
#### 方式 B：编辑器内手动执行
|
||
|
||
在 UE5 编辑器 Python 控制台中：
|
||
|
||
```
|
||
方式 B1 — Output Log Python 控制台:
|
||
exec(open(r"tools/level-builder/build_in_editor.py").read())
|
||
|
||
方式 B2 — File > Execute Python Script > 选择 build_in_editor.py
|
||
|
||
方式 B3 — CLI 方式（仅构建指定区域）:
|
||
exec(open(r"tools/level-builder/main.py").read())
|
||
main(["build", "-i", "output/level_v01.json", "--zones", "Z1,Z3"])
|
||
```
|
||
|
||
### 第四步：生成搭建报告（离线，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 策略
|