同图传送「加载超时」的业界兜底方案调研

一、先看我们现在的行为

16:41 那次传送的实测时间线（同图，无缝路径）：

QA 报的「场景异常回退」，就是 34.996 → 36.437 这 1.44 秒：玩家被放出来自己动了一下，然后 20 秒前的旧落点把他拉回去。

二、业界三种做法

模式 1 · 显式 Loading + ACK 握手（WoW / FF14 / ESO）

实证 即使同图远距离传送也照样黑屏 loading。协议是标准三段握手：

服务端 → 客户端：SMSG_NEW_WORLD（传送指令）
                同时置位 IsBeingTeleportedFar() 信标，此后拒收该玩家移动包
客户端：黑屏 → 加载 → 完成
客户端 → 服务端：MSG_MOVE_WORLDPORT_ACK
服务端：SetSemaphoreTeleportFar(false)，恢复收包

从 TrinityCore MovementHandler.cpp 的 HandleMoveWorldportAck() 能看到几个关键设计：

模式 2 · 可伸缩过场表演（原神 / 崩铁 / Star Citizen）

观察 这类是 UE / 自研 + 大世界流送 + 传送锚点，和我们最像。做法是用一段表演把加载时间藏起来，且表演时长跟随实际加载。

原神有一个很能说明问题的细节：

Star Citizen 的量子跳跃同理：把玩家扔进一条不需要加载的隧道场景，加载完了才推出去。隧道能开多久开多久。

模式 3 · UE 官方推荐：预热 Streaming Source

实证 Epic 在 World Partition 文档里给的标准传送流程是：

1. 在目标点激活一个 World Partition Streaming Source Component
2. 轮询 IsStreamingCompleted()
3. 返回 true 后才把玩家传过去
4. 传完 Deactivate 该 Source

也就是先让地形加载，再移动玩家。我们现在是反过来的：先 SafeMoveTeleport 把人挪过去，由玩家自身隐式产生 streaming source，然后等。

另外 Epic 文档明确提到一个陷阱：IsStreamingCompleted 只表示格子进入 Activated， 不等同于物理 collision 已 build。这正是我们之前踩过的坑（3x3 贴地预检就是为它加的）。

UE Seamless Travel 的一个前车之鉴

实证 UE5 有个已知 bug：seamless travel 时如果客户端比服务器先加载完， 服务端永远看不到该客户端「已加载」，PlayerController 不切换，服务器和所有客户端一起挂死。

三、三条没有例外的铁律

三种模式路子不同，但下面三条是共通的：

四、逐条对照我们的代码

违反铁律 2 —— 一个超时做了两件语义相反的事

TeleportController.OnTeleportSelfTimeout()（约 1012 行）：

private OnTeleportSelfTimeout(): void {
    Log.Error(..., `15s 兜底触发：超时仍未完成，强制结束并 Done`);
    //                          ↑ 日志自己都写着「仍未完成」
    const snap = ModelManager.TeleportModel!.GetLocalPlayerServerMoveSnapshot();
    this.SendSameSceneLoadDoneIfNeeded(snap.ServerMoveVersion);  // ← 对：服务端该放行
    this.UnlockLocalPlayerMovementForTeleport();                 // ← 错：地形还没好
    this.CleanupAfterTeleport();                                 // ← 里面还把 IsStreamingLevel 置 false
}

协议名字里的 LoadDone 就是「加载完成」。日志文本承认「仍未完成」，下一行就发这个包。 16:39 那次更极端：23.8 秒发出「我加载完了」，真正完成在 38.4 秒 —— 提前 14.6 秒。

而且注释里写得很清楚：

// 即便没收到 ServerMove，也用快照里现有的 version 回报；服务器对落后 version 会丢弃

「即便没收到 ServerMove」 —— 连服务器让我传送到哪儿都还不知道，就先回一句「我到了」。

然后为了自圆其说，只好把玩家也放开 —— 都跟服务器说「我到了」了，总不能还锁着。 一句谎话逼出了第二个错误动作。

违反铁律 3 —— 迟到的回调无人拦截

流送 executor 的 Success 回调（约 1299 行起）完全不知道超时已经发生过，无条件执行：

if (result === ECommandExecutorResult.Success) {
    moveSyncComp?.SafeMoveTeleport(targetPos, targetRot, ...);   // 约 1320 行 ← 拽回去
    ...
    this.ResetPlayerCameraRotation();                            // 约 1326 行 ← 第 2 次扭相机

targetPos / targetRot 是 20 秒前闭包捕获的。没有版本号校验，没有「这次事务还有效吗」的判断。 对比 TrinityCore 那句 if (!player->IsBeingTeleportedFar()) return; —— 我们缺的就是这一句。

违反铁律 1 —— 遮罩早于流送完成 8.3 秒撤掉

三者顺序是错的。遮罩比传送兜底早 7 秒撤，比流送完成早 8.3 秒撤。 遮罩超时的注释写的是「防止流送回调没触发把屏幕卡死」， 但它现在的实际效果是在流送正常进行中提前撤屏。

一个副作用：真·完成的上报会被吞掉

SendSameSceneLoadDoneIfNeeded 有 HasSentSameSceneLoadDone 幂等保护。 所以 15s 撒谎发完之后，流送真完成时那次诚实的上报会被直接吞掉。 服务器从头到尾只收到过那句谎话，永远收不到更正。

五、方案

方案 A · 客户端单方面修（推荐先做，不依赖服务器排期）

15s 超时到了：
  ├─ 照常 SendSameSceneLoadDone        ← 服务端该放行放行，不拖累别人
  └─ 玩家怎么办？看 IsStreamingLevel：
       ├─ true  → 不解锁。起一个宽限定时器继续等
       │           等 finalize 正常收尾时放人（顺便取消宽限）
       │           宽限也耗尽 → 才强制解锁，交坠落重生兜底
       └─ false → 快照缺失等异常，没有后续回调会来放人，就地收尾

+ 加 TeleportFinalizedByFallback 标志（对应 TrinityCore 的 IsBeingTeleportedFar 判断）
  超时置位、每次新传送清零
  回调 Success 分支先查标志，置位就只走 finalize，跳过：
      SafeMoveTeleport / ResetPlayerCameraRotation / 贴地预检

+ OnClear 补清 TeleportSelfTimeoutTimerId（现在漏了）

finalize 里这四件事必须继续跑：

宽限期建议 45s（覆盖实测最慢 38.4s，且考虑帧卡会让超时更晚触发）。 注意 TimerSystemConstants.MaxTime = 90000，CheckInterval 超上限会 静默返回 undefined、定时器根本不注册 —— 若哪天要调到 90s 以上， 必须显式传 needCheckMaxInterval = false，否则玩家会被永久锁死。

方案 B · 加「加载失败」协议（要服务器配合，建议同步推进）

方案 A 本质上是客户端撒谎换服务器放行，终究是补丁。干净的做法是让客户端能如实上报：

ClientSameSceneLoadFailedCSReq { serverMoveVersion, reason }

服务器收到后自己决定怎么处置这种玩家：踢下线（WoW 做法）、强制回上一个安全点、 或者继续等但不阻塞其他玩家。「我加载完了」和「我放弃了，别等我」是两件事，应该有两个表达。

方案 C · 遮罩不要定时撤（对应铁律 1）

• 保守版：遮罩超时对齐到宽限期，撤屏和放人同一时刻发生。改一个常量
• 完整版：超过 8s 不撤遮罩，而是升级成带进度提示的 loading 界面 （对齐原神的做法：让玩家知道在加载，而不是以为卡死了）。要 UI 配合

方案 D · 治「慢」本身（超出本次范围，列出备查）

六、建议范围与验收

复测验收点

1. 15s 兜底触发 之后不应该紧跟 传送-本地玩家移动解锁
2. 传送-解锁前贴地预检完成 应出现在 等待WP场景流送完成(结束) 之后 100ms 内
3. 整个传送过程只有一次 传送-重置相机旋转-目标位置
4. 在打包版跑同样用例，记录同图流送耗时分布，用于回调阈值

参考来源

• TrinityCore 3.3.5 — MovementHandler.cpp 源码（HandleMoveWorldportAck 实现）
• wow_messages — MSG_MOVE_WORLDPORT_ACK 协议文档
• Epic — World Partition 官方文档（Streaming Source 预热传送流程、IsStreamingCompleted）
• Epic — Travelling in Multiplayer（seamless / non-seamless、transition map）
• UE5 seamless travel 竞态 bug（客户端先于服务器加载完导致挂死）
• Multiplayer Compendium — Traveling in Multiplayer
• PerfGuard — World Partition & Streaming Performance（blocking load 检测、多人流送源陷阱）
• Genshin Impact Wiki — Loading Screen（两级 loading 行为观察）
• Roblox DevForum — 加载期间冻结玩家的讨论（ready 必须客户端上报 + 服务端不可全信）
• Gabriel Gambetta — Client-Server Game Architecture（服务器权威、RTT 内客户端会跑偏）