快速入门
插件版本 1.2.3 | 文档版本 1.2.3 | UE 5.3-5.7 面向读者:首次接入的内容开发(蓝图优先) 本篇只做三件事:装上插件 → 配好两个 DataAsset → 验证桥接连通。完整接入见 03 接入流程。
目录
-
- 下载与安装
-
- 初始配置
-
- 最小连通验证
-
- 蓝图接入
-
- 二进制包 C++ 接入(C API)
-
- 下一步
-
常见错误
目的
从零到「插件跑起来了、Bridge 连通了」的最小闭环。跑通本篇后再进 03 做完整接入。
前置条件
-
UE 5.3 或更高版本(已验证 5.3 / 5.4 / 5.5 / 5.6 / 5.7)
-
已获取插件包(见 §1)
本篇不覆盖什么
-
多人 DS 部署、Server target、
DefaultEngine.iniNetDriver 配置 → 03 接入流程 / 04 测试打包 -
Avatar 接入层级、多队伍、边界坐标归一化 → 03 接入流程 流程 A
-
完整 API 参数矩阵与事件签名 → 07 接口与事件
先纠正 4 个常见误解
-
BridgeTestComponent仅用于开发验证,不能作为正式发布接入实现(且 1.2.1 起已不在 Add Component 列表,见 §3)。 -
BridgeEventReceiver负责播控与连接状态;远程玩家 spawn/update/remove 事件在 URemotePlayerSubsystem,不在这里。 -
多人联调时,Bridge 地址权威来源是客户端 DA_CommandLineArgs 上报,不是 DS 命令行参数。
-
多人开跑前先过 03 §流程 A 步骤四 的硬前置,否则大概率在端口、Pawn、DA 一致性上卡住。
1. 下载与安装
步骤 1:获取插件包
从 Git 仓库下载对应 UE 版本的插件包:https://cnb.cool/configreality/YomovUESDKCore
仓库按 UE 版本提供独立目录,选择与你项目匹配的版本:
目录 | 适用版本 |
|---|---|
| UE 5.3 |
| UE 5.4 |
| UE 5.5 |
| UE 5.6 |
| UE 5.7 |
⚠️ 版本必须对齐:插件包按引擎版本分别编译(
.lib/.so的 ABI 与配置宏不同)。用错版本会在编译或链接阶段报错。
步骤 2:复制到项目
把对应版本目录下的 YomovUESDKCore/ 文件夹复制到你的 UE 项目 Plugins/ 目录下,确保目录结构为 Plugins/YomovUESDKCore/。
YourProject/
├── Content/
├── Plugins/
│ └── YomovUESDKCore/ ← 插件放这里
│ ├── YomovUESDKCore.uplugin
│ ├── Binaries/
│ ├── Content/
│ ├── Source/
│ └── ThirdParty/YomovCore/
└── YourProject.uproject
复制完成后的插件目录结构
步骤 3:重新生成项目文件
右键 .uproject 文件 → 选择 "Generate Visual Studio project files"。
右键菜单中的 Generate Visual Studio project files 选项
步骤 4:启动项目
双击 .uproject 打开项目。插件为预编译二进制分发,无需额外编译即可使用。
如果弹出版本不匹配提示,选择「以当前版本打开」即可。
步骤 5:验证安装成功
打开 Edit → Plugins,搜索 YomovUESDKCore,确认插件状态为 Enabled。
插件管理器中 YomovUESDKCore 的已启用状态
2. 初始配置
插件需要两个配置 DataAsset,用 InspectorPanel 一键创建:
DataAsset | 类 | 回答什么问题 |
|---|---|---|
|
| 连接哪里、我是谁(运行时连接与身份参数) |
|
| 内容怎么运行(编辑器 / 构建 / 玩法配置) |
2.1 创建两个配置资产(InspectorPanel)
InspectorPanel 配置自检面板
菜单 YOMOV SDK → InspectorPanel 打开配置自检面板(MajorTab),逐项检查共三行——上表两个运行时必需 DA + 叙事 fallback 资产 TestNarrative(见下方注记):
-
通过 → 绿色 ✓
-
缺失 / 资产类不匹配 → 红色 ✗ + 提示文案 + [Autofix] 按钮
点 [Autofix] 即按 C++ ctor 默认值在规范路径创建该资产并落盘,随后自动 ReloadConfig 并重跑检查刷新面板。
创建位置(与插件加载路径一致):
Content/YOMOVSDK/Config/
├── DA_CommandLineArgs (CommandLineArgsData)
└── DA_DataAsset (ConfigData)
⚠️ 不要自己在别的位置手动创建这两个 DA——路径必须与
UConfigManagerSubsystem的加载路径一致,放错位置不会被加载。[Autofix] 会创建到正确位置并保证资产类正确,且幂等(已存在的资产不覆盖,不会冲掉你已配好的内容)。 第三项检查 TestNarrative(1.2.1 起纳入):Sequence 模式叙事 fallback 默认资产(UNarrativeDataAsset,插件不分发)——未自配叙事 BP 时它是叙事链的兜底起点。缺失红显但不是运行时必需:[Autofix] 创建的是空StoryActs资产(叙事编辑起点,数据需另行配置,见 09 §3);已自配叙事 BP / DA 的项目不受影响。DA_BoundaryEffectConfig随插件包分发,无需创建。
InspectorPanel 失败态(红色 ✗ + Autofix 按钮)
InspectorPanel 通过态(三行绿色 ✓)
2.2 配置 DA_CommandLineArgs
打开 DA_CommandLineArgs。开发阶段需要关注的关键字段(Autofix 已按 C++ ctor 预填测试默认值,可直接联调):
字段 | 说明 | 默认值 |
|---|---|---|
| 桥接服务器地址 |
|
| 桥接服务器端口 |
|
| 内容 ID |
|
| 路径模式: |
|
| 场景尺寸(米) |
|
多人相关字段(单人模式可不配,多人模式必配):
字段 | 类型 | 默认值 | 说明 | 多人必配 |
|---|---|---|---|---|
| FString |
| DS 地址(客户端 | ✅ 客户端 |
| int32 | 9527 | 客户端连 DS 的端口,须与 DS config.ini 的 serverPort 一致 | ✅ 客户端 |
| FString |
| Bridge 业务服务器地址(客户端经 | ✅ 客户端 |
| int32 |
| Bridge 业务服务器端口 | ✅ 客户端 |
| int64 |
| 队伍源 ID(运行时 FString | ✅ 多人 |
| int64 |
| 玩家源 ID(同理推导为运行时 | ✅ 多人 |
| int64 |
| 场馆 / 房间 ID | 可选 |
| FString | 空 |
| 可选 |
⚠️ Bridge 地址配在客户端 DA(
BridgeServerIP/BridgeServerPort)。客户端连上 DS 后经Server_LoginRPC 把 Bridge 端点上报给 DS,DS 收到后才作为 TCP 客户端连接 Bridge。 DS 命令行-BridgeIP=不生效(DS 进程不解析该参数),别再按旧文档配它。
MapData 默认值(PathType = fixed 时 FlowController 用于边界对齐的测试数据,新建 DA 时已预填):
{"venue":"","room":"","StartPoint":{"x":0,"y":0},"StartForward":{"x":0,"y":0},"EndPoint":{"x":0.0,"y":0.0},"LocatePoint":{"x":0.0,"y":0.0},"LocateForward":{"x":0.0,"y":1.0},"ArcadePoly":[{"x":-5,"y":-5},{"x":5,"y":-5},{"x":5,"y":5},{"x":-5,"y":5}],"Obstacles":[]}
DA_CommandLineArgs 编辑面板(Bridge / Server 分组)
其它测试默认值:RoomName = 测试房间、ContentName = 测试内容、ContentVersion = 1.0.1、TeamName = 测试队伍、PlayerNick = 测试玩家。
正式运行时,这些字段会被播控系统下发的命令行参数(Windows)或 Android Intent(PICO)覆盖。完整启动参数说明见 播控命令行启动参数文档。
2.3 配置 DA_DataAsset
打开 DA_DataAsset。面板可配的基础字段:
字段 | 说明 | 默认值 | 分类 |
|---|---|---|---|
| 路径模式: |
|
|
| 锚点位置(厘米) |
|
|
| 锚点 Y 轴旋转(度) |
|
|
| 场景尺寸(米) |
|
|
| 是否显示边界 |
|
|
DA_DataAsset 编辑面板(Path 分组)
多人 / 远程玩家相关字段(单人模式可留默认):
字段 | 类型 | 默认值 | 分类 | 说明 |
|---|---|---|---|---|
|
|
|
| 同队远程 Avatar 类(推荐继承 |
|
|
|
| 异队远程 Avatar 类。⚠️ 必配:异队想隐藏也配一个无网格体的空 BP,勿留 nullptr |
|
|
|
| DS 的 |
| float |
|
| 远程玩家可见距离(cm):非同组进入该距离显示、超出 +50cm 隐藏(迟滞带); |
| bool |
|
| 同内容同组远程玩家恒可见;关闭后同组也按距离判定 |
| float |
|
| Avatar 标准身高(cm),BodyScale 身高校准缩放的分母。换非 1.7m 标准人形模型时按模型实际身高改 |
| FString |
|
| 初始场景关卡短包名(TeamProperty 未就绪时的 fallback),按首场景实际名配 |
多人网络行为相关字段(
bEnableSceneSyncBarrier/bEnableUplinkTimeoutKick/UplinkTimeoutSeconds/UplinkEchoStallSeconds,1.2.3 新增)默认值即推荐值,一般无需改动;需要调整时见 06 §4.3。
代码内置默认值(面板不可改,需要改请与游幕对接人确认):
字段 | 默认值 | 含义 |
|---|---|---|
|
| 虚空(越界保护)总开关 |
|
| Plot 边界近显提示开关 |
|
| 固定尺寸模式 |
|
| 边界交互 |
⚠️ DefaultAvatar / NonTeamAvatar 已废弃(1.1.0 破坏性变更):旧字段类型为
USkeletalMesh*,现为TSubclassOf<AActor>且更名为DefaultAvatarClass/NonTeamAvatarClass。旧项目升级时原引用会失效,需重配为 Avatar 蓝图类(新建 BP,Parent =ARemotePlayerCharacter,配 Skeletal Mesh + AnimClass)。
2.4 配置生效方式
-
两个 DataAsset 都放在
Content/YOMOVSDK/Config/ -
DA_CommandLineArgs回答「连接哪里、我是谁」;DA_DataAsset回答「内容怎么运行」 -
修改 DataAsset 后,可在编辑器 Console 执行 Yomov.Config.Reload 热重载,无需重启(该命令仅在编辑器 / PIE / Development 运行时可用,Shipping 不开放)
⚠️ 多人一致性前提:各客户端 APK 的
DA_CommandLineArgs.MapData与DA_DataAsset中边界相关字段(AnchorPoint/AnchorRotationY/ActSizeLength/ActSizeWidth)必须完全一致,否则跨机远程玩家坐标错位。推荐由内容统一分发同一份 DA,不要各端手配。
3. 最小连通验证
配置完成后,用 BP_BridgeEventReceiver 验证插件已装上、桥接通信连通。
3.1 使用预制蓝图(推荐)
-
在插件 Content 目录找到蓝图资产
BP_BridgeEventReceiver(路径/YomovUESDKCore/Blueprint/BP_BridgeEventReceiver),拖入场景 -
确认
DA_CommandLineArgs的连接信息正确 -
启动桥接服务器(联调工具见 08 §联调工具)
-
PIE 运行
-
Output Log 筛选
LogBridgeEventReceiver,看到 Bridge Connected!(同时屏幕显示绿色消息)即安装成功
3.2 关于 BridgeTestComponent(1.2.1 变更)
UBridgeTestComponent 是插件内部的桥接通信开发测试组件(含自动连接、本地玩家数据发送、远程玩家方块管理、断线重连、超时清理等完整参考实现)。
⚠️ 1.2.1 起 BridgeTestComponent 不再出现在 Details 面板的 Add Component 列表(测试组件不对外暴露)。它仍保留在插件源码中作为 C++ 参考实现——参考它的写法比挂它更合适:
- 需要快速看连通效果 → 用 §3.1 的
BP_BridgeEventReceiver
- 需要看完整 C++ 参考实现 → 见 07 §C++ 接入示例
⚠️ 不要同时挂 BridgeEventReceiver 与 BridgeTestComponent 做对比测试:两者共用同一条 TCP 连接(同一个
UTCPClientSubsystem单例),会互相干扰。
4. 蓝图接入
ABridgeEventReceiver 自动绑定桥接服务器的连接状态与播控指令事件,通过 Event Dispatcher 广播给蓝图。你不需要写代码,只需在蓝图中响应事件并实现业务逻辑。
所有播控事件统一带 ContentID / TeamID / ExtraData 三个 FString 参数(签名与语义见 07 §播控事件)。
方式 A:使用预制蓝图(推荐)
-
找到
/YomovUESDKCore/Blueprint/BP_BridgeEventReceiver,拖入场景 -
双击打开蓝图,在 Event Dispatchers 列表里选中事件 → Assign → 连接你的业务逻辑
-
点击 Play 测试
蓝图编辑器中的 Event Dispatchers 列表
方式 B:自行创建蓝图
-
Content Browser → 右键 → Blueprint Class → 父类选 Bridge Event Receiver(C++ 类
ABridgeEventReceiver;旧名 "Yomov Auto Starter" 已废弃) -
打开蓝图,将 Event Dispatchers 拖入事件图表 → 选择 Assign → 连接业务逻辑
-
将蓝图拖入场景,点击 Play 测试
BridgeEventReceiver 可配置属性
属性 | 默认值 | 说明 |
|---|---|---|
|
| 断线重试延迟 |
|
| 发送本机位置的周期(100ms) |
|
| BeginPlay 是否自动连 Bridge(1.1.1 新增)。单机播控直驱保持默认;多人 DS 权威模式建议关掉——连接时机由 SDK 按玩家登录管理 |
单机直驱 vs 多人 DS 权威(1.1.1 职责解耦):
BridgeEventReceiver在 DS 端不再自动连接、不重试、不发送数据。DS 的正确链路是UYomovDSServerComponent收集真实玩家经SyncToBridge上报;503 指令由UBridgeServerControllerComponent独立解析。 多人下的内容方两条推荐路径:① 绑 GameMode 上UBridgeServerControllerComponent的全套OnRemote*事件;② 客户端绑AYomovTeamProperty::OnPlaybackStateChanged(复制事件,APK 不连桥也可驱动)。详见 03 接入流程。
⚠️ 远程玩家事件不在 BridgeEventReceiver:
OnRemotePlayerSpawned/OnRemotePlayerUpdate/OnRemotePlayerRemoved定义在URemotePlayerSubsystem上。详见 07 接口与事件。
YomovManagerActor:仅播控、不用固定路径时可不手摆(Session 自动 spawn);要用固定路径 / Flow 边界时需手摆,见 01 §6.1。
5. 二进制包 C++ 接入(C API)
binary 包不支持消费方其他模块跨模块 C++ 调用 UE 业务 API(会报 LNK2019 __imp_...)。跨模块请走 YomovCore C API:
-
装 binary 包:
Plugins/YomovUESDKCore/(含ThirdParty/YomovCore/lib/+include/) -
模块依赖:消费方
.Build.cs添加YomovUESDKCore(会自动获得YomovCore.lib链接) -
引用头文件:
#include "YomovCore_Full.h" -
调用 C API:
YMC_*系列
成功标志:编译 0 LNK,YMC_TConnect 能连上 Bridge。
权威头文件:插件包内
ThirdParty/YomovCore/include/YomovCore_Full.h(完整 C API 清单与注释都在其中)。需要 C API 的详细接入指南请向游幕对接人索取。 消费方需要写 C++ 业务逻辑的场景(多人数据同步、远程玩家可视化),推荐用源码包-Source,可直接调用 UE 包装层 API。
6. 下一步
你要做什么 | 去哪 |
|---|---|
完整接入(含多人 / 播控 / 路径 / 服务端) | 03 接入流程 |
测试与打包 | 04 测试打包 |
路径单元怎么划分 | 05 大空间最佳实践 |
查 API / 事件签名 | 07 接口与事件 |
内容制作工具怎么用 | 09 编辑器工具 |
常见错误
现象 | 排查 |
|---|---|
安装报错 / 编译失败 | 确认 UE 版本与插件包目录匹配(§1 步骤 1);删 |
Bridge 连不上 | 检查 |
DataAsset 改了不生效 | Console 执行 |
插件提示找不到配置 / 配置未加载 | 开 YOMOV SDK → InspectorPanel 自检:配置 DA 缺失或资产类不对会红显,点 [Autofix] 一键创建到规范路径 |
多人下客户端连不上 DS | 端口三方对齐:客户端 DA |
远程 Avatar 不出现 | 检查 |