自动关联目录：World 调试与校验

官方依据：World Partition 的「Debugging and Runtime Overrides」一节（已核实全部 CVar），以及各特性篇中的调试手段汇总。

1. 定位

World 层的问题有一个共同特点：现象和原因常常不在同一个尺度上——看到的是"远处卡"，原因可能是某个草的材质还在用 WPO；看到的是"物体不出现"，原因可能是它被关卡蓝图引用成了 Always Loaded。

一句话定位：先分清是"加载"问题、"绘制"问题还是"阴影"问题，再进对应层。三层工具完全不同。

2. World Partition 运行时调试（官方已核实）

CVar	作用
`wp.Runtime.ToggleDrawRuntimeHash2D`	2D 调试显示运行时哈希网格
`wp.Runtime.ToggleDrawRuntimeHash3D`	3D 显示
`wp.Runtime.ShowRuntimeSpatialHashGridLevel`	显示哪个网格层级
`wp.Runtime.ShowRuntimeSpatialHashGridLevelCount`	显示几个层级
`wp.Runtime.ShowRuntimeSpatialHashGridIndex`	显示指定网格（无效索引显示全部）
`wp.Runtime.RuntimeSpatialHashCellToSourceAngleContributionToCellImportance`	0–1，调节"源→单元"向量与源前向夹角对单元重要性的贡献；越接近 0，角度影响越小
`wp.Runtime.OverrideRuntimeSpatialHashLoadingRange`	`-grid=[index] -range=[值]` 覆写加载范围
`wp.Runtime.MaxLoadingLevelStreamingCells`	限制并发加载单元数
`wp.Runtime.HLOD 0`	不带 HLOD 显示世界（对比排查第一命令）

3. 分层排查表

症状	层	工具
世界全部加载、没流式	加载	`Enable Streaming`；`wp.Runtime.ToggleDrawRuntimeHash2D`
Actor 常驻不卸载	加载	查关卡蓝图引用（见关卡与关卡编辑器）
传送/快移卡顿	加载	`wp.Runtime.MaxLoadingLevelStreamingCells`；流式源预加载
远处物体不出现	加载	`Is Spatially Loaded`；`wp.Runtime.OverrideRuntimeSpatialHashLoadingRange` 验证是否是范围问题
远景掉帧	绘制	`wp.Runtime.HLOD 0` 对比；HLOD
远处模型细节丢失	绘制	静态网格与 LOD
阴影极慢	阴影	VSM 的 Cached Page 可视化
铺植被后帧率崩	三者皆有	Foliage 的分项对比法
地形卡	绘制	Landscape 的降级顺序

4. 校验（发布前必做）

项	怎么做
Map Check	编辑器 `Build > Map Check`，看错误与警告
VSM 相关误报	已核实：启用 VSM 后"Lighting needs to be rebuilt"提示不会出现（但 Stationary 间接光仍是烘焙的）；preshadow 的警告可忽略
构建 HLOD	`Build > Build HLODs`；改动世界后必须重建
构建导航	见 `AI` 分支
构建 Minimap	`Build > Build Minimap`（需启用虚拟纹理支持）
Cook	WP 地图必须用 Cook commandlet（见 World Partition）
光照构建	见光照与烘焙

5. 编辑器侧

手段	用途
World Partition 窗口	区域加载/卸载、框选
Location Volume	定义工作区域
快捷键	Shift+Drag 吸附、Ctrl+Double Click 加载区域等（见 WP 篇）
Dynamic Loading Range Scaling	改善 PIE 性能与迭代速度
`Stat` 系列	`stat streaming`、`stat unit`、`stat rhi`

PIE 里性能与打包版差异很大——尤其是流式与 PSO 相关，必须测打包版本。

6. 代价与权衡

手段	收益	代价	注意
运行时哈希可视化	直观看到加载范围	需要认识颜色/层级含义	调完记得关
`OverrideRuntimeSpatialHashLoadingRange`	快速验证"是不是范围问题"	只是调试覆写	不写进正式配置
`wp.Runtime.HLOD 0`	一眼确认 HLOD 是否生效	看到的是未优化状态	对比用
Map Check 警告	提前发现问题	有已知误报（VSM 相关）	见上文
编辑器区域加载	编辑器不卡	需要记得加载要看的区域	容易忘

7. 踩坑与排查

坑	现象	怎么验证
只在编辑器测	打包后行为不同	必须测打包版本
开着调试可视化测性能	结果偏高	关掉所有可视化
改了世界没重建 HLOD	远景是旧的	重建 HLODs
把调试 CVar 写进配置	线上行为异常	`Override*` 类只用于调试
相信 Map Check 的全部警告	误判	VSM 相关警告有已知误报
Minimap 建了不显示	白建	启用虚拟纹理支持
PIE 流畅、打包卡	加载与 PSO	测打包 + `-clearPSODriverCache`（见 PSO）
只看 `stat unit` 就下结论	归因错误	见渲染调试与抓帧的分层顺序

8. 固定排查顺序

1. stat unit → 分清 Game / Draw / GPU
2. 是"加载"问题？→ wp.Runtime.* 可视化 + Is Spatially Loaded + 关卡蓝图引用
3. 是"绘制"问题？→ wp.Runtime.HLOD 0 对比 → LOD/HLOD
4. 是"阴影"问题？→ VSM Cached Page 可视化
5. 发布前 → Map Check + 重建 HLOD/导航/光照 + Cook commandlet
6. 全程 → 测打包版本，不要只信 PIE

参考

World Partition · HLOD · 关卡与关卡编辑器
渲染调试与抓帧 · 虚拟阴影贴图 · PSO 预缓存