核心组件
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
状态 | 含义 |
|---|---|
| 加载路径数据 / 首个 Act 场景 |
| 校验配置与场景数据 |
| 就绪,等播控 Start |
| 内容演绎中 / 暂停 |
| 叙事完结(Sequence)或播放结束(Single) |
| 出错(内容方可主动 |
关键方法: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 模式的内容数据分两层,正源关系必须分清:
层 | 载体 | 性质 | 什么时候改 |
|---|---|---|---|
骨架层 |
| 由 Update 烘焙生成,不手改 | 场景摆放变动后重跑 Update |
几何层 | 场景中的 | 手摆 / 手画,运行时直接查询 | 关卡制作时 |
FActData 关键字段:
字段 | 单位 | 来源 | 说明 |
|---|---|---|---|
| — | 烘焙 |
|
| 软引用 | 烘焙 | 该 Act 的场景关卡(动态加载) |
| — | 烘焙 | 本 Act 的 Plot 列表(顺序 = 推进顺序) |
| 2D cm | 派生(子 Plot 多边形并集) | 不手画 |
| 2D cm | 派生(ActArea 内缩 100cm) | 不手画([Generate Main Area] 生成) |
| 2D cm | 手画 | 进入区 / 出口点 |
| 世界绝对 cm | 烘焙 / 手配 | 报幕出口指示牌 fallback 用 |
| 秒 | 手配 | Act 级等待 / 总时长(默认 10s / 180s) |
| — / 秒 | 手配 | 转场效果(默认 FadeInOut)/ 闭眼时长(默认 2s) |
FPlotData 关键字段:
字段 | 单位 | 来源 | 说明 |
|---|---|---|---|
| — | 烘焙(PlotName 取 actor label) | 进度校验与日志 |
| 秒 | 手配 | 该 Plot 时长(0 = 无限,等驱动信号) |
| 2D cm | 手画 | Plot 内容区多边形(地面投影);虚空判定与边界可视化数据源 |
| 2D cm | 手画 | 最佳观景区 |
| bool | 手配 | 本 Plot 是否启用 BestView 指引(默认 false) |
| 秒 | 手配 | 引导显示延迟(默认 30; |
| 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 rebakeWarning 提示。场景摆放改动后必须重跑 Update。
内置校验(失败项在结果文本中列出):ActArea 少于 3 点 / 主区域·进入区越出 ActArea / 出口点出界 / Duration ≤ 0 / PlotBoundary 自交 / Plot 重叠 ≥ 90% / ActName 重复 / PlotID 重复。
1.4 Plot 推进的两条驱动轨
Sequence 模式的 Plot 推进完全由内容驱动(管理器不做定时推进):
维度 | 时间轨(一关一 LevelSequence,推荐) | 蓝图轨(替代 / 兜底) |
|---|---|---|
载体 | 每关卡一个带 Event key 的 | 关卡内驱动蓝图(BeginPlay → Delay → |
Signal 名 | 必须是 YomovPlotTransition | 直接调 |
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( |
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 / 重连对齐( |
不适用 | 同场景内连续 Act 推进(本就不需要等);单机 / PIE 无 DS 组件时自我放行 |
日志 |
|
关闭开关 = 各端各切(旧行为)。开关必须全队一致:关闭的端不发请求,开启的端会无限等待它的请求。
自动开演口径
环境 | 行为 |
|---|---|
PIE | 默认不自播( |
非 PIE 打包 | 仅 PackagingType = Test 自动开演;Release / OpenPackage / TrailerPackage / Vgen 一律等播控 |
二、空间与安全边界
2.1 边界组件族
组件 | 用途 | 可视化 | 材质 |
|---|---|---|---|
| Single 模式矩形锚点围栏(玩家活动区) | ✅ |
|
| 场馆级多边形围栏 | ✅ |
|
| 场馆内障碍物围栏 | ✅ | 复用 |
| 纯逻辑矩形边界(Point-in-Polygon 判定) | ❌ 无 mesh | 无 |
| 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 不可见 |
玩家趋近 | 进入 |
Plot 边界(Sequence) | 玩家靠近按距离淡入(30cm);进虚空(出并集)全亮 |
同 Act 切 Plot | 新边界闪亮一下( |
「默认透明 + 趋近淡入」是有意设计,与 Unity
BoundaryReal(常显)有意偏离——避免围栏干扰主体内容。不要当成 bug 改掉。
调试:
方式 | 说明 |
|---|---|
cvar | 强制显示(alpha = 1) |
cvar | 强制隐藏(alpha = 0) |
cvar | ⚠️ 无参命令,硬编码设为 1.0,不接 0.5 参数 |
蓝图 | 自定义透明度(唯一支持任意值的方式) |
蓝图 | 等价 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) |
引导雕像 |
|
引导目标退化链: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 | 内容方自选 |
|
Pawn | 任意本地 Pawn |
|
边界 | 本地实时边界 | 同单人;远程 Avatar 坐标基于边界局部坐标系 |
多人下两条下行链路(1.2.3 起解耦):
链路 | 数据源 | 频率 | 覆盖 |
|---|---|---|---|
同队(同 DS) | DS 由本服 | ~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 端组装 |
| 501 缓存合帧;每周期重建数组(本服 PS 现算 + 跨组 501 快照),条件发布 |
|
上行心跳 |
| 静止期位姿差在阈值内也强制上行一帧——防 DS / Bridge 按数据不变化判离线 |
|
客户端状态回放 |
| 每周期主动重放本地 GS 数组、刷新 LastSeen——replicated 属性无 delta 不推送,数据未变 ≠ 玩家离开 |
|
客户端超时清理 |
| 玩家消失不立即销毁,按最后更新时间 + 超时兜底 |
|
位置插值 |
| 每帧 |
|
跨组航位外推 |
| 低频数据按最近一次变化的速度把目标前移;指数衰减(停下后滑行收敛,不会持续走) | 窗口 |
多层去抖的设计意图:Bridge 一帧可能下发多条不一致的 501(实测玩家数 0/1/2/4 跳),若立即写 GS 会让 CrossContentPlayers 高频抖动 → 客户端 Avatar 反复重建(表现为闪烁)。DS 侧合帧 + 客户端状态回放 + 超时兜底共同解决;航位外推只改善跨组低频数据的观感,不改变数据本身。
内容方零配置。需要主动清理时调
URemotePlayerSubsystem::RemovePlayer(PlayerID)(立即销毁)或ClearAllPlayers()。
本地玩家过滤:Subsystem 通过 AYomovPlayerState::YomovPlayerID 自动过滤本机玩家,不会把本机玩家作为远程 Avatar spawn 出来。
3.4 坐标语义与归一化
项 | 约定 |
|---|---|
FRemotePlayerData.Position 语义 | 边界局部坐标(相对 |
变换位置 | 从 DS 移到客户端:DS 不做 |
Unity → UE 轴重标 |
|
单位 | Unity 米 → UE 厘米(×100) |
旋转 | 走四元数转换( |
上行半球规整 | 采集端做半球规整(与上次同半球,dot ≥ 0),防接收端线性插值遇 q ↔ -q 符号翻转时头朝向沿长弧转圈 |
HMD → 脚偏移 |
|
Avatar attach | spawn 后 attach 到场景 |
跨组同 DS | 跨组与同队统一边界局部坐标 attach(同场馆物理语义)——1.2.3 撤回早期的「世界坐标直通」,载具搬运 / 两组 Act 相位不同也能互看正确 |
跨 DS(跨服)锚定 | 501 条目携带锚定系头位:发送端 |
可见性观察点 | 距离判定的观察点 = 本机头显视点( |
归一化前提:上述「变换从 DS 移到客户端」依赖各端 DA 边界字段完全一致(
MapData/AnchorPoint/AnchorRotationY/ActSizeLength/ActSizeWidth)。任一端不一致 → 该端跨服玩家坐标错位。由内容统一分发同一份 DA 保证,详见 03 §3.3。
Unity→UE 旋转不可逆:
YMC_CoordQuatU2E/E2U不可逆(DLL 内部实现),roundtrip 测试注定失败,非 bug。生产中只需保证单向转换正确。
3.5 多队伍系统
复制相关性策略(两类对象,不要混淆)
复制对象 | 相关性策略 | 效果 |
|---|---|---|
远程 Avatar(经 | 不隔离(默认 | Avatar 数据全量下发;表现层显隐由可见性规则控制 |
AYomovTeamProperty | 同队隔离( | 异队客户端收不到对方 TeamProperty |
设计意图:「多队伍 = Avatar 也按队隔离」是常见误解。复制层设计是 Avatar 数据全广播,只有 TeamProperty(驱动按队切目标场景)按队隔离——防止异队客户端收到对方的 TargetLevel 而切错关。
自定义显隐:在 URemotePlayerSubsystem 的 OnRemotePlayerSpawned / OnRemotePlayerUpdate 回调里用 AreOnSameTeam 判断后切 Visibility。不要改远程玩家相关的 IsNetRelevantFor(那会影响所有队伍属性复制)。内容方自己的道具要按队伍隔离时,不需要改虚函数——按 10 多队伍道具与交互同步 用 Owner relevancy 配置即可。
TeamProperty 数据
每支队伍一个 AYomovTeamProperty(DS spawn,复制到客户端):
属性 | 类型 | 说明 |
|---|---|---|
| FString | 本队 ID(复制) |
| FString / int32 | 按队切目标场景指令 + 指令版本号(1.1.1 起每次 Seek 都递增,同值重切也生效) |
| FString | 当前场景( |
| uint8 | 播放状态(对齐 Unity 枚举) |
| FString | 当前叙事进度(Act / Plot) |
| 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。
切目标场景的两条路径(勿混用)
字段 | 加载方式 | 状态 | 说明 |
|---|---|---|---|
|
| **遗留(有 cook 坑) | 早期路径;cook 后 streaming levels 数量 = 0 坑。新内容不要用** |
|
| 当前推荐(无 cook 坑) | 客户端 OnRep 幂等对齐(断线重连 / 漏切恢复) |
勿混用:两套独立的「按队切目标场景」路径,混用会导致同一客户端两次加载 / 卸载冲突。
中途加入(Join In Progress)
AYomovGameState / AYomovTeamProperty 的字段都是 replicated 属性,晚加入的客户端经初始复制直接拿到当前状态并触发 OnRep——绑回调即可获知「已经开始播放」,无需额外补发订阅。回调逻辑请写幂等。
中途加入的组进度对齐见 §1.6。
3.6 断线与重连语义(1.2.3)
环节 | 机制 | 关键值 |
|---|---|---|
上行心跳 | 客户端位姿 5s 心跳兜底(静止也发一帧);DS 以「最后一次收到上行」判断活跃 |
|
DS 踢除 | 上行停滞超阈值 → DS 踢除该连接(从播控/其他玩家视野消失,对齐 Unity 断连即删);仅 Dedicated Server |
|
客户端探活 | 常驻 1s 检查 DS 回执( |
|
回前台 | 断流已达 DS 踢除阈值时,回前台下一帧直接重连(不等 Guard 周期);未达阈值走探活判定 | — |
握手 | IPv4 字面量地址禁用引擎异步地址解析(首包不再被引擎丢弃),握手 ~1.06s → ~0.06s;域名保留异步解析 | ini 可退回 |
DS→Bridge | 断线后 1s 间隔无限重连;重连成功立即全量重发一帧 msg500 重建 Bridge 缓存 | 1s |
重连后 | 场景级进度对齐(§1.6); | — |
片头 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 总览
单元 | 类型 | 职责 | 挂载 |
|---|---|---|---|
|
| DA + 命令行 + Intent 配置管理、热重载 | 引擎子系统自动 |
|
| 会话管理( | GameInstance 自动 |
| ActorComponent | 流程状态机 + 边界可视化 |
|
|
| 远程 Avatar 自动 spawn / 插值 / 超时清理 | World 子系统自动 |
| World 子系统 | 客户端上行探活(回声停滞判死)+ 回前台快速恢复,判死复用引擎重连链 | World 子系统自动 |
|
| 多队伍管理( | World 子系统自动 |
| World 子系统 | 场景加载 / 卸载( | World 子系统自动 |
| World 子系统 | 叙事数据加载与 Act / Plot 索引推进 | World 子系统自动 |
| World 子系统 | 虚空进出与白名单 | World 子系统自动 |
| World 子系统 | 边界 / 虚空 / 引导 / 报幕的材质与预制配置 | World 子系统自动 |
| World 子系统 | 边界多边形注册与几何运算 | World 子系统自动 |
| World 子系统 | 运行期事件总线(Act/Plot 加载、播控、报幕等) | World 子系统自动 |
| World 子系统 | 报幕牌显示 / 报幕流程 | World 子系统自动 |
| World 子系统 | 路径数据客户端(连路径服务器) | World 子系统自动 |
| 引擎 / GameInstance 子系统 | TCP 连接与协议编解码 | 引擎子系统自动 |
| GameInstance 子系统 | DLL 异步回调桥接回 GameThread | GameInstance 自动 |
蓝图函数库(无需挂组件,蓝图直接调):
函数库 | 职责 |
|---|---|
| 流程 / 配置快捷方法(取 Manager、自动播放、暂停切换、发送播控) |
| Bridge 连接 / 断开 / 发送同步数据快捷方法 |
| 自有数据源驱动远程 Avatar |
| 按 ID / 名称查找 Act / Plot Actor(编辑器与运行时通用) |
| 跨平台读取启播参数(PC 命令行 / Android Intent) |
| 坐标与旋转转换( |
接入决策提示:内容方不需要自己实例化组件——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 | 语义 |
|---|---|
| JSON 全量配置覆盖(支持 URL 转义解码) |
|
|
|
|
|
|
| 演出区尺寸(米) |
| 原点位置(米)与朝向(度) |
| Bridge 地址(客户端上报用) |
| 路径服务器 URL |
| 内容 / 场馆 ID |
| SaaS 鉴权基地址 |
4.3 运行时配置字段速查(DA_DataAsset)
面板可配(EditAnywhere):
字段 | 默认值 | 分类 |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
多人网络新字段说明(1.2.3):
字段 | 含义 |
|---|---|
| 跨 Act 切场景「全队 barrier」开关(见 §1.6),默认开 |
| DS 侧上行超时踢除开关(仅 Dedicated Server)。开启时片头压后台的玩家 15s 后从播控/其他玩家视野消失,回前台自动重连恢复(对齐 Unity 断连即删) |
| 上行停滞踢除阈值(秒),默认 15 = 心跳 ×3 |
| 客户端回声探活阈值(秒),默认 12(小于 DS 踢除值,客户端先自愈)。上行被内容方代码长时间阻断会触发整客户端重连 |
代码内置默认(BlueprintReadWrite,面板不可改):
字段 | 默认值 | 含义 |
|---|---|---|
|
| 虚空(越界保护)总开关 |
|
| Plot 边界近显提示 |
|
| 固定尺寸模式 |
|
| 边界交互 |
|
| SDK 多人路径开关 / 多人模式 |
4.4 常用调试入口
入口 | 用途 |
|---|---|
cvar | 边界强制显隐 / 透明度(Alpha 无参,见 §2.2) |
蓝图 | 同上(透明度支持 0~1) |
蓝图 | 手动触发报幕流程(调试用) |
Console | 热重载配置 |
| 播控指令自动序列发送(连上 Bridge 后自动发 6 种 ControlType)——开发验证用,不发布 |