FAQ
插件版本 1.2.3 | 文档版本 1.2.3 | UE 5.3-5.7 常见问题、验收日志字典、发版前检查清单、联调工具、已知限制。 排障第一原则:先看日志判阶段,不要先改代码。
目录
-
- 常见问题
-
- 验收日志字典(联调必看)
-
- 发版前检查清单
-
- 测试软件与联调工具
-
- 已知限制
1. 常见问题
安装与编译
Q:插件安装后编译报错?
确认 UE 版本为 5.3 或更高,且插件包目录与项目引擎版本匹配(YomovUESDKCore-5.4/ 配 5.4 引擎)。尝试删除项目的 Intermediate/ 和 Binaries/ 目录后,重新右键 .uproject 生成项目文件。
Q:打开 .sln 进 Visual Studio 生成解决方案出错?
现象 | 根因 | 处理 |
|---|---|---|
右键 |
| 核对 |
| UBT 报错 | 删 |
VS 打开后「生成解决方案」失败 | 模块 | 看 UBT 输出日志定位缺失依赖(如漏加 |
VS 能生成但跑起来崩 | Runtime DLL 缺失 | 确认 |
消费方 C++ 调业务 API 报 | 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 源码绕过:
-
编辑
<UE源码根>/Engine/Source/Programs/UnrealBuildTool/Platform/Windows/UEBuildWindows.cs,找到约 952 行的if (Target.bUseAutoRTFMCompiler) { Target.WindowsPlatform.Compiler = WindowsCompiler.ClangRTFM; },注释掉整个 if 块 -
在注释下方加一行:
Target.WindowsPlatform.Compiler = WindowsCompiler.VisualStudio2022; -
跑任意
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 修改后不生效?
-
先确认 DA 本身存在且资产类正确:菜单 YOMOV SDK → InspectorPanel 自检——缺失或类不匹配会红显,点 [Autofix] 一键创建到规范路径(
Content/YOMOVSDK/Config/)。放在别的位置的 DA 不会被加载 -
在编辑器 Console 中执行 Yomov.Config.Reload 热重载(或 SettingPanel 点 [Save & Apply],1.2.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:连接桥接服务器失败?
-
检查
DA_CommandLineArgs中的BridgeServerIP和BridgeServerPort -
确认桥接服务器进程已启动
-
检查防火墙是否放行了对应端口
-
DS 部署场景:DS 连 Bridge 的地址由客户端
Server_Login上报——确认客户端 DA 的BridgeServerIP正确(自动检测本机 IP 可能命中虚拟网卡如198.18.0.1)。⚠️ -BridgeIP= 命令行是历史遗留无效参数,DS 进程不解析它
Q:BridgeEventReceiver 事件不触发?
BridgeEventReceiver 通过 UTCPClientSubsystem(引擎级 Subsystem 单例)连 Bridge,不依赖 YomovManagerActor。请检查:
-
DA_CommandLineArgs中的服务器地址配置是否正确 -
bAutoConnectOnBeginPlay是否为true(DS 端此 Actor 已让位,不再自动连接——见 03 §流程 B) -
不要同时挂 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 找不到不报错,拼错也没提示):
-
PersistentMap 的关卡蓝图父类不是 AYomovLevelScriptActorBase
-
LevelSequence Event key 的 EventName 拼错(必须是
YomovPlotTransition) -
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 不出现?
逐项排查:
-
DA_DataAsset.DefaultAvatarClass非空;异队想看不同 Avatar 还要配NonTeamAvatarClass -
客户端已连上 DS(日志出现
Server_Login success) -
Bridge 业务服务器进程已启动,msg 501 正在下发跨服玩家数据
-
本地玩家自己不应出现在 spawn log(
URemotePlayerSubsystem按 PlayerID 跳过本地)——若只缺自己,这是正确行为 -
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。排查顺序:
-
AvatarDefaultBodyHeight是否等于 Avatar 模型实际身高(默认 170cm,换模型必须改) -
看发送端日志
BodyScale calibrated & locked: headZ=... scale=...确认校准值 -
播控下发身高指令可触发重算(日志
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.2.3 的已知问题——同队数据也挂在 Bridge 501 上,片头 APK 独占房间时 Bridge 停推 501,同队数组冻结在最后一次快照(长片头后为空)。1.2.3 起同队由 DS 直接发布(~10Hz),与 501 解耦——DS 单端升级即生效,旧客户端 APK 也受益。DS 日志
[Uplink] msg500 submitted teams=N players=M持续即上行正常 -
回前台短暂看不到人:片头压后台期间上行停发,DS 15s 后踢除连接(对齐 Unity 断线即删),回前台自动快速重连(设计目标 ~1s),恢复前短暂空窗属预期(见下一条)
Q:头显摘下 / 片头压后台,回来后被踢、多久能恢复?
环节 | 行为 |
|---|---|
被踢 | 片头 APK 压后台 = 上行停发,DS 15s 后踢除( |
回前台 | 断流已达踢除阈值时下一帧直接重连(不再等引擎 120s 超时);重连链设计目标 ~1s(旧版实测 ~2.5s),握手目标 ~0.06s(旧版实测 ~1.06s) |
空窗 | 入口世界 → DS 世界两次 LoadMap 是结构性下限(~0.7–0.8s),期间画面停在入口世界 |
不踢的选择 | 关 |
日志: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)+ 发送端拒收零头位帧(DSZero 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:等全队在线玩家都请求同一目标场景才放行。卡住时排查:
-
日志
[SceneBarrier] ready N/M, requests=[...]看谁没发请求——@none= 完全没发,(!=target)= 请求了别的场景(多为进度不一致) -
掉线玩家自动豁免,不阻塞其余人
-
等待无上限(对齐 Unity),超 30s 会打 Warning;播控 Seek / 重连对齐可打断等待
-
兜底:关
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。不出现:查 |
Bridge 连通(DS) |
| DS | DS 作为 TCP 客户端连上 Bridge(地址由客户端上报)。不出现:查客户端 DA 上报链路 |
客户端登录 DS |
| 客户端 | 客户端 RPC 到 DS 完成,PlayerID / TeamID 已进入复制链路。不出现:查 |
DS 监听端口 |
| DS | DS 端口配置生效(非默认 7777)。仍是 7777:查 |
远程玩家生成 |
| 客户端 |
|
Avatar 分流 |
| 客户端 | 同队 / 异队 Avatar 分支选择完成。分流不对:查本机 TeamID、远程 TeamID、两个 AvatarClass |
可见性规则(1.1.1) |
| 客户端 | 距离可见性规则生效。不出现:DA 未加载(走类默认值兜底 + 一次性 Warning);翻转行 |
BodyScale 校准(1.1.1) |
| 发送端 | 身高校准并锁定。不出现:头显高度不在 100~220cm 区间(HMD 未戴);播控下发身高指令后出现 |
LSA 接管(叙事) |
| 客户端 | 时间轨接管成功。不出现:Tag 拼错 / LSA 摆错关卡 |
LSA 缺失 |
| 客户端 | 合法状态(走蓝图轨);无意走蓝图轨则补摆 LSA |
误配纠偏 |
| 客户端 | LSA 勾了 Auto Play 被纠偏,取消勾选 |
Event key 触发 |
| 客户端 | 时间轨触发成功。不出现 → 三个静默失败点(见 §1 路径与叙事) |
Plot 推进 |
| 客户端 | 两条驱动轨最终都走这里 |
推进冻结 |
| 客户端 | Seek 转场窗口内属正常;卡死看下条 |
Seek 到达 |
| 客户端 | 落点稳定解冻;30s 超时有兜底 Warning |
重切生效 |
| 客户端 | 版本号到达(1.1.1 重切章节生效);DS 侧配对日志 |
中途加入对齐 |
| 客户端 | 新加入玩家对齐本队当前进度。不出现:本队 |
引导激活 |
| 客户端 | 引导延迟到期,值可在此核对 |
虚空进出 |
| 客户端 | 虚空判定工作正常 |
烘焙缺失 |
| 客户端 | 场景改动后需重跑 Update |
完结报幕 |
| 客户端 | 完整收尾链 |
进度上报 |
| DS | 进度链通(配对 |
播控链路 |
| 客户端 | 6 种 ControlType 收发通( |
1.2.3 新增诊断日志(联调按需扩展)
类别 | 日志关键字 | 端 | 含义 |
|---|---|---|---|
启动指纹 |
| 客户端 + DS | 启动一行给齐引擎 / 构建 / Core DLL 时间戳 / 模式 / 各类 ID / 地址。两端比对 |
上行心跳 |
| DS | DS→Bridge 上行持续(1s 降频)。缺失:DS 未连 Bridge 或上行链断 |
场景 barrier |
| 客户端 + DS | 切场景 barrier 等待 / 放行; |
DS→Bridge 自愈 |
| DS | 断线后 1s 无限重连;重连后 msg500 立即恢复 |
回前台 / 探活 |
| 客户端 | ConnectionGuard 分支:武装 / 已被踢立即重连 / 判死 / 活连接提前撤守 |
握手加速 |
| 客户端 | IPv4 字面量地址已禁用异步解析; |
零头位帧 |
| DS | 零头位帧被拒收、保留上次有效位置(静止 / 后台 / 放置玩家防御生效) |
幽灵 PS |
| DS | 同 PlayerID 僵尸 PlayerState 被选主挡下(Warning 带 PC 名与时间戳) |
坐标哨兵 |
| DS / 客户端 | ±9999 哨兵 / 原点零值的 Bridge 条目被拦截(不 spawn 僵尸 avatar) |
重连对齐 |
| 客户端 | 重连后场景级进度对齐(截断旧起点) |
采集无效帧 |
| 客户端 | 头显视点无效帧被丢弃(放置 / 后台 / 追踪丢失) |
建议顺序:先看 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 播控模拟器说明。
多人联调工具
工具 | 路径 | 用途 |
|---|---|---|
测试桥接服务器 |
| 替代真实业务服务器,收 DS msg 500 上报 + 下发 msg 501 / 503;轻量,本地联调首选 |
玩家模拟器 |
| 模拟其他内容客户端发队伍玩家信息给 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 为接口级 |
|
蓝图轨 Delay 不响应 PausePlay | 蓝图 Delay 节点是死等,暂停期间不会冻结;需要可控暂停请用时间轨 |
多人进度上报 = 每队单值聚合(Last-Write) | 同队多客户端异值上报时后到覆盖,无逐客户端区分 |
重连进度对齐粒度 = 场景级 | 重连后从本队当前场景的首个 Act / Plot0 起播,同场景内的 Plot 进度会从头播(对齐 Unity |
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 播控 |
EventName 拼错 / 接收层漏配 = 静默丢信号 | 引擎 |
跨服坐标依赖 DA 一致 | 跨 DS 玩家经 Act 基准锚定换算,仍要求各端 DA 边界字段一致;误差方向为「该显不显 / 该隐不隐」,联调以日志实际距离为准 |
报幕后虚空为终态 | 设计行为——叙事完结后走回 Plot / Act 区域也不恢复场景;播控 Seek 切回章节会重建一切 |
五个非 PlotTransition 信号函数为占位 |
|
并发场景装载请求会被单飞锁丢弃 | 有日志可查;Seek 冻结已掐掉主要触发源 |
无路径数据 fallback 链的摆放假设 | Act 按序访问;Seek 回跳时非首次访问位姿可能错(正常路径不走该链) |