跳到主要内容

快速入门

插件版本 1.2.3 | 文档版本 1.2.3 | UE 5.3-5.7 面向读者:首次接入的内容开发(蓝图优先) 本篇只做三件事:装上插件 → 配好两个 DataAsset → 验证桥接连通。完整接入见 03 接入流程。


目录​

    1. 下载与安装
    1. 初始配置
    1. 最小连通验证
    1. 蓝图接入
    1. 二进制包 C++ 接入(C API)
    1. 下一步
  • 常见错误


目的​

从零到「插件跑起来了、Bridge 连通了」的最小闭环。跑通本篇后再进 03 做完整接入。


前置条件​

  • UE 5.3 或更高版本(已验证 5.3 / 5.4 / 5.5 / 5.6 / 5.7)

  • 已获取插件包(见 §1)


本篇不覆盖什么​

  • 多人 DS 部署、Server target、DefaultEngine.ini NetDriver 配置 → 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 版本提供独立目录,选择与你项目匹配的版本:

目录

适用版本

YomovUESDKCore-5.3/

UE 5.3

YomovUESDKCore-5.4/

UE 5.4

YomovUESDKCore-5.5/

UE 5.5

YomovUESDKCore-5.6/

UE 5.6

YomovUESDKCore-5.7/

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 选项

右键菜单中的 Generate Visual Studio project files 选项

步骤 4:启动项目​

双击 .uproject 打开项目。插件为预编译二进制分发,无需额外编译即可使用。

如果弹出版本不匹配提示,选择「以当前版本打开」即可。

步骤 5:验证安装成功​

打开 Edit → Plugins,搜索 YomovUESDKCore,确认插件状态为 Enabled。

插件管理器中 YomovUESDKCore 的已启用状态

插件管理器中 YomovUESDKCore 的已启用状态


2. 初始配置​

插件需要两个配置 DataAsset,用 InspectorPanel 一键创建:

DataAsset

类

回答什么问题

DA_CommandLineArgs

CommandLineArgsData

连接哪里、我是谁(运行时连接与身份参数)

DA_DataAsset

ConfigData

内容怎么运行(编辑器 / 构建 / 玩法配置)

2.1 创建两个配置资产(InspectorPanel)​

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 失败态(红色 ✗ + Autofix 按钮)

InspectorPanel 通过态(三行绿色 ✓)

InspectorPanel 通过态(三行绿色 ✓)

2.2 配置 DA_CommandLineArgs​

打开 DA_CommandLineArgs。开发阶段需要关注的关键字段(Autofix 已按 C++ ctor 预填测试默认值,可直接联调):

字段

说明

默认值

BridgeServerIP

桥接服务器地址

127.0.0.1

BridgeServerPort

桥接服务器端口

7799

ContentID

内容 ID

123456789

PathType

路径模式:dynamic(=Sequence)/ fixed(=Single)

fixed

GameLength / GameWidth

场景尺寸(米)

5.0 / 5.0

多人相关字段(单人模式可不配,多人模式必配):

字段

类型

默认值

说明

多人必配

ServerIP

FString

127.0.0.1

DS 地址(客户端 ClientTravel 目标)

✅ 客户端

ServerPort

int32

9527

客户端连 DS 的端口,须与 DS config.ini 的 serverPort 一致

✅ 客户端

BridgeServerIP

FString

127.0.0.1

Bridge 业务服务器地址(客户端经 Server_Login RPC 上报给 DS)

✅ 客户端

BridgeServerPort

int32

7799

Bridge 业务服务器端口

✅ 客户端

TeamOriginID

int64

123456789

队伍源 ID(运行时 FString TeamID 由此推导)

✅ 多人

PlayerOriginID

int64

123456789

玩家源 ID(同理推导为运行时 PlayerID)

✅ 多人

VenueID / RoomID

int64

123456789

场馆 / 房间 ID

可选

NetRole

FString

空

"server" / "client"(标记本端角色)

可选

⚠️ Bridge 地址配在客户端 DA(BridgeServerIP / BridgeServerPort)。客户端连上 DS 后经 Server_Login RPC 把 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 分组)

DA_CommandLineArgs 编辑面板(Bridge / Server 分组)

其它测试默认值:RoomName = 测试房间、ContentName = 测试内容、ContentVersion = 1.0.1、TeamName = 测试队伍、PlayerNick = 测试玩家。

正式运行时,这些字段会被播控系统下发的命令行参数(Windows)或 Android Intent(PICO)覆盖。完整启动参数说明见 播控命令行启动参数文档。

2.3 配置 DA_DataAsset​

打开 DA_DataAsset。面板可配的基础字段:

字段

说明

默认值

分类

LBEPathType

路径模式:Sequence(动态路径)/ Single(固定路径)

Single

YOMOV|Path

AnchorPoint

锚点位置(厘米)

(0, 0, 0)

YOMOV|Path

AnchorRotationY

锚点 Y 轴旋转(度)

0

YOMOV|Path

ActSizeLength / ActSizeWidth

场景尺寸(米)

5.0 / 5.0

YOMOV|Path

bShowBoundary

是否显示边界

true

YOMOV|Path

DA_DataAsset 编辑面板(Path 分组)

DA_DataAsset 编辑面板(Path 分组)

多人 / 远程玩家相关字段(单人模式可留默认):

字段

类型

默认值

分类

说明

DefaultAvatarClass

TSubclassOf<AActor>

nullptr

YOMOV|Avatar

同队远程 Avatar 类(推荐继承 ARemotePlayerCharacter)

NonTeamAvatarClass

TSubclassOf<AActor>

nullptr

YOMOV|Avatar

异队远程 Avatar 类。⚠️ 必配:异队想隐藏也配一个无网格体的空 BP,勿留 nullptr

PawnClass

TSubclassOf<APawn>

nullptr

YOMOV|Avatar

DS 的 DefaultPawnClass 覆盖值(本地 Pawn 建议继承 AYomovPawn)

RemotePlayerVisibleDistance

float

500

YOMOV|Avatar

远程玩家可见距离(cm):非同组进入该距离显示、超出 +50cm 隐藏(迟滞带);<=0 禁用规则全显

bSameTeamAlwaysVisible

bool

true

YOMOV|Avatar

同内容同组远程玩家恒可见;关闭后同组也按距离判定

AvatarDefaultBodyHeight

float

170

YOMOV|Avatar

Avatar 标准身高(cm),BodyScale 身高校准缩放的分母。换非 1.7m 标准人形模型时按模型实际身高改

InitialSceneName

FString

LBEPath-SingleTest

YOMOV|SceneTransition

初始场景关卡短包名(TeamProperty 未就绪时的 fallback),按首场景实际名配

多人网络行为相关字段(bEnableSceneSyncBarrier / bEnableUplinkTimeoutKick / UplinkTimeoutSeconds / UplinkEchoStallSeconds,1.2.3 新增)默认值即推荐值,一般无需改动;需要调整时见 06 §4.3。

代码内置默认值(面板不可改,需要改请与游幕对接人确认):

字段

默认值

含义

bUseVoid

true

虚空(越界保护)总开关

bIsNearDisplayPlotBoundary

true

Plot 边界近显提示开关

bFixedSize

true

固定尺寸模式

bBoundaryInteraction

true

边界交互

⚠️ 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 使用预制蓝图(推荐)​

  1. 在插件 Content 目录找到蓝图资产 BP_BridgeEventReceiver(路径 /YomovUESDKCore/Blueprint/BP_BridgeEventReceiver),拖入场景

  2. 确认 DA_CommandLineArgs 的连接信息正确

  3. 启动桥接服务器(联调工具见 08 §联调工具)

  4. PIE 运行

  5. 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:使用预制蓝图(推荐)​

  1. 找到 /YomovUESDKCore/Blueprint/BP_BridgeEventReceiver,拖入场景

  2. 双击打开蓝图,在 Event Dispatchers 列表里选中事件 → Assign → 连接你的业务逻辑

  3. 点击 Play 测试

蓝图编辑器中的 Event Dispatchers 列表

蓝图编辑器中的 Event Dispatchers 列表

方式 B:自行创建蓝图​

  1. Content Browser → 右键 → Blueprint Class → 父类选 Bridge Event Receiver(C++ 类 ABridgeEventReceiver;旧名 "Yomov Auto Starter" 已废弃)

  2. 打开蓝图,将 Event Dispatchers 拖入事件图表 → 选择 Assign → 连接业务逻辑

  3. 将蓝图拖入场景,点击 Play 测试

BridgeEventReceiver 可配置属性​

属性

默认值

说明

RetryDelay

3.0s

断线重试延迟

SendInterval

0.1s

发送本机位置的周期(100ms)

bAutoConnectOnBeginPlay

true

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:

  1. 装 binary 包:Plugins/YomovUESDKCore/(含 ThirdParty/YomovCore/lib/ + include/)

  2. 模块依赖:消费方 .Build.cs 添加 YomovUESDKCore(会自动获得 YomovCore.lib 链接)

  3. 引用头文件:#include "YomovCore_Full.h"

  4. 调用 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);删 Intermediate/Binaries/ 后重新 Generate

Bridge 连不上

检查 DA_CommandLineArgs 的 BridgeServerIP / BridgeServerPort + 桥接服务器进程 + 防火墙

DataAsset 改了不生效

Console 执行 Yomov.Config.Reload(或 SettingPanel 点 [Save & Apply]);确认字段是面板可配的(§2.3 有不可配字段清单)

插件提示找不到配置 / 配置未加载

开 YOMOV SDK → InspectorPanel 自检:配置 DA 缺失或资产类不对会红显,点 [Autofix] 一键创建到规范路径

多人下客户端连不上 DS

端口三方对齐:客户端 DA ServerPort = DS config.ini 的 serverPort;DS 必须源码版引擎打包

远程 Avatar 不出现

检查 DefaultAvatarClass / NonTeamAvatarClass都不为空 + Bridge 服务器在跑