传送 · 技术方案文档

全项目最复杂的一条客户端链路。表面上是「把玩家从 A 挪到 B」，实际要同时解决 多人同步栅栏、World Partition 流送等待、黑屏遮丑的引用计数、 三种视觉表现的分流、9 种触发原因的差异化处理、分层级的安全等待与告警 六件事。 现由 TeleportController 保留稳定门面，表现、地面探测、同场景、过场序列、Seq3 绑定与转场编排分别由子对象承接。

1. 这个模块解决什么问题

1.1 一句话定义

把本地玩家（以及其他客户端上的同一玩家的镜像实体）从当前坐标移动到目标坐标， 过程中保证：不穿地、不下坠、不看到穿帮帧、多端进度一致；同图传送不再靠时间兜底强制放行， 卡住时以每 100 秒一条红色告警暴露。

1.2 为什么不能只写一句 SetActorLocation

2. 全项目的「传送」谱系

「传送」在这个工程里是一个词对五套东西。它们分属不同层、走不同协议、失败表现完全不同。 拿到一个「传送有问题」的反馈，第一步是先归类到下面哪一行，否则会去改错的文件。

2.1 ③ 战斗位移传送长什么样

它是个标准 ECS 组件，唯一调用方是蓝图库 TsTeleportBlueprintLibrary.NamiTeleport—— 也就是技能/蓝图侧发起，不经过任何协议。三段式：

2.2 ④ 位移原语 TeleportTo 的调用点

BaseActorComponent.TeleportTo() 是全工程唯一的「直接写 Actor 位置」出口。 它不做任何地形检查，安全性由调用方负责。全部调用点分三类：

2.3 ① 本模块的文件与职责

2026-09-07 的完整拆分范围、依赖方向、回调治理和验证记录见重构文档。

真正跑场景加载的那一半不在这里，而在 World/SceneLoading/ 的命令链—— 见 场景加载命令链。 本模块负责「决定要传、准备表现、确认能落地」，命令链负责「把场景换过去」。

3. 类型与关键常量

3.1 ETeleportType 五种类型

export const enum ETeleportType {
    SeamlessLevel = 0,  // 无缝传送：同一 WP 内挪位，不切 level，走流送等待
    ActiveTrigger = 1,  // 主动触发传送：玩家点传送点发起
    Dungeon       = 2,  // 副本传送：进/出副本，跨 world
    Respawn       = 3,  // 死亡复活传送
    SceneLoad     = 4,  // 带 load 的切换关卡：走完整 Loading 界面
}

3.2 关键常量：含义、单位、由来

下面每个常量都带单位和它到底在计量什么。 只记数字没用，被追问「为什么是这个值」时答不出来的常量，往往就是下一个 bug 的位置。

超时类（单位：毫秒 ms）

贴地预检的空间参数（单位：厘米 cm，即 UE 的世界单位）

次数与开关（无单位）

4. 完整时序

4.1 同关卡无缝传送（最常见路径）

4.2 跨关卡传送（走完整 Loading）

上面只讲了「加载什么」，没讲「谁遮屏」。这条链路里黑屏与系统 Loading 是分段交接的： 普通分支在 OnStartLoad 开 Loading、到 Seq3 就绪才关；淡入淡出分支则用黑屏当淡出起点， 且跳过 Seq1/2/3。开合顺序、失败兜底与 V2 的例外，见 复杂表现里「谁开谁关」。

5. reason 分支决策表

15512 携带的 reason 决定后续走哪条路。这是整个模块最需要背下来的一张表， 改任何传送逻辑前先确认影响哪些 reason。

5.1 isHeavy 判定

HandleLocalPlayerTeleportApplied 里用 isHeavy 区分「重量级传送」（需要流送等待 + 完整演出） 与「轻量级传送」（原地小挪，直接 SetLocation 完事）。判定依据是 reason + 目标点与当前点的距离/是否跨 cell。

6. 四个核心机制

下面四件事是本模块的技术主体，也是其它模块无法从中学到别处的部分： ① 怎么确认「地真的能站」；② 怎么让多个客户端在同一时刻继续； ③ 怎么让黑屏既遮得住又一定撤得掉；④ 怎么在换 world 的同时播一段不崩的过场。

6.1 机制一：3×3 贴地预检

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

在落点周围打 3×3 共 9 条向下的射线，全部命中才算地形真的好了。

// 参数
GroundReadyTraceHorizontalDist = 132;  // 3x3 网格水平间距(cm)，≈ 角色胶囊体直径
GroundReadyTraceVerticalDist   = 200;  // 向下探测距离
GroundReadyCheckIntervalMs     = 50;   // 每 50ms 试一次；打到就绪为止，没有次数上限

// 伪代码
for (dx of [-132, 0, 132]) {
    for (dy of [-132, 0, 132]) {
        const start = target + Vector(dx, dy, +100);
        const end   = target + Vector(dx, dy, -200);
        if (!UE.KismetSystemLibrary.LineTraceSingle(start, end, Visibility, ...)) {
            return false;  // 任一条没打到 → 地形还没好
        }
    }
}
return true;

为什么是 3×3 而不是 1 条

单条中心射线在斜坡边缘、平台边界、镂空网格上会假阳性：中心刚好命中一块已加载的地砖， 但玩家胶囊体的边缘还悬空。3×3 覆盖了胶囊体直径范围，把这类边界情况挡住。

为什么现在不再放行

原实现是 20 次都没成功（约 1 秒）就放行：宁可让他下坠（还有坠落重生兜底）， 也不能让他卡在黑屏里。 2026-09-21 起这条放行被移除：放行意味着在没确认地面时解锁移动、撤掉遮罩， 玩家会当着镜头的面穿地下坠，而且此时 LoadDone 也已提前发出——等于骗服务器「本端就绪」。

现在改为持续轮询到就绪，同时把「发 LoadDone + 解锁移动 + 撤遮罩」整体后移到地面确认之后。 代价是真正卡住时没有放行兜底，玩家会一直停在遮罩里，可发现性靠每 100 秒一条红色告警提供， 见 同图安全等待。

6.2 机制二：LoadDone 多人栅栏

语义

LoadDone（WorldClientSameSceneLoadDoneCSReq = 14716，回包 SCRsp = 14717） 不是「加载完了」，而是「本端已经准备好，可以让所有人一起继续了」。 它同时承担第二个职责：重置服务端「该玩家不可被选为主控」标记。 服务器靠请求里的 serverMoveVersion 做幂等去重，所以重发不怕重复处理。

退避重试

LoadDoneMaxAttempts   = 5;
LoadDoneTotalWindowMs = 80000;
// 退避阶梯：5s → 5s → 10s → 20s → 40s  （合计 80s，正好等于总窗口）

前两次间隔短，针对偶发丢包；后三次指数拉长，针对服务器侧真的处理不过来—— 这时候高频重试只会雪上加霜。

REVIVE 漏发的教训

6.3 机制三：黑屏与遮罩

三种遮挡手段

系统 Loading 与黑屏的互斥

需求写的是「传送点、传送门发起的传送都要有 Loading 界面」，但落到实现上，难点不在把 Loading 打开， 而在它和黑屏不能同时存在：黑屏挂在 ELayerType.CG（1<<10）， 系统 Loading 挂在 Loading（1<<8），层级上黑屏恒高于 Loading。 两者并存时玩家只看得到黑屏，连加载百分比一起被盖住。

所以「这一次传送由谁遮丑」必须由一条统一判定给出，不能让黑屏和 Loading 各按各的节奏自行开合。 判定收口在 TeleportPresentation：

// 本次传送是否该用系统 Loading 顶替黑屏
ShouldUseUiLoadingInsteadOfBlackScreen(enterShowType?) {
    if (IsFadeInOutTeleport(enterShowType)) return false;  // 淡入淡出要黑屏当淡出起点，保持原行为
    return ShouldShowUiLoadingForSequence();
}

// 两个静态开关共同决定：默认双 false ⇒ 所有主动传送都交给系统 Loading
ShouldShowUiLoadingForSequence() {
    return !UseSystemLoadingForTransition() && !DisableUiLoadingForTransition();
}

复杂表现里「谁开谁关」：飞天遁地 + Seq 过场

「复杂表现」指主动传送走飞天遁地（TeleportUpSkillId=1019），中间再夹一段 TPrefab_LoadScene 过场序列（Seq1/Seq2/Seq3）的那条链路。它由 TeleportSameSceneFlow.HandleLocalPlayerTeleportApplied 里的一个闸门分流：

isHeavy = (blackScreenType === BLACK_SCREEN_TYPE_BLACK)
       || (enterShowType  === TELEPORT_SHOW_TYPE_FADE_IN_OUT);

isHeavy  → OnStartLoad() / OnFadeInOutLevel()   // 上天入地 + Seq1/2/3 过场
!isHeavy → OnSeamlessLevel()                    // 纯无缝，见 4.1

黑屏与系统 Loading 在这条链路里是分段交接的，不是一次性开到底：

另外，淡入淡出的「离开淡出（out）」不在 OnStartLoad 里播， 而是在 ServerLevelUnInitCmd 清实体之前播——那里才是旧世界还没销毁、角色还在原地的最后一个时机。 清实体之后再播 out，就是拿新场景的空镜头做淡出，时序上根本不成立。配合 SetPendingTeleportEnterShowType 把表现类型跨过 UnInit 传给 in，才凑齐 out → UnInit → in 的完整曲线。

另一条线 TeleportV2Flow 反过来强制拉黑屏： OpenBlackView(true, true)——第一个 true 是 force（绕过上面的统一判定）， 第二个是 immediate（不做动画立即黑，否则中止本次传送）。V2 由序列演出独占屏幕， 不参与「有 Loading 就不叠黑屏」这条规则，所以必须显式绕开。

三处黑屏入口的收敛点

三条路都走 ShouldUseUiLoadingInsteadOfBlackScreen，不再各自判断。 判定覆盖不到的调用点另有全局兜底：BlackScreenController.AddBlackScreenAsync 里查 LoadingModel.IsLoadingView，系统 Loading 界面正在显示时直接跳过黑屏并打日志。 以 IsLoadingView 而不是 IsLoading 为准是有意的——后者只发 Start/FinishLoadingState，不一定有界面。

无缝升格 uiload

无缝传送依赖「目的地已就绪」这个前提。前提不成立时，入口遮罩和自身黑屏又都被上面那条判定跳过了，就会出现无遮挡窗口。 对策是按位移与流送状态把这次传送升格成 uiload：

// TeleportTransitionFlow
ShouldPromoteSeamlessToUiLoading(distanceMeters) {
    if (SameSceneFlow.IsTeleportStreaming) return false;  // 已在流送中，交给流送链自己收尾
    return distanceMeters > TeleportDefineConstants.SeamlessPromoteDistanceMeters;  // 100 米
}

判定为真时 PromoteSeamlessToUiLoading() 串行开系统 Loading（PromotedUiLoadingTask）， 并撤掉自己的无缝遮罩——黑屏/遮罩还盖着的话，升格出来的 uiload 和百分比同样看不到； 收尾对称走 ClosePromotedUiLoading()，重复收尾复用同一任务。 开关任务外面包了一层 AwaitWithTimeout，避免单次异常把串行链永久卡住。

按日志区分当前走了哪种遮挡

排查「传完没遮住」时，先看这几条日志落在哪一条上。表里是日志前缀，实际文案后面可能还带距离、reason 等补充字段。

这五条一条都不出时，说明这次传送既没有黑屏也没有 Loading，对应 无缝升格 uiload 里那段「位移 ≤ 100 米的流送窗口」。

引用计数：HasOwnBlackViewTag

黑屏是全局资源，多个系统（传送、重生、结算、剧情）都会 Add/Remove。早期直接 Add/Remove 造成两类问题：

• 提前撤：A 系统 Add 了，B 系统 Remove 了一下，A 的黑屏没了
• 永不撤：A Add 两次只 Remove 一次，计数永远 > 0

对策是每个调用方持有自己的 tag，只能 pop 自己那一份，且 HasOwnBlackViewTag 保证幂等—— 重复 Add 不会累加计数。

ResultCallback 被覆盖（黑屏残留 13 秒）

6.4 机制四：跨图过场序列

跨地图传送要在「旧 world 已经没了、新 world 还没好」这段时间里给玩家看东西。做法是加载一个 只有演出、没有玩法的过场关卡（TPrefab_LoadScene）， 在里面播一段 LevelSequence。它是本模块唯一会主动创建/销毁 UObject 的部分， 因此崩溃与残留都集中在这里。

三段式序列

演出闸门：等 Seq3 真的开播

落地后的解锁不能在切完 world 的那一刻做，否则玩家在 Seq3 还没起来时就恢复了操作。 所以设了一道闸门：等 Seq3 开播事件，EnterSeqWaitTimeoutMs = 20000 一级兜底， EnterSeqBackstopTimeoutMs = 40000 二级兜底。

三个必须做的清理

UE 的 level 卸载不会通知 TS 侧的持有者。凡是跨 level 生命周期的 UObject 引用， 都要自己在卸载前主动置空。

播序列前必须避开引擎 Tick

// SafePlaySequencePlayer：World 正在 Tick 时调 Play 会崩，
// 所以先判 !World->bInTick，处于 Tick 内则推迟到下一帧再播
if (World.bInTick) { TimerSystem.Next(() => player.Play()); }
else { player.Play(); }

在 Tick 内启动序列会改动正在被遍历的 Actor 集合，引擎侧直接崩。 凡是由引擎回调触发、又要反过来改引擎状态的操作，都要考虑推迟一帧。

试用角色要重建一次序列绑定

ApplyAvatarToLevelSequence 把玩家当前外观塞进序列的角色轨道。 试用角色（TrialRole）的实体是被整体替换的， 外观数据在实体重建时才最终确定，所以这里必须在序列播之前重新取一次， 不能沿用传送发起时的快照——否则过场里出现的是换角色之前的形象。

相机侧对应的是 ApplyCameraToLevelSequence，其中会把 bConstrainAspectRatio 置 false：序列相机自带的宽高比约束会在 非标准分辨率下压出黑边，过场是全屏演出，不能有黑边。

7. 六类典型雷区（改代码前必读）

8. 落地穿模裁剪

9. TeleportEntityBufferController 协议缓存

传送过程中，服务器可能持续下发实体的创建/移动/删除协议。如果直接应用，会出现 「角色还在黑屏里，实体已经在新场景创建又销毁」的错乱。

分桶的必要性：如果只用一个全局计数，先结束的那个传送会把还在进行中的传送的缓存也一起清空。

10. 编辑器可选参数：传送表现

三个编辑器节点（退出副本 / 传送副本 / 传送关卡）带可选的 ShowInfo 参数，策划可以逐节点选「进入/离开」的表现：飞天遁地（默认）或淡入淡出。

11. 日志约定

Log.Info(ELogModule.Net, ELogAuthor.ZZB,
    '传送-发包 WorldTeleportCSReq(23707)', ['teleportId', teleportId]);

Log.Info(ELogModule.Net, ELogAuthor.ZZB,
    '传送-收包 WorldTeleportCSRsp',
    ['teleportId', teleportId], ['retcode', response?.retcode]);

12. 面试怎么讲这个模块