---
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 策略