docs(workflow): 关卡设计工作流与关卡执行案体系

- Agent 文档新增关卡执行案产出规范与白模搭建工作流 - 开发流水线补充关卡执行案产出节点与白模搭建子任务(6a) - 新增关卡执行案模板、BSP资产参考卡、关卡设计工作流规范 - 新增原型阶段设计文档索引 README - .gitignore 补充 __pycache__ 规则
2026-06-06 23:55:14 +08:00
parent b951450345
commit 84bdfb22de
9 changed files with 1131 additions and 1 deletions
@@ -0,0 +1,73 @@
+# 原型阶段设计文档索引
+
+> 最后更新：2026-06-06
+> 阶段：原型阶段 | 版本范围：v0.1–v0.4
+
+---
+
+## 核心锚点
+
+| 文档 | 说明 |
+|------|------|
+| [game-vision.md](game-vision.md) | 游戏愿景、核心情感、三大支柱——所有设计决策的锚点 |
+
+---
+
+## 系统设计案
+
+| 文档 | 说明 | 当前版本覆盖 |
+|------|------|-------------|
+| [player-controller.md](player-controller.md) | 玩家角色控制——移动、摄像机、动画蓝图 | v0.1 ✅ |
+| [interaction-system.md](interaction-system.md) | 环境交互系统——交互组件、检测、UI 提示 | v0.1 ✅ |
+| [collection-system.md](collection-system.md) | 收集系统——拾取、进度追踪、图鉴（v0.1 基础版 → v0.4 完整版） | v0.1 ✅ v0.2+ 待补 |
+| [minigame-system.md](minigame-system.md) | 小游戏体系——弹珠、拍洋画、四驱车等千禧年童年游戏 | v0.2 待补执行案 |
+| [narrative-framework.md](narrative-framework.md) | 叙事框架——暑假结构、事件设计、角色系统 | v0.3-v0.4 待补 |
+
+---
+
+## 场景与角色
+
+| 文档 | 说明 |
+|------|------|
+| [scene-world.md](scene-world.md) | 完整场景与世界观设计（城市主场景 + 乡下场景） |
+| [scene-v01-suburban.md](scene-v01-suburban.md) | v0.1 白盒场景具体内容——6 区域布局、交互点位置 |
+| [protagonist-character.md](protagonist-character.md) | 主角角色描述——美术设计的核心参考 |
+
+---
+
+## 执行案
+
+| 文档 | 对应系统 | 版本 | 状态 |
+|------|---------|------|------|
+| [player-controller-execution.md](player-controller-execution.md) | 角色控制 | v0.1.1 | 📝 设计中 |
+| [interaction-system-execution.md](interaction-system-execution.md) | 交互系统 | v0.1.2 | 📝 设计中 |
+| [collection-system-execution.md](collection-system-execution.md) | 收集系统 | v0.1.1 | 📝 设计中 |
+
+---
+
+## 版本范围
+
+| 文档 | 说明 |
+|------|------|
+| [v01-scope.md](v01-scope.md) | v0.1 功能边界、验收标准、开发优先级 |
+
+---
+
+## 头脑风暴记录
+
+| 文档 | 日期 | 主题 |
+|------|------|------|
+| [brainstorm-2026-06-01-vision-pillars-world.md](brainstorm-2026-06-01-vision-pillars-world.md) | 2026-06-01 | 愿景三大支柱 + 世界观确认 |
+| [brainstorm-2026-06-04-era-tech-inspirations.md](brainstorm-2026-06-04-era-tech-inspirations.md) | 2026-06-04 | 千禧年时代技术灵感（随身听、小霸王、街机等） |
+| [brainstorm-2026-06-05-nostalgia-culture.md](brainstorm-2026-06-05-nostalgia-culture.md) | 2026-06-05 | 千禧年怀旧文化灵感（电视剧、广播体操、广场舞等） |
+
+---
+
+## 外部关联
+
+| 文档 | 位置 | 说明 |
+|------|------|------|
+| 概念草案 | [../concept.md](../concept.md) | 已冻结，只读参考 |
+| 原型路线图 | [../../plans/prototype-roadmap.md](../../plans/prototype-roadmap.md) | v0.1–v0.4 版本规划 |
+| 技术可行性评估 | [../../technical/feasibility-assessment.md](../../technical/feasibility-assessment.md) | 10 个系统的技术评估 |
+| 程序设计方案 | [../../technical/](../../technical/) | v0.1 程序设计文档 |
@@ -0,0 +1,310 @@
+# 关卡设计工作流：策划文档规范 + 程序白模搭建
+
+> 本文档定义 ChildHood 项目中策划如何产出关卡执行案、程序如何基于关卡执行案和 BlockingStarterPack 资产搭建白模关卡。是策划和程序两个角色之间的交接桥梁。
+
+---
+
+## 一、总览
+
+### 1.1 两个文档，两个角色
+
+| 文档 | 产出角色 | 性质 | 用途 |
+|------|---------|------|------|
+| 场景设计案 `scene-vXX-<name>.md` | 策划 | 氛围愿景 | 定义场景的感觉、叙事意图、时代元素 |
+| 关卡执行案 `level-vXX-<name>-execution.md` | 策划 | 空间精度搭建指南 | 坐标、尺寸、BSP 资产映射、交互/收集品位置 |
+
+**关系**：场景设计案描述"这里应该是什么感觉"，关卡执行案描述"程序应该在什么位置放什么资产来实现这个感觉"。两者互补，不是替代。
+
+### 1.2 在 7 步流水线中的位置
+
+```
+① 设计案（含场景设计案）
+    ↓
+② 阶段路线图
+    ↓
+③ 执行案（系统执行案 + 关卡执行案）  ← 关卡执行案在此阶段产出
+    ↓ [PM 审查：执行案质量门]
+④ 程序设计
+    ↓ [PM 审查：程序设计质量门]
+⑤ 美术产出
+    ↓ [PM 审查：美术资产验收门]
+⑥ 程序实现（含白模搭建子任务 6a）  ← 白模搭建在此阶段执行
+    ↓ [PM 审查：程序实现验收门]
+⑦ 版本复盘
+```
+
+**v0.1 特殊情况**：由于 v0.1 的 ③执行案质量门已通过（三个系统执行案已批准），关卡执行案作为补充文档在 ④或 ⑥早期补充，PM 做轻量审查。
+
+**v0.2 及以后**：关卡执行案纳入标准 ③执行案阶段，与其他系统执行案一起接受完整质量门审查。
+
+---
+
+## 二、策划职责边界
+
+### 2.1 策划在关卡执行案中做什么
+
+- ✅ 定义区域坐标范围和尺寸（cm 单位）
+- ✅ 定义每个结构体和布景的位置、尺寸
+- ✅ 标记可交互物体和收集品的精确位置
+- ✅ 引用 BSP 资产**类别名**和组合方式（如 "Wall_400x300 × 2 叠加"）
+- ✅ 为每个区域指定标识色材质（如 `MI_DevRed`）
+- ✅ 定义交通流线和区域连接关系
+- ✅ 定义场景边界遮挡方式
+- ✅ 提供光照方向建议（建议值，可调）
+
+### 2.2 策划不做什么
+
+- ❌ 不写引擎组件名（Actor、Component、Blueprint、Widget 等）
+- ❌ 不写文件路径（如 `/Game/Content/BlockingStarterPack/...`）
+- ❌ 不写 Blueprint 类名或 C++ 类名
+- ❌ 不写精确的硬编码参数值（标注"建议值，可调"并附范围）
+- ❌ 不写代码或脚本
+
+### 2.3 BSP 资产建议的性质
+
+策划在关卡执行案中引用的 BSP 资产建议是**方向性指引**，不是硬性要求。程序有权根据实际资产尺寸和可用性做替代，但必须在搭建报告中记录偏差。
+
+---
+
+## 三、坐标体系：混合方式
+
+### 3.1 场景绝对坐标系
+
+- **原点**：场景西南角地平面
+- **X 轴**：向东为正
+- **Y 轴**：向北为正
+- **Z 轴**：向上为正
+- **单位**：cm（对应 UE5 中 1 uu = 1 cm）
+
+程序在 UE5 中将关卡原点设在场景西南角，所有绝对坐标直接对应 UE5 世界坐标。
+
+### 3.2 区域内偏移坐标系
+
+- 每个区域定义一个**区域原点**（该区域西南角在场景中的绝对坐标）
+- 区域内所有物件的坐标使用**相对于区域原点的偏移**
+- 偏移格式：(ΔX, ΔY, ΔZ)，ΔX 向东为正，ΔY 向北为正，ΔZ 向上为正
+
+### 3.3 为什么用混合坐标
+
+- **区域级绝对坐标**：让程序快速定位每个区域在大场景中的位置，便于地面铺设和边界搭建
+- **区域内相对偏移**：策划不需要在脑中做加法，每个区域内部的物件位置从 (0,0,0) 开始数即可。程序搭建时先在绝对坐标放置区域原点空 Actor，再按偏移量摆放内部物件
+
+---
+
+## 四、程序白模搭建工作流
+
+白模搭建是 **⑥程序实现** 的子任务（记为 6a），在系统代码实现（6b-6d）之前或并行执行。
+
+### 4.1 输入与输出
+
+**输入**：
+- `level-vXX-<name>-execution.md` — 关卡执行案（空间指南）
+- `scene-vXX-<name>.md` — 场景设计案（氛围参考）
+- `interaction-system-execution.md` — 交互物清单
+- `collection-system-execution.md` — 收集品清单
+- `<system>-tech.md` — 技术设计方案
+- `Content/BlockingStarterPack/` — BSP 资产
+
+**输出**：
+- `Content/Maps/LVL_<SceneName>V<XX>.umap` — 白模关卡文件
+- `docs/technical/level-vXX-build-report.md` — 搭建报告（偏差记录）
+
+### 4.2 搭建流程
+
+```
+Phase A: 准备              Phase B: 地面与边界        Phase C: 逐区域搭建
+  A1 阅读关卡执行案           B1 铺设地面               C1 结构体
+  A2 创建资产映射表           B2 放置边界遮挡物          C2 布景物
+  A3 创建关卡文件                                     C3 交互物
+                                                     C4 收集品
+
+Phase D: 光照              Phase E: 验证
+  D1 定向光/天空光           E1 角色比例检查
+  D2 路灯/局部光源            E2 流线通行检查
+```
+
+#### Phase A: 准备
+
+**A1 — 阅读关卡执行案**
+
+通读整个关卡执行案，重点关注：
+- 场景参数（总尺寸、角色身高/视角高度）
+- 区域坐标布局表和交通流线
+- 每个区域的结构体和布景清单
+- 交互物和收集品的位置
+
+**A2 — 创建资产映射表**
+
+在搭建报告或技术方案中，将策划的 BSP 资产建议映射到引擎中的实际资产路径：
+
+| 设计文档资产建议 | 实际 UE 资产路径 | 备注 |
+|----------------|-----------------|------|
+| Wall_400x300 | `BlockingStarterPack/Meshes/Architecture/Walls/SM_Wall_400x300` | 400×20×300 cm |
+| BedSingle | `BlockingStarterPack/Meshes/Bedroom/SM_BedSingle` | |
+| Primitives 组合 | `BlockingStarterPack/Meshes/Primitives/SM_Cube` | 按需缩放 |
+
+**A3 — 创建关卡文件**
+
+创建 `Content/Maps/LVL_<SceneName>V<XX>.umap`。设置：
+- World Settings：GameMode override 指向项目 GameMode
+- Player Start：放在区域 Z1（家）门口附近
+- 无需 World Partition 或 Level Streaming（80m×60m 单关卡足够）
+
+#### Phase B: 地面与边界
+
+**B1 — 铺设地面**
+
+使用 `SM_Floor_1000x1000` 平铺覆盖整个场景。按区域分配标识色材质。
+
+**B2 — 放置边界遮挡物**
+
+按关卡执行案第五章放置边界围墙/围挡。确保所有边界启用物理碰撞。
+
+#### Phase C: 逐区域搭建
+
+按区域编号顺序搭建（建议 Z1 → Z3 → Z2 → Z4 → Z5 → Z6 → Z7，先搭主路径再搭分支）。
+
+每个区域按以下顺序：
+1. **C1 结构体**：放置墙体、地板、门框、窗框等建筑构件
+2. **C2 布景物**：放置家具、装饰物等场景道具
+3. **C3 交互物**：在指定位置放置交互物 Actor（按技术方案配置）
+4. **C4 收集品**：在指定位置放置收集品 Actor（按技术方案配置）
+
+#### Phase D: 光照
+
+1. **定向光**：根据关卡执行案光照建议放置 Directional Light
+2. **天空光**：Sky Light 提供环境补光
+3. **路灯/局部光源**：在全局物件清单中标记了光源的位置放置点光源
+
+#### Phase E: 验证
+
+**E1 — 角色比例检查**：
+
+以主角（身高 ~120cm）视角验证：
+- [ ] 所有门洞可通过（最低门洞高度 > 180cm）
+- [ ] 室内摄像机不穿墙/天花板
+- [ ] 窗台高度合理（主角能看出去或够不到）
+- [ ] 桌面/柜台高度与主角身高协调
+
+**E2 — 流线通行检查**：
+
+沿主流线行走验证：
+- [ ] 主要路径无死胡同（除非设计如此）
+- [ ] 区域过渡自然、方向感清晰
+- [ ] 步行距离合理（从家到最远点不超过 1 分钟游戏内步行）
+- [ ] 视线引导合理（玩家知道该往哪走）
+
+### 4.3 Actor 命名规范
+
+所有关卡内 Actor 遵循统一命名：
+
+```
+LVL_<ZoneID>_<Category>_<Description>
+
+ZoneID:   Z1-Z7
+Category: STR(结构体) | PROP(布景) | INTR(交互物) | COLL(收集品) | BND(边界) | LGT(光源)
+```
+
+示例：
+- `LVL_Z1_STR_SouthWall` — Z1 家的南墙
+- `LVL_Z1_PROP_OldBicycle` — Z1 家的旧自行车
+- `LVL_Z1_INTR_01_Fridge` — Z1 第 1 号交互物（冰箱）
+- `LVL_Z1_COLL_10_CatEyeMarble` — Z1 第 10 号收集品（猫眼弹珠）
+- `LVL_Z3_BND_EastBarricade` — Z3 街道东段施工围挡
+- `LVL_Z3_LGT_StreetLight_01` — Z3 第 1 盏路灯
+
+### 4.4 Outliner 文件夹结构
+
+```
+LVL_<SceneName>V<XX>/
+  Z1_<区域名>/
+    Structure/
+    Props/
+    Interactables/
+    Collectibles/
+  Z2_<区域名>/
+    ...
+  Zn_<区域名>/
+    ...
+  Global/
+    Boundaries/
+    Lighting/
+    PlayerStart/
+```
+
+### 4.5 搭建报告
+
+搭建完成后，产出 `docs/technical/level-vXX-build-report.md`，包含：
+
+| 章节 | 内容 |
+|------|------|
+| 搭建概要 | 总 Actor 数、各类别数量、实际关卡尺寸 |
+| 逐区域对照 | 文档要求 vs 实际搭建，标注偏差 |
+| 资产替代清单 | 文档建议资产 vs 实际使用资产，附原因 |
+| 缩放记录 | 使用了非 1:1 缩放的 Actor |
+| 未实现项 | 跳过或占位的项目及原因 |
+| 比例验证结果 | E1/E2 检查清单的实际结果 |
+
+**发布要求**：报告内容必须同时：
+1. 写入本地文件 `docs/technical/level-vXX-build-report.md`
+2. **以评论形式发布到对应任务 Issue**（与本地文件内容一致，供 PM 和策划直接在 Issue 中查看）
+
+搭建报告在 ⑦版本复盘时作为偏差分析的输入。
+
+---
+
+## 五、PM 关卡文档质量门检查项
+
+以下检查项补充到标准执行案质量门中，仅在审查关卡执行案时使用。
+
+### 5.1 关卡资产存在验证
+
+关卡执行案的质量门**仅做资产存在验证**——确认策划引用的 BSP 资产在 `Content/BlockingStarterPack/` 中实际存在：
+
+- [ ] 关卡执行案中引用的每个 BSP 资产类别是否在 BlockingStarterPack 中存在？
+- [ ] 标记为"Primitives 组合"的替代方案是否合理（Cube/Cylinder/Sphere 等）？
+- [ ] 标识色材质引用是否在 14 种可用材质范围内？
+
+### 5.2 搭建异常上报
+
+关卡执行案的空间精度、比例、跨文档一致性等维度的准确性，由**程序在白模搭建过程中验证**（Phase E 比例检查和流线检查）。PM 不在质量门阶段检查这些维度。
+
+**流程**：
+1. 程序在白模搭建 Issue 评论中发布搭建报告，包含偏差和异常
+2. PM 阅读搭建报告，如果发现程序汇报了异常（如尺寸偏差、资产无法匹配、比例问题、交互物位置冲突等），PM 将异常汇总并**汇报给用户确认**
+3. 用户决定是否需要策划修正关卡执行案，或接受当前偏差
+4. PM 不自行判断关卡空间精度的通过/不通过
+
+---
+
+## 六、特殊考虑
+
+### 6.1 儿童主角比例
+
+ChildHood 的主角是 ~120cm 身高的儿童，不是标准成人（~180cm）。这影响：
+
+- **门洞高度**：BSP 门框为成人设计（~200-300cm），儿童通过没有问题，但需要注意摄像机高度
+- **摄像机视角**：~100cm 高度，比标准第三人称低。2.5m 围墙在成人视角可以看过去，在儿童视角会感觉更高更封闭
+- **家具比例**：标准 BSP 家具（桌高 ~75cm、床高 ~50cm）对儿童视角是合理的
+- **街道宽度**：5m 宽的街道对儿童感觉宽敞但不空旷
+
+### 6.2 中式城郊场景的资产缺口
+
+BlockingStarterPack 以西式/现代城市场景为主。以下千禧年城郊物件没有精确匹配：
+
+- 小卖部招牌/柜台 → Primitives 组合 + 标识色材质
+- 公用电话亭 → Primitives 组合
+- 红砖墙 → Wall + MI_DevRed
+- 绿色铁门 → RotativeDoor + MI_DevGreen
+- 晾衣杆 → Beam + Cylinder 支撑
+- 水泥路面裂缝 → Floor + Decal 贴花
+
+完整替代方案参见 `.claude/refs/blockout-asset-reference.md` 第十五节。
+
+### 6.3 单关卡场景
+
+v0.1 场景为 80m×60m，不需要 World Partition、Level Streaming 或 Data Layer。整个场景在一个 `.umap` 文件中加载。后续版本扩展到 150m×120m 时可能需要评估是否使用 Data Layer 或 Sub-level。
+
+### 6.4 单人开发节奏
+
+单人开发者切换策划和程序角色时，关卡执行案就是**交接文档**。策划会话中产出执行案，程序会话中按执行案搭建白模。搭建报告是**反向交接**——记录实际搭建中的偏差，供策划下次更新执行案。