feat(tools): 新增execution-to-guide执行案转搭建指南工具

- execution_parser.py: 解析关卡执行案Markdown提取区域/结构体/布景/边界/光照
- asset_expander.py: BSP资产建议展开+绝对坐标计算+旋转推断
- guide_writer.py: 生成精确匹配build_guide_parser格式的搭建指南
- composite_writer.py: 组合资产清单+JSON模板生成
- converter.py: 主入口CLI工具
- 更新level-execution-template.md: 移除交互物/收集品章节,新增组合资产标记

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
2026-06-11 00:44:46 +08:00
parent f86ffb511e
commit 6f8b599629
9 changed files with 2731 additions and 29 deletions
+12 -29
View File
@@ -2,6 +2,8 @@
> 本模板供策划产出关卡执行案时使用。关卡执行案是场景设计案的"空间精度版本"——将氛围描述转化为带有坐标、尺寸和资产建议的结构化搭建指南,供程序在 UE5 编辑器中搭建白模。
>
> **注意**:交互物和收集品的放置**不在本模板范围内**,由交互系统/收集系统后续在白盒关卡上叠加。
>
> 文件命名:`关卡-v<XX>-<名称>-执行案.md`(如 `关卡-v01-城郊街区-执行案.md`)
> 存放位置:`docs/design/<阶段>/`(与其他执行案同目录)
@@ -131,30 +133,18 @@
| Zx-P02 | | | | | |
| ... | | | | | |
#### 3.x.4 可交互物体标记
#### 3.x.4 组合资产标记
<!-- 引用交互系统执行案中的交互物,此处只标注空间位置 -->
<!-- 需要多个 Primitives 拼搭的物件(无直接 BSP 匹配)。如无此类物件可删除本节。 -->
| 交互编号 | 物件名称 | 交互类型 | 相对原点偏移 (ΔX,ΔY,ΔZ) | 触发半径 (cm) | 引用 |
|---------|---------|---------|----------------------|-------------|------|
| Zx-I01 | <!-- 如 旧冰箱 --> | <!-- 如 观察 --> | (200,400,10) | <!-- 如 150 --> | 交互系统-执行案 #n |
| Zx-I02 | | | | | |
| ... | | | | | |
> 交互类型参照交互系统执行案中的分类(观察/拾取/操作/对话等)。
> "引用"列填写交互系统执行案中对应交互物的编号,确保跨文档一致。
#### 3.x.5 收集品标记
<!-- 引用收集系统执行案中的收集品,此处只标注空间位置 -->
| 收集编号 | 物品名称 | 稀有度 | 相对原点偏移 (ΔX,ΔY,ΔZ) | 引用 |
|---------|---------|--------|----------------------|------|
| Zx-C01 | <!-- 如 彩色弹珠 --> | <!-- 如 普通/稀有 --> | (500,200,0) | 收集系统-执行案 #n |
| 编号 | 物件名称 | 期望尺寸 (约, cm) | 推荐拼搭方案 | 说明 |
|------|---------|-----------------|-------------|------|
| Zx-C01 | <!-- 如 旧收音机 --> | <!-- 如 20x15x12 --> | <!-- 如 Cube(0.2,0.15,0.12) + Cylinder天线 --> | <!-- 如 放在柜台上 --> |
| Zx-C02 | | | | |
| ... | | | | | |
> 稀有度影响拾取物的视觉效果标识(普通=白色光,稀有=金色光),具体表现由收集系统技术方案定义。
> 组合资产将在搭建指南生成阶段展开为多个 Primitive Actor,并在组合资产清单中记录拼搭方案。
> 用户确认后的组合资产方案将回馈到 asset-catalog 模板库,供后续关卡直接引用。
---
@@ -183,14 +173,6 @@
| G-E02 | | | | | |
| ... | | | | | |
### 4.3 收集品位置汇总
| # | 物品名称 | 所在区域 | 绝对坐标 (X,Y,Z) | 稀有度 | 引用 |
|---|---------|---------|-----------------|--------|------|
| 1 | | | | | 收集系统-执行案 #n |
| 2 | | | | | |
| ... | | | | | |
---
## 五、场景边界与遮挡
@@ -225,10 +207,10 @@
### 策划填写要点
1. **先确定区域坐标布局**(第二章),确保所有区域在总尺寸内不重叠、流线合理
2. **逐区域填写**(第三章),按"结构体 → 布景 → 交互物 → 收集品"的顺序
2. **逐区域填写**(第三章),按"结构体 → 布景 → 组合资产"的顺序
3. **BSP 资产建议是方向性指引**:写资产类别名和组合方式即可(如 "Wall_400x300 × 2"),不需要写文件路径
4. **尺寸以 cm 为单位**,对应 UE5 的 1 uu = 1 cm
5. **交叉引用**:交互物和收集品必须引用对应系统执行案中的编号,保持跨文档一致
5. **组合资产**:无法用单个 BSP 资产匹配的物件,在 3.x.4 中记录拼搭方案
### 不要填写的内容
@@ -237,6 +219,7 @@
- ❌ Blueprint 类名
- ❌ 精确的硬编码参数值(标注"建议值,可调"并附范围)
- ❌ 代码或脚本
- ❌ 交互物和收集品位置(由系统后续叠加)
### 与场景设计案的关系