Files
ChildHood/docs/technical/关卡-v01-搭建报告.md
T

216 lines
9.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# v0.1 白模搭建报告 — 城郊小街
> P-006 任务产出
> 最后更新:2026-06-08
---
## 一、搭建概要
| 项目 | 值 |
|------|-----|
| 关卡文件 | `Content/Maps/LVL_SuburbanV01.umap` |
| 搭建方式 | Level Builder Python 脚本自动生成 + Bugfix 重建 |
| 搭建指南 | `docs/technical/关卡-v01-搭建指南.md` |
| 场景尺寸 | 8000cm × 6000cm(80m × 60m) |
| 区域数量 | 7 个(Z1-Z7) |
| 最终 Actor 数 | **238** |
| BSP 资产包 | `Content/BlockingStarterPack/` |
| 提交记录 | `e31151a`(首建 265 Actor)→ `a3c38aa`(工具修复)→ `a8bcfb8`(重建 238 Actor) |
### 各类别最终数量
| 类别 | 数量 | 说明 |
|------|------|------|
| 结构体 (STR) | ~95 | 墙体、地板、门框、屋顶、围挡 |
| 布景 (PROP) | ~40 | 家具、装饰、车辆、植被 |
| 交互物 (INTR) | 10 | 占位标记(MI_DevYellow Cube) |
| 收集品 (COLL) | 9 | 占位标记(CirclePlatform 缩小) |
| 边界 (BND) | ~61 | 四面围挡 |
| 光源 (LGT) | 8 | 1 定向光 + 1 天空光 + 3 路灯 + 3 点光源 |
| PlayerStart | 1 | (500, 720, 0) |
| 天空盒 | 1 | Exponential Height Fog + Atmospheric Fog |
| **合计** | **~238** | |
> 数量变化:首建 265 Actor → Bugfix 后 238 Actor(去重解析器双重解析 + 锚点补偿后部分重叠 Actor 合并)。
---
## 二、搭建过程
### 2.1 工具链
使用 `tools/level-builder/` Python 脚本自动在 UE5 编辑器中生成关卡:
1. **解析**:`build_guide_parser.py` 解析搭建指南 Markdown → `level_v01.json`
2. **验证**:`validator.py` 检查资产名、坐标范围、命名规范
3. **构建**:`scene_builder.py` 通过 UE5 Python API 在编辑器中 spawn Actor
4. **锚点补偿**:`asset_mapping.py` 中的 `get_pivot_compensation()` 自动处理不同 BSP 资产的锚点偏移
### 2.2 Bugfix 历史
| 阶段 | 提交 | Actor 数 | 问题 | 修复 |
|------|------|---------|------|------|
| 首建 | `e31151a` | 265 | 8 个问题(详见下方) | — |
| 工具修复 | `a3c38aa` | — | 解析器双重解析 + 构建器静默 fallback | 解析器去重 + 缺失资产粉色标记 |
| 重建 | `a8bcfb8` | 238 | 锚点偏移 + 旋转错误 + 天空盒缺失 | 锚点补偿 + 天空盒 + 全部重建 |
### 2.3 首建 8 个问题诊断
| # | 问题 | 源头 | 修复方式 |
|---|------|------|---------|
| 1 | 全局地面 Floor 缩放不正确 | 搭建指南 | 修正缩放参数 |
| 2 | Z1 出现两个重复 Floor | 搭建指南 | 删除重复 |
| 3 | 西边界旋转不统一 | 搭建指南 | 统一为 (0,90,0) |
| 4 | 东边界使用了 BarrierWall_600 | 搭建指南 | 改用 Wall_400x300 |
| 5 | Z1 房屋墙旋转错误 | 搭建指南 | 修正旋转 |
| 6 | 院门改用 WallDoorDouble | 搭建指南 | 新增资产映射 |
| 7 | 南边界 Z7 区段重复放置 | 解析器 | 去重逻辑 |
| 8 | 缺失天空盒 | 搭建指南 | 新增 Atmospheric Fog + Height Fog |
> 6 个源头在搭建指南,2 个涉及解析器。详见 Agent 记忆 `level-builder-bugfix-v01.md`。
---
## 三、逐区域对照
### Z1 家(40 Actor)
| 条目 | 文档要求 | 实际情况 | 偏差 |
|------|---------|---------|------|
| 院墙高度 | 250cm | Wall_400x300(300cm 高) | 轻微:+50cm,视觉影响小 |
| 院门 | 200cm 宽双开门 | WallDoorDouble_400x300 + RotativeDoor_01 | ✅ 匹配(Bugfix 后改用双开门洞) |
| 房屋尺寸 | 600×380×280 | 墙体围合 | ✅ 匹配 |
| 旧自行车 | Car01 缩放 50% | Car01 缩放 20% | 轻微:BSP Car01 默认较大,20% 更接近自行车 |
| 老式冰箱 | Barrel 或 Cube | Barrel 缩放 (0.3, 0.3, 1.6) | ✅ 匹配 |
| 交互物 3 个 | I01/I02/I06 | MI_DevYellow Cube 占位 | ✅ 匹配 |
| 收集品 1 个 | C10 猫眼弹珠 | CirclePlatform 缩小占位 | ✅ 匹配 |
### Z2 小卖部(26 Actor)
| 条目 | 文档要求 | 实际情况 | 偏差 |
|------|---------|---------|------|
| 建筑尺寸 | 600×400×280 | 墙体围合 | ✅ 匹配 |
| 卷帘门 | GarageDoorOpen_01 | ✅ | ✅ 匹配 |
| 遮阳棚 | Floor_200x300 × 2 | ✅ | ✅ 匹配 |
| 玻璃柜台 | Cube + MI_DevGlassWhite | ✅ | ✅ 匹配 |
| 零食货架 | Fence_Small_400 × 3 | ✅ | ✅ 匹配 |
| 交互物 2 个 | I05/I07 | ✅ | ✅ 匹配 |
| 收集品 1 个 | C09 | ✅ | ✅ 匹配 |
### Z3 主街道(42 Actor)
| 条目 | 文档要求 | 实际情况 | 偏差 |
|------|---------|---------|------|
| 街道尺寸 | 5000×500 | 5 块 Floor_1000x1000 平铺 | ✅ 匹配 |
| 南墙 C+D 段 | 8 块 Wall | ✅ | ✅ 匹配 |
| 北墙 A+C 段 | 含巷子/空地开口 | ✅ | ✅ 匹配 |
| 公用电话亭 | Cube+Cylinder | Cube 单体缩放 | 轻微:简化为单体 |
| 交互物 2 个 | I04/I09 | ✅ | ✅ 匹配 |
| 收集品 1 个 | C08 | ✅ | ✅ 匹配 |
| 路灯 3 个 | RoadLamp_01 | ✅ | ✅ 匹配 |
### Z4 空地(20 Actor)
| 条目 | 文档要求 | 实际情况 | 偏差 |
|------|---------|---------|------|
| 地面高度 | +10cm | ✅ | ✅ 匹配 |
| 东/北边界围挡 | BarrierWall_600 | ✅ | ⚠️ 高度仅 210cm(实测),接近设计 200cm |
| 西边界矮墙 | BarrierWall_200 × 3 | ✅ | ✅ 匹配 |
| 大梧桐树 | Tree_01 缩放 1.2 | ✅ | ✅ 匹配 |
| 交互物 2 个 | I03/I08 | ✅ | ✅ 匹配 |
| 收集品 3 个 | C01/C03/C04 | ✅ | ✅ 匹配 |
### Z5 巷子(19 Actor)
| 条目 | 文档要求 | 实际情况 | 偏差 |
|------|---------|---------|------|
| 巷子宽度 | 300cm | 实际约 260cm(2580-2300-20墙厚) | **重大**:宽度差 40cm,仅 87% 设计宽度 |
| 巷子长度 | 2000cm | ✅ | ✅ 匹配 |
| 墙壁高度 | 300cm | ✅ | ✅ 匹配 |
| 交互物 1 个 | I10 | ✅ | ✅ 匹配 |
| 收集品 1 个 | C02 | ✅ | ✅ 匹配 |
### Z6 水塘边(16 Actor)
| 条目 | 文档要求 | 实际情况 | 偏差 |
|------|---------|---------|------|
| 水面高度 | Z=-20cm | ✅ | ✅ 匹配 |
| 水面尺寸 | 1200×800 | ✅ | ✅ 匹配 |
| 芦苇/荷叶 | Cylinder/CirclePlatform | ✅ | ✅ 匹配 |
| 收集品 2 个 | C05/C06 | ✅ | ✅ 匹配 |
### Z7 老居民楼(10 Actor)
| 条目 | 文档要求 | 实际情况 | 偏差 |
|------|---------|---------|------|
| 建筑体 | Building_01 | ✅ | ⚠️ 默认尺寸待验证是否匹配设计 1200×600×1800 |
| 碰撞围墙 | 阻止靠近 | Wall_400x300 × 5 | ✅ 匹配 |
| 晾衣杆 3 个 | Beam_300 × 3 | ✅ | ✅ 匹配 |
| 不可进入 | 无门洞 | ✅ | ✅ 匹配 |
### GLOBAL 全局(65 Actor)
| 条目 | 文档要求 | 实际情况 | 偏差 |
|------|---------|---------|------|
| 西边界 15 块 | Wall_400x300 | ✅ | ✅ 匹配 |
| 东边界 15 块 | 改用 Wall_400x300 | ✅(Bugfix 后修正) | ✅ 匹配 |
| 北边界 20 块 | Wall_400x300 | ✅ | ✅ 匹配 |
| 南边界 12 块 | 分段处理 | ✅ | ✅ 匹配(Z7 碰撞围墙覆盖 X=5500-7000) |
| 全局地面 | Floor_1000x1000 × 8×6 | ✅ | ✅ 匹配 |
| 光源 | Directional + Sky | ✅ | ✅ 匹配 |
| 天空盒 | — | Exponential Height Fog + Atmospheric Fog | 新增:增强场景氛围 |
| PlayerStart | (500, 720, 0) | ✅ | ✅ 匹配 |
---
## 四、资产替代清单
| # | 文档建议 | 实际使用 | 原因 |
|---|---------|---------|------|
| 1 | Car01 缩放 50%(自行车) | Car01 缩放 20% | BSP Car01 默认约 450cm 长,20% 缩放至约 90cm 更接近自行车 |
| 2 | BarrierWall_600(东边界) | Wall_400x300 | Bugfix 后改用,Wall_400x300 高 300cm 一步到位 |
| 3 | WallDoor_200x300(院门) | WallDoorDouble_400x300 | Bugfix 后改用双开门洞,门洞更宽 |
---
## 五、已知偏差汇总
| # | 偏差 | 等级 | 说明 | 建议处理 |
|---|------|------|------|---------|
| 1 | Z5 巷子实际宽度约 260cm vs 设计 300cm | **重大** | Wall 厚度 20cm × 2 占用空间 | 接受(260cm 仍可通行)或将东墙东移至 X=2620 |
| 2 | Z7 Building_01 默认尺寸待确认 vs 设计 1200×600×1800 | 轻微 | 需在编辑器中测量并按需缩放 | 编辑器中手动调整 |
| 3 | Z3 北墙偏移 480cm vs 区域深度 500cm | 轻微 | 20cm 差异在 500cm 深度中影响极小 | 接受 |
| 4 | 交互物/收集品仅为占位标记 | 计划内 | 不含交互逻辑 | 6b-6f 子任务实现 |
| 5 | Outliner 文件夹分组未自动完成 | 计划内 | 需编辑器中手动组织 | 手动操作 |
| 6 | 物理碰撞预设未批量设置 | 计划内 | 边界墙体需 BlockAll | 搭建验证时设置 |
---
## 六、缩放记录
关键非默认缩放的 Actor:
| Actor | 资产 | 缩放 | 实际尺寸 (cm) | 用途 |
|-------|------|------|-------------|------|
| 自行车 × 2 | Car01 | (0.2, 0.2, 0.2) | ~90×36×30 | Z1/Z3 旧自行车 |
| 冰箱 | Barrel | (0.3, 0.3, 1.6) | ~Ø30×160 | Z1 老式冰箱 |
| 玻璃柜台 | Cube | (2, 0.6, 0.9) | 200×60×90 | Z2 柜台 |
| 招牌 | Cube | (3, 0.05, 0.4) | 300×5×40 | Z2 招牌 |
| 电话亭 | Cube | (0.8, 0.8, 2.2) | 80×80×220 | Z3 电话亭 |
| 电线杆 × 2 | Cylinder | (0.04, 0.04, 12) | ~Ø4×600 | Z3 电线杆 |
| 支撑柱 × 3 | Cylinder | (0.05, 0.05, 3.6) | ~Ø5×180 | 晾衣杆柱 |
| 芦苇 × 3 组 | Cylinder | (0.08, 0.08, 2/1.6) | ~Ø8×200/160 | Z6 芦苇 |
| 积水坑 | Cube | (1.2, 0.8, 0.01) | 120×80×1 | Z4 水坑 |
| 全局地面 | Floor_1000x1000 | (8, 6, 1) | 8000×6000×10 | 兜底地面 |
---
## 七、下一步
1. **编辑器验证**:在 UE5 编辑器中打开关卡,执行 E1/E2/E3 验证清单
2. **Outliner 组织**:按搭建指南的文件夹结构手动分组
3. **碰撞设置**:边界和墙体启用 BlockAll 碰撞
4. **PM 验收门审查**:通知 PM 执行 ⑥ 程序实现验收门审查
5. **后续子任务**:6b-6f 实现交互逻辑和收集逻辑