Seq2 → Seq3 衔接问题

2026-09-28 更新：当前代码事实、独立 Transition 方案、黑屏与 All 静态评审、验收矩阵和 P4 交付边界。本次只更新文档；不实现业务代码，不创建或提交 CL。历史试验记录保留在文末，不作为当前实现依据。

1. 当前事实：首次完整循环不等于最后一圈结束

检查基线为 D:\zhaozibo_071 工作区当前本地内容与对应 #have 的差异，不将整个文件或历史提交都归因于今日新增。主要涉及 TeleportV2Flow、TeleportController、TeleportPresentation、SceneWaitWpStreamingCmd；同时核查原生配置头、生成类型与 UE 5.5.4 本分支源码。

• TeleportV2Flow.ts:1713–1732：Seq2 的 LoopCount=-1；用当前帧小于上次帧判断回绕，第一次回绕后不再监测。HasSeq2PlayedOnce 只表示至少播过一圈，不能代表当前圈结束。
• TeleportV2Flow.ts:2145–2234：Seq3 资源、角色、绑定准备完成后，等待 Seq1 和 Seq2 的首次播放标志，然后进入交接。
• TeleportV2Flow.ts:3730–3917：新 Seq3 播放器有 Play/Pause 预热；正式交接直接 Stop 旧 Seq2、Scrub 新段起点并 Play。当前圈可能在中途截断。
• TeleportV2Flow.ts:49–139、2935–3115、3318–3333：All 解析严格要求三个正长度、不重叠 Shot。旧播放器播放 Seq1/Seq2，新播放器播放第三个 Shot；当前不能直接加第四个 Shot。
• 因此，循环轨道尾部直接放“生成特效”事件会每圈执行；仅检查首次播放标志，同样不能选出最后一次。此项属于新需求缺口，不据此认定今日改动引入回归。

已确认 Teleport01_All.uasset 存在，位于角色 R1012 的 Teleport/01 目录，今日 CL 842533 新增、have/head 均为 #1。尚未在编辑器读取其实际 Shot 边界、事件、绑定 locator 或软引用，也未运行 UE 验收。

2. 已选方案：循环自然收尾 → 独立 Transition → Seq3

语义约定：特效不得在普通循环触发；最后一次 Seq2 正常完成后，进入非循环 Transition，在其中触发并完成约定的特效表现，Transition 结束后才正式开始 Seq3。完成以演出时间轴契约为准，不能默认 Niagara 自动销毁就代表表现结束。

flowchart TD
    A[Seq2 循环等待] --> B{退出条件全部满足?}
    B -- 否 --> A
    B -- 是 --> C[关闭无限循环，继续当前圈]
    C --> D[自然结束通知，一次性消费]
    D --> E[非循环 Transition：轨道触发一次特效]
    E --> F[Transition 完成且特效已触发]
    F --> G[正式交接并启动 Seq3]
    C -. 取消或异常 .-> X[统一恢复和清理，不触发退出特效]
    E -. 取消或异常 .-> X

2.1 资源组织与协议

1. 拟采用四个有序 Shot：Seq1 / Seq2Loop / Transition / Seq3。Transition 是独立非循环子序列，在旧过场容器中沿用 Seq2 假人、场景与相机；结束后才执行原来的真假人切换。不要在其开始时提前移动旧容器或隐藏假人。
2. 将三段范围返回值改为具名四段范围，校验恰好四个有效、不重叠、顺序正确的 Shot；Seq1/Seq2 索引不变，Seq3 从第三段改为第四段，新 Transition 使用第三段。调用方全部一起修改，不能只把 ranges.length===3 改成 4。
3. 所有配置使用 All 的资产必须与代码协议同步迁移。未配置 All 的独立 Seq1/2/3 路径保持原行为，不宣称自动具备 Transition 功能。若该需求也覆盖独立资源路径，需另行补明确的 Transition 配置，不猜路径、不按名字自动兜底。
4. Transition 的开头姿态和相机接 Seq2 尾部，结尾接 Seq3 起点。核查子序列时间偏移、播放速率、相机 Cut、主组件及每个武器槽的绑定；扩展后仍须补齐全部 Shot 的 Player 子轨。
5. 特效事件放在 Transition 内明确的正向播放时刻，建议避开 Scrub 起点及 exclusive End 边界；不得继续放在循环 Seq2 内。Transition 总长度须覆盖特效可见生命周期，结束前显式收束或停止持续特效。

2.2 退出就绪与自然圈尾

就绪条件由流程决定：流送已完成、Seq3 资产/目标角色/换装/绑定已准备、Transition 资源及特效可用、当前 generation/epoch/world/目标角色仍匹配。条件满足只设置一次 ExitArmed，不 Stop、不跳尾、不生成特效。

本分支引擎依据：MovieSceneSequencePlayer.cpp:1282–1384 仅在到达结束边界时判断是否循环，条件为 LoopCount<0 || CurrentNumLoops+NumTimesLooped<=LoopCount。正向播放中，将无限循环设置为 new UE.MovieSceneSequenceLoopCount(0) 后，不会主动改变当前位置；下一次到边界时进入自然结束路径。无需把已累计循环数清零，也不要用 Stop/重新 Play 来清数。

实施时先注册本阶段专属结束回调、更新状态，再通过项目已有的 struct 赋值方式修改 LoopCount。保留 bPauseAtEnd=true 与姿态保持，等待自然结束；puerts 写入是否即时生效必须在编辑器验证。若准备在当前帧回绕之后才就绪，则下一整圈成为最后一圈，这是明确允许的边界语义。

新流程不再使用“帧号回绕”作为最终交接依据。Seq1 正常结束、Seq2 正向从起点播放后，即使第一圈内准备就绪，也可关闭循环，让该圈自然结束，已经满足至少完整播放一圈；不要再强制等待 HasSeq2PlayedOnce 才允许 arm，造成额外一圈。旧标志若用于其他逻辑应分别核查，不在本次方案中盲删。

结束回调必须幂等：MovieSceneSequencePlayer.cpp:575–593 的 FinishPlaybackInternal 会广播 OnFinished；同文件 1407–1432 还会排队结束广播。不得把一次回调等同于一次独立流程。回调入口同步消费状态，再解除自己的委托，不对共享播放器粗暴 Clear 所有监听。切范围/启播应排到当前求值及结束回调派发之后的安全 Tick，使用 TimerSystem 与代次校验，避免旧结束通知误消费新阶段。安全 Tick 的先后顺序须用引擎运行日志验证。

2.3 轨道事件与一次性特效

• 状态只允许 Looping → ExitArmed → Transition → Seq3 → Done；取消可从任意中间状态进入 Aborted，不再回到播放链。
• Transition 真正 Play 前完成范围设置、绑定、起点定位及事件上下文；Scrub、编辑器预览、反向播放、Seq3 的 Play/Pause 预热均不得使该事件通过。
• 拟增加 V2 专用轨道事件入口，携带可核对的播放器/演员上下文。仅当当前流程代次、Transition 阶段、播放器所有者、world、目标句柄均匹配，且 EffectFired=false 时接受。先置为 true，再执行生成，抵御同帧重入和重复事件。
• 现有 TsSceneItemBlueprintFunctionLibrary.GameLevelSequenceEvent 转发到 StoryController 的 Director，尚未证明可用于 V2 独立播放器，不能直接接用。先做一条最小事件验证调用能到达当前 V2 流程，再扩展资产。
• 本方案中“玩家特效”的可见对象明确为 Transition 阶段仍在画面中的 AvatarActor 假人。当前 AddPlayerMaterialEffect 也作用于该假人；不要把事件接到已隐藏的真实玩家。如果策划要求特效跨入真实角色，必须另定转移契约，不能靠遗留特效自然延续。
• Transition 正常结束且 EffectFired 为 true，才允许正式提交 Seq3。漏配/漏触发事件、生成失败或特效资源无效均报错并走统一恢复，不在 Seq3 后补放，不伪造验收成功。
• Transition 使用有界结束等待（资产时长、正向播放速率及加载超时策略），取消/超时/角色销毁/世界切换均清理委托、TimerSystem 句柄、特效句柄、播放器和状态。暂停策略须明确：正常暂停不推进序列；若外层看门狗超时，安全恢复，不绕过 Transition 直接播成功路径。

2.4 实施次序与日志

1. 先在最小编辑器用例验证“播放中 -1 改 0 的圈尾结束”、重复 OnFinished 防护、求值结束后安全切段、V2 轨道事件及 puerts 上下文；该步骤未完成前不批量迁移 All 资产。
2. 调整四段解析/所有调用点、预载及校验；同步制作 Transition 子序列和第四 Shot。Seq3 可后台准备，但不得提前提交可见交接。
3. 在 OnStartDownInternal/ExitLoadLevelAsync 链中插入 arm 与 Transition 等待，将原先 Stop 旧播放器的提交路径移到 Transition 完成之后。
4. 实现阶段令牌与特效一次性入口，把新增等待/资源纳入 ClearSeq3Preparation 和统一失败恢复；不新增全局事件开关。
5. 日志沿用“传送-V2”前缀，记录 generation、阶段、播放器ID、world、角色ID、范围/当前帧、ExitArmed、Seq2Finished、EffectTriggered、TransitionFinished、Seq3Committed、Abort。记录引擎帧号与帧内序号；不能只靠毫秒时间戳区分同帧顺序。

3. 今日相关改动的静态评审

结论：确认 1 项格式规范问题；未确认黑屏或 All 的新增运行时逻辑缺陷。静态审查不能替代资源和画面验收。

静态工具记录：四个业务文件定向 ESLint 返回 7 errors / 154 warnings，退出 1。警告包含拼写、TeleportV2Flow.ts:3808 的 setTimeout 限制；未逐条证明警告由本次差异引入，故不计作新增缺陷。直接执行 tsc -p tsconfig.json --noEmit 退出 0。此前 npm 包装命令也退出 0，但输出未展示传入的 noEmit 参数，不能保证该次没有编译产物；因此补跑了显式 noEmit 命令。未对潜在生成产物做删除或回滚。

4. 测试与验收方法（待执行，不是通过记录）

成功流程应满足事件偏序：Seq2Finished < EffectTriggered < TransitionFinished < Seq3Committed。比较帧号和帧内序号；允许相邻事件在同一引擎帧，但不允许逆序。普通循环与所有预热期间触发数为 0；正常完成的一次流程触发数恰为 1。发生取消的流程不能要求必有特效，但取消后不得再新增触发。

5. P4 状态与评审材料

遵照最新选择：不 sync、不 resolve、不实际 reconcile、不创建 CL、不 submit。所有读取命令显式使用 p4 -c zhaozibo_071。本轮人工编辑仅此站点页面，位于 P4 workspace 外；未归入任何 P4 changelist。

resolve -n 未列出待处理项，只说明当前没有已排队的 resolve，不表示版本已对齐或冲突流程已完成。本轮没有声称已解决所有合并冲突。

default 原有五项保持不动、不纳入：DefaultKuroPuerts.ini、P_SE_Flash.uasset、M_PP_TeleportSolidCover.uasset、STeleportDef.h、FightCameraLogicComponent.ts.orig。后两种特效资源可能与演出有关，但未验证引用及打包依赖，不自动纳入，也不将 .orig 当业务交付。

后续 CL 说明草案（未创建）：【传送】完善 V2 遮挡与 All 序列衔接。说明应列黑屏时序、All 分段及多 Shot 绑定、流送等待清理、对应资产/配置依赖、lint与类型检查结果、UE用例证据和残余限制；Transition 目前只有方案，未实现前不得写进“已完成”列表。本页即方案与评审材料，不额外创建文档副本。

历史试验：现象定位（非当前实现）

以下为旧版切场试验的压缩留档，临时埋点代码当时已还原，原始会话时间为 19:09 与对照组 10:47，未记录完整日期和对应 revision。不得据此断言当前必须固定等待 200/300ms、没有相机保持或落地收尾固定约10ms。当前已有独立准备与相机保持相关实现，应以源码与新的运行证据为准。

历史阶段顺序

Seq2 循环 → 退出 loading/暂停 Seq2 → Seq3 资产就绪 → 演员接管 → 换装等待 → binding 等待 → Seq3 播放/OnFinished → 落地还原。

历史实测耗时

历史落地采样

19:09:04.998 设置 CameraActor_20；05.001 相机压栈释放；08.129 Seq3 OnFinished；08.132 LightDown；08.140 OnEnd；08.637 还原后陷入量采样 −2.15。当时记录显示相机在 Seq3 结束前约3.1s交回。此结论不得替代当前验收。

来源与限制

历史数据来自旧 Client.log 摘要，原页面中的导航锚点保留。本次结论来自当前工作区差异、原生 UE 源码、两项独立审查及工具运行结果；未新增运行时测量。工具证据日期：2026-09-28。