地图流送与 DataLayer

World Partition 是这个项目大世界的地基。「传送完掉下去」「地形突然消失」「实体没出来」「卡在等流送」 这几类问题的根都在这里。 本页把 WP / DataLayer / 流送源 / 子关卡这四组概念讲清， 再回答一个最容易被当成引擎 bug 的问题：cell 已 Activated，为什么碰撞体还没好？

1. 三组概念，先分清

1.1 World Partition 是什么

UE5 把一整张大地图切成网格 cell，按玩家所在位置动态加载/卸载附近的 cell， 远处的用 HLOD 代理顶着。这样一张几平方公里的图不需要一次性载进内存。

一张 WP 地图（本项目里叫 WPMap）内部又通过 DataLayer 划分出可独立开关的内容层。 所以「换场景」在这个项目里有两种量级：

1.2 DataLayer：本项目的六种前缀

DataLayer 的命名前缀就是它的类型，运行时靠 startsWith 分派处理。 这是一个用命名约定代替枚举的设计。

1.3 两个重置函数，管的不是同一批

2. 流送源：谁决定加载哪些 cell

2.1 流送源就是一个「灯」

WP 不知道玩家在哪，它只认流送源（streaming source）—— 场景里一个带 WorldPartitionStreamingSourceComponent 的 Actor （本项目用 BP_StreamingSource_C）。引擎加载它周围的 cell。

可以把它想成一盏灯：灯照到哪，那块地形就存在；灯灭了或移开，地形被回收。

2.2 两盏灯：跟随玩家的 + 锁定落点的

为什么要两盏：玩家还没到落点，跟随玩家的那盏灯照不到落点。 如果等玩家搬过去再加载，那一瞬间脚下是空的，直接穿地。 所以先在落点点一盏灯把地形烤好，再把玩家搬过去。

2.3 灯交接：主链 ⑪ 真正在做的事

// SceneLoadingMoveCmd.MoveToNewScene()
gameModeModel.StreamingSourceInfo.EnsureStreamingSource();
StreamingSourceInfo.CopyStreamingSourceInfo(
    gameModeModel.StreamingSourceInfo,        // to：跟随玩家那盏
    gameModeModel.TargetStreamingSourceInfo,  // from：落点那盏
);
// 移动完成，关闭TargetStreamingSource流送
gameModeModel.TargetStreamingSourceInfo.SetStreamingSourceState(EStreamingSourceState.Unload);

CopyStreamingSourceInfo 拷三样东西：位置、LevelLayerName、流送状态。 交接完成后落点那盏灯立刻关掉——两盏灯照同一片地，留着是浪费。

2.4 锁定流送

SetStreamingLockStateAndPosition(isLock: boolean, lockPosition?: Vector)

锁定后 Tick() 直接 return，灯不再跟随玩家，停在 lockPosition。 用于「玩家位置暂时不可信」的时刻——比如传送过程中玩家 Actor 已经被挪走但地形还没准备好。

2.5 第三种灯：临时流送源

TransientStreamingSourceManager 提供按需创建的额外流送源， 典型用途是过场镜头飞到远处——镜头看得到的地方必须加载，但玩家并没有过去。

3. 等待流送完成

3.1 查询口径：五个字段决定「等什么」

const querySource = new UE.WorldPartitionStreamingQuerySource();
querySource.Location = location;                                  // 检查位置 = 落点
querySource.Radius = ResourceSystemConstants.StreamingSourceRadius;
querySource.bUseGridLoadingRange = false;
querySource.DataLayers = dataLayers;
querySource.bDataLayersOnly = false;
querySource.bSpatialQuery = true;
querySource.bClampedByGridLoadingRange = true;

等待层的组装：目标关卡的 EntityLevel 层 + Client 与 Server 两套子关卡层， 用 Set 去重后逐个转成 FName：

dataLayerLabels.add(gameModeModel.TargetStreamingSourceInfo.GetLevelLayerName()!.toString());
for (const label of ControllerHolder.WorldController.ClientLayerTasks) {
    dataLayerLabels.add(`DataLayerRuntime_SubMap_${label}`);
}
for (const label of ControllerHolder.WorldController.ServerLayerTasks) {
    dataLayerLabels.add(`DataLayerRuntime_SubMap_${label}`);
}

3.2 轮询而不是回调

const timerId = TimerSystem.Forever(() => {
    const completed = worldPartitionSubsystem.IsStreamingCompleted(
        UE.EWorldPartitionRuntimeCellState.Activated, querySources, true);
    if (!completed) { return; }
    TimerSystem.Remove(timerId);
    completedPromise.SetResult(true);
}, ResourceSystemConstants.CheckStreamingInterval)!;

4. 核心问题：cell 已 Activated，为什么碰撞体还没好

这是本项目最典型的一个「引擎说完成了，实际没完成」。 表现是：流送等待返回 true，解锁放人，玩家直接穿过地面持续下坠，直到坠落重生兜底。

4.1 三个原因叠在一起

原因一：Activated 断言的是流送状态，不是物理状态

EWorldPartitionRuntimeCellState.Activated 的语义是 「这个 cell 的 Level 已经完成 AddToWorld、进入可见状态」。 而 Actor 的组件注册和物理刚体创建是引擎分帧摊平的增量工作—— Level 变可见和「里面所有 collision 都 build 完」不是同一个时刻。

原因二：查询口径本身有边界

由 3.1 的字段直接推出来的三条盲区：

原因三：HLOD 代理会让「看起来有地」

远处 cell 未加载时由 HLOD 代理顶着显示。代理是给眼睛看的，不是给物理用的。 所以画面上地形完好、脚下却没有碰撞，这个组合是正常的引擎行为。

4.2 实测结论

4.3 解法：不信标志位，直接问物理系统

既然「流送完成」不能证明「能站人」，那就换一个能直接证明它的检查： 以落点为中心做 3×3 网格向下射线，九条全部命中才算脚下有地。

private static readonly GroundReadyTraceHorizontalDist = 132;  // 相邻射线水平间距，约等于角色胶囊体直径
private static readonly GroundReadyTraceVerticalDist = 200;    // 向下探测深度

for (let i = -1; i <= 1; i++) {
    for (let j = -1; j <= 1; j++) {
        trace.SetStartLocation(targetPos.X + h * i, targetPos.Y + h * j, targetPos.Z);
        trace.SetEndLocation  (targetPos.X + h * i, targetPos.Y + h * j, targetPos.Z - v);
        if (!TraceElementCommon.LineTrace(trace, '[传送-解锁前贴地预检]')) { return false; }
    }
}

4.4 另一面：流送假死而不是假阳性

假阳性是「说完成了其实没完成」，还有一种相反的失效：永远不说完成。

const timerId = TimerSystem.Forever(() => { ... });   // Forever：没有次数上限

5. 子关卡 LayerTasks：两套集合求差

子关卡是「同一张图上可动态开关的一片内容」，比如某个任务专属的建筑。 它由两个来源各维护一套集合：

private SetLayerTasks(type: ESetLayerTasksType, newLayerTasks: Set<string>): void {
    const oldLayerTasks = type === Client ? this.ClientLayerTasks : this.ServerLayerTasks;
    // 卸载旧的：在 old 不在 new
    for (const dl of oldLayerTasks) {
        if (!newLayerTasks.has(dl)) { this.SetWorldPartitionDataLayerState(`DataLayerRuntime_SubMap_${dl}`, false); }
    }
    // 加载新的：在 new 不在 old
    for (const dl of newLayerTasks) {
        if (!oldLayerTasks.has(dl)) { this.SetWorldPartitionDataLayerState(`DataLayerRuntime_SubMap_${dl}`, true); }
    }
    ...
}

每次 SetWorldPartitionDataLayerState 都会 Emit OnLayerTasksChanged， 表现层据此刷新。注意这个事件是逐个 DataLayer 发的，一次批量变更会发多条。

6. 预加载与「移交」

SceneLoadingController 提供一组 DataLayer 预加载接口， 让目标关卡的内容在正式切场景之前就开始加载。

6.1 「移交」而不是「取消再重来」

预加载和正式加载可能要的是同一批 DataLayer。 如果正式加载开始时把预加载单纯取消掉（还原 DataLayer 状态）， 那些刚加载好的内容会被卸载，然后立刻又被加载一遍——预加载完全白做。

所以取消时判断：

7. 调试工具清单

7.1 GM 命令

7.2 代码内调试接口

7.3 引擎控制台

wp.Runtime.StopLoadingLevelStreamingCells 1   // 冻结 cell 加载
wp.Runtime.StopLoadingLevelStreamingCells 0   // 恢复

这两行在 SetStreamingLockStateAndPosition 里以注释形式保留着—— 曾经用它配合流送锁定来复现「地形不加载」，现在没有启用。 需要手动构造流送假死场景时，这是最直接的手段。

7.4 日志关键字

8. 排查速查表

9. 面试怎么讲