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

9.5 KiB
Raw Blame History

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 实现交互逻辑和收集逻辑