跳到主要内容

接入流程

03 - YomovUESDKCore 接入流程

插件版本 1.2.3 | 文档版本 1.2.3 | UE 5.3-5.7 面向读者:接入开发、多人联调与部署同学 本篇是自包含的完整接入指引:选定流程后从头读到尾即可完成接入,不需要来回跳转。纵深参考见 05 大空间最佳实践 / 06 核心组件 / 07 接口与事件。


目录​

  • 概述

  • 流程 A:接入 SDK 多人同步

    • 步骤一:初始化设置

    • 步骤二:创建大空间路径

    • 步骤三:玩家角色配置

    • 步骤四:服务端设置

  • 流程 B:不接入 SDK 多人同步

  • 附录 A. DS 部署排障

  • 接入完成检查清单


概述​

接入方式分两种,先选定你的流程再往下读:

流程

适用

步骤

流程 A:接入 SDK 多人同步

多人 / 多设备联机、需要远程 Avatar 与跨内容混播

步骤一 初始化设置 → 步骤二 创建大空间路径 → 步骤三 玩家角色配置 → 步骤四 服务端设置

流程 B:不接入 SDK 多人同步

单机体验,或内容已有自研多人方案

一 初始化设置 → 二 创建大空间路径 → 三 服务端设置

📌 接入建议:多人同步在 LBEVR 中与角色动作、手势交互、大空间路径、多应用桥接都存在耦合。即使多人同步不是接入分发平台的必选项,在内容中没有定制多人玩法的情况下,我们仍推荐使用 SDK 的多人同步能力——这是经过大量 LBEVR 内容与场馆长期验证的稳定能力,能最大程度保证多人稳定性并显著减少调试工作量。 已有自研多人方案的团队见 流程 B 与 06 §多人同步。

前置条件:已完成 02 快速入门(插件安装 + 两个 DataAsset 配置)。 📌 路径变量:本篇命令中的 <PROJECT_ROOT>(你的 UE 项目根)、<UE_SOURCE_ROOT>(源码版引擎根,打 DS 必需)、<TOOLS_ROOT>(联调工具根,如 C:/Yomov)按本机实际替换。


流程 A:接入 SDK 多人同步

步骤一:初始化设置​

SDK 初始化涉及关卡结构、GameMode、本地 Pawn 与边界锚点。这一步决定后续路径与多人的链路能否建立。

1.1 关卡结构​

多人场景的关卡组织方式:

关卡

用途

要求

PersistentMap(持久关卡)

常驻主世界,承载 AYomovManagerActor、边界、报幕等跨场景常驻对象

作为启动地图;World Settings 里 GameMode Override = BP_YomovDSGameMode

叙事场景关卡(sub-level)

每个 Act 一个关卡,动态加载 / 卸载

通过 LoadLevelInstance 动态加载(不是 Level Streaming 预配)

PersistentMap + sub-level 的关卡结构

PersistentMap + sub-level 的关卡结构

1.2 GameMode 设置​

推荐直接用插件预制,内容方一般不必自建:

资产 / 类

路径

说明

蓝图预制(推荐)

/YomovUESDKCore/Blueprint/BP_YomovDSGameMode

已挂两组件 + 设 GS/PS/PC(测试组件已移除)

C++ 模板

AYomovDSGameModeTemplate

与 BP 同职责;可作父类继承扩展

两处配置(至少配一处):

  1. Config/DefaultEngine.ini 设 GlobalDefaultServerGameMode 指向上述 BP / Template(打包 DS 走这条)

  2. 或:关卡 World Settings → GameMode Override = BP_YomovDSGameMode

⚠️ PIE 的 server 读地图级 GameMode Override,不读 GlobalDefaultServerGameMode:用 PIE 测 DS 行为时必须设地图 Override,否则 DS 组件不会挂上。

模板已内置:

项

值

GameStateClass

AYomovGameState

PlayerStateClass

AYomovPlayerState

PlayerControllerClass

AYomovPlayerController

UBridgeServerControllerComponent

桥接协议层

UYomovDSServerComponent

DS 业务层

DefaultPawnClass

BeginPlay 读 DA_DataAsset.PawnClass(非空则覆盖)

⚠️ GS/PS/PC 三件套是 UE 复制硬要求:无论用预制还是自建,只要走 UE 复制路径,GameStateClass / PlayerStateClass / PlayerControllerClass都必须指向 Yomov 类(或其子类),否则 CrossContentPlayers / TeamID / Server_Login 等复制字段不会生效。

可选:自建 / 继承扩展​

三种接入粒度:

粒度

适用

做什么

继承

GameMode / Pawn 与插件模板接近

GameMode 继承 AYomovDSGameModeTemplate(或 BP 继承 BP_YomovDSGameMode);本地 Pawn 继承 AYomovPawn

组合

已有自己的 GameMode,只想接入部分能力

自建 AGameModeBase 子类 + 挂 UBridgeServerControllerComponent + UYomovDSServerComponent + 设 GS/PS/PC 三件套

替换

自有 Bridge 协议 / 自有跨服同步

不用两个核心组件,自有业务层调 UBridgeRemotePlayerLibrary::SpawnOrUpdateRemotePlayer 喂数据给 URemotePlayerSubsystem(Subsystem 自动管理 Avatar 生命周期)

⚠️ 两个核心组件必须挂同一个 Owner:UYomovDSServerComponent::GetBridgeController() 用 FindComponentByClass 找同 Owner 的协议组件,找不到会打 Error 日志且 DS 同步不启动。

1.3 放置 YomovManagerActor(YMMA)​

AYomovManagerActor 是插件运行时核心入口(自带 FlowController + BridgeController)。

你的用法

要不要手摆

只播控

不必手摆,客户端由 UYomovSessionSubsystem 自动 spawn

用固定路径 / Marker / FlowController 边界

必须手摆

手摆方式:场景大纲或视口右键 → 搜 "Yomov Manager Actor" → 拖入 PersistentMap。

DS 端不会自动 spawn YMMA(Dedicated Server 设计如此)。

1.4 放置 StationaryActUnitMarker(仅 Single 模式)​

仅 Single(固定路径) 模式需要;Sequence 模式跳过本步。

AStationaryActUnitMarker 定义物理房间在虚拟场景中的映射位置,插件每帧读其 Transform 将玩家围栏与场馆边界空间对齐。

放置:场景右键 → 搜 "Stationary Act Unit Marker" → 放到玩家应该进入的起始位置。每场景只能放一个。

  • Single 模式启动后 10 秒内未找到 Marker 会打 Warning(continuing without Marker)并继续运行(降级状态,VRPawn 不会对齐到物理房间)

  • 若依赖载具移动效果(观光车 / 电梯),必须确认 Marker 已放置且命名正确——Single 模式下移动 Marker 位置可带动 VRPawn 跟随移动

1.5 放置边界与引导(按需)​

对象

路径

何时需要

边界材质

/YomovUESDKCore/Boundary/Materials/(M_Boundary_Real / M_Boundary_Line)

1.1.0 起 CDO 自动 wire,无需手配;要换自定义材质在 FlowController 面板对应属性覆盖

DA_BoundaryEffectConfig

/YomovUESDKCore/Boundary/DA_BoundaryEffectConfig

需要配置虚空 / 引导 / 报幕的材质与预制时(见 09 编辑器工具 的 Act Runtime Effect 区)

四种边界组件(由 UFlowControllerComponent 自动创建):

组件

用途

可视化

材质

AnchorBoundaryComponent

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

✅

M_Boundary_Line

RealBoundaryComponent

场馆级多边形围栏

✅

M_Boundary_Real

ObstacleBoundaryComponent

场馆内障碍物围栏

✅

复用 M_Boundary_Real

FixedBoundaryComponent

纯逻辑矩形边界(碰撞 / 范围判定)

❌ 无 mesh

无

可见性规则:玩家距边界超过 ShowDistance(Anchor = 30cm / Real = 80cm)时 alpha = 0 不可见——这是有意设计(避免围栏干扰主体内容),不是 bug。调试强制显示用 cvar Yomov.Boundary.Show 或蓝图节点 DebugSetBoundaryAlpha(1.0)。

YMMA Details 面板的 Flow Controller → Spatial 分组(四种边界组件)

YMMA Details 面板的 Flow Controller → Spatial 分组(四种边界组件)


步骤二:创建大空间路径​

大空间路径设置与管理是 LBEVR SDK 中最核心的步骤:需要基于内容体验对路径单元进行合理拆分,并设置触发切换的逻辑与顺序。 设计原则(Act/Plot 尺寸、衔接、三区参数)见 05 大空间最佳实践;编辑器操作细节(ActBuilder / EdMode 加点 / SettingPanel / BestPath)见 09 编辑器工具。本篇只讲流程与产出。

2.1 选择路径类型​

在 DA_DataAsset 的 LBEPathType 中选择(或经 SettingPanel 顶部下拉写回):

类型

对应内容

说明

Sequence

大空间奇境(动态路径)

多 Act × 多 Plot;内容自带叙事节奏,Plot 推进由内容驱动

Single

小空间游戏(固定路径)

单一路径单元;边界跟随 Marker,固定时长播放

2.2 创建路径单元(Act / Plot)​

  1. 菜单 YOMOV SDK → Create ActBuilder:在当前关卡一键创建 AYomovActBuilderActor + 首个 AYomovActDescriptor(Act_01)+ 首个 AYomovPlotBoundary

  2. 通过 Details 面板按钮续建:ActBuilder → [Create Act];Act → [Create Plot]

  3. 每个 Plot 用 [Draw PlotBoundary] 进入 EdMode,视口左键点地面画多边形;[Draw BestView] 画最佳观景区

  4. 每个 Act 用 [Draw Arrival] / [Draw Exit] 画进入区 / 出口点

Act/Plot 的层级顺序 = 播放顺序(attach 顺序决定)。Act 下方还必须满足:上一个 Act 的出口点落在当前 Act 的进入区内——BestPath 编辑器保存时会强制校验,不满足则画布红显、无法保存。

ActBuilder / Act / Plot 在 Outliner 中的层级 + 视口中的绿/橙多边形轮廓

ActBuilder / Act / Plot 在 Outliner 中的层级 + 视口中的绿/橙多边形轮廓

Act 细节

Act 细节

Plot 细节

Plot 细节

EdMode 绘制 Plot 边界的完整操作(视口点地加点 → 收尾闭合)

2.3 烘焙叙事数据(Sequence 模式)​

Sequence 模式下需要把场景摆放烘焙进 Narrative 数据资产:

  1. 新建 Narrative DataAsset:Content Browser 右键 → Miscellaneous → Data Asset → 选 NarrativeDataAsset

  2. 打开 SettingPanel,选中该 Narrative,填入 SourceScenes(要扫描的场景清单)

  3. 点 [Update Act Sequence] 烘焙:依次加载 SourceScenes,扫描其中的 ActDescriptor 与其子 PlotBoundary,覆盖重写StoryActs,并烘焙派生量(ActAreaPoints = 子 Plot 多边形并集、MainAreaPoints = ActArea 内缩 100cm)

⚠️ 烘焙会覆盖重写,且 Anchor 每次重定位到 ActArea 几何中心——手改 Anchor 会被下次 Update 冲掉(Anchor 不是手配字段)。场景摆放(Act/Plot actor、多边形顶点)改动后必须重跑 Update。 未重烘不致命:运行时规则是「runtime actor 数据非空才采用,空则回退 DA 兜底」,日志会出现 bake-derived field empty — run Update rebake Warning 提示重烘。

单人与 Sequence 的 PIE 开演口径:PIE 默认不自播(等播控 Start 或手动 FC.StartPlay);打包后仅 PackagingType = Test 自动开演,Release / OpenPackage 一律等播控。

2.4 配置 Plot 推进驱动(Sequence 模式)​

Plot 推进完全由内容驱动(管理器不做定时推进)。插件自带两个现成驱动蓝图,摆进关卡即可用,无需自绘(多人推送版,适合 APK 不连桥、只听播控复制的场景):

蓝图

触发方式

典型用途

BP_PlotAdvanceOnStart

播控开始放映:监听本队 TeamProperty.OnPlaybackStateChanged,Playing 且未处理过时自动推进

播控一键开演后自动切入下个 Plot

BP_PlotAdvanceManual

外部调用:任意蓝图对其实例调用 AdvanceNextPlot 自定义事件

交互完成 / 计时器 / 自有逻辑触发推进(内部走可判错的 TryNextPlot,失败打日志)

蓝图位于插件内容目录 /YomovUESDKCore/Blueprint/,两种用法:

用法一:直接用(零改动)——把蓝图拖进关卡即可。BP_PlotAdvanceOnStart 自动监听播控开演;BP_PlotAdvanceManual 摆好后由你的蓝图调用它:

(示例)交互蓝图 / 关卡蓝图:
Get Actor Of Class(BP_PlotAdvanceManual) → AdvanceNextPlot(自定义事件)

用法二:复制到项目自定义(需改逻辑时):

  1. Content Browser 打开插件内容目录 /YomovUESDKCore/Blueprint/(齿轮菜单勾选 Show Plugin Content 可见)

  2. 选中 BP_PlotAdvanceOnStart(或 BP_PlotAdvanceManual)→ 右键 → Duplicate(Ctrl+W)→ 保存到自己项目 Content/ 下

  3. 打开副本按需调整:Delay 时长、推进链路(哪些节点后切下个 Plot)、自检逻辑、触发事件

  4. 把副本摆进关卡(插件原版不再摆)

⚠️ 不要原地改插件目录内的资产——插件包升级是整目录替换,原地改动会丢;复制到项目 Content/ 的副本不受升级影响。副本引用的均为 SDK 蓝图公开 API(GetYomovManagerActor / GetFlowController / TryNextPlot),binary 包下可用。

🎬 【录屏】在项目中复制驱动蓝图并按需调整的完整操作(打开录屏)

BP_PlotAdvanceOnStart 内部链路(复制后可照此结构调整):

Event BeginPlay → Get My Team Property(无效则 0.2s × 20 次延迟重试)
→ Bind OnPlaybackStateChanged → 绑定成功后立即自检一次当前状态(防错过早到的 Start)
→ 自定义事件:PlaybackState == 0(Playing)?且未处理过(bStartHandled 门禁)
→ Delay → TryNextPlot ×3

⚠️ 「开始放映没触发」的最常见时序坑:播控 Start 到达时客户端叙事还没就绪(片头链路下 APK 启动+切前台/后台切换,就绪窗口可达数十秒),早到的 Playing 事件会被错过。插件 FlowController 在就绪时会自动补消费——发现本队已 Playing 立即补 StartPlay,与「绑定后自检」双保险。自绘或调整蓝图时两条都建议保留。

⚠️ 交互触发切 Plot 的内容必须配超时兜底(N 秒未触发则强制切下个 Plot),否则玩家卡在某个交互会导致整个体验卡死——设计原则见 05 §2.3。

📌 时间轨(一关一 LevelSequence)方案:适合正式内容(节奏与视听对齐,Pause/Seek 表现天然正确)。完整机制——Event key 信号契约(YomovPlotTransition)、三个静默失败点、五个非 PlotTransition 信号——见 06 §1.4。

2.5 摆放最佳路径(BestPath)​

菜单 YOMOV SDK → Open BestPath Editor 打开独立窗口,在场馆地图上摆放各 Act 的位置与旋转,点 [保存路径] 一键双写到 Content/PathData/BestPath.json(运行时唯一读取源)。

⚠️ 面板与 BestPath 编辑器都不落盘(只 MarkPackageDirty)——最后必须 Ctrl+S 手动保存 DA 与关卡。

最佳路径的两个作用:

  1. 接入阶段:按本地测试场地尺寸(如 6×8、8×10m)摆一条路径,完成本地全真模拟测试

  2. 发行阶段:导出的是导演视角的最佳体验路径——分发算法适配场馆地图时会读取路径中单元的相对位置与旋转角度作为计算权重,尽可能还原最佳体验

操作细节与画布交互见 09 §BestPath 路径编辑器。

BestPath 编辑器画布全貌(场馆多边形 + 多个 Act + 进入区/出口点)

BestPath 编辑器画布全貌(场馆多边形 + 多个 Act + 进入区/出口点)

绘制最佳路径操作

2.6 模拟播控测试​

动态路径测试

  • 初始配置文件

  • 绘制好Act / Plot

  • 配置好Plot推进驱动 - 蓝图

  • 摆放最佳路径

  • 准备软件

    • 桥接服务器

    • 简易播控

  • 视频录制:模拟播控测试录制


步骤三:玩家角色配置​

3.1 本地 Pawn(⚠️ 多人必须)​

⚠️ 本地 Pawn 必须设 AutoPossessPlayer = Disabled——多人 DS 下非 Disabled 的 Pawn 在 spawn 时会抢占先连入玩家的 PlayerController,导致该玩家位姿卡死、远程看不到他移动。继承 AYomovPawn 即无需关心:C++ ctor 已强制 Disabled,Pawn 由 GameMode.RestartPlayer → NewPC.Possess 正式驱动(单机 Standalone 同样工作)。

AYomovPawn 基类 ctor 做三件事:

设置

值

用途

bOnlyRelevantToOwner

true

原生 Pawn 只对本玩家(owner)可见。远程玩家统一走 Avatar

AutoPossessPlayer

Disabled

多人 DS 防 AutoPossess 抢占

YomovReplication 组件

自动 CreateDefaultSubobject

统一位姿上报组件,子类蓝图无需手挂(避免漏挂)

若本地 Pawn 不继承 AYomovPawn(如直接用官方 VR 模板的 VRPawn),必须手动补齐两件事:

  1. C++ Pawn:ctor 里设 bOnlyRelevantToOwner = true; + AutoPossessPlayer = EAutoReceiveInput::Disabled;

  2. 蓝图 Pawn(如官方 VRPawn):

    • 防 DS spawn 崩溃:VRPawn 的 BeginPlay 会访问 VR 对象,DS 无 VR 运行时会 null 崩溃。Event BeginPlay 后插 Switch Has Authority:Authority(DS)→ 留空;Remote(客户端)→ 接原逻辑

    • 位姿上报:Components 面板手动加 YomovReplicationComponent(搜索 Yomov Replication Component,YOMOV 分组),否则 DS 收到的位姿恒 (0,0,0)

PA_DataAsset.PawnClass:DS BeginPlay 读 UConfigData::PawnClass,非空则覆盖 GameMode 的 DefaultPawnClass,决定 DS 为每个连入客户端 spawn 什么 Pawn。

VRPawn Event Graph 中插入的 Switch Has Authority 节点结构

VRPawn Event Graph 中插入的 Switch Has Authority 节点结构

Components 面板中添加 YomovReplicationComponent

Components 面板中添加 YomovReplicationComponent

验证:PIE 或运行时读 AutoPossessPlayer,应为 Disabled。

PIE 里做 WASD 键鼠测试:用 BP_FirstPersonCharacter 作本地 Pawn 时,需在其 Class Settings → Interfaces 添加 YomovPawnInputProvider 并 Override GetDefaultInputContexts(构造 TArray<FYomovInputContext> 加入 IMC_Default),否则 WASD 无效。日志出现 auto-registered IMC 'IMC_Default' = 注册成功。

3.2 远程 Avatar 配置​

远程玩家 Avatar 完全由插件自动 spawn 与更新,内容方不需要写任何 spawn 代码。推荐路径:先用官方 ThirdPerson 角色零改动跑通链路,再按项目实际模型换成生产 Avatar。

数据链路(了解即可):

Bridge ──msg 501──▶ DS 缓存 + 100ms 去抖合并 ──▶ AYomovGameState::CrossContentPlayers
│ UE 复制
▼
Client URemotePlayerSubsystem 按 PlayerID diff ──▶ spawn/更新 Avatar(位置插值)
└──▶ 2s 未更新则清理

第一步(推荐起步):直接用现成角色蓝图

任何 ACharacter/Actor 蓝图(如 ThirdPerson 模板的 BP_ThirdPersonCharacter)零改动直接配到 DefaultAvatarClass 即可工作——位置、朝向、身高等比缩放都正常同步(子系统按 L3 纯位移驱动)。

  • DA_DataAsset.DefaultAvatarClass → 指向 BP_ThirdPersonCharacter_C

  • DA_DataAsset.NonTeamAvatarClass → ⚠️ 必配:留空时该异队玩家 Avatar 不会 spawn(每 PlayerID 打一次 Warning)。异队想隐藏就配一个无 Skeletal Mesh / 无 AnimBP 的空 BP(如 FirstPerson 模板角色去掉网格体),不要留 nullptr

  • 代价:不继承 ARemotePlayerCharacter 就没有 Acceleration 驱动,远程玩家移动时原地播 Idle(滑步感)。联调演示够用

  • 录制视频:ThirdPerson 起步演示

第二步(生产 Avatar):换成项目自己的模型

  1. Content Browser 右键 → Blueprint Class → 搜 RemotePlayerCharacter → 命名如 BP_RemoteAvatar_Manny

  2. BP 的 Mesh 组件(Inherited)→ Skeletal Mesh Asset 选你的骨架网格体

  3. 同一 Mesh 组件 → Anim Class 选你的 AnimBP(如 ABP_Manny)

  4. DA_DataAsset 的 DefaultAvatarClass / NonTeamAvatarClass 改指向新 BP

  5. (可选)调 HeadToFootOffset:远程头显位置到 Actor 原点(capsule 中心)的 Z 偏移,默认 = capsule 半高(构造期读)。若网格体脚底悬空或沉地,在此微调

  6. (非 1.7m 标准人形模型)改 DA_DataAsset.AvatarDefaultBodyHeight——见 §3.5

为何继承 ARemotePlayerCharacter(即上面的「换」):它内部每帧按反射设 CharacterMovementComponent::Acceleration,让标准 AnimBP 的走路条件(GroundSpeed > 3 AND CurrentAcceleration != 0)正常触发、走路/Idle 自动切换;并提供 HeadToFootOffset 脚底对齐。这是「生产 Avatar」与「直接拿现成蓝图」的唯一实质差别。

接入层级速查(子系统按预制体类型自动判定):

层级

预制体类型

驱动方式

适用

L2(推荐)

继承 ARemotePlayerCharacter

Acceleration 驱动标准 AnimBP(走路/Idle 自动切换)

人形角色(上一步)

L1

实现 IRemoteDrivenActor 接口

Subsystem 每帧回调 OnRemoteMove(DeltaPosition, DeltaTime),业务自写驱动

非 Character 但需自定义动画

L3

任意 AActor

仅 SetActorLocation / SetActorRotation

静态占位 / 现成角色蓝图(第一步)

📷 【截图待补】 Avatar 蓝图 Mesh 组件的 Skeletal Mesh / Anim Class 设置 📷 【截图待补】 DA_DataAsset 中两个 AvatarClass 字段的指向

3.3 队伍与坐标一致性​

TeamID 推导链路(重要)​

DA_CommandLineArgs 里没有FString TeamID / PlayerID,只有 int64 TeamOriginID / PlayerOriginID:

① DA_CommandLineArgs (int64 TeamOriginID = 123456789)
│ ConfigManagerSubsystem 加载 DA 时类型转换(%lld 格式化)
▼
② UConfigManagerSubsystem.TeamID (FString, 客户端本地值)
│ 客户端 BeginPlay 后约 0.5s 触发 Server_Login RPC
▼
③ DS 端 Server_Login_Implementation 写入 PlayerState(PS->TeamID)
│ UPROPERTY(Replicated) 自动下发到所有客户端
▼
④ AYomovPlayerState.TeamID (FString, 权威复制值)

⚠️ 不要在 DA 里直接配 FString TeamID——DA 字段是 int64 TeamOriginID,配错会导致 PlayerState.TeamID 为空、Avatar 同队/异队分支失效、TeamProperty 注册到空 TeamID。

已有自研队伍系统但 ID 仍来自 DA(多数情况):把约定好的队伍源 ID 写入 DA_CommandLineArgs.TeamOriginID(或由运营命令行 / Intent 覆盖),不要调SetLocalTeamIDOverride。

仅当 TeamID 来自非 DA 源(如 Steam Party / EOS Session 当场算出的 ID):在 Server_Login之前调 UYomovTeamSubsystem::SetLocalTeamIDOverride(MyTeamID);切 World 后需重调。蓝图节点:Get YomovTeam Subsystem → Set Local TeamID Override。

队伍查询 API(AreOnSameTeam 同队判定 / FindTeamProperty 按 TeamID 查属性 / GetLocalTeamID 取本机)与多队伍系统机制见 07 §4.6 / 06 §3.5。 同队道具/交互同步(异队互不干扰):一个 DS 承载多支队伍、需要同队玩家共同操作道具时,按 10 多队伍道具与交互同步 配置。

⚠️ 边界坐标归一化前提(多队伍最常踩的坑)​

msg 500 / 501 的 Position 字段 = 边界局部坐标(相对 BoundaryRealActor),不是世界绝对坐标。多队伍下要求各端 DA 边界字段必须完全一致,否则跨机远程玩家坐标错位(Avatar 飘到错误位置 / 钻地 / 飞天):

DA

必须一致的字段

DA_CommandLineArgs

MapData(含 StartPoint / LocatePoint / ArcadePoly 等)

DA_DataAsset

AnchorPoint / AnchorRotationY / ActSizeLength / ActSizeWidth

保证方式:由内容统一分发同一份 DA(复制到所有客户端 APK + DS),不要各端手配。任一端不一致 → 该端看到的跨服玩家坐标错位,且现象具有「单端错位」特征。坐标语义与转换细节见 06 §3.4。

跨 DS(跨服)玩家:各 DS 世界没有共同真值,1.2.3 起经锚定系换算(锚定到 Act 基准),载具 / Plot 推进造成的边界位移不进入坐标。同一 DS 上的跨组玩家统一走边界局部坐标(同场馆物理语义),无需额外配置。

3.4 远程玩家可见性规则(1.1.1 起,配置即生效)​

表现层距离可见性规则(数据复制不变,只控制 Avatar 显隐):

远程玩家

可见性

同内容 + 同队

恒可见(不受虚空状态与距离影响)

其余(异内容 / 异队)

距离迟滞:进入 RemotePlayerVisibleDistance(默认 500cm)显示,超出 +50cm 隐藏

  • 距离按头显视点计算(1.2.3):观察点取本机头显位置(GetPlayerViewPoint),不是 Pawn 根——Pawn 根被钉在边界 / Act 原点,用它会变成「离场地中心多远」

  • 调参:设 <= 0 恢复全部恒显(语义对齐 Unity otherTeamDistance = 5);设极小值(如 1cm)近乎彻底隐藏异队

  • 诊断日志(客户端):Visibility: rules active (ShowDist=...)——没有这行先查 DA 是否加载

  • 跨内容 / 跨 DS 玩家经统一锚定换算后与同服同一口径;联调时以日志里实际距离(Visibility: ... -> shown/hidden)为准

3.5 身高校准缩放(BodyScale,1.1.1)​

远程 Avatar 按本地玩家真实头显高度等比缩放(对齐 Unity SingleAvatar.SetBodyHeight 口径):

BodyScale = 头显离边界地面高度 ÷ AvatarDefaultBodyHeight

  • 静态校准:首次有效头高(100~220cm 合理区间)即锁定,不随每帧头高漂移

  • 播控 SetHeight 触发解锁重算(日志 BodyScale recalibration requested);⚠️ 指令值本身不参与缩放——缩放恒来自真实头显高度

  • 缩放值钳下限 0.3;同服(同 DS)玩家生效,跨服(Bridge 回传)数据恒 1.0 不缩放(501 协议无身高字段,1.2.3 起显式默认 1.0,对齐 Unity)

  • Z 联动:缩放后模型脚仍着地、头 ≈ HMD 高度——前提是 AvatarDefaultBodyHeight 配的是 Avatar 模型实际身高

⚠️ 换非 1.7m 标准人形模型时必须改 DA_DataAsset.AvatarDefaultBodyHeight,否则缩放后头/脚高度不准。


步骤四:服务端设置​

本步打 DS 并打通 DS ↔ Bridge 链路。排障细节见本篇末尾的「附录 A. DS 部署排障」。

4.1 前置检查​

⚠️ 硬要求:打 headless DS 必须用源码版引擎(<UE_SOURCE_ROOT>)。Epic 官方限制:Launcher 安装的预编译引擎不含 Server target,UBT 直接拒绝(exit 6,10 秒内退出)。

打包前检查:关闭编辑器 + 关掉所有 YOMOVSDKServer.exe 旧进程(否则 YomovCore.dll 文件锁 / UAT stage 阶段 retry 失败)。

基础 DefaultEngine.ini 三段配置见 附录 A.2。

4.2 编译 Server target​

& "<UE_SOURCE_ROOT>/Engine/Build/BatchFiles/Build.bat" YOMOVSDKServer Win64 Development "<PROJECT_ROOT>/YOMOVSDK.uproject" -WaitMutex

4.3 打包 DS​

& "<UE_SOURCE_ROOT>/Engine/Build/BatchFiles/RunUAT.bat" BuildCookRun `
-project="<PROJECT_ROOT>/YOMOVSDK.uproject" `
-noP4 -platform=Win64 -server -noclient -serverconfig=Development `
-Target=YOMOVSDKServer -cook -build -stage -pak -archive `
-archivedirectory="<PROJECT_ROOT>/PackageOutput/DS"

⚠️ UAT 命令必须用 PowerShell 调用,不要用 Bash:Git Bash(MSYS2)会把 -Maps=/Game/YourMap/... 这类参数当成路径转换成 C:/Program Files/Git/Game/...,导致 cook 找不到地图。

产物路径树(PackageOutput/DS/WindowsServer/):

WindowsServer/
├── YOMOVSDKServer.exe # DS 主程序(headless)
├── config.ini # DS 运行时配置(放安装顶层,见 4.4)
└── YOMOVSDK/
├── Binaries/Win64/
│ └── YomovCore.dll # SDK 核心 DLL
├── Content/Paks/
│ └── YOMOVSDK-WindowsServer.pak
└── Saved/Logs/
└── YOMOVSDK.log # 运行时日志(排查看这个)

binary 包消费方:用 binary 分发的插件打 DS 时,插件包必须含 YomovUESDKCore-Server.lib(Server target obj 编译的导入库)。Build.cs 会按 Target.Type 自动选——Server target 链 -Server.lib,Game/Editor target 链 YomovUESDKCore.lib;缺失会直接 BuildException。源码包无此要求。

4.4 部署 config.ini 并启动​

DS 监听端口不走命令行,由 YomovIpNetDriver 读 config.ini 的 config serverPort 字段决定。

✅ config.ini 放 DS 安装顶层 WindowsServer/config.ini(exe 旁——播控/业务系统约定的部署位置)。驱动启动时按候选链查找、取第一个命中:ProjectDir → exe 所在目录(Binaries/Win64)→ exe 目录逐级向上 6 层(覆盖到安装顶层)。放顶层或 Binaries/Win64/ 均可命中,推荐顶层(与业务部署约定一致)。

[config]
serverPort=9527

启动:

YOMOVSDKServer.exe /Game/YourMap?Listen -server -log

命令行若显式带 -Port=xxxx,YomovIpNetDriver 会尊重显式指定,不覆盖;不带才用 config.ini serverPort。

4.5 客户端连入 DS​

① 自动 ClientTravel(打包客户端,推荐):客户端 AYomovPlayerController 在 BeginPlay 检测到 NetMode == NM_Standalone && !GIsEditor(即打包客户端,非 PIE)时,读 DA 的 ServerIP / ServerPort 自动 ClientTravel 连 DS。

② 手动 open(PIE / 编辑器 console):

open <ds-ip>:9527

⚠️ 端口必须对齐:客户端 DA ServerPort(默认 9527)必须与 DS config.ini 的 serverPort 一致。登录成功后日志出现 Server_Login success。

4.6 启动联调顺序​

顺序建议 Bridge 先就绪。1.2.3 起 DS→Bridge 断线自愈(1s 间隔无限重连,重连成功立即全量重发一帧 msg500 重建缓存)——Bridge 后起 / 中途重启也能自动恢复,但 Bridge 未就绪期间的跨组数据会缺失,且期间登录的玩家需要等一轮重连周期。

① 启动 BridgeServer(<TOOLS_ROOT>/BridgeServer*/BridgeServer.exe)
② 启动 DS(?Listen -server -log)
③ 启动 VR 客户端(自动 ClientTravel 或 open <ds-ip>:9527)
④ (可选)用 ContentSimulator 注入跨内容玩家,验证跨服 Avatar

联调工具路径与用法见 08 §联调工具。

4.7 成功标志​

按顺序确认:

  1. 编译成功:Server target exit 0,无 LNK 错误

  2. 打包产物:PackageOutput/DS/WindowsServer/ 下有 YOMOVSDKServer.exe + YomovCore.dll + config.ini + Content/Paks/

  3. 启动监听:DS 日志出现 YomovIpNetDriver 监听 config.ini serverPort(默认 9527),不是 7777

  4. 客户端连入:客户端日志出现 Server_Login success

  5. Bridge 连接:DS 日志出现 UTCPClientSubsystem: Connected to(DS 作为 TCP 客户端连上 Bridge,地址由客户端 DA 上报)

  6. 远程玩家:客户端日志出现 Spawned remote player + ResolveAvatarClass,画面能看到远程 Avatar

✅ 本地玩家不应出现在 spawn log 里:URemotePlayerSubsystem 通过 AYomovPlayerState::YomovPlayerID 自动过滤本机玩家。若看到本地 Avatar 被 spawn 成远程玩家,先检查 YomovPlayerID 是否正常复制、本地 Pawn 是否被错误当作远程数据上报。


流程 B:不接入 SDK 多人同步

适用:单机体验内容,或内容已有自研多人方案、只需 SDK 的播控 / 桥接 / 大空间路径能力。

一、初始化设置​

  1. 关卡结构与 GameMode 按内容自身需要配置(不挂UBridgeServerControllerComponent / UYomovDSServerComponent)

  2. 若使用固定路径 / Marker / FlowController 边界,按 流程 A 步骤一 §1.3–§1.5 放置 AYomovManagerActor / StationaryActUnitMarker / 边界

二、创建大空间路径​

与 流程 A 步骤二 完全一致(路径能力与多人无关)。

三、服务端设置​

不使用 DS:客户端直接连 Bridge 业务服务器(单机播控直驱模式)。

  1. DA_CommandLineArgs 配好 BridgeServerIP / BridgeServerPort

  2. 场景中放 BP_BridgeEventReceiver,保持 bAutoConnectOnBeginPlay = true(默认)

  3. BeginPlay 自动连 Bridge,绑 On Remote * 事件驱动业务

若已有自研多人方案,但想复用 SDK 的远程 Avatar 可视化:走 流程 A 步骤一 §1.2 的「替换」粒度——自有业务层调 UBridgeRemotePlayerLibrary::SpawnOrUpdateRemotePlayer 喂数据给 URemotePlayerSubsystem(Subsystem 自动管理 Avatar 生命周期),不需要两个核心组件。


附录 A. DS 部署排障

线性接入不需要读本附录。DS 起不来 / 端口不对 / 连不上 Bridge 时来这里按编号查。

A.1 十一个坑(现象 + 根因 + 规避)​

现象

根因 / 规避

1

打包 DS 时 UBT 文件锁 / exit 6 / UAT stage retry 失败

打包前关编辑器 + 关所有 YOMOVSDKServer.exe 旧进程:YomovCore.dll / YOMOVSDKServer.exe 被占用导致写入失败

2

UBT 报 Server targets are not currently supported from this engine distribution(exit 6,10 秒内退出)

必须用源码版引擎(<UE_SOURCE_ROOT>)。Launcher 安装版打不了 Server target

3

DS 作为管道子进程跑时 stdout 停在 FEngineLoop::Init() 假死(缓冲不刷)

别信 stdout,读日志文件<DS>/YOMOVSDK/Saved/Logs/YOMOVSDK.log。完整启动链路、报错、msg 收发都在日志里

4

DS 启动后 config.ini 找不到 / 端口不对

config.ini 放安装顶层 WindowsServer/config.ini(exe 旁);驱动按候选链查找(ProjectDir → exe 目录 → 向上 6 层),见 §4.4

5

DS 连 Bridge 失败 / 连到错误 IP

Bridge 地址配在客户端 DA(BridgeServerIP / BridgeServerPort),经 Server_Login RPC 上报给 DS。DS 命令行 -BridgeIP=不生效(进程不解析)

6

binary 消费方打 DS 报 YomovUESDKCore-Server.lib 缺失 / LNK 错

binary 包必须含 YomovUESDKCore-Server.lib;若用旧版 binary 包无 Server lib,重打插件包

7

PIE listen server 测 DS 行为时 DS 组件没挂上 / 行为异常

PIE 的 server 读地图级 GameMode Override,不读 GlobalDefaultServerGameMode。单玩家 PIE 无远程 client 触发 RPC,走不到 DS→Bridge 链路;2 玩家 PIE(Number of Players = 2)可走通完整链路(实测)

8

DS 监听端口仍是 7777 / YomovIpNetDriver 不生效

DefaultEngine.ini 必须 !NetDriverDefinitions=ClearArray 再 +:不清空直接 +,引擎默认的 GameNetDriver → IpNetDriver 排在数组 0 优先命中,你的 YomovIpNetDriver 永远不被实例化

9

UAT BuildCookRun 报 cook 找不到地图 / 路径错乱

UAT 命令用 PowerShell 调,不要用 Bash(Git Bash 会转换路径参数)

10

客户端连不上 DS / 播控模拟器看到「测试玩家」假数据刷屏

端口不一致(见 §4.5)或旧包已知缺陷。按 §4.5 核对端口三方一致;若是旧包(< 1.1.1)的 DS 端 BridgeEventReceiver 自动连 DA 默认地址占住连接,升级插件即可(1.1.1 已解耦)

11

重启 Bridge 后播控显示「程序关闭」/ 玩家位置停在注册值

旧版 DS→Bridge 断线后 msg500 流静默中断。1.2.3 已修:DS 每 1s 自动重连并在重连成功后立即全量重建上报,播控数据 ≤2s 恢复,无需重启 DS / 重新登录。排查 grep DS 日志 Bridge disconnected, reconnect timer armed / Bridge reconnected after N attempt(s)

A.2 DefaultEngine.ini 关键配置​

① NetDriver 配置​

/Script/Engine.Engine
!NetDriverDefinitions=ClearArray
+NetDriverDefinitions=(DefName="GameNetDriver",DriverClassName="/Script/YomovUESDKCore.YomovIpNetDriver",DriverClassNameFallback="/Script/OnlineSubsystemUtils.IpNetDriver")
+NetDriverDefinitions=(DefName="DemoNetDriver",DriverClassName="Engine.DemoNetDriver",DriverClassNameFallback="Engine.DemoNetDriver")

⚠️ 必须先 !NetDriverDefinitions=ClearArray 再 +:UE 的 FindNetDriverDefinition 返回数组里第一个匹配项,引擎 BaseEngine.ini 默认的 GameNetDriver → IpNetDriver 排在 0。不清空直接 + 你的 YomovIpNetDriver,结果还是走引擎默认驱动,DS 监听端口读不到 config.ini serverPort。 YomovIpNetDriver 的作用:DS 启动时读项目根 config.ini 的 serverPort 写入 LocalURL.Port,让 DS 监听可配置端口(缺该字段会回退引擎默认 7777)。 客户端握手加速(1.2.3,默认启用,可选覆盖):客户端 Host 为 IPv4 字面量地址时禁用引擎异步地址解析(首包不再被丢弃),握手 ~1.06s → ~0.06s。需要退回引擎默认行为时,在 DefaultEngine.ini 加 [/Script/YomovUESDKCore.YomovIpNetDriver] 段并设 KeepAddressResolution=True;重发间隔可设 HandshakeResendInterval=0.25(夹取 [0.1, 1.0])。机制见 06 §3.6。

② Server 默认地图与 GameMode​

/Script/Engine.GameSession
GameDefaultMap=/Game/YourContent/YourStartupMap.YourStartupMap
ServerDefaultMap=/Game/YourContent/YourServerMap.YourServerMap
GlobalDefaultGameMode=/Game/YourContent/VRGameMode.VRGameMode_C
; 推荐:插件预制蓝图
GlobalDefaultServerGameMode=/YomovUESDKCore/Blueprint/BP_YomovDSGameMode.BP_YomovDSGameMode_C
; 或 C++ 模板:/Script/YomovUESDKCore.YomovDSGameModeTemplate

③ Server target 排除 VR 插件​

// Source/YOURPROJECTServer.Target.cs
public class YOURPROJECTServerTarget : TargetRules
{
public YOURPROJECTServerTarget(TargetInfo Target) : base(Target)
{
Type = TargetType.Server;
DefaultBuildSettings = BuildSettingsVersion.V4;
// ⚠️ 改为你自己项目的 game module 名
ExtraModuleNames.AddRange(new string[] { "YourGame" });

// Dedicated Server 不渲染,排除 VR 客户端插件(仅作用于本 Server target)
DisablePlugins.AddRange(new string[] { "PICOOpenXR" });
}
}

DS 是 headless,不渲染也不需要 OpenXR/PICO VR 运行时;不排除会在打包阶段报 PICO 插件缺失渲染相关依赖。DisablePlugins 只作用于本 Server target,不影响编辑器或客户端 target。

与自有多人系统共存(NetDriver 三档)​

UE 的 GameNetDriver 是 engine 级单例(关卡 / GameMode 切换不换 NetDriver),因此「切换 SDK 多人 / 自有多人」= 部署或构建时按场景选一套 DefaultEngine.ini,不支持运行时热切。

档

场景

GameNetDriver 指向

端口来源

档 0(默认)

无自有多人能力,全靠 SDK

YomovIpNetDriver(按 A.2 ① 配置,含 !ClearArray)

SDK config.ini serverPort

档 1(共存·SDK 主)

用 SDK 多人 + 另需独立网络通道

YomovIpNetDriver;内容方 NetDriver 用独立 DefName 并存(如 ContentNetDriver)

SDK config.ini serverPort

档 2(共存·内容方主)

自有多人做主复制,SDK 仅用单机 / Bridge 能力

内容方 NetDriver(如 OnlineSubsystemSteam.SteamNetDriver);不抄 !ClearArray

内容方自管(自有 driver 或 -Port=)

  • 档 1 示例追加行:+NetDriverDefinitions=(DefName="ContentNetDriver",DriverClassName="<内容方 NetDriver 类路径>",DriverClassNameFallback="/Script/OnlineSubsystemUtils.IpNetDriver");代码用 GetWorld()->GetNetDriverByName(TEXT("ContentNetDriver")) 取用

  • 档 2 下 SDK 多人复制链路不启用(内容方用自己的 GameMode),但 SDK 其他能力(边界 / 路径 / 场景 / Bridge)仍可用


接入完成检查清单

接入完成后逐条确认:

  • 插件安装并启用,版本与引擎匹配

  • DA_CommandLineArgs / DA_DataAsset 已创建,字段按 02 §2 配齐

  • 多人:各端使用同一份 DA(MapData / AnchorPoint / AnchorRotationY / ActSizeLength / ActSizeWidth 完全一致)

  • 多人:GameMode 用 BP_YomovDSGameMode(或自建时 GS/PS/PC 三件套指向 Yomov 类 + 两组件同 Owner)

  • 多人:本地 Pawn AutoPossessPlayer = Disabled(继承 AYomovPawn 或手动设)+ 位姿上报组件已挂

  • 多人:DefaultAvatarClass / NonTeamAvatarClass都不为空

  • 多人:DS 用源码版引擎打包;config.ini 部署到 Binaries/Win64/;端口三方一致

  • 多人:DefaultEngine.ini 的 NetDriver 配置含 !ClearArray

  • 多人:切场景 barrier / 上行超时踢除开关全队一致(bEnableSceneSyncBarrier / bEnableUplinkTimeoutKick / UplinkTimeoutSeconds,默认值即推荐)

  • 路径单元(Act / Plot)已摆放并烘焙(Sequence 模式跑过 [Update Act Sequence])

  • BestPath 已摆放并 [保存路径],且已 Ctrl+S 手动保存(1.2.3 起 SettingPanel 配置写回会自动落盘,BestPath 仍需手动保存)

  • Sequence 模式:Plot 推进驱动已配置(蓝图轨:驱动蓝图或自定义副本已摆进关卡;时间轨方案见 06 §1.4)

  • 联调顺序正确:Bridge → DS → 客户端(1.2.3 起 Bridge 可后起,DS 自动重连恢复)

  • 测试与打包按 04 测试打包 走完三阶段