diff --git a/.claude/agents/game-designer.md b/.claude/agents/game-designer.md index abcadd4..be445fe 100644 --- a/.claude/agents/game-designer.md +++ b/.claude/agents/game-designer.md @@ -64,6 +64,7 @@ GameConfig/ # 数值配置表 | 系统设计案 | `.md` | `interaction-system.md` | | 执行案 | `-execution.md` | `player-controller-execution.md` | | 场景设计 | `scene-v-.md` | `scene-v01-suburban.md` | +| 关卡执行案 | `level-v--execution.md` | `level-v01-suburban-execution.md` | | 配置表 | `.csv` 或 `.json` | `marble-params.csv` | --- @@ -341,6 +342,31 @@ GameConfig/ # 数值配置表 --- +## 关卡执行案 + +关卡执行案是场景设计案的**空间精度版本**——将氛围描述转化为带有坐标、尺寸和资产建议的结构化搭建指南。 + +### 产出时机 + +关卡执行案在 **③执行案阶段** 产出，与系统执行案同步。产出前先阅读： +- 对应的场景设计案 `scene-v-.md`（氛围愿景） +- `.claude/refs/level-execution-template.md`（文档模板） +- `.claude/refs/blockout-asset-reference.md`（BSP 资产参考卡） + +### 关键规则 + +1. **混合坐标体系**：区域用场景绝对坐标（原点在西南角），区域内物件用相对偏移坐标 +2. **BSP 资产建议是方向性指引**：引用资产类别名和组合方式（如 "Wall_400x300 × 2"），不写文件路径 +3. **交叉引用**：交互物引用 `interaction-system-execution.md` 编号，收集品引用 `collection-system-execution.md` 编号 +4. **不越界**：不写引擎组件名、文件路径、Blueprint 类名 +5. **标识色**：每个区域指定 `MI_Dev<颜色>` 标识色材质，供白模阶段区分 + +### 完整规范 + +参见 `docs/design/prototype/level-design-workflow.md`。 + +--- + **持续更新你的 Agent 记忆**——当你发现设计模式、已确认的创意决策、头脑风暴共识点、跨系统关系、以及项目特有的叙事元素时记录下来。这会在多次对话中积累组织知识。写简洁的笔记——发现了什么、在哪里。 例如： diff --git a/.claude/agents/game-dev.md b/.claude/agents/game-dev.md index 881416a..9638e30 100644 --- a/.claude/agents/game-dev.md +++ b/.claude/agents/game-dev.md @@ -113,7 +113,40 @@ memory: project | UI | ... | ... | ... | ... | ``` -### 工作流 B：实现（步骤⑥） +### 工作流 B：白模搭建（步骤⑥子任务 6a） + +当版本开发涉及场景搭建时，白模搭建是 ⑥程序实现的首要子任务。 + +**输入**： +- `level-v--execution.md` — 关卡执行案（空间指南） +- `scene-v-.md` — 场景设计案（氛围参考） +- 系统执行案（交互物/收集品清单） +- `Content/BlockingStarterPack/` — BSP 资产 + +**输出**： +- `Content/Maps/LVL_V.umap` — 白模关卡文件 +- `docs/technical/level-v-build-report.md` — 搭建报告（偏差记录） +- **在对应任务 Issue 下以评论发布搭建报告**（包含偏差清单、资产替代、缩放记录、比例验证结果，使 PM 和策划能直接在 Issue 中查看） + +**搭建流程**： +1. **准备**：阅读关卡执行案 → 创建 BSP 资产映射表 → 创建关卡文件 +2. **地面与边界**：铺设地面 Floor → 放置边界围墙/围挡 +3. **逐区域搭建**：按结构体 → 布景 → 交互物 → 收集品顺序 +4. **光照**：定向光/天空光 → 路灯/局部光源 +5. **验证**：角色比例检查（门洞/摄像机/家具） → 流线通行检查 + +**Actor 命名规范**：`LVL___` +- Category: STR(结构体) | PROP(布景) | INTR(交互物) | COLL(收集品) | BND(边界) | LGT(光源) + +**Outliner 结构**：按区域分文件夹（Z1_家/Structure/、Z1_家/Props/、...），Global/ 放边界和光照。 + +**搭建报告**：逐区域对照文档要求记录偏差，包含资产替代清单、缩放记录、未实现项、比例验证结果。**报告必须同时**： +1. 写入 `docs/technical/level-v-build-report.md`（本地文件） +2. 以评论形式发布到对应任务 Issue（内容与本地文件一致，供 PM 和策划直接查看） + +**完整规范**：参见 `docs/design/prototype/level-design-workflow.md` 第四章。 + +### 工作流 C：代码实现（步骤⑥子任务 6b-6f） ``` 阅读技术方案 → 阅读美术资产清单 → 编写代码 → 集成美术资产 → 验证功能 → 汇报结果 diff --git a/.claude/agents/game-pm.md b/.claude/agents/game-pm.md index 332eb26..02b3942 100644 --- a/.claude/agents/game-pm.md +++ b/.claude/agents/game-pm.md @@ -90,6 +90,11 @@ memory: project - **系统间关联**：与其他系统的依赖关系是否记录？ - **技术越界检查**：策划是否误入技术实现细节？参数应标注"建议值，可调" +**关卡执行案附加检查**（仅当执行案包含关卡文档时）： +- **关卡资产存在验证**：关卡执行案中引用的 BSP 资产是否在 `Content/BlockingStarterPack/` 中实际存在？逐项验证可行性 + +> 关卡执行案的质量门**仅做资产存在验证**。空间精度、比例、跨文档一致性等维度的准确性由程序在白模搭建过程中验证——如果程序在 Issue 中汇报了搭建异常（尺寸偏差、资产无法匹配、比例问题等），PM 将异常汇总并汇报给用户确认，不自行判断通过或不通过。 + ### 质量门 2：程序设计质量门（④→⑤） 检查维度： @@ -242,6 +247,12 @@ memory: project - 单个代码任务应在一次工作会话中可完成（约 1-3 小时有效工作时间） - 如果一个系统的实现需要跨越多天，必须按程序设计文档的建议拆分 +**③执行案任务拆分**： +- PM 为**每一份系统执行案**创建独立的任务 Issue（如 `D-001 交互系统执行案`、`D-002 收集系统执行案`） +- 当版本涉及场景搭建时，为**关卡执行案**单独创建一个任务 Issue（如 `D-005 v0.1 城郊小街关卡执行案`） +- 不将多份系统执行案或关卡执行案合并为同一个任务 +- 关卡执行案任务与系统执行案任务**并行存在**，策划可按任意顺序完成，全部通过质量门后才进入 ④ + --- ## 9. 文档标准 diff --git a/.claude/refs/blockout-asset-reference.md b/.claude/refs/blockout-asset-reference.md new file mode 100644 index 0000000..16343b7 --- /dev/null +++ b/.claude/refs/blockout-asset-reference.md @@ -0,0 +1,404 @@ +# BlockingStarterPack 资产参考卡 + +> 供策划产出关卡执行案时引用 BSP 资产。策划只需引用资产**类别名和近似尺寸**（如 `Wall_400x300`），不需要写文件路径。程序负责最终映射到引擎中的具体资产。 +> +> 所有尺寸以厘米（cm）为单位。资产路径前缀：`Content/BlockingStarterPack/Meshes/` + +--- + +## 一、建筑模块（Architecture） + +### 1.1 墙体（Walls） + +**命名规律**：`SM_Wall_<宽>x<高>` — 宽度/高度均为 cm 单位 + +| 资产名 | 尺寸（宽cm × 高cm） | 用途 | +|--------|-------------------|------| +| Wall_100x100 | 100 × 100 | 短墙、装饰墙段 | +| Wall_100x300 | 100 × 300 | 标准宽度墙面 | +| Wall_100x400 | 100 × 400 | 标准宽度高墙 | +| Wall_200x100 | 200 × 100 | 矮墙、半墙 | +| Wall_200x300 | 200 × 300 | **常用** — 标准墙面 | +| Wall_200x400 | 200 × 400 | 高墙面 | +| Wall_400x100 | 400 × 100 | 矮长墙 | +| Wall_400x300 | 400 × 300 | **常用** — 大片墙面 | +| Wall_400x400 | 400 × 400 | 大片高墙 | + +**含门洞的墙**：`SM_WallDoor_<宽>x<高>` + +| 资产名 | 尺寸 | 说明 | +|--------|------|------| +| WallDoor_200x300 | 200 × 300 | 单门洞墙 | +| WallDoor_200x400 | 200 × 400 | 单门洞高墙 | +| WallDoor_400x300 | 400 × 300 | 宽墙含单门洞 | +| WallDoor_400x400 | 400 × 400 | 宽墙含单门洞（高） | +| WallDoorDouble_400x300 | 400 × 300 | 宽墙含双门洞 | +| WallDoorDouble_400x400 | 400 × 400 | 宽墙含双门洞（高） | +| WallDoorGarage_400x300 | 400 × 300 | 车库门墙 | +| WallDoorGarage_400x400 | 400 × 400 | 车库门墙（高） | + +**含窗户的墙**：`SM_WallWindow_<宽>x<高>` + +| 资产名 | 尺寸 | 说明 | +|--------|------|------| +| WallWindow_200x300 | 200 × 300 | 单窗墙 | +| WallWindow_200x400 | 200 × 400 | 单窗墙（高） | +| WallWindow_400x300 | 400 × 300 | 宽窗墙 | +| WallWindow_400x400 | 400 × 400 | 宽窗墙（高） | +| WallWindowDouble_400x300 | 400 × 300 | 双窗墙 | +| WallWindowDouble_400x400 | 400 × 400 | 双窗墙（高） | +| WallWindowSmall_200x300 | 200 × 300 | 小窗墙 | +| WallWindowSmall_200x400 | 200 × 400 | 小窗墙（高） | + +**圆角墙**：`SM_WallRoundedCorner_<宽>x<高>_<角度>d`（角度 45d 或 90d） + +### 1.2 地板（Floors） + +**命名规律**：`SM_Floor_<宽>x<深>` + +| 资产名 | 尺寸（cm） | 用途 | +|--------|-----------|------| +| Floor_100x100 | 100 × 100 | 小面积填充 | +| Floor_100x200 | 100 × 200 | 窄条地面 | +| Floor_100x300 | 100 × 300 | 走廊地面 | +| Floor_100x400 | 100 × 400 | 长走廊 | +| Floor_200x150 | 200 × 150 | 不规则填充 | +| Floor_200x200 | 200 × 200 | 中等面积 | +| Floor_200x300 | 200 × 300 | **常用** | +| Floor_200x400 | 200 × 400 | **常用** | +| Floor_300x300 | 300 × 300 | 大面积 | +| Floor_300x400 | 300 × 400 | 大面积 | +| Floor_400x400 | 400 × 400 | 大面积 | +| Floor_1000x1000 | 1000 × 1000 | **超大地砖** — 快速铺设大范围地面 | + +另有：FloorCorner（转角）、FloorRounded（圆角）、FloorTriangle（三角）、Floor 含 Trap（带活门开口） + +### 1.3 门（Doors） + +| 资产名 | 说明 | +|--------|------| +| DoorFrame | 单门框 | +| DoorFrameDouble | 双门框 | +| DoorFrameGarage | 车库门框 | +| RotativeDoor_01 / 02 / 03 | 旋转门（三种样式） | +| LateralDoor | 推拉门 | +| LateralDoorFrame_150 / 300 | 推拉门框（150cm/300cm 宽） | +| FakeDoor / FakeDoorDouble | 假门（装饰，不可开） | +| GarageDoor_01 / 02 | 车库门（关闭） | +| GarageDoorOpen_01 / 02 | 车库门（打开） | + +### 1.4 窗户（Windows） + +| 资产名 | 说明 | +|--------|------| +| WindowsFrame / WindowsGlass | 单窗框/玻璃 | +| WindowsFrameDouble / WindowsGlassDouble | 双窗 | +| WindowsFrameUp / WindowsGlassUp | 上开窗 | +| FakeWindowsFrame / FakeWindowsFrameDouble / FakeWindowsFrameUp | 假窗（装饰） | + +### 1.5 楼梯（Stairs） + +| 资产名 | 说明 | +|--------|------| +| Stair_100 / Stair_200 | 直梯（100cm/200cm 高） | +| StairPlane_100 / StairPlane_200 | 楼梯面（无侧板） | +| StairRounded_300_45d / 90d | 圆弧梯 | + +### 1.6 栏杆/围栏（Barriers） + +**命名规律**：`SM_Barrier<类型>_<长度>cm` + +- Barrier01/02/03 — 三种样式（直线段，50/100/200/500cm） +- BarrierAngle — 角度栏杆 +- BarrierBeam — 横梁栏杆 +- BarrierRounded01/02_45/90 — 圆弧栏杆（200-800cm） +- BarrierStair — 楼梯栏杆 +- BarrierWall_200/400/600 — 实墙式栏杆（**常用作围墙**） +- BarrierWallRoundedCorner — 实墙式圆角 + +**独立围栏**： +- Fence_Normal_100/200/300/400 — 普通围栏 +- Fence_Small_100/200/300/400 — 矮围栏 + +### 1.7 飘窗（BayWindows） + +`SM_BayWindow<类型>_<宽>x<高>` — 宽度 100/200/400，高度 300/400 +- BayWindow — 纯飘窗 +- BayWindowDoor — 带门的飘窗 +- BayWindowDoorDouble — 带双门的飘窗 + +### 1.8 横梁（Beams） + +| 资产名 | 说明 | +|--------|------| +| Beam_300 / Beam_400 | 直梁（300/400cm） | +| RoundedBeam_300 / RoundedBeam_400 | 圆弧梁 | +| Beam_400_45d / RoundedBeam_400_45d | 45 度转角梁 | + +--- + +## 二、建筑整体（Buildings） + +### 2.1 小型建筑（SmallBuildings） + +| 资产名 | 说明 | 建议用途 | +|--------|------|---------| +| House_01 | 小房屋 A | 家、小卖部等单层建筑 | +| House_02 | 小房屋 B | 居民平房 | +| House_03 | 小房屋 C | 仓库/杂物间 | +| House_04 | 小房屋 D | 另一种风格平房 | + +### 2.2 大型建筑（BigBuildings） + +| 资产名 | 说明 | 建议用途 | +|--------|------|---------| +| Building_01 | 大楼 A | 老居民楼（5-6层） | +| Building_02 | 大楼 B | 办公楼/商场 | +| Building_03 | 大楼 C | 工业建筑 | +| Building_04 | 大楼 D | 另一种风格大楼 | + +--- + +## 三、家具（Furnitures） + +| 资产名 | 说明 | 尺寸参考 | +|--------|------|---------| +| SimpleTable_01 | 简易桌 | ~120×60cm | +| SimpleTable_02 | 简易桌 B | ~100×60cm | +| DinnerTable_01 / 02 / 03 | 餐桌（三种） | ~120-150cm | +| DiningChair_01 | 餐椅 | ~45cm 座高 | +| OfficeChair_01 | 办公椅 | 带轮 | +| Armchair_01 | 扶手椅 | 休闲用 | +| Laptop | 笔记本电脑 | 小型桌面物件 | +| Monitor_01 | 显示器 | ~50cm 宽 | +| Keyboard | 键盘 | 桌面物件 | +| Broom | 扫帚 | 靠墙放 | +| Cushion | 坐垫 | 小型 | + +--- + +## 四、卧室（Bedroom） + +| 资产名 | 说明 | +|--------|------| +| BedSingle | 单人床（含被褥） | +| BedSingle_Empty | 单人床（空床） | +| BedDouble | 双人床（含被褥） | +| BedDouble_Empty | 双人床（空床） | + +--- + +## 五、卫浴（Bathroom） + +| 资产名 | 说明 | +|--------|------| +| Toilet_01 | 马桶 | +| ToiletClosed_01 | 马桶（盖关） | +| Urinal_01 | 小便池 | +| ToiletPaper_01 / 02 | 卫生纸 | + +--- + +## 六、装饰小物件（Decorations） + +| 资产名 | 说明 | 用途 | +|--------|------|------| +| Bottle_01 / 02 / 03 | 饮料瓶/酒瓶 | 小卖部、街头散落 | +| Books_01 / BooksOpen_01 | 书本 | 书桌、书架 | +| Can_01 | 易拉罐 | 散落物、垃圾桶内 | +| Flask_01 | 烧瓶 | 实验室场景 | +| GlassFlask_01-04 | 玻璃瓶（四种） | 装饰、收集 | +| Mug_01 | 马克杯 | 桌面物件 | +| Plate_01 | 盘子 | 餐桌 | +| WaterGlass_01 | 水杯 | 桌面物件 | +| Bucket_01 | 水桶 | 院子、巷子 | +| Padlock_01 / Padlock_Open / Padlock_Break | 挂锁（三种状态） | 门、箱子 | +| SimplePlug_01 | 插头 | 墙面细节 | +| SimpleSwitch_01 | 开关 | 墙面细节 | +| SpikedBall_01 / 02 | 铁蒺藜 | 路障 | + +--- + +## 七、载具（Vehicles） + +| 资产名 | 说明 | +|--------|------| +| Car01 / Car02 | 轿车（两种） | +| Truck01 / Truck02 | 卡车（两种） | +| TruckWithoutTrailer | 卡车（无挂车） | +| HoodTruckWithoutTrailer | 皮卡 | +| Bus_Big | 大巴 | +| Boat_01 / Boat_02 | 船（两种） | +| Plane_01 | 飞机 | +| Metro_01 | 地铁车厢 | +| Trailer_01 / 02 / 03 | 挂车（三种） | +| SimpleWheel / SimpleRims | 车轮/轮毂 | +| TruckWheel / TruckRims | 卡车轮 | +| SimpleTire | 轮胎 | +| SmallLocomotive | 小型机车 | +| SmallWagon_Normal / SmallWagon_Large | 小型车厢 | +| SmallRail_200-1000 | 小型铁轨 | +| SmallRailTurn_45d / 90d | 小型铁轨转辙 | + +--- + +## 八、道路设施（Roads） + +| 资产名 | 说明 | +|--------|------| +| BarricadeBlocks_100 / 200 | 水马路障 | +| Barricade_200 / 300 / 400 | 栏式路障 | +| BarricadeWall_100 | 矮路障墙 | +| RoadCone_Big / Normal / Small | 锥桶（三种大小） | +| SpeedBump_100/200/400/600 | 减速带 | +| SpeedBumpWithEnds_200/400/600 | 减速带（含端头） | +| SpeedBumpEnd | 减速带端头 | +| MetalPost_01 | 金属路桩 | +| RoadLamp_01 | 路灯 | +| RoadLight | 道路照明灯 | + +--- + +## 九、工业物件（Industrials） + +| 资产名 | 说明 | 用途 | +|--------|------|------| +| Barrel | 铁桶 | 巷子、工地散落 | +| ExplosiveBarrel | 爆炸桶（红色） | 游戏交互物 | +| WoodenBox_Small / Normal / Large | 木箱（三种大小） | 杂物堆、仓库 | +| WoodenCrate_01 | 木条箱 | 搬运箱 | +| WoodenPallet_01 / 02 | 木托盘 | 地面垫板 | +| Container_Normal / Large | 集装箱 | 工地 | +| ContainerClosed_Normal / Large | 集装箱（关闭） | 工地 | +| ContainerDoor_Left / Right | 集装箱门 | 工地 | +| ContainerShip_01 / ContainerShipEmpty_01 | 船运集装箱 | 港口场景 | +| BigDumpster | 大垃圾箱 | 街道 | +| Fence_Normal_100-400 / Fence_Small_100-400 | 围栏 | 场地分隔 | +| Radiator | 散热器 | 室内墙面 | + +--- + +## 十、垃圾（Trashs） + +| 资产名 | 说明 | +|--------|------| +| TrashCans_01 | 垃圾桶（盖着） | +| TrashCansOpen_01 | 垃圾桶（打开） | +| TrashCansLid_01 | 垃圾桶盖（单独） | + +--- + +## 十一、灯光（Lights） + +| 资产名 | 说明 | +|--------|------| +| CeilingLight01 / 02a / 02b / 03a / 03b | 吸顶灯（多种） | +| CeilingLightBulb / CeilingLightBulbBreak | 灯泡（正常/损坏） | +| CeilingLightFlat02a / 02b | 平板灯 | +| CeilingLightRotaryWarning | 旋转警示灯 | +| SpotLight / SpotLight_Support | 射灯 | +| FlamingTorch / FlamingTorchWithSupport / FlamingTorch_Support | 火把 | +| FlashLight | 手电筒 | +| RoadLamp_01 | 路灯 | +| RoadLight | 道路灯 | + +--- + +## 十二、基础体（Primitives） + +| 资产名 | 说明 | 用途 | +|--------|------|------| +| Cube | 立方体 | 万能替代，可缩放 | +| Cylinder | 圆柱体 | 柱子、管道 | +| Sphere | 球体 | 装饰 | +| Cone | 圆锥体 | 装饰 | +| Ramp | 斜坡 | 地形过渡 | +| QuarterPipe | 四分之一管 | 装饰/地形 | +| QuarterCylinder | 四分之一圆柱 | 角落装饰 | +| CirclePlatform | 圆形平台 | 地面标记 | +| SquarePlatform | 方形平台 | 地面标记 | +| SphereOctant / SphereOctantInvert | 球体切片 | 装饰 | + +**弯曲基础体**（CylinderBend/RectangleBend/RectangleAngle，各种半径 150-450cm） + +--- + +## 十三、其他（Extra） + +| 资产名 | 说明 | +|--------|------| +| Tree_01 | 树木（唯一的植被资产） | +| Ladder_01_200 / Ladder_01_Unit | 梯子（两种） | +| Ladder_02_200 / Ladder_02_Unit | 梯子 B（两种） | +| SnowMan_01 | 雪人 | +| Campfire | 营火 | +| HumanMesh_01 / 02 | 人体参考网格 | +| HumanCage / HumanCageWithFloor | 人体碰撞参考框 | +| ArrowBody / ArrowHead / ArrowBack | 箭头组件 | +| CameraPose_01-04 | 摄像机参考姿态 | +| DisplayPanels_50x50 到 400x200 | 展示面板（8种尺寸） | + +--- + +## 十四、标识色材质速查 + +> 用于白模阶段区分不同区域/物体类型。命名规律：`MI_Dev<颜色>` 或 `MI_Dev<颜色>_TPLA/TPWA`（三平面变体）。 + +| 材质名 | 颜色 | 推荐用途 | +|--------|------|---------| +| MI_DevRed | 红色 | 危险区域、交互热点、围墙 | +| MI_DevBlue | 蓝色 | 水域、天空相关 | +| MI_DevGreen | 绿色 | 植被、草地、可通行 | +| MI_DevBrown | 棕色 | 泥土、木质结构 | +| MI_DevGray | 灰色 | 水泥、混凝土、道路 | +| MI_DevWhite | 白色 | 墙壁、室内 | +| MI_DevBlack | 黑色 | 阴影区域、遮挡 | +| MI_DevYellow | 黄色 | 警示、收集品标记 | +| MI_DevOrange | 橙色 | 施工区域、路障 | +| MI_DevPink | 粉色 | 角色/NPC 相关 | +| MI_DevPurple | 紫色 | 特殊/隐藏区域 | +| MI_DevSkyBlue | 天蓝 | 水面、天空 | +| MI_DevFoliage | 草绿 | 植物、树木 | +| MI_LightGreen | 浅绿 | 草地细节 | + +**特殊材质**： +- `MI_DevGrid` — 带网格的灰色材质，用于地面 +- `M_DevMirror` — 镜面材质 +- `M_FullyBlack` — 纯黑材质，用于遮挡/剪影 +- `MI_DevGlassBlue/Green/Red/White` — 透明玻璃材质 +- `MI_DevLight_*` — 自发光材质（绿/蓝/橙/白/黄/红/天蓝） +- `MI_StainDecalColor*` — 污渍贴花（黑/蓝/绿/红/天蓝/黄） + +--- + +## 十五、中式城郊场景替代方案速查 + +> 千禧年城郊结合区的许多物件在 BSP 中没有精确匹配，下表提供替代策略。 + +| 场景物件 | BSP 替代方案 | 标识色建议 | +|---------|-------------|-----------| +| 红砖围墙 | Wall_400x300 组合 + MI_DevRed | 红 | +| 绿色铁门/木门 | RotativeDoor_01 + MI_DevGreen | 绿 | +| 小卖部招牌 | Cube 缩放为薄长条 + MI_DevBlue/Orange | 蓝/橙 | +| 卷帘门 | GarageDoor_01 + MI_DevGray | 灰 | +| 玻璃柜台 | Cube 缩放为扁长方体 + MI_DevGlassWhite | 透明白 | +| 老式冰柜 | Container_Normal 缩小 + MI_DevWhite | 白 | +| 金属货架 | Fence_Small 排列 + MI_DevGray | 灰 | +| 公用电话亭 | Cube+Cylinder 组合 | 灰 | +| 电线杆 | Cylinder 高缩放 + MI_DevGray | 灰 | +| 晾衣杆 | Beam_300 + Cylinder 支撑 + MI_DevWhite | 白 | +| 铁栏杆窗户 | WallWindow + Beam 细条前置 | 灰 | +| 水泥路裂缝 | Floor + MI_DevGray + Decal 贴花 | 灰 | +| 积水坑 | Floor 嵌入地面 + MI_DevGlassBlue | 天蓝 | +| 水塘水面 | Floor_1000x1000 + MI_DevSkyBlue/GlassBlue | 天蓝 | +| 芦苇/杂草 | 多个小 Cylinder 不同角度 + MI_DevFoliage | 草绿 | +| 施工围挡 | BarricadeWall_200/400/600 + MI_DevBlue | 蓝 | +| 垃圾桶 | TrashCans_01 + MI_DevGreen | 绿 | +| 老式自行车 | Car01 缩小至 ~50% 或 Primitives 组合 | 黑 | +| 弹珠/小物件 | Sphere 缩小至 ~2cm | 彩色 | +| 老式冰箱 | Barrel 竖放或 Cube + MI_DevWhite | 白 | +| 大脑袋电视 | Monitor_01 + MI_DevGray | 灰 | +| 水塔/工业设备 | Cylinder + CylinderBend 组合 | 灰/棕 | +| 平房屋顶 | Floor 覆盖 + MI_DevBrown | 棕 | +| 台阶 | Stair_100 或 Ramp | 灰 | +| 围墙门洞 | WallDoor_200x300 + RotativeDoor | 红 | diff --git a/.claude/refs/development-workflow.md b/.claude/refs/development-workflow.md index 32b53be..e31eeb2 100644 --- a/.claude/refs/development-workflow.md +++ b/.claude/refs/development-workflow.md @@ -434,6 +434,14 @@ docs/design/production/ - 每个系统一份执行案，放在 `docs/design/<阶段>/` 目录下 - 文件命名：`<系统名>-execution.md`（如 `player-controller-execution.md`） - 不按版本分文件，通过迭代记录表头追踪变更 +- **关卡执行案**（如有场景搭建需求）：文件命名 `level-v--execution.md`，产出模板参见 `.claude/refs/level-execution-template.md` + +**关卡执行案**： +- 当版本开发涉及场景搭建时，策划额外产出一份关卡执行案 +- 关卡执行案将场景设计案的氛围描述转化为空间精度搭建指南（坐标、尺寸、BSP 资产映射） +- 使用混合坐标体系：区域用场景绝对坐标，区域内物件用相对偏移坐标 +- 交互物和收集品的位置标注必须与交互系统/收集系统执行案交叉引用 +- 完整规范参见 `docs/design/prototype/level-design-workflow.md` --- @@ -451,6 +459,10 @@ docs/design/production/ 4. **系统间关联**：与其他系统的关联和影响是否说明？ 5. **技术越界检查**：是否误入了技术细节？精确参数值是否标注为"建议值，可调"？ +**关卡执行案附加检查**（仅当审查对象包含关卡执行案时）： +- **关卡资产存在验证**：关卡执行案中引用的 BSP 资产是否在 `Content/BlockingStarterPack/` 中实际存在？标识色材质是否在可用范围内？ +- 关卡执行案的质量门**仅做资产存在验证**。空间精度、比例、跨文档一致性等维度由程序在白模搭建过程中验证——如果程序在 Issue 中汇报搭建异常，PM 汇总异常并汇报给用户确认，不自行判断通过/不通过。 + **判定**： - **通过** → 进入 ④ 程序设计 - **不通过** → 退回策划修改，列出具体问题清单 @@ -550,6 +562,16 @@ docs/design/production/ **前置条件**：程序设计（④）已就绪且 PM 审查通过，美术资产（⑤）已就位且 PM 验收通过。 +**白模搭建子任务（6a）**： +当版本开发涉及场景搭建时，⑥的第一个子任务是白模关卡搭建： +- 读取关卡执行案 `level-v--execution.md` 和场景设计案 +- 使用 `Content/BlockingStarterPack/` 资产在 UE5 编辑器中搭建白模关卡 +- 按区域分文件夹组织 Actor（命名规范：`LVL___`） +- 完成比例验证（角色可通过门洞、摄像机不穿墙、流线通行） +- 产出搭建报告 `docs/technical/level-v-build-report.md` 记录偏差 +- **搭建报告必须以评论形式发布到对应任务 Issue**（与本地文件内容一致） +- 完整搭建流程参见 `docs/design/prototype/level-design-workflow.md` 第四章 + **阶段差异**： | 维度 | 原型阶段 | 批量生产阶段 | diff --git a/.claude/refs/level-execution-template.md b/.claude/refs/level-execution-template.md new file mode 100644 index 0000000..102efea --- /dev/null +++ b/.claude/refs/level-execution-template.md @@ -0,0 +1,245 @@ +# 关卡执行案模板 + +> 本模板供策划产出关卡执行案时使用。关卡执行案是场景设计案的"空间精度版本"——将氛围描述转化为带有坐标、尺寸和资产建议的结构化搭建指南，供程序在 UE5 编辑器中搭建白模。 +> +> 文件命名：`level-v--execution.md`（如 `level-v01-suburban-execution.md`） +> 存放位置：`docs/design/<阶段>/`（与其他执行案同目录） + +--- + +```markdown +# v<版本号> 关卡执行案 — <场景名> + +## 迭代记录 + +| 迭代版本 | 修改日期 | 状态 | 说明 | +|----------|----------|------|------| +| v<版本号> | YYYY-MM-DD | 📝 设计中 | 初始版本 | + +> 状态标记：📝 设计中 | 🔄 开发中 | ✅ 已同步 + +--- + +## 一、场景参数 + +| 参数 | 值 | 说明 | +|------|-----|------| +| 场景总尺寸 | | UE5 单位（1 uu = 1 cm） | +| 地面高度基准 | | 统一地面平面高度（UE5 Z 轴，单位 cm） | +| 主角身高 | | 影响门高、窗台高、摄像机高度 | +| 主角视角高度 | | 摄像机距地面（SpringArm 高度参考） | +| 时间设定 | | 影响光照方向和色温 | +| 坐标系原点 | 场景西南角地平面 | X 轴向东（+），Y 轴向北（+），Z 轴向上（+） | + +**坐标系说明**： +- 区域级定位使用**场景绝对坐标**（原点在西南角，单位 cm） +- 区域内物件使用**相对于该区域西南角的偏移坐标**（0,0 为区域西南角） +- 偏移格式：(ΔX, ΔY, ΔZ)，ΔX 向东为正，ΔY 向北为正，ΔZ 向上为正 + +--- + +## 二、区域坐标布局 + +### 2.1 区域总览表 + +| 区域编号 | 区域名称 | 绝对坐标范围 (X,Y) | 尺寸 (宽x深) | 地面材质建议 | 标识色 | +|---------|---------|-------------------|-------------|-------------|--------| +| Z1 | | (X1,Y1)-(X2,Y2) | Wm × Dm | | | +| Z2 | | | | | | +| ... | | | | | | +| Zn | | | | | | + +> 标识色使用 BSP 材质名（参见 `blockout-asset-reference.md`），程序用对应材质标识区域。 + +### 2.2 交通流线 + +| 流线路径 | 宽度 | 说明 | +|---------|------|------| +| | | | +| | | | +| | | | + +### 2.3 ASCII 总览图 + + + +``` + Y↑ (北) + │ + ┌─────┤ + │ Zn │ + └──┬──┘ + │ + ┌──────┴──────┐ + │ Z... │ + └──┬──────┬───┘ + │ │ + ┌──────┴──┐ ┌─┴───────┐ + ─────┤ Z1 │ │ Z... ├───── + └─────────┘ └─────────┘ + ────────────────────────────────→ X (东) + (0,0) +``` + +--- + +## 三、逐区域搭建指南 + + + + + +### Z: <区域名称> + +**区域绝对原点**：(X, Y, Z) — 该区域西南角在场景中的绝对坐标 + +#### 3.x.1 区域参数 + +| 参数 | 值 | 说明 | +|------|-----|------| +| 地面高度 | | 相对场景地面基准 | +| 围墙/外墙高度 | | | +| 门洞宽度 | | | +| 门洞高度 | | | +| 室内净高 | | 如为室内区域 | +| 屋檐高度 | | | + +#### 3.x.2 结构体清单 + + + +| 编号 | 构件名称 | 尺寸 (宽x深x高, cm) | 相对原点偏移 (ΔX,ΔY,ΔZ) | BSP 资产建议 | 标识色 | +|------|---------|-------------------|----------------------|-------------|--------| +| Zx-S01 | | | (0,0,0) | | | +| Zx-S02 | | | | | | +| Zx-S03 | | | | | | +| ... | | | | | | + +**BSP 资产建议说明**： +- 填写 BSP 资产类别名和组合方式（如 "Wall_400x300 × 2 叠加"） +- 程序负责映射到引擎中的具体资产路径 +- 如无精确匹配，写"Primitives 组合"并注明替代意图 +- 参见 `.claude/refs/blockout-asset-reference.md` 中的替代方案 + +#### 3.x.3 布景物清单 + + + +| 编号 | 物件名称 | 尺寸 (约, cm) | 相对原点偏移 (ΔX,ΔY,ΔZ) | BSP 资产建议 | 说明 | +|------|---------|-------------|----------------------|-------------|------| +| Zx-P01 | | | (100,100,0) | | | +| Zx-P02 | | | | | | +| ... | | | | | | + +#### 3.x.4 可交互物体标记 + + + +| 交互编号 | 物件名称 | 交互类型 | 相对原点偏移 (ΔX,ΔY,ΔZ) | 触发半径 (cm) | 引用 | +|---------|---------|---------|----------------------|-------------|------| +| Zx-I01 | | | (200,400,10) | | interaction-system-execution #n | +| Zx-I02 | | | | | | +| ... | | | | | | + +> 交互类型参照交互系统执行案中的分类（观察/拾取/操作/对话等）。 +> "引用"列填写交互系统执行案中对应交互物的编号，确保跨文档一致。 + +#### 3.x.5 收集品标记 + + + +| 收集编号 | 物品名称 | 稀有度 | 相对原点偏移 (ΔX,ΔY,ΔZ) | 引用 | +|---------|---------|--------|----------------------|------| +| Zx-C01 | | | (500,200,0) | collection-system-execution #n | +| Zx-C02 | | | | | +| ... | | | | | | + +> 稀有度影响拾取物的视觉效果标识（普通=白色光，稀有=金色光），具体表现由收集系统技术方案定义。 + +--- + + + +--- + +## 四、全局物件清单 + + + +### 4.1 街道家具 + +| 编号 | 物件名称 | 数量 | 放置位置 (绝对坐标 X,Y,Z) | BSP 资产建议 | 说明 | +|------|---------|------|------------------------|-------------|------| +| G-01 | | | | | | +| G-02 | | | | | | +| ... | | | | | | + +### 4.2 环境物件 + +| 编号 | 物件名称 | 数量 | 放置位置 (绝对坐标 X,Y,Z) | BSP 资产建议 | 说明 | +|------|---------|------|------------------------|-------------|------| +| G-E01 | | | | | | +| G-E02 | | | | | | +| ... | | | | | | + +### 4.3 收集品位置汇总 + +| # | 物品名称 | 所在区域 | 绝对坐标 (X,Y,Z) | 稀有度 | 引用 | +|---|---------|---------|-----------------|--------|------| +| 1 | | | | | collection-system-execution #n | +| 2 | | | | | | +| ... | | | | | | + +--- + +## 五、场景边界与遮挡 + +| 边界段 | 位置范围 | 遮挡方式 | BSP 资产建议 | 标识色 | +|--------|---------|---------|-------------|--------| +| 西边界 | X=0 全线 | | | | +| 南边界 | Y=0 全线 | | | | +| 东边界 | X= | | | | +| 北边界 | Y= | | | | + +> 边界必须确保玩家无法走出场景范围。所有边界物体启用物理碰撞。 +> 自然边界（如水塘）通过不可通行水面实现，无需额外围墙。 + +--- + +## 六、光照建议（可选） + +| 光源类型 | 数量 | 位置/方向 | 参数建议 | 说明 | +|---------|------|---------|---------|------| +| 定向光 | 1 | | | 夏日午后主光源 | +| 天空光 | 1 | 全局 | | 环境补光 | +| 路灯 | N | 见全局物件清单 | | 点光源/聚光灯 | + +> 光照参数为建议值，可调。程序根据实际效果微调方向和强度。 +``` + +--- + +## 模板使用说明 + +### 策划填写要点 + +1. **先确定区域坐标布局**（第二章），确保所有区域在总尺寸内不重叠、流线合理 +2. **逐区域填写**（第三章），按"结构体 → 布景 → 交互物 → 收集品"的顺序 +3. **BSP 资产建议是方向性指引**：写资产类别名和组合方式即可（如 "Wall_400x300 × 2"），不需要写文件路径 +4. **尺寸以 cm 为单位**，对应 UE5 的 1 uu = 1 cm +5. **交叉引用**：交互物和收集品必须引用对应系统执行案中的编号，保持跨文档一致 + +### 不要填写的内容 + +- ❌ 引擎组件名（Actor、Component、Blueprint 等） +- ❌ 文件路径（如 `/Game/Content/...`） +- ❌ Blueprint 类名 +- ❌ 精确的硬编码参数值（标注"建议值，可调"并附范围） +- ❌ 代码或脚本 + +### 与场景设计案的关系 + +- 场景设计案（`scene-vXX-.md`）= **氛围愿景** — 描述感觉、氛围、叙事意图 +- 关卡执行案 = **空间精度搭建指南** — 坐标、尺寸、资产映射 +- 两者是互补关系，不是替代关系。程序搭建时两个文档都需要参考。 diff --git a/.gitignore b/.gitignore index effc92f..ceed3fc 100644 --- a/.gitignore +++ b/.gitignore @@ -102,6 +102,12 @@ Desktop.ini # ============================== scripts/.gitea-tokens.json +# ============================== +# Python +# ============================== +__pycache__/ +*.pyc + # ============================== # 其他 # ============================== diff --git a/docs/design/prototype/README.md b/docs/design/prototype/README.md new file mode 100644 index 0000000..5b199dd --- /dev/null +++ b/docs/design/prototype/README.md @@ -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 程序设计文档 | diff --git a/docs/design/prototype/level-design-workflow.md b/docs/design/prototype/level-design-workflow.md new file mode 100644 index 0000000..b977a79 --- /dev/null +++ b/docs/design/prototype/level-design-workflow.md @@ -0,0 +1,310 @@ +# 关卡设计工作流：策划文档规范 + 程序白模搭建 + +> 本文档定义 ChildHood 项目中策划如何产出关卡执行案、程序如何基于关卡执行案和 BlockingStarterPack 资产搭建白模关卡。是策划和程序两个角色之间的交接桥梁。 + +--- + +## 一、总览 + +### 1.1 两个文档，两个角色 + +| 文档 | 产出角色 | 性质 | 用途 | +|------|---------|------|------| +| 场景设计案 `scene-vXX-.md` | 策划 | 氛围愿景 | 定义场景的感觉、叙事意图、时代元素 | +| 关卡执行案 `level-vXX--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--execution.md` — 关卡执行案（空间指南） +- `scene-vXX-.md` — 场景设计案（氛围参考） +- `interaction-system-execution.md` — 交互物清单 +- `collection-system-execution.md` — 收集品清单 +- `-tech.md` — 技术设计方案 +- `Content/BlockingStarterPack/` — BSP 资产 + +**输出**： +- `Content/Maps/LVL_V.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_V.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: 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_V/ + 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 单人开发节奏 + +单人开发者切换策划和程序角色时，关卡执行案就是**交接文档**。策划会话中产出执行案，程序会话中按执行案搭建白模。搭建报告是**反向交接**——记录实际搭建中的偏差，供策划下次更新执行案。