场景加载命令链 SceneLoading

整个客户端最长的一条链路，也是所有「卡 Loading / 黑屏不消 / 落地穿地 / 实体没出来」问题的共同上游。 传送、进副本、登录、重连、序章演出——全部都是这条链的不同走法。 先看懂这里，再去看 ① 传送 才不会迷路。

1. 为什么是命令链，而不是一个大函数

1.1 场景加载到底要做多少事

换一次场景，客户端要按严格顺序完成：进入加载模式 → 开加载界面 → 切 WPMap → 重置 DataLayer → 加载过场关卡 → 更新子关卡 → 开始 WPLayer 流送 → 预加载实体资源 → 预加载 Actor → 等流送完成 → 把玩家搬过去 → 预加载战斗 UI → 预加载通用 UI → 落地后处理 → 清理无引用资源 → 等传送指令收尾 → 关加载界面 → 通知加载完成 → 播落地表现。

这里面大部分步骤是异步的（资源加载、地图切换、WP 流送）， 而且不同场合要跳过不同的步骤（无缝切换跳流送、序章要保住演出 Actor、重连要复用已有关卡）。 写成一个大函数的话，会变成回调套回调 + 到处 if (是不是无缝)。

1.2 命令链换来的四件事

2. 命令框架本身

框架在 Src/Core/Utils/Command/，不只服务场景加载，但场景加载是它最重的用户。

2.1 七个状态

export const enum ECommandState {
    Idle,        // 已创建未执行
    Executing,   // 正在执行
    Succeeded,   // 成功；"跳过本步、链条继续"也走这里
    Failed,      // 失败，链条中断（可配置回滚）
    Bailed,      // 主动中止整条链（不算失败），会回滚已执行命令
    Disposed,    // 已销毁
    Fatal,       // 严重错误，无法继续
}

2.2 InitCommand：子命令在初始化时就展开

这是这套框架最容易理解错的地方。InitCommand 类型的命令， 其 OnAddInitCommand(context) 在整条链构建阶段就被调用， 把自己的子命令原地展开进主链——不是执行到它时才展开。

// 展开发生在构链阶段，不是执行阶段
protected override OnAddInitCommand(context: SceneLoadingCmdContext): void {
    this.AddInitCommand(new SubCmdA());   // → Executor.AddInitCommandAdvance(cmd, depth + 1)
    this.AddInitCommand(new SubCmdB());
}

2.3 四种结束方式

2.4 FailCritical：从「加载失败」升级为「客户端异常」

// 关键节点出错时不是简单 Fail，而是把客户端整体状态标记为异常销毁
context.FailCritical(reason);
// → 日志：'关卡加载关键节点出现严重错误，客户端状态转为 ExceptionalDestroyed'

普通 Fail() 只是这条链断了，玩家可能还能操作； FailCritical 表示「场景处于不可用状态，继续玩下去只会产生更奇怪的问题」， 于是把客户端推到 ExceptionalDestroyed，交给上层做重连或回登录。

2.5 关键事实：场景加载的 executor 没有超时兜底

executor.Init(context, name, true, TimerSystemConstants.MaxTime);
//                                    ↑ 过期时间取"最大时间" = 实际等于永不过期

框架自带 CommandExecutor.DefaultExpireTime = 60000（60 秒）以及 RollbackOnTimeout、TriggerCallbackOnTimeout 这些机制， 但所有场景加载 executor 都显式传入 TimerSystemConstants.MaxTime 把它关掉了。

3. 五条入口链

3.1 三路选择器

SceneLoadingController.LoadSceneMain 按玩家当前处境选链，不按目标场景选：

const executor = isReconnecting
    ? SceneLoadingCommandHelper.BuildReconnectSceneLoadingCommand(context, cb)
    : isNewPlayer   // gameModeModel.TagComponent.HasTag(GameModeModel.TagNewUser)
    ? SceneLoadingCommandHelper.BuildPrologueSceneLoadingCommand(context, cb)
    : SceneLoadingCommandHelper.BuildSceneLoadingCommand(context, cb);

第四条 BuildSceneTeleportCommand 由传送流程单独调用，第五条是卸载链 SceneUnloadCmd。

注意每个 Build* 其实只往 executor 里塞了一个根命令， 19 个节点是这个根命令在构链阶段展开出来的：

所以读链要读根命令的 OnAddInitCommand，不是读 Helper。 Helper 只负责选链、拼 context、装超时和回调。

3.2 五条链的差异

3.3 序章链为什么要伪造 CurLevelId

context.CurLevelId = PrologueFlowController.GetPrologueLevelId();
// 使得 context.IsWpChanged() === false，引擎加载地图时不会走硬加载流程,
// 避免演出Actor被意外销毁

序章是一段已经在播的演出：玩家进游戏时演出 Actor 已经存在于场景里。 如果按正常判定，「当前关卡」和「目标关卡」不同 → IsWpMapChanged() 为真 → 走硬加载 → 演出 Actor 连带被销毁，序章直接黑掉。

所以这里反向利用了判定函数：把 CurLevelId 直接改成序章关卡 Id， 让 IsWpMapChanged() 返回 false，从而绕开硬加载分支。 这是全链路唯一一处「主动改写 context 来影响判定结果」的地方。

4. ESceneLoadingType 与它的哨兵值

4.1 枚举

export const enum ESceneLoadingType {
    LoadingWpMap        = 0,  // 换 WPMap：最重，走完整加载
    LoadingWpLayer      = 1,  // 同 WPMap 换 Layer，非无缝
    FlagSeamlessLoading = 2,  // ← 哨兵：不是真实类型，只是"无缝起点"的分界线
    SwitchDimension     = 3,  // 无缝切换
    Teleport            = 4,  // 传送
}

// 哨兵的用法：一次比较代替一串枚举罗列
public IsSeamlessLoading(): boolean {
    return this.SceneLoadingType >= ESceneLoadingType.FlagSeamlessLoading;
}

4.2 GetSceneLoadingType 的五步判定链

顺序即优先级，命中即返回：

5. SceneLoadingCmdContext：谓词的唯一权威

context 既是链上共享的数据袋，也是所有「这步要不要做」判断的唯一出处。 命令里不允许自己重新推导条件，必须问 context。

5.1 深挖：跳过条件不是同一个开关

流程图上把 ⑦⑧⑩⑪ 四个节点画成「受同一个无缝开关影响」。实际代码里它们分成两组：

6. 主链 19 节点完整时间轴

下面是 SceneLoadingWpMapCmd.OnAddInitCommand 的完整顺序， 已省略夹在中间的纯事件分发命令（SceneLoadingDispatchEventCmd，见 §8）。

6.1 初始化（①②）

6.2 地图切换（③，带分支）

6.3 场景搭建（④⑤⑥）

6.4 资源预加载（⑦⑧⑨）

6.5 流送与落位（⑩⑪）

6.6 UI 资源预加载（⑫⑬）

6.7 收尾（⑭～⑲）

7. 两个值得单独看的子链

7.1 SceneLoadingLogicSceneCmd：7 个子命令

逻辑场景（ServerLevel）的初始化被打包成一个 InitCommand，展开成 7 条子命令。 它管的是服务器概念上的关卡——玩法数据、实体列表、玩法组件—— 与前面那 19 个节点管的「引擎概念上的地图」是两回事。

7.2 SceneUnloadCmd：卸载链

卸载不是加载的简单逆序，它有自己的顺序约束： 先销毁实体，再清 UI，最后卸 DataLayer 与释放资源。

顺序不能颠倒的原因是引用方向：UI 可能持有实体引用，实体持有资源引用。 先卸资源会让实体和 UI 拿到野引用；先清 UI 则会在实体销毁时少一次刷新通知， 表现为「界面上还残留已销毁实体的信息」。

8. 事件分发：为什么单独抽一个命令

链上散布着 SceneLoadingDispatchEventCmd——它本身不做任何加载， 只负责在确定的时间点向外广播事件。业务模块通过监听这些事件参与加载流程， 而不需要被写进链里。

9. 日志：一条前缀定位到步

SceneLoadingLogContext 给这条链的所有日志加统一前缀：

[Loading|当前关卡→目标关卡|资源名|阶段|已完成/总数] 具体内容

10. 出生点是怎么定下来的

SetLoadingContextBornTransform 按优先级取坐标，先命中的赢：

10.1 朝向的两个补救

补救一：dirPos 全零时反算方向

/** 兜底朝向目标点与出生点的距离：取足够远以逼近"纯方向"，
  * 避免实际落点（如队伍站位重寻路）相对出生点的微小偏移干扰求出的朝向角 */
private static readonly FallbackCameraDirDistance = 100000;

取 100000（1 公里）而不是随便一个值，是因为朝向是用「出生点 → 目标点」两点求出来的。 如果目标点离出生点很近，出生点的微小偏移（比如组队时被重新寻路挪了半米） 会让求出的角度偏很多。把目标点放到 1 公里外，两点连线几乎就是纯方向，偏移可以忽略。

补救二：只在旋转为零时才用 dirPos

11. 静默登录

开发/编辑器专用的快速登录：跳过登录界面，读本地配置直接把角色扔进指定地图。 PublicUtil.GetIsSilentLogin() 需要三个条件同时满足：

因为它跳过了正式登录该做的初始化，所以在本链里有一条特例： 即使目标地图与当前地图是同一张 WPMap（不满足跨关卡分支）， 只要是首次登录且处于静默登录，也会强制补一次 StartEnterMap/EndEnterMap 事件和一次 DataLayer 重置。

const isFromLoginScene = context.CurLevelId === 0;   // 没有当前关卡 = 还没进过游戏
if (isWpMapChanged) {
    this.AddInitCommand(new SceneLoadingMainMapCmd());
    shouldRaiseMapChangeEvents = true;
} else if (isFromLoginScene && PublicUtil.GetIsSilentLogin()) {
    shouldRaiseMapChangeEvents = true;   // 不加载新 WPMap，但事件照发
}

注意 shouldRaiseMapChangeEvents 与「是否加载新 WPMap」是两个独立的东西： 静默登录这条分支只抬事件旗子，不加地图命令。 把二者当成一个开关来读，就会以为「没换图就不会有 EnterMap 事件」—— 有模块靠 EndEnterMap 做初始化，这个误解会让人找错初始化时机。

12. 这条链上的五种防御式写法

13. 常见排查

13.1 卡在加载界面 / 黑屏不消

13.2 某个步骤「好像没执行」

先确认它是被条件跳过、还是根本没到：
· 被跳过（该命令返回 Succeeded）→ 去查它的跳过条件，注意 ⑦⑩⑪ 与 ⑧ 用的不是同一个条件；
· 没到 → 前面某条卡住了，回到 13.1。

13.3 落地位置不对 / 朝向不对

grep '[传送]无缝加载判定' 拿到完整决策快照，先确认走的是哪条路径； 然后对照 出生点优先级：无缝非换落点用的是玩家当前坐标， 这时候「位置没变」是正确行为，不是 bug。朝向不对则看 10.1 两个补救。

14. 面试怎么讲