starmen1265
6f8b599629
- 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>
229 lines
8.9 KiB
Markdown
229 lines
8.9 KiB
Markdown
# 关卡执行案模板
|
||
|
||
> 本模板供策划产出关卡执行案时使用。关卡执行案是场景设计案的"空间精度版本"——将氛围描述转化为带有坐标、尺寸和资产建议的结构化搭建指南，供程序在 UE5 编辑器中搭建白模。
|
||
>
|
||
> **注意**：交互物和收集品的放置**不在本模板范围内**，由交互系统/收集系统后续在白盒关卡上叠加。
|
||
>
|
||
> 文件命名：`关卡-v<XX>-<名称>-执行案.md`（如 `关卡-v01-城郊街区-执行案.md`）
|
||
> 存放位置：`docs/design/<阶段>/`（与其他执行案同目录）
|
||
|
||
---
|
||
|
||
```markdown
|
||
# v<版本号> 关卡执行案 — <场景名>
|
||
|
||
## 迭代记录
|
||
|
||
| 迭代版本 | 修改日期 | 状态 | 说明 |
|
||
|----------|----------|------|------|
|
||
| v<版本号> | YYYY-MM-DD | 📝 设计中 | 初始版本 |
|
||
|
||
> 状态标记：📝 设计中 | 🔄 开发中 | ✅ 已同步
|
||
|
||
---
|
||
|
||
## 一、场景参数
|
||
|
||
| 参数 | 值 | 说明 |
|
||
|------|-----|------|
|
||
| 场景总尺寸 | <!-- 如 80m x 60m --> | UE5 单位（1 uu = 1 cm） |
|
||
| 地面高度基准 | <!-- 如 0 --> | 统一地面平面高度（UE5 Z 轴，单位 cm） |
|
||
| 主角身高 | <!-- 如 ~120cm --> | 影响门高、窗台高、摄像机高度 |
|
||
| 主角视角高度 | <!-- 如 ~100cm --> | 摄像机距地面（SpringArm 高度参考） |
|
||
| 时间设定 | <!-- 如 夏日午后 15:00 --> | 影响光照方向和色温 |
|
||
| 坐标系原点 | 场景西南角地平面 | X 轴向东（+），Y 轴向北（+），Z 轴向上（+） |
|
||
|
||
**坐标系说明**：
|
||
- 区域级定位使用**场景绝对坐标**（原点在西南角，单位 cm）
|
||
- 区域内物件使用**相对于该区域西南角的偏移坐标**（0,0 为区域西南角）
|
||
- 偏移格式：(ΔX, ΔY, ΔZ)，ΔX 向东为正，ΔY 向北为正，ΔZ 向上为正
|
||
|
||
---
|
||
|
||
## 二、区域坐标布局
|
||
|
||
### 2.1 区域总览表
|
||
|
||
| 区域编号 | 区域名称 | 绝对坐标范围 (X,Y) | 尺寸 (宽x深) | 地面材质建议 | 标识色 |
|
||
|---------|---------|-------------------|-------------|-------------|--------|
|
||
| Z1 | <!-- 区域名 --> | (X1,Y1)-(X2,Y2) | Wm × Dm | <!-- 如 水泥/砖/泥 --> | <!-- 如 MI_DevRed --> |
|
||
| Z2 | | | | | |
|
||
| ... | | | | | |
|
||
| Zn | | | | | |
|
||
|
||
> 标识色使用 BSP 材质名（参见 `白模资产参考.md`），程序用对应材质标识区域。
|
||
|
||
### 2.2 交通流线
|
||
|
||
| 流线路径 | 宽度 | 说明 |
|
||
|---------|------|------|
|
||
| <!-- 如 Z1 → Z3 家门 → 街道 --> | <!-- 如 200cm --> | <!-- 如 出院门直接接主街 --> |
|
||
| | | |
|
||
| | | |
|
||
|
||
### 2.3 ASCII 总览图
|
||
|
||
<!-- 用简化的方块图展示区域相对位置关系和流线方向 -->
|
||
|
||
```
|
||
Y↑ (北)
|
||
│
|
||
┌─────┤
|
||
│ Zn │
|
||
└──┬──┘
|
||
│
|
||
┌──────┴──────┐
|
||
│ Z... │
|
||
└──┬──────┬───┘
|
||
│ │
|
||
┌──────┴──┐ ┌─┴───────┐
|
||
─────┤ Z1 │ │ Z... ├─────
|
||
└─────────┘ └─────────┘
|
||
────────────────────────────────→ X (东)
|
||
(0,0)
|
||
```
|
||
|
||
---
|
||
|
||
## 三、逐区域搭建指南
|
||
|
||
<!-- ============================================ -->
|
||
<!-- 以下为每个区域的模板，每个区域复制一份并填写 -->
|
||
<!-- ============================================ -->
|
||
|
||
### Z<x>: <区域名称>
|
||
|
||
**区域绝对原点**：(X, Y, Z) — 该区域西南角在场景中的绝对坐标
|
||
|
||
#### 3.x.1 区域参数
|
||
|
||
| 参数 | 值 | 说明 |
|
||
|------|-----|------|
|
||
| 地面高度 | <!-- 如 0cm / +10cm --> | 相对场景地面基准 |
|
||
| 围墙/外墙高度 | <!-- 如 250cm --> | |
|
||
| 门洞宽度 | <!-- 如 120cm --> | |
|
||
| 门洞高度 | <!-- 如 220cm --> | |
|
||
| 室内净高 | <!-- 如 280cm --> | 如为室内区域 |
|
||
| 屋檐高度 | <!-- 如 300cm --> | |
|
||
|
||
#### 3.x.2 结构体清单
|
||
|
||
<!-- 结构体 = 墙、地板、屋顶、门框、窗框、围栏等建筑构件 -->
|
||
|
||
| 编号 | 构件名称 | 尺寸 (宽x深x高, cm) | 相对原点偏移 (ΔX,ΔY,ΔZ) | BSP 资产建议 | 标识色 |
|
||
|------|---------|-------------------|----------------------|-------------|--------|
|
||
| Zx-S01 | <!-- 如 南围墙 --> | <!-- 如 800x20x250 --> | (0,0,0) | <!-- 如 Wall_400x300×2 --> | <!-- 如 MI_DevRed --> |
|
||
| Zx-S02 | | | | | |
|
||
| Zx-S03 | | | | | |
|
||
| ... | | | | | |
|
||
|
||
**BSP 资产建议说明**：
|
||
- 填写 BSP 资产类别名和组合方式（如 "Wall_400x300 × 2 叠加"）
|
||
- 程序负责映射到引擎中的具体资产路径
|
||
- 如无精确匹配，写"Primitives 组合"并注明替代意图
|
||
- 参见 `.claude/refs/白模资产参考.md` 中的替代方案
|
||
|
||
#### 3.x.3 布景物清单
|
||
|
||
<!-- 布景 = 非建筑结构的场景物件：家具、道具、装饰品等 -->
|
||
|
||
| 编号 | 物件名称 | 尺寸 (约, cm) | 相对原点偏移 (ΔX,ΔY,ΔZ) | BSP 资产建议 | 说明 |
|
||
|------|---------|-------------|----------------------|-------------|------|
|
||
| Zx-P01 | <!-- 如 旧自行车 --> | <!-- 如 50x150x100 --> | (100,100,0) | <!-- 如 Car01 缩放50% --> | <!-- 如 靠墙停放 --> |
|
||
| Zx-P02 | | | | | |
|
||
| ... | | | | | |
|
||
|
||
#### 3.x.4 组合资产标记
|
||
|
||
<!-- 需要多个 Primitives 拼搭的物件（无直接 BSP 匹配）。如无此类物件可删除本节。 -->
|
||
|
||
| 编号 | 物件名称 | 期望尺寸 (约, cm) | 推荐拼搭方案 | 说明 |
|
||
|------|---------|-----------------|-------------|------|
|
||
| Zx-C01 | <!-- 如 旧收音机 --> | <!-- 如 20x15x12 --> | <!-- 如 Cube(0.2,0.15,0.12) + Cylinder天线 --> | <!-- 如 放在柜台上 --> |
|
||
| Zx-C02 | | | | |
|
||
| ... | | | | | |
|
||
|
||
> 组合资产将在搭建指南生成阶段展开为多个 Primitive Actor，并在组合资产清单中记录拼搭方案。
|
||
> 用户确认后的组合资产方案将回馈到 asset-catalog 模板库，供后续关卡直接引用。
|
||
|
||
---
|
||
|
||
<!-- 重复 Z2...Zn 的搭建指南 -->
|
||
|
||
---
|
||
|
||
## 四、全局物件清单
|
||
|
||
<!-- 不属于任何特定区域的场景物件，如街道家具、环境物件等。
|
||
全局物件使用场景绝对坐标定位。 -->
|
||
|
||
### 4.1 街道家具
|
||
|
||
| 编号 | 物件名称 | 数量 | 放置位置 (绝对坐标 X,Y,Z) | BSP 资产建议 | 说明 |
|
||
|------|---------|------|------------------------|-------------|------|
|
||
| G-01 | <!-- 如 路灯 --> | <!-- 如 3 --> | <!-- 如 (2000,200,0) --> | <!-- 如 RoadLamp_01 --> | |
|
||
| G-02 | | | | | |
|
||
| ... | | | | | |
|
||
|
||
### 4.2 环境物件
|
||
|
||
| 编号 | 物件名称 | 数量 | 放置位置 (绝对坐标 X,Y,Z) | BSP 资产建议 | 说明 |
|
||
|------|---------|------|------------------------|-------------|------|
|
||
| G-E01 | <!-- 如 电线杆 --> | <!-- 如 2 --> | <!-- 如 (3000,200,0) --> | <!-- 如 Cylinder 缩放 --> | |
|
||
| G-E02 | | | | | |
|
||
| ... | | | | | |
|
||
|
||
---
|
||
|
||
## 五、场景边界与遮挡
|
||
|
||
| 边界段 | 位置范围 | 遮挡方式 | BSP 资产建议 | 标识色 |
|
||
|--------|---------|---------|-------------|--------|
|
||
| 西边界 | X=0 全线 | <!-- 如 围墙 --> | <!-- 如 Wall_400x300 --> | |
|
||
| 南边界 | Y=0 全线 | | | |
|
||
| 东边界 | X=<!-- --> | | | |
|
||
| 北边界 | Y=<!-- --> | | | |
|
||
|
||
> 边界必须确保玩家无法走出场景范围。所有边界物体启用物理碰撞。
|
||
> 自然边界（如水塘）通过不可通行水面实现，无需额外围墙。
|
||
|
||
---
|
||
|
||
## 六、光照建议（可选）
|
||
|
||
| 光源类型 | 数量 | 位置/方向 | 参数建议 | 说明 |
|
||
|---------|------|---------|---------|------|
|
||
| 定向光 | 1 | <!-- 如 从西南向东北照射 --> | <!-- 如 色温 6500K，强度 中 --> | 夏日午后主光源 |
|
||
| 天空光 | 1 | 全局 | | 环境补光 |
|
||
| 路灯 | N | 见全局物件清单 | | 点光源/聚光灯 |
|
||
|
||
> 光照参数为建议值，可调。程序根据实际效果微调方向和强度。
|
||
```
|
||
|
||
---
|
||
|
||
## 模板使用说明
|
||
|
||
### 策划填写要点
|
||
|
||
1. **先确定区域坐标布局**（第二章），确保所有区域在总尺寸内不重叠、流线合理
|
||
2. **逐区域填写**（第三章），按"结构体 → 布景 → 组合资产"的顺序
|
||
3. **BSP 资产建议是方向性指引**：写资产类别名和组合方式即可（如 "Wall_400x300 × 2"），不需要写文件路径
|
||
4. **尺寸以 cm 为单位**，对应 UE5 的 1 uu = 1 cm
|
||
5. **组合资产**：无法用单个 BSP 资产匹配的物件，在 3.x.4 中记录拼搭方案
|
||
|
||
### 不要填写的内容
|
||
|
||
- ❌ 引擎组件名（Actor、Component、Blueprint 等）
|
||
- ❌ 文件路径（如 `/Game/Content/...`）
|
||
- ❌ Blueprint 类名
|
||
- ❌ 精确的硬编码参数值（标注"建议值，可调"并附范围）
|
||
- ❌ 代码或脚本
|
||
- ❌ 交互物和收集品位置（由系统后续叠加）
|
||
|
||
### 与场景设计案的关系
|
||
|
||
- 场景设计案（`场景-v<XX>-<名称>.md`）= **氛围愿景** — 描述感觉、氛围、叙事意图
|
||
- 关卡执行案 = **空间精度搭建指南** — 坐标、尺寸、资产映射
|
||
- 两者是互补关系，不是替代关系。程序搭建时两个文档都需要参考。
|