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 编辑器中生成关卡:
- 解析:
build_guide_parser.py 解析搭建指南 Markdown → level_v01.json
- 验证:
validator.py 检查资产名、坐标范围、命名规范
- 构建:
scene_builder.py 通过 UE5 Python API 在编辑器中 spawn Actor
- 锚点补偿:
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 |
兜底地面 |
七、下一步
- 编辑器验证:在 UE5 编辑器中打开关卡,执行 E1/E2/E3 验证清单
- Outliner 组织:按搭建指南的文件夹结构手动分组
- 碰撞设置:边界和墙体启用 BlockAll 碰撞
- PM 验收门审查:通知 PM 执行 ⑥ 程序实现验收门审查
- 后续子任务:6b-6f 实现交互逻辑和收集逻辑