产品简介
插件版本 1.2.3 | 文档版本 1.2.3 | UE 5.3-5.7 本篇讲清「这是什么、解决什么业务、有哪些核心概念」;接入操作见 02 快速入门 与 03 接入流程。 术语与命名统一写法见本篇 附录 A / 附录 B。
目录
-
- 这是什么
-
- 产品架构
-
- 功能模块
-
- 核心概念
-
- 完整接入链路全景
-
- SDK 核心组件速览
-
- 发布记录
-
附录 A. 术语速查
-
附录 B. 命名对照(统一写法)
1. 这是什么
游幕是国内领先的 LBEVR 分发平台,帮助优秀的 LBEVR 内容通过线下门店方式触达用户。YOMOV SDK 帮助开发者快速接入平台,完成 VR 应用分发闭环。
YomovUESDKCore 是该平台的 Unreal Engine 版本接入插件,覆盖分发的核心能力:
-
放映鉴权与启播参数解析(Win 命令行 / PICO Android Intent)
-
播控系统通信(开始 / 暂停 / 恢复 / 跳转 / 设高 / 退出)
-
桥接数据同步(多应用混播下的跨内容玩家数据)
-
大空间路径(路径单元创建、参数设置、配置导出、运行演绎)
-
多人同步(Dedicated Server + 远程 Avatar)
-
虚空边界、玩家引导、报幕
一句话:装上插件 → 连 Bridge 业务服务器 → 收播控指令 / 看到远程玩家 Avatar。单人蓝图即可跑通;多人需 Dedicated Server。
本手册范围:聚焦 UE 侧插件操作,不替代运营系统接入说明。后台启播、内容管理、场次编排见 YOMOV 分发 & 运营系统接入说明。
1.1 与 Unity 版 YOMOV SDK 的关系
游幕平台同时提供 Unity 版(SDK Core + SDK Creator)与 UE 版(本插件)。两版核心业务概念一致,术语与实现不同——完整对照表见 00 §Unity 版 ↔ UE 版 对照。
最需要记住的一条:
内容类型 | Unity 版 | UE 版 |
|---|---|---|
大空间奇境(行走观看、剧情体验、空间探索) | 动态路径 | Sequence 模式 |
小空间游戏(高频交互、玩法对抗) | 固定路径 | Single 模式 |
⚠️ 能力范围差异:Unity 版 SDK Creator 的部分增值能力(玩家角色 IK 动作、游后分享、LBE 先导片、载具类 Plot、多语言自动适配)UE 版暂未提供或覆盖范围不同。接入前请与游幕对接人确认 UE 侧支持范围。
2. 产品架构
2.1 通信架构
LBEVR 分发链路自上而下分为五层,UE 插件工作在「内容逻辑层」:
账号权限 / 内容管理 / 接收管理 / 对账管理 运营管理层
设备管理 / 应用下载 / 内容启播 / 排映管控 播控运营层
玩家方位同步服务 / 标准内容指令同步 / 播控指令同步 多内容桥接层(Bridge)
内容服务器 A · 内容服务器 N 内容逻辑层 ← ★ UE 插件在这里
VRAgent / 头显硬件 头显硬件层
产品通信架构图(分层 + 数据上下行箭头)
2.2 UE 插件在链路中的位置
播控运营系统 ──启播参数──▶ VR 客户端(UE 插件)
│
│ Server_Login 上报 Bridge 端点
▼
Dedicated Server(UE 插件)
│ TCP 自定义协议(msg 500 / 501 / 503)
▼
Bridge 业务服务器
│
│ 跨内容玩家数据 / 播控指令
▼
各内容的 DS → UE 复制 → 各 VR 客户端
三条关键事实(后面所有章节都建立在这三条上):
-
客户端连 DS,DS 连 Bridge。 客户端不直连 Bridge 业务服务器(单机播控直驱模式除外)。
-
Bridge 地址来源是客户端上报,不是 DS 命令行参数——客户端 DA 里配
BridgeServerIP/BridgeServerPort,登录 DS 时经Server_LoginRPC 上报。 -
DS 是网络权威:对下(VR 客户端)走 UE 原生复制,对上(Bridge)是 TCP 客户端。
3. 功能模块
UE 版插件覆盖的模块(对照 Unity 版 SDK Core / Creator 的能力划分):
模块 | UE 版 | 说明 |
|---|---|---|
放映鉴权 | ✅ | 启播放映内容经密钥下发解析鉴权放行 |
播控系统通信 | ✅ | 读取解析启播参数及放映中播控指令(msg 503) |
桥接数据同步 | ✅ | 接收与转发桥接服务器多应用数据(msg 500 / 501) |
大空间路径 | ✅ | 动态(Sequence)/ 固定(Single)两种模式;路径单元创建、参数设置、配置导出、运行演绎全流程 |
多人同步 | ✅ | Dedicated Server + 玩家位姿同步 + 远程 Avatar + 多队伍 |
虚空 / 引导 / 报幕 | ✅ | 越界保护、BestView 引导、完结报幕 |
多设备适配 | ✅ | 通过 OpenXR 适配 PICO 等主流设备(UE 引擎侧负责) |
玩家角色 IK 动作 | ⚠️ 部分 | 远程 Avatar 手部 IK 有接口;完整动作库未提供 |
游后分享 / LBE 先导片 | ❌ | UE 版未提供 |
载具类 Plot | ⚠️ 部分 | Sequence 模式暂无载具 Plot;Single 模式可用 Marker 方案实现载具效果(见 §5.3) |
多语言自动适配 | ❌ | UE 版未提供 |
表中 ⚠️ / ❌ 项接入前请与游幕对接人确认,不要按 Unity 版能力清单直接排期。
4. 核心概念
4.1 大空间 VR 类型
游幕基于内容的体验方式、互动强度、运营方式,将大空间 VR 内容划分为两类。内容方需先判定自己的类型,再选择对应的路径模式:
对比维度 | 大空间奇境 | 小空间游戏 |
|---|---|---|
核心体验 | 行走观看、剧情体验、沉浸式游览 | 高频交互、游戏挑战、动作玩法 |
内容重点 | 场景氛围、叙事节奏、角色/剧情演出、空间探索 | 玩法机制、操作反馈、胜负目标、关卡挑战 |
交互强度 | 较轻(触发、观看、简单选择) | 较强(持续操作、躲避、射击、挥砍) |
玩家运动强度 | 适中,以自然行走、停留观看为主 | 较高,可能包含快速移动、转身、蹲避 |
适合客群 | 亲子、文旅、展览、轻度玩家 | 游戏玩家、年轻客群、团队挑战 |
场馆运营方式 | 可混播(同空间安排不同批次/内容组合) | 通常隔离空间运营 |
UE 路径模式 | Sequence(动态路径) | Single(固定路径) |
4.2 大空间路径
大空间路径是理解 LBEVR 分发的核心概念——把内容切割成离散体验单元,用路径把它们首尾相连,实现内容在物理空间中连续行进。
动态路径 → UE 的 Sequence 模式
把 VR 内容切分为多个离散体验单元(Act),通过路径形式首尾相接,形成在虚拟内容与物理空间中连续的行进式体验。核心步骤是定义路径单元与连接路径单元。
-
适用:大空间奇境
-
产品功能:SDK 层定义内容单元元素,运营放映层由路径服务器完成动态路径连接,实现场馆地图精准适配与玩家最大化避让调度
动态路径示意图(多 Act 首尾相接 + 高坪效算法适配场馆地图)
两个基本单元:Act 与 Plot
单元 | 定义 | 组成 | 说明 |
|---|---|---|---|
Act | 最小连续可行走空间单元 | 1 个进入区 + 1 个退出区 + 1 个连续可行走区域 | 跨 Act 体验时内容空间会发生旋转/偏移;是分发适配的最小空间单元(高坪效算法适配场馆地图) |
Plot | 最小内容体验单元 | 1 个内容体验边界 + N 段故事表演 | 体验超出 Plot 边界会进入虚空层空间;多个 Plot 组成 1 个 Act |
路径单元的尺寸、数量、衔接设计原则见 05 大空间最佳实践。
固定路径 → UE 的 Single 模式
把整体体验范围作为唯一路径单元,在场馆中动态调度。
-
适用:小空间游戏
-
产品功能:SDK 层定义整体内容体验范围,该范围尺寸被路径服务器调度,实现不同小空间游戏之间的隔离调度
固定路径调度示意图(应用 A/B/C 各自范围被重新排列)
4.3 多应用桥接同步
通过封装一层桥接服务实现跨应用的玩家位姿数据同步,实现同场馆多应用混播。
-
桥接服务器(Bridge):接收与转发放映中多个应用服务器的数据
-
应用服务器(DS):作为 TCP 客户端连接 Bridge,上报本服玩家数据、接收跨服玩家数据与播控指令
-
效果:同一个场馆空间中可同时运营多款内容,玩家之间以「跨服玩家」形式互相可见
多应用桥接同步架构图
5. 完整接入链路全景
内容方将 VR 体验接入运营系统,需要完成以下核心环节:
运营系统启播 → 启播参数下发 → 内容初始化(位置/队伍/玩家/Avatar)
→ 桥接服务器连接 → 播控指令同步 → 多人数据同步 → 联调验证
接入环节 | 说明 | 本手册覆盖 | 对应篇章 |
|---|---|---|---|
运营系统启播 | 运营后台创建场次、分配队伍和玩家 | ❌ 参考运营系统文档 | — |
启播参数下发 | 系统将场次信息传递给 UE(命令行 / Intent) | ✅ 参数接收与消费 | 02 §初始配置 |
内容初始化 | 根据参数设置启动位置、队伍、玩家、Avatar | ⚠️ 插件提供能力,业务侧实现逻辑 | 03 流程 A 步骤三 |
桥接服务器连接 | 建立 TCP 连接、收发数据 | ✅ 插件自动管理 | 03 流程 A 步骤四 |
播控指令同步 | 接收并响应开始/暂停/恢复/跳转/退出 | ✅ 事件转发,业务侧响应 | 07 §播控事件 |
多人数据同步 | 发送本地玩家数据、接收远程玩家数据 | ⚠️ 下行接收自动( | 03 流程 A 步骤三 |
联调验证 | 确认各环节功能正常 | ✅ 测试组件和验证方法 | 04 测试打包 |
图例:✅ 手册完整覆盖 | ⚠️ 插件提供能力,需业务侧代码 | ❌ 超出本手册范围
5.1 单人 vs 多人,差在哪
维度 | 单人流程 | 多人流程(DS) |
|---|---|---|
GameMode | 任意 | 插件预制 |
服务器 | 无 DS | Dedicated Server(必须源码版引擎打包,见 04 §DS 打包) |
远程玩家 | 无 | 远程 Avatar 自动 spawn( |
队伍 | 无 | 多队伍 + 边界坐标归一化(见 03 §流程A 步骤三) |
单人与多人的路径选择见 03 接入流程:流程 A(接入 SDK 多人同步)/流程 B(不接入多人)。
5.2 蓝图 vs C++ 能力边界(5 分钟判定)
需求 | 蓝图可完成 | 需要 C++ | 建议入口 |
|---|---|---|---|
单人播控接入(Start/Pause/Resume/Seek/Exit/SetHeight) | ✅ | ❌ |
|
Bridge 连接状态展示(Connected/Disconnected/Reconnecting) | ✅ | ❌ |
|
远程玩家自动生成/更新/清理(标准多人链路) | ✅(配置为主) | ❌(可选) | 配 |
自有数据源手动喂远程玩家(不走标准 501 链路) | ✅(函数库) | 可选 |
|
DS 部署、Server target、 | ❌ | ✅(工程层) | 04 §DS 打包 / 03 附录 |
binary 包下跨模块业务 API 调用(避免 LNK2019) | ❌ | ✅ | 走 |
6. SDK 核心组件速览
6.1 YomovManagerActor(YMMA)
AYomovManagerActor 是插件运行时核心入口,自带 FlowControllerComponent(流程 / 边界)+ BridgeServerControllerComponent(桥接)。是否手摆进关卡:
你的用法 | 要不要手摆 |
|---|---|
只播控( | 不必手摆。客户端由 |
用固定路径 / Marker / FlowController 边界 | 要手摆,并按下方配 Flow / Marker |
手摆方式:场景大纲或视口右键 → 搜 "Yomov Manager Actor" → 拖入场景。
DS 端不会自动 spawn YMMA(Dedicated Server 设计如此)。
6.2 FlowController 边界
选中 YomovManagerActor → Details 面板 → Flow Controller → Spatial。
1.1.0 起 CDO 自动 wire 边界材质(M_Boundary_Real / M_Boundary_Line,路径 /YomovUESDKCore/Boundary/Materials/,随插件包分发),内容方无需手配;要换自定义材质在面板对应属性覆盖即可。
四种边界组件:
组件 | 用途 | 可视化 | 材质 |
|---|---|---|---|
| Single 矩形锚点围栏(玩家活动区) | ✅ |
|
| 场馆级多边形围栏 | ✅ |
|
| 场馆内障碍物围栏 | ✅ | 复用 |
| 纯逻辑矩形边界(碰撞 / 范围判定) | ❌ 无 mesh | 无 |
可见性规则:玩家距边界超过 ShowDistance(Anchor = 30cm / Real = 80cm)时 alpha = 0 不可见——这是有意设计(避免围栏干扰主体内容),不是 bug。
调试强制显示:cvar Yomov.Boundary.Show,或蓝图节点 DebugSetBoundaryAlpha(1.0)。
⚠️
Yomov.Boundary.Alpha是无参命令(硬编码设为 1.0,不接0.5参数);要自定义透明度用蓝图节点DebugSetBoundaryAlpha(0~1)。
6.3 StationaryActUnitMarker(仅 Single 模式)
仅 Single(小空间固定路径) 模式需要;Sequence 模式不需要。
StationaryActUnitMarker 定义物理房间在虚拟场景中的映射位置,插件每帧读其 Transform,将玩家围栏与场馆边界空间对齐。
放置:场景右键 → 搜 "Stationary Act Unit Marker" → 放到玩家应该进入的起始位置(Marker 世界坐标 = 物理房间中心在虚拟场景的映射点)。
-
每场景只能放一个
-
Single 模式启动后 10 秒内未找到 Marker 会打 Warning(
continuing without Marker)并继续运行(降级状态,VRPawn 不会对齐到物理房间) -
若依赖载具移动效果,必须确认 Marker 已放置且命名正确
移动载具效果:Single 模式下 VRPawn 跟随真实边界、真实边界跟随 Marker 锚点。因此移动 Marker 的位置可带动 VRPawn 跟随移动,实现观光车 / 电梯等载具移动效果。
7. 发布记录
版本 | 日期 | 改动 |
|---|---|---|
1.2.3 | 2026-11-11 | 多人同步稳定性专项(实机场次问题集中根治):① 同队同步与 Bridge 501 解耦——同队玩家位姿由 DS 直接发布( |
1.2.2 | 2026-09-28 | 修复三问题(实机反馈)+ 新增两蓝图:① 开始放映补消费——播控 Start 在客户端叙事未就绪窗口内到达时不再丢失(就绪时若本队已在播放则自动补启),修复「播控点了开始放映但一直不触发」;② BodySync 5s 心跳兜底——静止 / 后台恢复期位姿数据停跳会被下游按超时误判离线,导致远程 Avatar 消失(实测 47s 空窗); |
1.2.1 | 2026-09-24 | ① 新增 18 个 Try* 蓝图函数(可判错版本,返回 |
1.1.1 | 2026-09-16 | ① 远程玩家可见性规则(同组恒显 / 异组 5m 显·5.5m 隐迟滞;DA 新增 |
1.1.0 | 2026-07-28 | 新增多人功能(DS / 远程 Avatar / 多队伍 / 完整示例 / 检查清单)。⚠️ 破坏性变更: |
1.0.3 | 2026-06-25 | 播控事件委托签名统一为 |
升级提示(1.0.x → 1.1.x):两处破坏性变更(Avatar 字段类型、播控委托签名)需手工重配,详见对应版本行。
Try*家族为渐进式变更,旧函数仍可用。
附录 A. 术语速查
术语 | 全称 / 含义 | 一句话定义 |
|---|---|---|
Bridge | 桥接业务服务器 | YOMOV 自定义 TCP 协议的业务服务器;DS 作为 TCP 客户端连接它,收发 msg 500/501/503(跨内容玩家数据聚合 + 播控指令转发) |
Act | 路径单元 | 最小连续可行走空间单元(1 进入区 + 1 退出区 + 连续可行走区;边界 = 子 Plot 并集);跨 Act 体验会有空间旋转/偏移;是分发适配的最小空间单元(高坪效算法适配场馆地图) |
Plot | 内容单元 | 最小内容体验单元(1 个内容体验边界 + N 段故事表演);出 Plot 边界进入虚空;多个 Plot 组成 1 个 Act |
虚空(VoidSpace) | 越界保护态 | 玩家走出 Plot 边界并集后的保护场景:隐藏全部场景内容,只留虚空天球/地面与引导元素 |
DS | Dedicated Server(专用服务器) | UE headless 专用服务器;多人方案的网络权威(对下 UE 复制)+ 协议网关(对上连 Bridge)。必须源码版引擎打包 |
CrossContentPlayers | 跨内容玩家列表 |
|
TeamProperty | 队伍属性 |
|
BodyScale | 身高校准缩放 | 远程 Avatar 的等比缩放系数(= 头显离边界地面高度 ÷ |
BoundaryRealActor | 边界真实 Actor | 远程 Avatar 坐标的基准 Actor(边界局部坐标系原点);远程 Avatar attach 到它,坐标用边界局部语义,保证跨端一致 |
Server_Login | 登录 Server RPC | 客户端连入 DS 后发的 Server RPC( |
msg 500 / 501 / 503 | 桥接协议消息 | 500 = UE→Bridge 本服玩家位姿(100ms);501 = Bridge→UE 跨服玩家数据;503 = 双向播控指令(1=Pause 2=Resume 3=Seek 4=Exit 5=Start 6=SetHeight) |
附录 B. 命名对照(统一写法)
为避免「同一对象多个名字」造成误读,本手册统一采用下表写法:
统一写法(推荐) | 你可能看到的别名 | 说明 |
|---|---|---|
| YomovManagerActor、YMMA、Manager Actor | 插件运行时核心 Actor;正文统一写 |
| BridgeEventReceiver | 蓝图接入入口资产名;其父类是 |
| BridgeEventReceiver(C++ 语境) | C++ 类名;仅在 API / 源码语境使用 |
| RemotePlayerSubsystem | 远程玩家生命周期统一入口(spawn / update / remove 事件) |
| CommandLineArgsData(实例类型) | 推荐把 DataAsset 实例命名为 |
| ConfigData(实例类型) | 推荐把 DataAsset 实例命名为 |
Sequence 模式 | 动态路径、Sequence | UE 侧统一写 |
Single 模式 | 固定路径、Single | UE 侧统一写 |