跳到主要内容

核心组件

06 - YomovUESDKCore 核心组件

插件版本 1.2.3 | 文档版本 1.2.3 | UE 5.3-5.7 面向读者:需要理解插件内部机制的开发者 本篇是纵深参考,按需查阅,不需要通读。接入操作见 03 接入流程;API 签名见 07 接口与事件。


目录​

  • 一、核心运行逻辑

  • 二、空间与安全边界

  • 三、多人同步

  • 四、配置与子系统


一、核心运行逻辑

1.1 FlowControllerComponent(流程状态机)​

UFlowControllerComponent 挂在 AYomovManagerActor 上,是插件流程控制的核心。

状态机:

None → Loading → Validating → Ready → Playing ⇄ Paused → Completed
└──────────────→ Error

状态

含义

Loading

加载路径数据 / 首个 Act 场景

Validating

校验配置与场景数据

Ready

就绪,等播控 Start

Playing / Paused

内容演绎中 / 暂停

Completed

叙事完结(Sequence)或播放结束(Single)

Error

出错(内容方可主动 ReportError(Code, Message) 上报)

关键方法:Initialize / StartPlay / PausePlay / ResumePlay / StopPlay / NextPlot / JumpToActAndPlot(StageName, AreaName) / SetPlayerHeight / GetCurrentState。

1.2.1 起每个动作方法都有对应的 Try* 版本(返回 bool,失败分支带日志)。旧版仍可用但已标记 Deprecated——新代码用 Try*,对照表见 07 §Try 家族。

事件:OnFlowStateChanged(EFlowState) / OnFlowError(ErrorCode, ErrorMessage)。

1.2 叙事数据两层​

Sequence 模式的内容数据分两层,正源关系必须分清:

层

载体

性质

什么时候改

骨架层

UNarrativeDataAsset(StoryActs / EndingAct / SourceScenes)

由 Update 烘焙生成,不手改

场景摆放变动后重跑 Update

几何层

场景中的 AYomovActDescriptor / AYomovPlotBoundary Actor

手摆 / 手画,运行时直接查询

关卡制作时

FActData 关键字段:

字段

单位

来源

说明

ActID / ActName

—

烘焙

ActName 用于 Seek 的 stageName 匹配;跨场景重名会自动加 场景名_ 前缀

SceneAsset

软引用

烘焙

该 Act 的场景关卡(动态加载)

Plots

—

烘焙

本 Act 的 Plot 列表(顺序 = 推进顺序)

ActAreaPoints

2D cm

派生(子 Plot 多边形并集)

不手画

MainAreaPoints

2D cm

派生(ActArea 内缩 100cm)

不手画([Generate Main Area] 生成)

ArrivalAreaPoints / ExitPoint

2D cm

手画

进入区 / 出口点

EntrancePosition / ExitPosition

世界绝对 cm

烘焙 / 手配

报幕出口指示牌 fallback 用

WaitTime / Duration

秒

手配

Act 级等待 / 总时长(默认 10s / 180s)

TransitionEffect / CloseEyeDuration

— / 秒

手配

转场效果(默认 FadeInOut)/ 闭眼时长(默认 2s)

FPlotData 关键字段:

字段

单位

来源

说明

PlotID / PlotName

—

烘焙(PlotName 取 actor label)

进度校验与日志

Duration

秒

手配

该 Plot 时长(0 = 无限,等驱动信号)

PlotBoundary

2D cm

手画

Plot 内容区多边形(地面投影);虚空判定与边界可视化数据源

BestViewAreaPoints

2D cm

手画

最佳观景区

bEnableBestViewArea

bool

手配

本 Plot 是否启用 BestView 指引(默认 false)

BestViewDisplayDelay

秒

手配

引导显示延迟(默认 30;<=0 回退全局)

GuidePoint

2D cm

半自动

引导目标点;编辑器拖 PlotBoundary 时自动 = 顶点平均

运行时兜底:插件找不到配置的 Narrative 资产时,会依次 fallback:配置蓝图资产 → /Game/YOMOVSDK/Config/TestNarrative → null(打 Warning)。内容方应配置自己的 Narrative DA,不要依赖 TestNarrative——它只是空 fallback 资产(插件不分发,缺失可由 InspectorPanel [Autofix] 创建,见 09 §2)。

1.3 烘焙(Update Act Sequence)的正源规则​

SettingPanel → [Update Act Sequence](或 UYomovSequenceEditorLibrary::UpdateNarrativeFromScenes):

  • 依次加载 SourceScenes 列出的场景,扫描其中 ActDescriptor(attach 序 = Act 序)与其子 PlotBoundary(attach 序 = Plot 序),覆盖重写StoryActs

  • 烘焙派生量:ActAreaPoints = Union(子 Plot PlotBoundary)、MainAreaPoints = ActAreaPoints 内缩 100cm

  • AnchorTransform每次重定位到 ActArea 几何中心(XY;旋转/Z 不动)

  • 守卫:PIE 运行中拒绝、Untitled 地图拒绝、dirty 地图先弹保存框;全程事务化可 Undo

运行时正源规则:runtime actor 数据非空才采用,空则回退 DA 兜底。未重烘不致命——日志会出现 bake-derived field empty — run Update rebake Warning 提示。场景摆放改动后必须重跑 Update。

内置校验(失败项在结果文本中列出):ActArea 少于 3 点 / 主区域·进入区越出 ActArea / 出口点出界 / Duration ≤ 0 / PlotBoundary 自交 / Plot 重叠 ≥ 90% / ActName 重复 / PlotID 重复。

1.4 Plot 推进的两条驱动轨​

Sequence 模式的 Plot 推进完全由内容驱动(管理器不做定时推进):

维度

时间轨(一关一 LevelSequence,推荐)

蓝图轨(替代 / 兜底)

载体

每关卡一个带 Event key 的 ULevelSequence 资产 + ALevelSequenceActor(Tags = YomovNarrativeSequence)

关卡内驱动蓝图(BeginPlay → Delay → NextPlot 串联)

Signal 名

必须是 YomovPlotTransition

直接调 NextPlot

Pause / Resume

✅ 正常暂停 / 恢复时间轴

⚠️ Delay 节点不响应 Pause(死等)

Seek 切回恢复

✅ 场景重载后 LSA 自动恢复播放

⚠️ 依赖 Seek 的场景重载机制重建

兜底性

天然兜底(key 到点必发)

需自行加超时兜底

适用

正式内容(节奏与视听对齐)

快速验证 / 纯逻辑推进 / 不连桥推送驱动

时间轨的信号投递机制(关键):

LevelSequence Event key 到点
→ 引擎按名字对各级关卡脚本 FindFunction("YomovPlotTransition")
→ 命中 PersistentMap 关卡蓝图(Parent = AYomovLevelScriptActorBase)
→ 转发给 FlowController::NextPlot

⚠️ EventName 拼错 / 接收层漏配 = 静默丢信号(引擎 FindFunction 找不到不报错)。三个静默失败点:① PersistentMap 关卡蓝图父类未配 AYomovLevelScriptActorBase;② key 的 EventName 拼错;③ key 被拖出 playback 范围。

五个非 PlotTransition 信号函数(AYomovLevelScriptActorBase 上,YomovEyeClose / YomovEyeOpen / YomovOpenComPass / YomovOpenPlotHide / YomovOpenQuit)当前为占位实现(仅打 log),行为后续版本接入。

1.5 Sequencer Director(LSA 接管)​

UYomovSequencerDirectorComponent(AYomovManagerActor 自带)负责 LevelSequence 的生命周期与播放决策:

  • 场景就绪后扫描带 YomovNarrativeSequence Tag 的 LSA 并接管

  • 强制不自动播、不循环、播完 KeepState——误配 bAutoPlay = true 会被纠偏 Stop 并打 Warning(... was auto-playing (bAutoPlay) — stopped)

  • 同场景连续 Act 共用 LSA 连续播放,不重启;跨场景随 sublevel 卸载,新关卡重新接管

  • 本关没有带 Tag 的 LSA 是合法状态(日志 Warning timeline driver absent)——Sequencer 与叙事不强绑定,此时推进交给蓝图轨等其它驱动源

查询接口(BlueprintPure):IsNarrativeStarted() / GetLevelSequenceActor() / IsSequencePlaying()。

1.6 播控与推进行为(Sequence 口径)​

指令

Sequence 行为

Start

Director Play 时间轨;同时上报当前进度到 DS(Narrative progress reported)

Pause / Resume

暂停 / 恢复时间轨(蓝图轨 Delay 不受控)

Seek

见下方

Exit / SetHeight

与通用播控一致;SetHeight 同时触发 BodyScale 重算

Seek(切章节)详细行为​

播控 Seek 的 ExtraData 为 {"stageName":"...","areaName":"..."}:

  • DS 按队下发 TargetLevel = stageName + 版本号无条件递增(TargetLevelVersion)→ 客户端 JumpToActAndPlot

  • 版本号机制保证「重切当前章节」也生效(对抗 UE 复制「值不变不触发 OnRep」——1.1.0 旧包同值重切静默无效)

  • areaName当前不参与 Plot 定位(落点 Plot 固定归 0,对齐 Unity 播控 plots[0],字段保留)

  • 跨 Act 跳转:fade 闭眼 → 卸旧场景 → 载目标场景 → 睁眼;同场景 Seek 也走全重载(先卸载等真卸载再装载,对齐 Unity 重载语义——蓝图轨 BeginPlay 链因此能重建)

  • 转场窗口推进冻结:跳转置位 seek-in-flight,期间一切 NextPlot 驱动源被拒绝(日志 NextPlot: deferred),落点稳定后解冻(Seek arrival settled — plot advance unfrozen);30s 超时兜底

  • 玩家位姿:切回后保持相对边界的位姿(不传送到落点区,对齐 Unity Seek 语义;日志 Seek arrival settled without teleport)

  • 报幕产物清理:跳转前删除残留的出口指示牌 / 报幕牌(JumpToActAndPlot: cleaned N curtain-call artifact(s))

中途加入与进度同步​

Plot 推进 → 客户端 Server RPC → DS 按队写 TeamProperty CurrentStage / CurrentArea
(IsValidStageArea 校验 + 同值去重)→ 随 msg 500 上报 Bridge
  • 中途加入:新玩家首个场景就绪后检查本队 CurrentStage——非空且 ≠ 本地当前 Act → 自动跳转对齐组进度(日志 Join snapshot: ... jumping to align);本队无进度记录(从未 Seek)则从首 Act 开始

  • 重连对齐 = 场景级(1.2.3):断线重连 / 重启头显后,进度恢复到本队当前场景的首个 Act、从该场景 Plot0 起播(对齐 Unity LoadStageScene 语义)。对齐先于本地起播上报,避免「重连端从头播 → 覆盖全队进度 → 把未重启的玩家也拉回第一幕」。触发窗口覆盖:重连主路径(TeamProperty 到达)、叙事链晚建、自动开演——三处幂等

  • 客户端监听组进度:GetMyTeamProperty → 绑 OnStageAreaChanged(同帧双到达可能连发两次,消费侧请幂等)

  • ⚠️ 范围 = 同一 DS 存续期:DS 新起 / 重连 Bridge 后不会向 Bridge 拉取当前进度(后续版本)

  • ⚠️ 多人进度 = 每队单值聚合(Last-Write):同队多客户端异值上报时后到覆盖,无逐客户端区分

切场景全队 barrier(1.2.3,bEnableSceneSyncBarrier 默认开启)​

Plot 推进需要跨 Act 且切换场景时,不再各端各切——等全队在线玩家都发出同一目标场景的切换请求后才放行(对齐 Unity BeforeLoadSceneTask waitOtherPlayers=true):

维度

行为

放行条件

全队在线玩家请求一致;DS 即时判定 + 100ms 周期复核后逐个放行

掉线豁免

断线玩家自动移出在线集合,不阻塞其余玩家

等待上限

无(对齐 Unity);超过 30s 打 Warning 供排查

解锁方式

播控 Seek / 重连对齐(JumpToActAndPlot)可打断等待

不适用

同场景内连续 Act 推进(本就不需要等);单机 / PIE 无 DS 组件时自我放行

日志

[SceneBarrier] ready N/M, requests=[...] / approved players=[...]

关闭开关 = 各端各切(旧行为)。开关必须全队一致:关闭的端不发请求,开启的端会无限等待它的请求。

自动开演口径​

环境

行为

PIE

默认不自播(bAutoStartInPIE 默认 false,DA 可开),日志 StartPlay auto-start suppressed (waiting for remote playback control)

非 PIE 打包

仅 PackagingType = Test 自动开演;Release / OpenPackage / TrailerPackage / Vgen 一律等播控


二、空间与安全边界

2.1 边界组件族​

组件

用途

可视化

材质

UAnchorBoundaryComponent

Single 模式矩形锚点围栏(玩家活动区)

✅

M_Boundary_Line

URealBoundaryComponent

场馆级多边形围栏

✅

M_Boundary_Real

UObstacleBoundaryComponent

场馆内障碍物围栏

✅

复用 M_Boundary_Real

UFixedBoundaryComponent

纯逻辑矩形边界(Point-in-Polygon 判定)

❌ 无 mesh

无

UActAreaBoundaryComponent / UPlotAreaBoundaryComponent / UBestViewAreaBoundaryComponent

Sequence 模式的 Act / Plot / 最佳观景区轮廓

✅

见 09 编辑器工具配色说明

边界 mesh:由 UBoundaryMeshComponent 用 ProceduralMesh 生成。

共用手册:Initialize(BoundaryID, Polygon, Height, bWorldSpacePoints) / SetAlpha / SetBoundaryVisible / SetBoundaryMaterial。

⚠️ bWorldSpacePoints 是关键参数:传 true 表示多边形点是世界坐标,false 表示边界局部坐标(随边界 Actor 一起搬动)。ArcadePoly / 障碍物数据是场馆局部形状,必须传 false——传错会导致 Tick 距离查询用错坐标系、边界可见性判定永不满足。修改边界相关代码时务必确认此参数。

边界事件(BlueprintAssignable):OnEnterBoundary / OnExitBoundary / OnNearBoundary(Distance)。

2.2 边界可见性规则​

情形

行为

默认

玩家距边界超过 ShowDistance(Anchor = 30cm / Real = 80cm)→ alpha = 0 不可见

玩家趋近

进入 ShowDistance 内 → 淡入

Plot 边界(Sequence)

玩家靠近按距离淡入(30cm);进虚空(出并集)全亮

同 Act 切 Plot

新边界闪亮一下(Plot boundary flashed,对齐 Unity 再高亮语义;跨 Act 不闪)

「默认透明 + 趋近淡入」是有意设计,与 Unity BoundaryReal(常显)有意偏离——避免围栏干扰主体内容。不要当成 bug 改掉。

调试:

方式

说明

cvar Yomov.Boundary.Show

强制显示(alpha = 1)

cvar Yomov.Boundary.Hide

强制隐藏(alpha = 0)

cvar Yomov.Boundary.Alpha

⚠️ 无参命令,硬编码设为 1.0,不接 0.5 参数

蓝图 DebugSetBoundaryAlpha(0~1)

自定义透明度(唯一支持任意值的方式)

蓝图 DebugShowBoundary() / DebugHideBoundary()

等价 cvar

2.3 虚空(VoidSpace)​

是什么:玩家走在内容区域外(Plot 多边形并集外)时的保护态——隐藏全部场景内容,只留虚空专用天球 / 地面与引导元素,防玩家看到「世界尽头」。

判定:玩家在「激活 Plot 多边形动态并集」之外 = 虚空。

  • 并集 = 当前 Plot ∪ 延迟销毁期内的旧 Plot(见 §2.4)

  • 并集源为空时退化为 ActArea 静态多边形兜底

进入虚空的行为(EnterVoidSpace):

  • 反转白名单:隐藏所有非白名单 Actor(内容方无需给场景对象打 tag)

  • 白名单 8 类:Pawn / PlayerController / PlayerCameraManager / 边界真实 Actor(BRA)/ VoidSpaceActor / 报幕牌 / 出口指示牌 / 引导指示物

  • 显示虚空天球(反向半球 r = 50m)+ 虚空地面圆盘(r = 50m)

  • 走回 Plot 并集内自动恢复(ExitVoidSpace)

保底天光(重要):虚空会隐藏一切灯光,而地图常无 SkyLight → DefaultLit 模型会全黑。AVoidSpaceActor 自带 SkyLight 组件保底(指定引擎灰暗 cubemap,不依赖场景捕获);强度由 DA_BoundaryEffectConfig.VoidSkyLightIntensity 控制(默认 1,0 = 关闭并隐藏组件)。

报幕后虚空为终态:叙事完结进入报幕后,虚空不再自动退出(走回 Plot / Act 区域也不恢复场景)——设计行为;真实边界(白名单)恒可见。播控 Seek 切回章节会重建一切。

2.4 BestView 指引(越界引导)​

是什么:玩家在 Plot 内游玩时,若最佳观景区延迟后仍未就位 / 玩家越界走散,用地面丝带 + 浮动指引点把玩家引导回目标位置。

显示条件(三者同时满足,每帧统一快照判定):

显示 = 引导模式活跃(delay 已过) && 玩家在当前 Plot 内 && 玩家不在 BestView 区内

「Plot 内才显示」是对 Unity 的有意偏离:玩家进虚空(Plot 外)时不显示 BestView 指引,由虚空态与引导丝带接管。

延迟三级解析(取第一个 > 0 的):

场景 PlotBoundary 组件的 BestViewDisplayDelay(细节面板直改即生效)
→ FPlotData 烘焙值 → 全局 BestViewGuideDelaySeconds(默认 30s)

delay 到期只激活「引导模式」,之后显隐由位置持续判定(就位过再离开会重新显示,对齐 Unity 持续判断)——不是一次性触发。

Plot 边界的延迟隐藏与并集融合:

  • 切换 Plot 时旧 Plot 边界不立即消失——等玩家走进新 Plot 后才启动 5s 倒计时销毁

  • 期间两 Plot 多边形重叠时边界 mesh 重建为并集形状,重叠区打通一条连通边界(对齐 Unity)

  • 玩家在新 Plot 前磨蹭时旧边界保留显示,不误触发倒计时

  • 5s 到期后边界收回新 Plot 自己的多边形

指引视觉三件套(都挂边界真实 Actor 下):

元素

形态

引导丝带

地面 ProceduralMesh 丝带,从引导点到玩家水平投影,材质 UV 滚动自驱流动感

引导点 billboard

面向相机的浮动箭头(上下浮动 ±23cm、周期 2s)

引导雕像

DA_BoundaryEffectConfig.PlotReturnGuideStatuePrefab 预制(进虚空时的回归目标标记)

引导目标退化链:GuidePoint → BestView 质心 → PlotBoundary 质心 → 世界原点。

设计立场:SDK 引导是玩家越界后的兜底,不是首选。设计上优先用 NPC 表演与内容原生交互引导玩家(见 05 §3)。

2.5 报幕(CurtainCall)​

触发:最后一个 Act 的最后一个 Plot 放尽 → Narrative complete → CurtainCall。

流程(DLL 状态机驱动,每步有日志):

停所有音频 → 白屏 fade(闭眼)→ 抑制内容边界(真实边界保留可见)
→ 进虚空 → 加载出口指示牌 → 显示报幕牌 → Complete(虚空终态)

出口指示牌:DA_BoundaryEffectConfig.ExitIndicatorPrefab(= BP_ExitIndicator:浮动箭头 + "Exit 离场出口" 文字 + 向玩家引导线 + 循环提示音)。

位置来源链:场景 ActDescriptor ExitPoint → FActData.ExitPosition → 都为零用 BRA 位置。

报幕牌:DA_BoundaryEffectConfig.AnnouncementPrefab(品牌版式,画布 500×250,面向相机 billboard)。

文字 fallback 链:事件传入文字 → 结尾 Act 的 ActName → AnnouncementDefaultText(默认 "剧终")。

二次报幕:DLL 状态机停在 Complete 终态且无 Reset API——再次触发报幕时插件自动检测非 Idle 并重建 handle(日志 DLL state machine not Idle ... recreating handle for re-entry),二次报幕正常工作。

报幕终态不清播放标记(对齐 Unity PlayEffect 自动开演)——播控切回章节后时间轨自动恢复播放。

残留清理:报幕产物 spawn 在持久世界(不随 sublevel 卸载)——切章节与二次报幕前插件自动删除全部出口指示牌 / 报幕牌,防残留叠加。


三、多人同步

3.1 消息模型(500 / 501 / 503)​

msg

方向

频率

内容

500

UE → Bridge

~100ms

本队伍本地玩家位姿(头/手位置与姿态)+ 当前关卡 / 阶段

501

Bridge → UE

事件驱动

跨服 / 跨内容玩家数据(其他内容队伍的玩家位姿、队伍、Avatar 信息)

503

双向

事件驱动

播控指令:1 = Pause, 2 = Resume, 3 = Seek, 4 = Exit, 5 = Start, 6 = SetHeight

协议格式:Header(16B)+ Protobuf body。权威 schema 见插件包内 ThirdParty/YomovCore/include/YomovCore.h。

DS 不直接与播控系统通信;播控指令经 Bridge 用 msg 503 下发,DS 转发给客户端。

单人 vs 多人数据通道:

维度

单人(无 DS)

多人(有 DS)

数据通道

仅本地

本地 → DS(UE 复制)→ Bridge(TCP 500)→ 其他内容(Bridge 501 下发)

GameMode

内容方自选

BP_YomovDSGameMode / AYomovDSGameModeTemplate

Pawn

任意本地 Pawn

AYomovPawn(ctor 强制 AutoPossessPlayer = Disabled)

边界

本地实时边界

同单人;远程 Avatar 坐标基于边界局部坐标系

多人下两条下行链路(1.2.3 起解耦):

链路

数据源

频率

覆盖

同队(同 DS)

DS 由本服 PlayerState 直接组装

~10Hz(100ms 重建发布)

本队玩家位姿,不依赖 Bridge 501

跨组 / 跨内容

Bridge msg 501 快照

~1.5Hz(Bridge 广播周期,业务侧决定)

其他队伍 / 其他内容玩家位姿

旧版同队数据也挂在 501 上:Bridge 停推 501 时同队 avatar 会「冻结 / 消失」且仅 ~1.5Hz。1.2.3 起同队与 501 解耦(DS 单端升级即生效,旧客户端 APK 同样受益);跨组仍走 501,低频由客户端航位外推补偿(见 §3.3)。

3.2 跨服玩家数据流​

Bridge ──msg 501 (FSyncContentData, 含 Teams[] / Players[])──▶
DS UYomovDSServerComponent::OnSyncContentDataReceived
│ ⚠️ 不立即写 GS —— 缓存到 PendingSyncData_(合并一帧内多条抖动的 501)
▼
DS ConsumePendingSync 每 SyncInterval (100ms) 重建:
│ - 本服(同 DS)玩家:从本服 PlayerState 现算,恒为最新,不依赖 501
│ - 跨组玩家:沿用最近一份 501 快照(无新 501 时保持不变)
│ - 有新 501 / 有条目 / 需清空已发布条目时才发布(全空不空转广播)
▼
DS AYomovGameState::CrossContentPlayers (TArray<FRemotePlayerData>)
│ DOREPLIFETIME + OnRep_CrossContentPlayers → Broadcast
▼
Client URemotePlayerSubsystem::HandleCrossContentPlayersUpdated
│ - 遍历 CrossContentPlayers,按 PlayerID diff
│ - 新增 → SpawnOrUpdatePlayer(ResolveAvatarClass 选类)
│ - 已存在 → 更新位置 / 旋转(Tick 内插值)
│ - 消失 → 交给 Tick 的 CleanupStalePlayers 按超时清理
▼
Client 场景中出现远程 Avatar(位置每帧插值)

同队不再被 501 断流冻住:本服玩家条目每 100ms 现算并发布;玩家被踢光后数组在 100ms 内清空(不再保留最后一次 501 触发的空快照)。Bridge 只影响跨组条目。

3.3 去抖与插值(内置常量)​

层级

位置

机制

常量

DS 端组装

UYomovDSServerComponent::OnSyncContentDataReceived + ConsumePendingSync

501 缓存合帧;每周期重建数组(本服 PS 现算 + 跨组 501 快照),条件发布

SyncInterval = 100ms

上行心跳

UYomovReplicationComponent

静止期位姿差在阈值内也强制上行一帧——防 DS / Bridge 按数据不变化判离线

BodyHeartbeatInterval = 5s

客户端状态回放

URemotePlayerSubsystem::Tick

每周期主动重放本地 GS 数组、刷新 LastSeen——replicated 属性无 delta 不推送,数据未变 ≠ 玩家离开

StateReplayInterval = 1s

客户端超时清理

CleanupStalePlayers

玩家消失不立即销毁,按最后更新时间 + 超时兜底

CleanupTimeout = 2.0f 秒

位置插值

URemotePlayerSubsystem::Tick

每帧 VInterpTo / RInterpTo 平滑;距离过大直接传送防拉弓

InterpSpeed = 10.0f,TeleportThresholdSq = 500² cm²

跨组航位外推

URemotePlayerSubsystem::Tick

低频数据按最近一次变化的速度把目标前移;指数衰减(停下后滑行收敛,不会持续走)

窗口 0.5s、衰减 τ = 0.3s、限速 500cm/s

多层去抖的设计意图:Bridge 一帧可能下发多条不一致的 501(实测玩家数 0/1/2/4 跳),若立即写 GS 会让 CrossContentPlayers 高频抖动 → 客户端 Avatar 反复重建(表现为闪烁)。DS 侧合帧 + 客户端状态回放 + 超时兜底共同解决;航位外推只改善跨组低频数据的观感,不改变数据本身。

内容方零配置。需要主动清理时调 URemotePlayerSubsystem::RemovePlayer(PlayerID)(立即销毁)或 ClearAllPlayers()。

本地玩家过滤:Subsystem 通过 AYomovPlayerState::YomovPlayerID 自动过滤本机玩家,不会把本机玩家作为远程 Avatar spawn 出来。

3.4 坐标语义与归一化​

项

约定

FRemotePlayerData.Position 语义

边界局部坐标(相对 BoundaryRealActor,非世界坐标)——上行(msg 500)与下行(msg 501)同一语义

变换位置

从 DS 移到客户端:DS 不做 InverseTransformPosition(DS 无 YomovManagerActor),客户端 attach 到本端 BRA 后用相对位置写入

Unity → UE 轴重标

(X, Y, Z) → (Z, X, Y),由 UCoordinateConverter 完成

单位

Unity 米 → UE 厘米(×100)

旋转

走四元数转换(ConvertUnityQuaternionToUE / ConvertUEQuaternionToUnity),不经 Rotator 规格化(避免 yaw 跨 ±180° 时 quat 整体符号翻转)

上行半球规整

采集端做半球规整(与上次同半球,dot ≥ 0),防接收端线性插值遇 q ↔ -q 符号翻转时头朝向沿长弧转圈

HMD → 脚偏移

ARemotePlayerCharacter.HeadToFootOffset:远程头显位置到 Actor 原点的 Z 偏移,Subsystem 每帧把目标 Z 减此值让脚着地

Avatar attach

spawn 后 attach 到场景 BoundaryRealActor(KeepWorldTransform),保证边界整体移动时 Avatar 跟随

跨组同 DS

跨组与同队统一边界局部坐标 attach(同场馆物理语义)——1.2.3 撤回早期的「世界坐标直通」,载具搬运 / 两组 Act 相位不同也能互看正确

跨 DS(跨服)锚定

501 条目携带锚定系头位:发送端 Anchor = ActBase⁻¹ × World,接收端 World = ActBase × Anchor。各 DS 世界无共同真值,锚定到 Act 基准(场景装载时的世界快照)是两端唯一公共语义——载具 / Plot 推进造成的边界位移因此不进入坐标

可见性观察点

距离判定的观察点 = 本机头显视点(GetPlayerViewPoint;无效帧回落 Pawn 根)——Pawn 根被 MoveBoundaryWithPawn 钉在边界/Act 原点,不能代表玩家物理位置

归一化前提:上述「变换从 DS 移到客户端」依赖各端 DA 边界字段完全一致(MapData / AnchorPoint / AnchorRotationY / ActSizeLength / ActSizeWidth)。任一端不一致 → 该端跨服玩家坐标错位。由内容统一分发同一份 DA 保证,详见 03 §3.3。

Unity→UE 旋转不可逆:YMC_CoordQuatU2E / E2U 不可逆(DLL 内部实现),roundtrip 测试注定失败,非 bug。生产中只需保证单向转换正确。

3.5 多队伍系统​

复制相关性策略(两类对象,不要混淆)​

复制对象

相关性策略

效果

远程 Avatar(经 CrossContentPlayers)

不隔离(默认 Replicated,全广播)

Avatar 数据全量下发;表现层显隐由可见性规则控制

AYomovTeamProperty

同队隔离(IsNetRelevantFor 只对同队客户端返回 true)

异队客户端收不到对方 TeamProperty

设计意图:「多队伍 = Avatar 也按队隔离」是常见误解。复制层设计是 Avatar 数据全广播,只有 TeamProperty(驱动按队切目标场景)按队隔离——防止异队客户端收到对方的 TargetLevel 而切错关。

自定义显隐:在 URemotePlayerSubsystem 的 OnRemotePlayerSpawned / OnRemotePlayerUpdate 回调里用 AreOnSameTeam 判断后切 Visibility。不要改远程玩家相关的 IsNetRelevantFor(那会影响所有队伍属性复制)。内容方自己的道具要按队伍隔离时,不需要改虚函数——按 10 多队伍道具与交互同步 用 Owner relevancy 配置即可。

TeamProperty 数据​

每支队伍一个 AYomovTeamProperty(DS spawn,复制到客户端):

属性

类型

说明

TeamID

FString

本队 ID(复制)

TargetLevel / TargetLevelVersion

FString / int32

按队切目标场景指令 + 指令版本号(1.1.1 起每次 Seek 都递增,同值重切也生效)

CurrentSceneName

FString

当前场景(LoadLevelInstance 动态加载路径,推荐)

PlaybackState

uint8

播放状态(对齐 Unity 枚举)

CurrentStage / CurrentArea

FString

当前叙事进度(Act / Plot)

RemoteHeight / RemoteExitVersion

float / int32

高度偏移 / 退出指令版本

事件(BlueprintAssignable):OnPlaybackStateChanged / OnStageAreaChanged(Stage, Area)。

客户端取本队实例:UYomovBlueprintLibrary::GetMyTeamProperty(WorldContext)——TeamProperty 是复制进来的 Actor,客户端没有注册表可查,必须用此 BlueprintPure(TeamID 未定或尚未复制到达时返回 null,蓝图侧 0.2s 延迟重试)。

⚠️ SpanTimeMs(队伍在当前 (Stage, Area) 的滞留毫秒)不复制客户端——DS 权威累计、只随 msg 500 上报 Bridge 做运营统计。客户端读不到,进度监听请用 OnStageAreaChanged。

切目标场景的两条路径(勿混用)​

字段

加载方式

状态

说明

TargetLevel

LoadStreamLevel(streaming levels,预配)

**遗留(有 cook 坑)

早期路径;cook 后 streaming levels 数量 = 0 坑。新内容不要用**

CurrentSceneName

LoadLevelInstance(动态加载)

当前推荐(无 cook 坑)

客户端 OnRep 幂等对齐(断线重连 / 漏切恢复)

勿混用:两套独立的「按队切目标场景」路径,混用会导致同一客户端两次加载 / 卸载冲突。

中途加入(Join In Progress)​

AYomovGameState / AYomovTeamProperty 的字段都是 replicated 属性,晚加入的客户端经初始复制直接拿到当前状态并触发 OnRep——绑回调即可获知「已经开始播放」,无需额外补发订阅。回调逻辑请写幂等。

中途加入的组进度对齐见 §1.6。

3.6 断线与重连语义(1.2.3)​

环节

机制

关键值

上行心跳

客户端位姿 5s 心跳兜底(静止也发一帧);DS 以「最后一次收到上行」判断活跃

BodyHeartbeatInterval = 5s

DS 踢除

上行停滞超阈值 → DS 踢除该连接(从播控/其他玩家视野消失,对齐 Unity 断连即删);仅 Dedicated Server

UplinkTimeoutSeconds = 15s

客户端探活

常驻 1s 检查 DS 回执(PlayerState.LastBodySyncServerTime);回声停滞超阈值 → 主动走引擎重连链

UplinkEchoStallSeconds = 12s

回前台

断流已达 DS 踢除阈值时,回前台下一帧直接重连(不等 Guard 周期);未达阈值走探活判定

—

握手

IPv4 字面量地址禁用引擎异步地址解析(首包不再被引擎丢弃),握手 ~1.06s → ~0.06s;域名保留异步解析

ini 可退回

DS→Bridge

断线后 1s 间隔无限重连;重连成功立即全量重发一帧 msg500 重建 Bridge 缓存

1s

重连后

场景级进度对齐(§1.6);?closed 入口世界 + DS 世界两次 LoadMap 是结构性下限(~0.7–0.8s)

—

片头 APK 压后台 = 预期断线:播控片头把内容 APK 压后台期间上行停发,DS 15s 后踢除,回前台自动快速重连(重连链设计目标 ~1s,旧版实测 ~2.5s)。这是对齐 Unity 的既定业务语义,不是故障。需要片头期保留在线可关 bEnableUplinkTimeoutKick(代价:片头期间其他玩家屏幕上该 avatar 不消失,与 Unity「断线即移除」不一致)。 握手 ini 覆盖(可选,默认无需配置):[/Script/YomovUESDKCore.YomovIpNetDriver] 段 HandshakeResendInterval=0.25(夹取 [0.1, 1.0],只调小不调大)、KeepAddressResolution=True(退回引擎异步解析)。


四、配置与子系统

4.1 Subsystem 总览​

单元

类型

职责

挂载

UConfigManagerSubsystem

UEngineSubsystem

DA + 命令行 + Intent 配置管理、热重载

引擎子系统自动

UYomovSessionSubsystem

UGameInstanceSubsystem

会话管理(AYomovManagerActor 自动 spawn / 清理)

GameInstance 自动

UFlowControllerComponent

ActorComponent

流程状态机 + 边界可视化

AYomovManagerActor 自动挂

URemotePlayerSubsystem

UTickableWorldSubsystem

远程 Avatar 自动 spawn / 插值 / 超时清理

World 子系统自动

UYomovConnectionGuardSubsystem

World 子系统

客户端上行探活(回声停滞判死)+ 回前台快速恢复,判死复用引擎重连链

World 子系统自动

UYomovTeamSubsystem

UWorldSubsystem

多队伍管理(AreOnSameTeam / FindTeamProperty)

World 子系统自动

USceneManagerSubsystem

World 子系统

场景加载 / 卸载(LoadLevelInstance 路径)

World 子系统自动

UActPlotSubsystem

World 子系统

叙事数据加载与 Act / Plot 索引推进

World 子系统自动

UVoidSpaceManager

World 子系统

虚空进出与白名单

World 子系统自动

UBoundaryEffectManager

World 子系统

边界 / 虚空 / 引导 / 报幕的材质与预制配置

World 子系统自动

UBoundarySubsystem

World 子系统

边界多边形注册与几何运算

World 子系统自动

UEventBusSubsystem

World 子系统

运行期事件总线(Act/Plot 加载、播控、报幕等)

World 子系统自动

UAnnouncementManager / UCurtainCallManager

World 子系统

报幕牌显示 / 报幕流程

World 子系统自动

UPathClientSubsystem

World 子系统

路径数据客户端(连路径服务器)

World 子系统自动

UTCPClientSubsystem / UProtobufSubsystem

引擎 / GameInstance 子系统

TCP 连接与协议编解码

引擎子系统自动

UAsyncTaskSubsystem

GameInstance 子系统

DLL 异步回调桥接回 GameThread

GameInstance 自动

蓝图函数库(无需挂组件,蓝图直接调):

函数库

职责

UYomovBlueprintLibrary

流程 / 配置快捷方法(取 Manager、自动播放、暂停切换、发送播控)

UBridgeSDKBlueprintLibrary

Bridge 连接 / 断开 / 发送同步数据快捷方法

UBridgeRemotePlayerLibrary

自有数据源驱动远程 Avatar

UYomovNarrativeActorLibrary

按 ID / 名称查找 Act / Plot Actor(编辑器与运行时通用)

ULaunchParamsHelper

跨平台读取启播参数(PC 命令行 / Android Intent)

UCoordinateConverter

坐标与旋转转换(UObject + 静态方法,调用方式同函数库)

接入决策提示:内容方不需要自己实例化组件——DS 端挂两个核心组件到 GameMode,客户端 AYomovManagerActor 自动挂 FlowController,子系统自动注册。内容方主要工作是:① 配置 DA ② 选 Avatar BP ③ 响应播控事件。

4.2 配置正源与热重载​

  • 正源唯一:运行时配置以 DA_DataAsset(经 UConfigManagerSubsystem)为正源。不要另开 ini / 全局变量旁路。

  • 热重载:编辑器 Console 执行 Yomov.Config.Reload(= ReloadConfig()),或 SettingPanel 点 [Save & Apply](1.2.3 起先落盘再重载)——两者都会重载 ConfigManager + 虚空 / 边界效果管理器,无需重启编辑器 / PIE。

  • 配置缺失的兜底:配置未加载时按类默认值兜底并打一次性 Warning,不静默失效。

  • 命令行参数:-jsonData= 走 JSON 全量覆盖;其余 key(-LBEPathType= / -PackagingType= / -MultiplayerSync= / -ActSizeLength= / -originX= / -BridgeServerIP= / -ContentID= 等)逐条 FParse::Value。跨平台读取统一入口是 ULaunchParamsHelper(PC 走命令行,Android 走 Intent Extras)。

命令行 key

语义

-jsonData=

JSON 全量配置覆盖(支持 URL 转义解码)

-LBEPathType=

Single / Sequence

-PackagingType=

Test / OpenPackage / Release / TrailerPackage / Vgen

-MultiplayerSync=

SinglePlayer / TeamPlayer / NoTeam / NoTeamPlayer

-ActSizeLength= / -ActSizeWidth=

演出区尺寸(米)

-originX= / -originY= / -originRotation=

原点位置(米)与朝向(度)

-BridgeServerIP= / -BridgeServerPort=

Bridge 地址(客户端上报用)

-PathServerURL=

路径服务器 URL

-ContentID= / -VenueID=

内容 / 场馆 ID

-url=

SaaS 鉴权基地址

4.3 运行时配置字段速查(DA_DataAsset)​

面板可配(EditAnywhere):

字段

默认值

分类

LBEPathType / AnchorPoint / AnchorRotationY / ActSizeLength / ActSizeWidth / bShowBoundary

Single / (0,0,0) / 0 / 5.0 / 5.0 / true

YOMOV|Path

DefaultAvatarClass / NonTeamAvatarClass / PawnClass

nullptr × 3

YOMOV|Avatar

RemotePlayerVisibleDistance / bSameTeamAlwaysVisible / AvatarDefaultBodyHeight

500 / true / 170

YOMOV|Avatar

InitialSceneName / bEnableSceneSyncBarrier

LBEPath-SingleTest / true

YOMOV|SceneTransition

bEnableUplinkTimeoutKick / UplinkTimeoutSeconds / UplinkEchoStallSeconds

true / 15 / 12

YOMOV|Net

BuildType

Test

YOMOV|Build

多人网络新字段说明(1.2.3):

字段

含义

bEnableSceneSyncBarrier

跨 Act 切场景「全队 barrier」开关(见 §1.6),默认开

bEnableUplinkTimeoutKick

DS 侧上行超时踢除开关(仅 Dedicated Server)。开启时片头压后台的玩家 15s 后从播控/其他玩家视野消失,回前台自动重连恢复(对齐 Unity 断连即删)

UplinkTimeoutSeconds

上行停滞踢除阈值(秒),默认 15 = 心跳 ×3

UplinkEchoStallSeconds

客户端回声探活阈值(秒),默认 12(小于 DS 踢除值,客户端先自愈)。上行被内容方代码长时间阻断会触发整客户端重连

代码内置默认(BlueprintReadWrite,面板不可改):

字段

默认值

含义

bUseVoid

true

虚空(越界保护)总开关

bIsNearDisplayPlotBoundary

true

Plot 边界近显提示

bFixedSize

true

固定尺寸模式

bBoundaryInteraction

true

边界交互

bUseSDKMultiplayer / MultiplayerMode

true / SinglePlayer

SDK 多人路径开关 / 多人模式

4.4 常用调试入口​

入口

用途

cvar Yomov.Boundary.Show / Hide / Alpha

边界强制显隐 / 透明度(Alpha 无参,见 §2.2)

蓝图 DebugShowBoundary / DebugHideBoundary / DebugSetBoundaryAlpha

同上(透明度支持 0~1)

蓝图 DebugTriggerCurtainCall()

手动触发报幕流程(调试用)

Console Yomov.Config.Reload

热重载配置

UControlSimulatorComponent

播控指令自动序列发送(连上 Bridge 后自动发 6 种 ControlType)——开发验证用,不发布