diff --git a/.claude/skills/level-builder/SKILL.md b/.claude/skills/level-builder/SKILL.md new file mode 100644 index 0000000..fd72413 --- /dev/null +++ b/.claude/skills/level-builder/SKILL.md @@ -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-搭建指南.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___` + +| 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//关卡-v-<名称>-执行案.md` +2. **程序产出搭建指南** → `docs/technical/关卡-v-搭建指南.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-搭建报告.md` +2. **Issue 评论**: 在对应任务 Issue 下以评论形式发布（供 PM 和策划直接查看） + +--- + +## 未来扩展 + +- **执行案解析器** — 直接从 `关卡-v-<名称>-执行案.md` 解析，跳过手动搭建指南 +- **蓝图支持** — 除 StaticMesh 外支持 Blueprint Actor 放置 +- **碰撞预设** — 自动为不同 Category 设置碰撞 Profile +- **LOD 标记** — 为远距离布景标记 LOD 策略