跳到主要内容

FAQ

插件版本 1.2.3 | 文档版本 1.2.3 | UE 5.3-5.7 常见问题、验收日志字典、发版前检查清单、联调工具、已知限制。 排障第一原则:先看日志判阶段,不要先改代码。


目录​

    1. 常见问题
    1. 验收日志字典(联调必看)
    1. 发版前检查清单
    1. 测试软件与联调工具
    1. 已知限制

1. 常见问题​

安装与编译​

Q:插件安装后编译报错?

确认 UE 版本为 5.3 或更高,且插件包目录与项目引擎版本匹配(YomovUESDKCore-5.4/ 配 5.4 引擎)。尝试删除项目的 Intermediate/ 和 Binaries/ 目录后,重新右键 .uproject 生成项目文件。

Q:打开 .sln 进 Visual Studio 生成解决方案出错?

现象

根因

处理

右键 .uproject → Generate VS project files 卡住

.uproject 的 EngineAssociation 错

核对 EngineAssociation(版本号或源码版 GUID)

.sln 没生成

UBT 报错

删 Intermediate/Binaries/Saved/ 后重试

VS 打开后「生成解决方案」失败

模块 Build.cs 依赖错

看 UBT 输出日志定位缺失依赖(如漏加 YomovUESDKCore 模块依赖)

VS 能生成但跑起来崩

Runtime DLL 缺失

确认 Binaries/Win64/YomovCore.dll 被拷贝到可执行目录

消费方 C++ 调业务 API 报 LNK2019 __imp_...

binary 包导入库不含业务符号(跨模块限制)

改用 Blueprint 接入 / YomovCore C API(见 02 §5)/ 换源码包

Q:UE 5.3 源码引擎打开项目报 "ClangRTFM x64 must be installed"?

这是 UE 5.3 源码引擎的已知问题(非本插件造成)。UE 5.3 源码默认启用 Verse 语言(bUseVerse = true),需要 Epic 内部编译器 verse-clang-cl.exe(位于 NotForLicensees 文件夹,公开源码不含)。UE 5.4+ 已修复;安装版(Launcher)引擎不受影响。

解决(二选一):

  • 方案 1(推荐):升级到 UE 5.4 或更高版本

  • 方案 2(坚持 5.3 源码):修改引擎 UBT 源码绕过:

    1. 编辑 <UE源码根>/Engine/Source/Programs/UnrealBuildTool/Platform/Windows/UEBuildWindows.cs,找到约 952 行的 if (Target.bUseAutoRTFMCompiler) { Target.WindowsPlatform.Compiler = WindowsCompiler.ClangRTFM; },注释掉整个 if 块

    2. 在注释下方加一行:Target.WindowsPlatform.Compiler = WindowsCompiler.VisualStudio2022;

    3. 跑任意 Build.bat <Target> Win64 Development -Project=<你的项目>.uproject,UBT 会自动检测源码变化并重编 UBT(约 1 分钟,不需重编整个引擎)

✅ 本插件 binary 包已在 UE 5.3.2 源码引擎下验证通过。ClangRTFM 是引擎层问题,按上述任一方案解决后插件即可正常使用。

配置​

Q:DA_CommandLineArgs 和 DA_DataAsset 有什么区别?

DA_CommandLineArgs 管理运行时连接与身份参数,部分字段(如 BridgeServerIP / BridgeServerPort / ContentID)在正式运行时会被命令行参数 / 启动器配置覆盖。DA_DataAsset 管理内容运行配置,完全由内容方控制。详见 02 §2。

Q:DataAsset 修改后不生效?

  1. 先确认 DA 本身存在且资产类正确:菜单 YOMOV SDK → InspectorPanel 自检——缺失或类不匹配会红显,点 [Autofix] 一键创建到规范路径(Content/YOMOVSDK/Config/)。放在别的位置的 DA 不会被加载

  2. 在编辑器 Console 中执行 Yomov.Config.Reload 热重载(或 SettingPanel 点 [Save & Apply],1.2.3 起先落盘再重载,未保存的改动不会再被磁盘旧值回滚),无需重启

  3. 若仍不生效,确认该字段是面板可配的——bUseVoid / bIsNearDisplayPlotBoundary / bFixedSize / bBoundaryInteraction 等字段是代码内置默认值,面板不可改(清单见 06 §4.3)

Console 命令仅在编辑器 / PIE / Development 运行时可用,Shipping 打包后不开放。

Q:蓝图中如何获取配置?

Get Engine Subsystem → 选 ConfigManagerSubsystem → 直接读属性。需要全部字段时调 GetCommandLineArgsData() 拿完整数据对象。

Q:怎么读取播控系统下发的启播参数?

用 ULaunchParamsHelper(跨平台统一入口:Windows 走命令行,Android 走 Intent Extras):GetContentID() / GetTeamID() / GetPlayerID() / GetServerAddress(),或通用 GetLaunchParamString(Key)。

连接与播控​

Q:连接桥接服务器失败?

  1. 检查 DA_CommandLineArgs 中的 BridgeServerIP 和 BridgeServerPort

  2. 确认桥接服务器进程已启动

  3. 检查防火墙是否放行了对应端口

  4. DS 部署场景:DS 连 Bridge 的地址由客户端 Server_Login 上报——确认客户端 DA 的 BridgeServerIP 正确(自动检测本机 IP 可能命中虚拟网卡如 198.18.0.1)。⚠️ -BridgeIP= 命令行是历史遗留无效参数,DS 进程不解析它

Q:BridgeEventReceiver 事件不触发?

BridgeEventReceiver 通过 UTCPClientSubsystem(引擎级 Subsystem 单例)连 Bridge,不依赖 YomovManagerActor。请检查:

  1. DA_CommandLineArgs 中的服务器地址配置是否正确

  2. bAutoConnectOnBeginPlay 是否为 true(DS 端此 Actor 已让位,不再自动连接——见 03 §流程 B)

  3. 不要同时挂 BridgeEventReceiver 与 BridgeTestComponent 做对比测试——两者共用同一条 TCP 连接(同一个 UTCPClientSubsystem 单例),会互相干扰

Q:单人 standalone PIE 下怎么会看到远程 Avatar?

这是预期行为,不是 bug。BP_BridgeEventReceiver 收到 Bridge 下发的 msg 501(跨服玩家数据)后,直接调用 URemotePlayerSubsystem::SpawnOrUpdatePlayer(不经 GameState.CrossContentPlayers)spawn 远程 Avatar。这条链路在 standalone 单人 PIE 下同样工作(只要有 BridgeServer + ContentSimulator 推送 501),并不要求必须开 DS。

注意:这条 standalone 触发链路与多人 DS 的远程玩家链路是两条不同路径——DS 链路走复制(AYomovGameState::CrossContentPlayers 由 DS 复制到客户端),standalone 链路是 BP_BridgeEventReceiver 收到 501 后直接调 URemotePlayerSubsystem。

若内容方不希望 standalone 下触发 Avatar spawn(例如单人项目接入了插件但不需要远程可视化),可在 BP_BridgeEventReceiver 蓝图里按 NetMode 判断:standalone 下不把 501 数据传给 URemotePlayerSubsystem。

Q:如何发送播控指令?

C++ 用 BridgeController->SendControlCommand(ControlType, JsonData),蓝图用 SendBridgeCommand 节点。

ControlType:1 = Pause, 2 = Resume, 3 = Seek, 4 = Exit, 5 = Start, 6 = SetHeight。

Q:BridgeTestComponent 可以用于正式发布吗?

不可以。它只用于开发验证桥接通信。1.2.1 起它不再出现在 Add Component 列表(测试组件不对外暴露),作为 C++ 参考实现保留——正式接入请用 BP_BridgeEventReceiver(蓝图,见 02 §4)或直接调 UBridgeServerControllerComponent。

Q:播控第二次切回同一个章节没反应?

插件 < 1.1.1 的已知限制(UE 复制「值不变不触发 OnRep」导致同值 TargetLevel 静默无效)。1.1.1 起已修:Seek 指令带版本号(TargetLevelVersion 每次递增),重切当前章节正常触发。升级插件即可。

Q:自研播控 / 模拟器发 Seek 不生效?

检查 ExtraData JSON 的字段名:必须是 {"stageName":"...","areaName":"..."}(对齐 Unity ChapterSwitchData)。旧写法 stage / area静默失效(不报错、不生效)。

路径与叙事​

Q:Sequence 模式 Plot 不推进 / 时间轨没反应?

三个静默失败点(引擎 FindFunction 找不到不报错,拼错也没提示):

  1. PersistentMap 的关卡蓝图父类不是 AYomovLevelScriptActorBase

  2. LevelSequence Event key 的 EventName 拼错(必须是 YomovPlotTransition)

  3. key 被拖出 playback 范围

排查先看日志:[SeqDirector] Adopted level LSA 是否出现 → [SeqSignal] YomovPlotTransition -> NextPlot 是否出现。详见 03 §2.4。

Q:日志出现 bake-derived field empty — run Update rebake?

场景摆放改动后没重跑烘焙。运行时会用 DA 兜底值(不致命),但建议立即回 SettingPanel 点 [Update Act Sequence]。详见 09 §5.2。

Q:怎么实现移动载具(如观光车、电梯)效果?

Single 模式下:VRPawn 跟随真实边界,真实边界跟随 StationaryActUnitMarker 锚点——因此只需在蓝图中移动 Marker 的 Transform,即可带动 VRPawn 跟随移动(见 01 §6.3)。

⚠️ Sequence 模式的载具 Plot(边界随载具移动)UE 暂未提供,接入前请与游幕对接人确认。

Q:要不要在关卡里手摆 YomovManagerActor?

  • 不用固定路径 / Flow 边界:可不手摆,客户端 UYomovSessionSubsystem 会自动 spawn

  • 要用固定路径 / Marker / 边界可视化:必须手摆

  • 关卡里若已有实例,自动 spawn 会跳过,不会双实例。DS 端不 spawn YMMA

远程玩家与多人​

Q:远程玩家 Avatar 不出现?

逐项排查:

  1. DA_DataAsset.DefaultAvatarClass 非空;异队想看不同 Avatar 还要配 NonTeamAvatarClass

  2. 客户端已连上 DS(日志出现 Server_Login success)

  3. Bridge 业务服务器进程已启动,msg 501 正在下发跨服玩家数据

  4. 本地玩家自己不应出现在 spawn log(URemotePlayerSubsystem 按 PlayerID 跳过本地)——若只缺自己,这是正确行为

  5. grep Spawned remote player / ResolveAvatarClass 看分流分支

Q:日志被 ResolveAvatarClass / No AvatarClass resolved 刷屏?

DA_DataAsset.NonTeamAvatarClass 留空(nullptr)所致。异队玩家数据到达时 ResolveAvatarClass 会打 Warning(No AvatarClass resolved for PlayerID=...,已节流到每 PlayerID 只 Warning 一次),该异队玩家 Avatar 不会 spawn。

修复:给 NonTeamAvatarClass 配一个 Avatar BP——异队想隐藏就配一个无网格体的空 BP(Parent = ARemotePlayerCharacter),不要留 nullptr。

Q:异队玩家走近才显示 / 超过 5 米就消失?

可见性规则(1.1.1 默认开启)的预期行为:同组恒显;异组进入 500cm 显示、超出 550cm 隐藏(50cm 迟滞带)。

  • 距离按本机头显位置计算(1.2.3 起):以玩家实际物理位置为准,不再受 Pawn 根(钉在场地原点)影响

  • 想恢复「全部恒显」(1.1.0 行为):RemotePlayerVisibleDistance <= 0

  • 想近乎彻底隐藏异组:把该值设为极小(如 1cm)

  • 诊断看客户端日志 Visibility: rules active (ShowDist=...) 与翻转行回带的实际距离

Q:远程玩家模型过大 / 过小?

BodyScale 身高校准缩放(1.1.1)在起作用:BodyScale = 头显离地高度 / AvatarDefaultBodyHeight。排查顺序:

  1. AvatarDefaultBodyHeight 是否等于 Avatar 模型实际身高(默认 170cm,换模型必须改)

  2. 看发送端日志 BodyScale calibrated & locked: headZ=... scale=... 确认校准值

  3. 播控下发身高指令可触发重算(日志 BodyScale recalibration requested)

跨服玩家第一期不缩放(恒 1.0,符合设计范围)。

Q:多人下先连入的玩家位置卡死 / 丢 pawn?

本地 VRPawn 的 AutoPossessPlayer 未设 Disabled,DS 重启或多人 travel 时抢占了先连入者的 PlayerController。修复:本地 Pawn 继承 AYomovPawn(ctor 强制 AutoPossessPlayer = Disabled),或在自定义 Pawn 的 ctor 手动设。见 03 §3.1。

Q:跨机看到的远程玩家坐标错位?

各端 DA 边界字段不一致 → 边界局部坐标系不统一 → 跨服玩家坐标错位。各端必须用同一份 DA:MapData / AnchorPoint / AnchorRotationY / ActSizeLength / ActSizeWidth。归一化前提与完整说明见 03 §3.3。

Q:片头结束回到内容后,同队玩家看不到 / 位置不更新?

分两种情形:

  1. 长片头后同队全员不可见、位置冻结:插件 < 1.2.3 的已知问题——同队数据也挂在 Bridge 501 上,片头 APK 独占房间时 Bridge 停推 501,同队数组冻结在最后一次快照(长片头后为空)。1.2.3 起同队由 DS 直接发布(~10Hz),与 501 解耦——DS 单端升级即生效,旧客户端 APK 也受益。DS 日志 [Uplink] msg500 submitted teams=N players=M 持续即上行正常

  2. 回前台短暂看不到人:片头压后台期间上行停发,DS 15s 后踢除连接(对齐 Unity 断线即删),回前台自动快速重连(设计目标 ~1s),恢复前短暂空窗属预期(见下一条)

Q:头显摘下 / 片头压后台,回来后被踢、多久能恢复?

环节

行为

被踢

片头 APK 压后台 = 上行停发,DS 15s 后踢除(UplinkTimeoutSeconds),其他玩家屏幕上该 avatar 消失(Unity 同语义)

回前台

断流已达踢除阈值时下一帧直接重连(不再等引擎 120s 超时);重连链设计目标 ~1s(旧版实测 ~2.5s),握手目标 ~0.06s(旧版实测 ~1.06s)

空窗

入口世界 → DS 世界两次 LoadMap 是结构性下限(~0.7–0.8s),期间画面停在入口世界

不踢的选择

关 DA_DataAsset.bEnableUplinkTimeoutKick——片头期保留在线,代价是其他玩家屏幕上 avatar 不消失(与 Unity 不一致)

日志:armed after resume / link already kicked, reconnect immediately / dead link after resume / uplink echo restored after resume -> early disarm。

Q:别人站着不动,avatar 却周期性跳到场地中间;或者停下后还在滑?

  • 跳场地中间(< 1.2.3):头显放置 / 后台 / 追踪丢失时 OpenXR 返回零视点,旧版当有效位置上报。1.2.3 三层防御:采集端丢无效帧(客户端 CollectLocalVRData skip: zero viewpoint)+ 发送端拒收零头位帧(DS Zero HeadPosition ... keep last known)+ DS 零值哨兵保留最后有效位置

  • 停下后滑走:跨组数据 ~1.5Hz,客户端航位外推在 1.2.3 改为指数衰减(0.5s 窗口、τ=0.3s)——步行停下最多再滑 ~45cm 并快速趋停(旧版匀速外推最多 1.8m)

  • 静止玩家消失-瞬移:客户端每 1s 状态回放刷新 LastSeen,replicated 属性无 delta 不再被误判「玩家离开」(1.2.3)

Q:重启桥接服务器后播控显示「程序关闭」/ 玩家位置停在原地?

插件 < 1.2.3 的已知问题(DS→Bridge 断线后 msg500 流静默中断,播控看到的是冻结数据)。1.2.3 起 DS 断线自愈:每 1s 自动重连(无限重试),重连成功立即全量重建上报,数据 ≤2s 恢复,无需重启 DS / 重新登录。日志:Bridge disconnected, reconnect timer armed → Bridge reconnected after N attempt(s), resuming msg500 stream。

Q:玩家重启头显 / 断线重连后从第一幕开始,还把别人也拉回第一幕?

插件 < 1.2.3 的已知问题。1.2.3 起按场景级进度对齐:重连玩家恢复到本队当前场景的首个 Act、从该场景 Plot0 起播(对齐 Unity LoadStageScene),且对齐先于本地起播上报,不会覆盖全队进度。日志 reconcile ... jump to scene first act。

粒度是场景级:同场景内的 Plot 进度会从头播(与 Unity 一致)。

Q:多队伍一起切场景时,有人先走、有人卡住?

1.2.3 起跨 Act 切场景有全队 barrier:等全队在线玩家都请求同一目标场景才放行。卡住时排查:

  1. 日志 [SceneBarrier] ready N/M, requests=[...] 看谁没发请求——@none = 完全没发,(!=target) = 请求了别的场景(多为进度不一致)

  2. 掉线玩家自动豁免,不阻塞其余人

  3. 等待无上限(对齐 Unity),超 30s 会打 Warning;播控 Seek / 重连对齐可打断等待

  4. 兜底:关 DA_DataAsset.bEnableSceneSyncBarrier(各端各切,旧行为)——⚠️ 开关必须全队一致,关闭的端不发请求,开启的端会一直等它

Q:DS 空跑时播控模拟器看到「测试玩家」假数据 / DS 连不上当次放映的 Bridge 房间端口?

插件 < 1.1.1 的已知 bug(DS 地图里 BP_BridgeEventReceiver 自动连 DA 默认地址占住连接 + 假玩家上报)。1.1.1 已修:DS 端 BridgeEventReceiver 不再自动连接 / 发送(职责解耦)。

旧包临时规避:关掉 BP_BridgeEventReceiver 的 Auto Connect On Begin Play。

版本与能力​

Q:支持哪些 UE 版本?

已验证 UE 5.3 / 5.4 / 5.5 / 5.6 / 5.7 全版本通过。

Q:不写 C++ 能用这个插件吗?

可以。通过蓝图方式(BP_BridgeEventReceiver + DA 配置)即可接入播控指令与远程玩家可视化。若要做 DS 部署、Server target、binary 包跨模块业务调用等工程能力,需走 C++ 路径。

Q:UE 版相比 Unity 版缺哪些能力?

玩家角色 IK 动作(部分)、游后分享、LBE 先导片、载具类 Plot、多语言自动适配等 UE 侧暂未提供或覆盖范围不同——完整对照见 01 §3 功能模块。接入前请与游幕对接人确认。


2. 验收日志字典(联调必看)​

联调时优先「看日志判阶段」,不要先改代码。以下是最常用的验收日志最小集合(均为插件内实际会打印的字符串):

阶段

日志关键字

端

含义 / 不出现时优先排查

Bridge 连通(客户端)

Bridge Connected!

客户端

客户端已连上 Bridge。不出现:查 DA_CommandLineArgs.BridgeServerIP/Port、Bridge 进程、防火墙

Bridge 连通(DS)

UTCPClientSubsystem: Connected to

DS

DS 作为 TCP 客户端连上 Bridge(地址由客户端上报)。不出现:查客户端 DA 上报链路

客户端登录 DS

Server_Login success

客户端

客户端 RPC 到 DS 完成,PlayerID / TeamID 已进入复制链路。不出现:查 open <ds-ip>:<port>、端口一致性

DS 监听端口

YomovIpNetDriver + 端口(9527)

DS

DS 端口配置生效(非默认 7777)。仍是 7777:查 !NetDriverDefinitions=ClearArray、config.ini 部署路径

远程玩家生成

Spawned remote player

客户端

URemotePlayerSubsystem 已 spawn 远程 Avatar。不出现:查 DefaultAvatarClass、Bridge 501 是否到达、本地玩家过滤

Avatar 分流

ResolveAvatarClass

客户端

同队 / 异队 Avatar 分支选择完成。分流不对:查本机 TeamID、远程 TeamID、两个 AvatarClass

可见性规则(1.1.1)

Visibility: rules active (ShowDist=...)

客户端

距离可见性规则生效。不出现:DA 未加载(走类默认值兜底 + 一次性 Warning);翻转行 Visibility: ... -> hidden/shown 回带实际距离

BodyScale 校准(1.1.1)

BodyScale calibrated & locked: headZ=... scale=...

发送端

身高校准并锁定。不出现:头显高度不在 100~220cm 区间(HMD 未戴);播控下发身高指令后出现 BodyScale recalibration requested

LSA 接管(叙事)

[SeqDirector] Adopted level LSA '<名>'

客户端

时间轨接管成功。不出现:Tag 拼错 / LSA 摆错关卡

LSA 缺失

timeline driver absent

客户端

合法状态(走蓝图轨);无意走蓝图轨则补摆 LSA

误配纠偏

was auto-playing (bAutoPlay) — stopped

客户端

LSA 勾了 Auto Play 被纠偏,取消勾选

Event key 触发

[SeqSignal] YomovPlotTransition -> NextPlot

客户端

时间轨触发成功。不出现 → 三个静默失败点(见 §1 路径与叙事)

Plot 推进

NextPlot: Advanced to plot '...'

客户端

两条驱动轨最终都走这里

推进冻结

NextPlot: deferred — seek arrival in flight

客户端

Seek 转场窗口内属正常;卡死看下条

Seek 到达

Seek arrival settled — plot advance unfrozen

客户端

落点稳定解冻;30s 超时有兜底 Warning

重切生效

OnRep_TargetLevelVersion v=N -> FC.JumpToActAndPlot(...)

客户端

版本号到达(1.1.1 重切章节生效);DS 侧配对日志 Remote command: Seek

中途加入对齐

Join snapshot: ... jumping to align

客户端

新加入玩家对齐本队当前进度。不出现:本队 CurrentStage 为空(未 Seek 过的场次恒空,走首 Act 开始,属正常)

引导激活

BestView guide mode activated (delay=...s...)

客户端

引导延迟到期,值可在此核对

虚空进出

EnterVoidSpace — void shown, N non-whitelist actors hidden / ExitVoidSpace — void hidden, actors restored

客户端

虚空判定工作正常

烘焙缺失

bake-derived field empty — run Update rebake

客户端

场景改动后需重跑 Update

完结报幕

Narrative complete → CurtainCall → Showing ending credits

客户端

完整收尾链

进度上报

Narrative progress reported: Team=... Stage=... Area=...

DS

进度链通(配对 Stage/Area changed ... SpanTimeMs=...)

播控链路

LogControlSimulator SENT

客户端

6 种 ControlType 收发通(UControlSimulatorComponent 开发验证用)

1.2.3 新增诊断日志(联调按需扩展)​

类别

日志关键字

端

含义

启动指纹

[Fingerprint] engine=... build=... core=... PackagingType=... LBEPathType=...

客户端 + DS

启动一行给齐引擎 / 构建 / Core DLL 时间戳 / 模式 / 各类 ID / 地址。两端比对 core= 即知是否错版

上行心跳

[Uplink] msg500 submitted teams=N players=M

DS

DS→Bridge 上行持续(1s 降频)。缺失:DS 未连 Bridge 或上行链断

场景 barrier

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

客户端 + DS

切场景 barrier 等待 / 放行;@none = 未发请求,(!=target) = 请求了别的场景

DS→Bridge 自愈

Bridge disconnected, reconnect timer armed、Bridge reconnected after N attempt(s), resuming msg500 stream

DS

断线后 1s 无限重连;重连后 msg500 立即恢复

回前台 / 探活

armed after resume、link already kicked, reconnect immediately、dead link after resume、uplink echo restored after resume -> early disarm

客户端

ConnectionGuard 分支:武装 / 已被踢立即重连 / 判死 / 活连接提前撤守

握手加速

net.IpConnectionDisableResolution -> 1 for numeric host <ip>

客户端

IPv4 字面量地址已禁用异步解析;Stateless Handshake → SendChallengeResponse 间隔应 ≈0.06s(旧 ≈1.06s)

零头位帧

Zero HeadPosition ... keep last known

DS

零头位帧被拒收、保留上次有效位置(静止 / 后台 / 放置玩家防御生效)

幽灵 PS

Ghost PS suppressed

DS

同 PlayerID 僵尸 PlayerState 被选主挡下(Warning 带 PC 名与时间戳)

坐标哨兵

OnSync bridge player ... sentinel skip、skip far-sentinel entry

DS / 客户端

±9999 哨兵 / 原点零值的 Bridge 条目被拦截(不 spawn 僵尸 avatar)

重连对齐

reconcile ... jump to scene first act

客户端

重连后场景级进度对齐(截断旧起点)

采集无效帧

CollectLocalVRData skip: zero viewpoint

客户端

头显视点无效帧被丢弃(放置 / 后台 / 追踪丢失)

建议顺序:先看 DS 端 YOMOVSDK.log,再看客户端 YOMOVSDK.log。stdout 可能有缓冲,排障以日志文件为准。 日志路径:客户端 Saved/Logs/YOMOVSDK.log;DS 端 <DS>/YOMOVSDK/Saved/Logs/YOMOVSDK.log;Android 设备 Logs/<date>/YOMOVSDK.log。


3. 发版前检查清单​

下面 15 条是多人接入「最容易漏」的点。发版前对照逐条确认。

关卡与配置​

  • 各端 DA 边界字段完全一致:MapData / AnchorPoint / AnchorRotationY / ActSizeLength / ActSizeWidth 由内容统一分发同一份 DA,任一端不一致 → 该端跨服玩家坐标错位

  • DA Avatar 字段类型为 TSubclassOf<AActor>(1.1.0 破坏性变更);DefaultAvatarClass / NonTeamAvatarClass均必配(异队隐藏也配空网格体 BP,勿留 nullptr)

  • AvatarDefaultBodyHeight 按模型实际身高配(BodyScale 身高校准的分母,默认 170cm);换非 1.7m 标准人形模型必须改

  • YMMA 按需手摆:不用固定路径可不摆;用固定路径 / Flow 边界必须摆

  • 路径已摆放并烘焙:[Update Act Sequence] 跑过、BestPath [保存路径] 点过、Ctrl+S 手动落盘

  • Sequence Plot 推进驱动已配置:蓝图轨(驱动蓝图 / 副本摆进关卡)或时间轨三步契约(Sequence 资产 + Tag YomovNarrativeSequence + PersistentMap 关卡蓝图父类 AYomovLevelScriptActorBase,见 06 §1.4)

多人链路​

  • 本地 Pawn AutoPossessPlayer = Disabled:继承 AYomovPawn 或在 ctor 手动设;否则 VRPawn 抢占 Player0 导致 DS 端 spawn 链路异常

  • 远程玩家事件绑 URemotePlayerSubsystem(非 BridgeEventReceiver)

  • 客户端 Bridge 地址配在 DA(BridgeServerIP / BridgeServerPort):DS 命令行 -BridgeIP 无效

  • 可见性规则默认开启(1.1.1):异组走近(默认 500cm)才显示属预期;距离按本机头显位置计算(1.2.3);想恢复全显把 RemotePlayerVisibleDistance <= 0

  • 切场景 barrier 开关全队一致:bEnableSceneSyncBarrier(默认开)——关闭的端不发请求,开启的端会一直等它;灰度关掉时各端必须同时关

  • DS 上行超时踢除口径与服务约定对齐:bEnableUplinkTimeoutKick(默认开)/ UplinkTimeoutSeconds(默认 15s)——片头压后台玩家 15s 后从其他玩家视野消失,回前台自动重连;需要片头期保留在线再关

  • Seek ExtraData 字段名 stageName / areaName:自研播控 / 模拟器发 Seek 时 JSON 必须用这两个 key,旧 stage / area 静默失效

部署与打包​

  • DS GameMode 用插件预制(BP_YomovDSGameMode / AYomovDSGameModeTemplate);模式切换后确认监听端口非 7777

  • 打 DS 必须用源码版引擎 + config.ini 部署到 WindowsServer/config.ini(安装顶层,exe 旁)

已知待验证项​

  • 边界跨机一致性(待验证):多客户端下边界 mesh / 局部坐标系端到端一致性尚未闭环实测;联调请先保证各端 DA 边界字段完全一致,发现问题请反馈游幕对接人

打包格式(版本号规则 / 包体校验)见 04 §四;接入完成检查见 03 §接入完成检查清单。


4. 测试软件与联调工具​

单人 / 播控测试软件​

通过播控模拟器、VRAgent、桥接服务器等软件,可在本地模拟实际运行中的应用启播、地图调度及多应用同步等情况。

下载与说明:YOMOV 播控模拟器说明。

多人联调工具​

工具

路径

用途

测试桥接服务器

<TOOLS_ROOT>/BridgeServer*/BridgeServer.exe(BridgeServer/ 或 BridgeServer1/BridgeServer2/ 子目录)

替代真实业务服务器,收 DS msg 500 上报 + 下发 msg 501 / 503;轻量,本地联调首选

玩家模拟器

<TOOLS_ROOT>/ContentSimulator/ContentSimulator/ContentSimulator.exe

模拟其他内容客户端发队伍玩家信息给 Bridge,验证跨内容玩家在本地 DS 展示是否正确

典型联调顺序(顺序不能反):

① 启动 BridgeServer
② 启动 DS(标准 UE Server 参数,监听端口走 config.ini serverPort)
③ VR 客户端连入(`open <ds-ip>:9527`)
④ 用 ContentSimulator 注入跨内容玩家 → 观察 VR 客户端是否 spawn 远程 Avatar

<TOOLS_ROOT> 通常为 C:/Yomov。用 PIE 快验时不需打包 DS,配置见 04 §2.1。


5. 已知限制​

以下为当前版本(1.2.3)的已知边界,非缺陷,接入设计时请纳入考虑:

限制

说明

多语言自动适配未提供

UE 版未提供 Unity 版的自动多语言能力;如需多语言请自行实现

游后分享 / LBE 先导片未提供

见 01 §3 功能模块

Sequence 模式无载具 Plot

Unity 的 Plot Type(Walking / Vehicle,边界随载具移动)UE 暂未提供等价物;载具移动效果走 Single 模式 Marker 方案

远程 Avatar 手部 IK 为接口级

ARemotePlayerCharacter 提供手 IK 目标接口与查询,完整动作库未提供

蓝图轨 Delay 不响应 PausePlay

蓝图 Delay 节点是死等,暂停期间不会冻结;需要可控暂停请用时间轨

多人进度上报 = 每队单值聚合(Last-Write)

同队多客户端异值上报时后到覆盖,无逐客户端区分

重连进度对齐粒度 = 场景级

重连后从本队当前场景的首个 Act / Plot0 起播,同场景内的 Plot 进度会从头播(对齐 Unity LoadStageScene)

DS 新起 / 重连 Bridge 后不拉取 Bridge 当前进度

中途加入对齐仅同一 DS 存续期内有效(1.2.3 的 Bridge 自愈只恢复 msg500 上行,不拉取历史进度)

片头压后台 = 预期断线

DS 15s 踢除 + 回前台重连(~1s)是既定业务语义;入口世界两次 LoadMap 的 ~0.7–0.8s 空窗是结构性下限

跨组数据 ~1.5Hz

Bridge 501 广播周期由业务侧决定;SDK 侧航位外推只做表现层补偿,治本需 Bridge 提高广播频率

Seek 的 areaName 不参与 Plot 定位

落点 Plot 固定归 0(对齐 Unity 播控 plots[0]),字段保留

EventName 拼错 / 接收层漏配 = 静默丢信号

引擎 FindFunction 找不到不报错;联调先查 §2 的 LSA / SeqSignal 三行日志

跨服坐标依赖 DA 一致

跨 DS 玩家经 Act 基准锚定换算,仍要求各端 DA 边界字段一致;误差方向为「该显不显 / 该隐不隐」,联调以日志实际距离为准

报幕后虚空为终态

设计行为——叙事完结后走回 Plot / Act 区域也不恢复场景;播控 Seek 切回章节会重建一切

五个非 PlotTransition 信号函数为占位

YomovEyeClose / YomovEyeOpen / YomovOpenComPass / YomovOpenPlotHide / YomovOpenQuit 当前仅打 log,行为后续版本接入

并发场景装载请求会被单飞锁丢弃

有日志可查;Seek 冻结已掐掉主要触发源

无路径数据 fallback 链的摆放假设

Act 按序访问;Seek 回跳时非首次访问位姿可能错(正常路径不走该链)