ChildHood/.claude/skills/level-builder/SKILL.md

name, description

name	description
level-builder	白模关卡自动生成工具。当需要"搭建白模关卡"、"生成白模"、"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 中间数据：

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 中所有资产引用是否有效：

python main.py validate -i output/level_v01.json

预期输出：

[INFO] level_builder: ✅ 验证通过!
[INFO] level_builder: 有效 Actor: 265/265

生成文件: output/validation_result.json

第三步：UE5 构建

有两种方式，推荐使用命令行方式（全自动，无需手动操作编辑器）：

方式 A：命令行一键构建（推荐）

REM 从项目根目录运行
tools\level-builder\build_level.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 可执行）

python main.py report -i output/level_v01.json -l output/build_log.json -o output/搭建报告.md

生成文件: output/搭建报告.md（Markdown 格式，含逐区域对照表）

---

输出说明

JSON 中间数据结构

每个 Actor 的数据格式：

{
  "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，添加条目：

"新资产名": {
    "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 策略