fix(assets): v01白模关卡重建——238Actor锚点补偿+天空盒

关卡文件更新：雾+大气+锚点补偿后的238个Actor Agent记忆：BSP锚点类型+Rotator关键字参数+V01修复记录
2026-06-08 19:05:58 +08:00
parent a3c38aa92a
commit a8bcfb8218
5 changed files with 78 additions and 4 deletions
@@ -1,2 +1,4 @@
- [Level Builder Tool](level-builder-tool.md) — 白模关卡自动生成 Python 脚本（tools/level-builder/，265 Actor 解析验证通过）
- [UE5.7 Python API](ue57-python-api.md) — 实测 API 差异（set_actor_rotation、new_level、CWD、import 路径）
+- [Level Builder Tool](level-builder-tool.md) — 白模关卡自动生成 Python 脚本（tools/level-builder/，265→238 Actor 修复后验证通过）
+- [UE5.7 Python API](ue57-python-api.md) — 实测 API 差异（set_actor_rotation、new_level、CWD、import 路径、Rotator 关键字参数）
+- [V01 Bugfix](level-builder-bugfix-v01.md) — 8个白模关卡问题诊断修复（搭建指南6+解析器双重解析+构建器静默fallback）
+- [BSP Pivot Types](bsp-pivot-types.md) — 38种 BSP 资产实测锚点+自动补偿机制（角落/底边中心/底面中心）
@@ -0,0 +1,34 @@
+---
+name: bsp-pivot-types
+description: BlockingStarterPack 全部 38 种 BSP 资产的实测锚点位置和补偿方案
+metadata:
+  type: project
+---
+
+# BSP 资产锚点实测数据（2026-06-08）
+
+## 锚点模式分类
+
+| 模式 | 资产 | 特征 | 补偿 |
+|------|------|------|------|
+| **角落** | Floor_*, Cube, Fence_Small_400 | min≈(0,0,0) | XY 各偏半尺寸 |
+| **底边中心** | Wall_*, BarrierWall_* | min≈(0, ±half_thickness, 0) | X 偏半宽度，Y 已居中 |
+| **底面中心** | Cylinder, CirclePlatform, 家具, 道具 | min≈(-half, -half, 0) | 无需补偿 |
+
+## 关键实测尺寸（非 default_size）
+
+- **BarrierWall_600**: 实际 600×**60**×**210**cm（非 mapping 中的 20×100）
+- **BarrierWall_200**: 实际 200×**60**×**210**cm
+- **Floor_1000x1000**: Z 范围 -20 到 2（厚度 22cm，表面在 Z=2）
+- **Fence_Small_400**: 实际 407×6×112cm
+- **Wall_400x300**: 所有墙体 Y 方向已居中（±10cm）
+
+## 补偿实现
+
+`asset_mapping.py` 中 `pivot_offset_xy` 字段 + `get_pivot_compensation()` 函数：
+- 输入: asset_key, scale, rotation
+- 输出: (dx, dy) 偏移量
+- builder 中: spawn_pos = json_pos - compensation
+
+## Why: 搭建指南统一用视觉中心坐标，但 BSP 资产锚点各异，不补偿会差半模型
+## How to apply: 新增 BSP 资产时先跑 check_pivots.py 实测锚点，再填 pivot_offset_xy。新增搭建指南时位置直接写视觉中心即可。
@@ -0,0 +1,27 @@
+---
+name: level-builder-bugfix-v01
+description: v01白模关卡8个问题的诊断和修复记录，包括搭建指南/解析器/构建器的修改
+metadata:
+  type: project
+---
+
+# v01 白模关卡问题修复记录（2026-06-08）
+
+## 修复的文件
+
+| 文件 | 修改内容 |
+|------|---------|
+| `docs/technical/关卡-v01-搭建指南.md` | 修复6个问题：全局地面、Z1双Floor、西边界旋转统一、东边界改Wall_400x300、Z1房屋墙旋转、院门改WallDoorDouble、南边界Z7去重 |
+| `tools/level-builder/parsers/build_guide_parser.py` | 新增 `_deduplicate_actors()` 去重；`_parse_phase_ground` 缩小范围到B1段；支持 `旋转 (P,Y,R)` 列名；支持全局地面标题 |
+| `tools/level-builder/builder/scene_builder.py` | `load_asset` 失败时用 Cube 占位 + `[MISSING]` 前缀 + MI_DevPink 标记 |
+| `tools/level-builder/config/asset_mapping.py` | 新增 `WallDoorDouble_400x300` 资产映射 |
+| `tools/level-builder/parsers/markdown_table.py` | `parse_rotation` 增加箭头注释处理说明 |
+
+## 诊断结论
+
+- 8个问题中6个源头在**搭建指南**，2个涉及执行案
+- 解析器有双重解析bug（地面段解析了边界表格）已修复
+- 构建器有静默fallback已改为醒目标记
+
+## Why: 用户检查生成的白模关卡发现多处明显错误，需要追溯源头并修复
+## How to apply: 重新生成关卡时使用修复后的 JSON（238 Actor）。如再出问题，先查搭建指南再查解析器。
@@ -20,6 +20,17 @@ actor.set_actor_rotation(unreal.Rotator(pitch, yaw, roll), False)
 **Why:** UE5.7 改了 API 签名，positional argument `teleport_physics` 变为必需
 **How to apply:** 所有 `set_actor_rotation()` 调用都加第二个参数 `False`

+### `unreal.Rotator` 位置参数顺序不是 (Pitch, Yaw, Roll)
+```python
+# ❌ 错误：位置参数顺序非 P,Y,R，Yaw=90 会落到 Pitch(Y显示)
+actor.set_actor_rotation(unreal.Rotator(0, 90, 0), False)
+
+# ✅ 正确：用关键字参数避免歧义
+actor.set_actor_rotation(unreal.Rotator(pitch=0, yaw=90, roll=0), False)
+```
+**Why:** UE5.7 Python `unreal.Rotator` 的位置参数顺序与关键字参数名不一致，第二个位置参数映射到 Pitch 而非 Yaw
+**How to apply:** 所有 `unreal.Rotator()` 调用必须使用关键字参数 `pitch=, yaw=, roll=`
+
 ### `-ExecutePythonScript` 模式下 CWD 不是项目目录
 ```python
 # ❌ 错误：CWD 是引擎 Binaries 目录