接口与事件
插件版本 1.2.3 | 文档版本 1.2.3 | UE 5.3-5.7 面向读者:使用 YomovUESDKCore 开发大空间 VR 内容的程序与技术美术。 本篇按「类 → 功能描述 → 成员表 → 典型用法」组织,是按需查阅的速查手册,不需要通读。接入流程见 03 接入流程;机制原理见 06 核心组件。
目录
-
- 从内容需求找到 API
-
- 接口约定
-
- 播控指令与事件
-
- 蓝图 API 参考
-
Try*家族对照表(1.2.1)
-
- 事件委托总表
-
- 数据结构
-
- C++ 接入示例
1. 从内容需求找到 API
内容开发需求 | 主要入口 |
|---|---|
获取核心入口(Manager / Flow / Bridge) |
|
推进下一个 Plot、跳到指定 Act / Plot |
|
开始 / 暂停 / 恢复 / 停止播放 |
|
响应播控通知(开始/暂停/恢复/Seek/设高/退出) |
|
主动发送播控指令(msg 503) |
|
判断 Bridge 是否连上 |
|
发送同步数据(msg 500) |
|
监听远程玩家生成 / 更新 / 移除 |
|
用自有数据源驱动远程 Avatar |
|
监听本队播控 / 叙事进度(APK 不连桥) |
|
判断同队 / 查队伍属性 |
|
监听 Act / Plot 加载、转场、报幕等运行期事件 |
|
查找场景内的 Act / Plot Actor |
|
读取 / 热重载配置、读启播参数 |
|
坐标与旋转转换(Unity ↔ UE) |
|
场景加载 / 卸载 / 跳转 |
|
调试边界显示与透明度 |
|
2. 接口约定
先读这节再看具体签名——下面这些约定适用于本篇所有接口。
约定 | 说明 |
|---|---|
公开不等于开放 | 本篇列出的成员才是内容开发契约。插件中其他 |
名称 vs ID | Seek 与场景加载用叙事配置中的名称( |
时间单位 | 本篇未特别说明的时长均为秒。 |
坐标语义 | 远程玩家相关接口( |
委托订阅生命周期 |
|
UObject 持有 | 委托回调里的 |
权威端 | 播控与状态类接口以服务器为准。DS / listen server 上用 |
Try* 优先 | 1.2.1 起动作类方法都有 |
本地玩家过滤 |
|
3. 播控指令与事件
3.1 播控指令(ControlType)
播控指令经 Bridge 用 msg 503 双向传递,ControlType 决定含义:
ControlType | 指令名 | 含义 |
|---|---|---|
5 | Start | 正式开始:初始化内容状态,进入主体内容,启用交互 |
1 | Pause | 暂停:冻结所有进度、动画、交互,保持当前画面 |
2 | Resume | 恢复:从暂停点恢复 |
3 | Seek | 跳转到指定场景 / 区域(stageName / areaName 在 |
6 | SetHeight | 调整高度偏移(裸数字,单位 cm);同时触发 BodyScale 身高重算 |
4 | Exit | 结束退出:退出当前内容,清理状态,返回等待界面 |
⚠️ Seek 的 ExtraData 字段名是 stageName / areaName(对齐 Unity
ChapterSwitchData):
{"stageName":"Act02","areaName":"Plot01"}
> 旧写法 `stage` / `area`<b>静默失效</b>(不报错、不生效)。自研播控 / 模拟器发 Seek 时务必用正确字段名。
> `areaName` 当前<b>不参与 Plot 定位</b>(落点 Plot 固定归 0,对齐 Unity 播控 `plots[0]`,字段保留)。
### 3.2 播控事件(权威源:`UBridgeServerControllerComponent`)
`UActorComponent` — 桥接通信层(DS 端挂在 GameMode 上)。
<b>方法</b>:
<table header_row="1">
<colgroup><col width="328"/><col width="309"/></colgroup>
<thead>
<tr><th><p>方法</p></th><th><p>说明</p></th></tr>
</thead>
<tbody>
<tr><td><p><code>IsConnected()</code> → bool</p></td><td><p>是否已连接</p></td></tr>
<tr><td><p><code>SendSyncContentData(FSyncContentData)</code> → bool</p></td><td><p>发送同步数据(msg 500)</p></td></tr>
<tr><td><p><code>SendControlCommand(int32 ControlType, FString JsonData)</code> → bool</p></td><td><p>发送控制指令(msg 503)</p></td></tr>
</tbody>
</table>
<b>事件</b>(全部为 BlueprintAssignable,统一三参数):
<table header_row="1">
<colgroup><col width="269"/><col width="185"/><col width="292"/></colgroup>
<thead>
<tr><th><p>事件</p></th><th><p>参数</p></th><th><p>说明</p></th></tr>
</thead>
<tbody>
<tr><td><p><code>OnSyncContentDataReceived</code></p></td><td><p><code>const FSyncContentData&</code></p></td><td><p>收到同步数据(msg 501)</p></td></tr>
<tr><td><p><code>OnRemoteStart</code></p></td><td><p><code>ContentID</code>, <code>TeamID</code>, <code>ExtraData</code></p></td><td><p>Start(5)</p></td></tr>
<tr><td><p><code>OnRemotePause</code></p></td><td><p>同上</p></td><td><p>Pause(1)</p></td></tr>
<tr><td><p><code>OnRemoteResume</code></p></td><td><p>同上</p></td><td><p>Resume(2)</p></td></tr>
<tr><td><p><code>OnRemoteSeek</code></p></td><td><p>同上</p></td><td><p>Seek(3),<code>ExtraData</code> = <code>{"stageName":"...","areaName":"..."}</code></p></td></tr>
<tr><td><p><code>OnRemoteSetHeight</code></p></td><td><p>同上</p></td><td><p>SetHeight(6),<code>ExtraData</code> = 裸数字(身高 cm)</p></td></tr>
<tr><td><p><code>OnRemoteExit</code></p></td><td><p>同上</p></td><td><p>Exit(4)</p></td></tr>
</tbody>
</table>
<b>参数语义</b>:
- `ContentID` / `TeamID`:服务器下发的当前内容 / 队伍标识(<b>可能为空</b>)
- `ExtraData`:ControlData 原始 JSON 字符串。Start / Pause / Resume / Exit 通常为空
- C++ 兜底:<b>屏幕青色消息 </b><b>Bridge <TypeName> | CID=... TID=... | <Extra></b><b> 由场景中的 </b><b>ABridgeEventReceiver</b><b> 打印</b>;`UBridgeServerControllerComponent` 本身只打 `LogBridgeController` 日志,不发屏幕消息
> ⚠️ <b>Breaking Change(版本 ≥ 1.0.3)</b>:播控事件委托签名变更为 `ContentID` / `TeamID` / `ExtraData`。升级时 C++ / 蓝图均需按新签名重绑。
### 3.3 蓝图接入:`ABridgeEventReceiver`
`AActor` — 播控事件分发蓝图 Actor。使用方式与可配置属性见 02 §4。
<table header_row="1">
<colgroup><col width="328"/><col width="328"/></colgroup>
<thead>
<tr><th><p>事件</p></th><th><p>参数</p></th></tr>
</thead>
<tbody>
<tr><td><p><code>OnRemoteStart</code> / <code>OnRemotePause</code> / <code>OnRemoteResume</code> / <code>OnRemoteSeek</code> / <code>OnRemoteSetHeight</code> / <code>OnRemoteExit</code></p></td><td><p><code>ContentID</code>, <code>TeamID</code>, <code>ExtraData</code>(三参数)</p></td></tr>
<tr><td><p><code>OnBridgeConnectedEvent</code> / <code>OnBridgeDisconnectedEvent</code> / <code>OnBridgeReconnectingEvent</code></p></td><td><p>无参</p></td></tr>
</tbody>
</table>
> ⚠️ <b>远程玩家事件不在这里</b>:`OnRemotePlayerSpawned` / `OnRemotePlayerUpdate` / `OnRemotePlayerRemoved` 定义在 `URemotePlayerSubsystem` 上。
> ⚠️ <b>1.1.1 起 DS 端让位</b>:`ABridgeEventReceiver` 在 DS 上不再自动连接 Bridge、不重试、不发送数据。DS 正确链路是 `UYomovDSServerComponent` 收集真实玩家上报。
### 3.4 运行期事件总线:`UEventBusSubsystem`
`UWorldSubsystem` — 插件内部的类型事件总线,<b>内容方订阅运行期事件的主要入口</b>(取实例:蓝图 `Get World Subsystem` 选 `EventBusSubsystem`)。
> ⚠️ <b>这些委托是「只读订阅」</b>:内容方<b>订阅</b>即可,不要主动 Broadcast(会干扰插件内部状态机)。
<table header_row="1">
<colgroup><col width="265"/><col width="208"/><col width="265"/></colgroup>
<thead>
<tr><th><p>事件</p></th><th><p>参数</p></th><th><p>触发时机</p></th></tr>
</thead>
<tbody>
<tr><td><p><code>OnActLoaded</code> / <code>OnUnloadAct</code></p></td><td><p><code>const FString& ActID</code></p></td><td><p>Act 加载完成 / 卸载</p></td></tr>
<tr><td><p><code>OnPlotLoaded</code></p></td><td><p><code>const FString& PlotID</code></p></td><td><p>Plot 选定(<b>不代表内容资源已加载完</b>)</p></td></tr>
<tr><td><p><code>OnChangePlot</code></p></td><td><p><code>OldPlotID</code>, <code>NewPlotID</code></p></td><td><p>当前位置确认后</p></td></tr>
<tr><td><p><code>OnBeforeLoadScene</code></p></td><td><p><code>const FString& SceneName</code></p></td><td><p>转场完成后、目标场景真正开始加载前</p></td></tr>
<tr><td><p><code>OnLastPlotLoaded</code></p></td><td><p>无参</p></td><td><p>请求推进但已无下一个 Act / Plot(内容序列结束)</p></td></tr>
<tr><td><p><code>OnStartGame</code> / <code>OnPauseGame</code> / <code>OnResumeGame</code></p></td><td><p>无参</p></td><td><p>播控 Start / Pause / Resume</p></td></tr>
<tr><td><p><code>OnSeekGame</code></p></td><td><p><code>float Time</code></p></td><td><p>播控 Seek(时间参数)</p></td></tr>
<tr><td><p><code>OnSeekToStage</code></p></td><td><p><code>StageName</code>, <code>AreaName</code></p></td><td><p>播控 Seek(章节参数)</p></td></tr>
<tr><td><p><code>OnSetPlayerHeight</code></p></td><td><p><code>float Height</code></p></td><td><p>播控 SetHeight</p></td></tr>
<tr><td><p><code>OnValidateFailed</code></p></td><td><p><code>int32 ErrorCode</code>, <code>const FString& ErrorMessage</code></p></td><td><p>校验失败</p></td></tr>
<tr><td><p><code>OnConfigReloaded</code></p></td><td><p>无参</p></td><td><p>配置热重载完成</p></td></tr>
<tr><td><p><code>OnShowAnnouncement</code> / <code>OnHideAnnouncement</code></p></td><td><p><code>const FString& Content</code> / 无参</p></td><td><p>报幕牌显示 / 隐藏</p></td></tr>
<tr><td><p><code>OnTriggerCurtainCall</code></p></td><td><p><code>const FString& Content</code></p></td><td><p>触发报幕</p></td></tr>
</tbody>
</table>
<b>典型用法</b>(C++):
if (UEventBusSubsystem* Bus = GetWorld()->GetSubsystem
---
## 4. 蓝图 API 参考
### 4.1 `AYomovManagerActor`
`AActor` — 插件运行时核心入口(是否手摆见 03 §1.3)。
<table header_row="1">
<colgroup><col width="328"/><col width="328"/></colgroup>
<thead>
<tr><th><p>方法</p></th><th><p>说明</p></th></tr>
</thead>
<tbody>
<tr><td><p><code>GetFlowController()</code></p></td><td><p>获取 <code>UFlowControllerComponent</code></p></td></tr>
<tr><td><p><code>GetBridgeController()</code></p></td><td><p>获取 <code>UBridgeServerControllerComponent</code></p></td></tr>
<tr><td><p><code>GetSceneTransitionComponent()</code></p></td><td><p>获取 <code>UYomovSceneTransitionComponent</code></p></td></tr>
<tr><td><p><code>GetSequencerDirector()</code></p></td><td><p>获取 <code>UYomovSequencerDirectorComponent</code></p></td></tr>
<tr><td><p><code>GetVehicleSession()</code></p></td><td><p>获取 <code>UVehicleSessionComponent</code></p></td></tr>
<tr><td><p><code>SaveToSession()</code></p></td><td><p>保存当前状态到 Session</p></td></tr>
</tbody>
</table>
> 蓝图取实例用 `UYomovBlueprintLibrary::GetYomovManagerActor(WorldContext)`。
### 4.2 `UFlowControllerComponent`
`UActorComponent` — 流程状态机(状态图见 06 §1.1)。
<table header_row="1">
<colgroup><col width="289"/><col width="283"/><col width="166"/></colgroup>
<thead>
<tr><th><p>方法</p></th><th><p>说明</p></th><th><p>Try 版</p></th></tr>
</thead>
<tbody>
<tr><td><p><code>Initialize()</code></p></td><td><p>初始化</p></td><td><p><code>TryInitialize()</code> → bool</p></td></tr>
<tr><td><p><code>StartPlay()</code></p></td><td><p>开始播放</p></td><td><p><code>TryStartPlay()</code></p></td></tr>
<tr><td><p><code>PausePlay()</code></p></td><td><p>暂停</p></td><td><p><code>TryPausePlay()</code></p></td></tr>
<tr><td><p><code>ResumePlay()</code></p></td><td><p>恢复</p></td><td><p><code>TryResumePlay()</code></p></td></tr>
<tr><td><p><code>StopPlay()</code></p></td><td><p>停止</p></td><td><p><code>TryStopPlay()</code></p></td></tr>
<tr><td><p><code>NextPlot()</code></p></td><td><p>推进到下一个 Plot</p></td><td><p><code>TryNextPlot()</code></p></td></tr>
<tr><td><p><code>JumpToActAndPlot(StageName, AreaName)</code></p></td><td><p>跳到指定 Act / Plot</p></td><td><p>—</p></td></tr>
<tr><td><p><code>SetPlayerHeight(Height)</code></p></td><td><p>设置玩家高度偏移</p></td><td><p>—</p></td></tr>
<tr><td><p><code>GetCurrentState()</code> → <code>EFlowState</code></p></td><td><p>当前状态(BlueprintPure)</p></td><td><p>—</p></td></tr>
<tr><td><p><code>GetRealBoundary()</code></p></td><td><p>获取 RealBoundary 组件(Pure)</p></td><td><p>—</p></td></tr>
<tr><td><p><code>GetSingleModeManager()</code></p></td><td><p>获取 SingleModeManager(Pure)</p></td><td><p>—</p></td></tr>
<tr><td><p><code>ReportError(Code, Message)</code></p></td><td><p>内容方主动上报错误(进入 Error 状态)</p></td><td><p>—</p></td></tr>
<tr><td><p><code>DebugShowBoundary()</code> / <code>DebugHideBoundary()</code></p></td><td><p>调试:强制显示 / 隐藏边界</p></td><td><p>—</p></td></tr>
<tr><td><p><code>DebugSetBoundaryAlpha(Alpha)</code></p></td><td><p>调试:自定义透明度(0.0~1.0)</p></td><td><p>—</p></td></tr>
<tr><td><p><code>DebugTriggerCurtainCall()</code></p></td><td><p>调试:手动触发报幕流程</p></td><td><p>—</p></td></tr>
</tbody>
</table>
<b>事件</b>:`OnFlowStateChanged(EFlowState)` / `OnFlowError(ErrorCode, ErrorMessage)`。
> <b>TryNextPlot</b><b> 语义</b>:到达最后 Plot 时广播 Completed = <b>请求已正常处理</b>,返回 `true`(返回 `false` 会误导调用方重试多推一格)。seek-in-flight 冻结 / 非 Playing / cursor 缺失 时返回 `false`。
### 4.3 `UYomovBlueprintLibrary`
`UBlueprintFunctionLibrary` — 流程 / 配置快捷方法(无需挂组件,蓝图直接调)。
<table header_row="1">
<colgroup><col width="328"/><col width="328"/></colgroup>
<thead>
<tr><th><p>方法</p></th><th><p>说明</p></th></tr>
</thead>
<tbody>
<tr><td><p><code>GetYomovManagerActor(WorldContext)</code></p></td><td><p>取 <code>AYomovManagerActor</code>(BlueprintPure)</p></td></tr>
<tr><td><p><code>GetFlowController(WorldContext)</code></p></td><td><p>取 <code>UFlowControllerComponent</code>(Pure)</p></td></tr>
<tr><td><p><code>TryInitializeAndAutoPlay(WorldContext)</code> → bool</p></td><td><p>初始化并自动播放(1.2.1;旧版 <code>InitializeAndAutoPlay</code> 已弃用)</p></td></tr>
<tr><td><p><code>TryTogglePause(WorldContext)</code> → bool</p></td><td><p>切换暂停 / 恢复(1.2.1;旧版 <code>TogglePause</code> 已弃用)</p></td></tr>
<tr><td><p><code>GetFlowStateText(EFlowState)</code> → FString</p></td><td><p>状态转可读字符串(Pure)</p></td></tr>
<tr><td><p><code>SendBridgeCommand(WorldContext, ControlType, JsonData)</code> → bool</p></td><td><p>发送播控指令(msg 503)</p></td></tr>
<tr><td><p><code>GetYomovTeamSubsystem(WorldContext)</code></p></td><td><p>取 <code>UYomovTeamSubsystem</code>(Pure)</p></td></tr>
<tr><td><p><code>GetMyTeamProperty(WorldContext)</code></p></td><td><p>取本队 <code>AYomovTeamProperty</code>(Pure,1.1.1)。按 <code>PlayerState.TeamID</code> 遍历匹配;TeamID 未定或 TeamProperty 尚未复制到达时返回 <code>null</code>(蓝图侧 0.2s 延迟重试)</p></td></tr>
</tbody>
</table>
### 4.4 `UBridgeSDKBlueprintLibrary`
`UBlueprintFunctionLibrary` — Bridge 连接与同步数据快捷方法。
<table header_row="1">
<colgroup><col width="328"/><col width="410"/></colgroup>
<thead>
<tr><th><p>方法</p></th><th><p>说明</p></th></tr>
</thead>
<tbody>
<tr><td><p><code>TryConnectToBridge(WorldContext, IP, Port)</code> → bool</p></td><td><p>连接桥接服务器(1.2.1;旧版 <code>ConnectToBridge</code> 已弃用)。<code>true</code> = 发起成功,建立态请查 <code>IsBridgeConnected</code></p></td></tr>
<tr><td><p><code>DisconnectBridge(WorldContext)</code></p></td><td><p>断开连接</p></td></tr>
<tr><td><p><code>IsBridgeConnected(WorldContext)</code> → bool</p></td><td><p>查询连接状态(Pure)</p></td></tr>
<tr><td><p><code>SendSyncData(WorldContext, FVector Pos, FRotator Rot)</code> → bool</p></td><td><p>发送同步数据(坐标自动转换)。⚠️ 旋转经 Rotator 规格化,yaw 跨 ±180° 时 quat 可能整体符号翻转</p></td></tr>
<tr><td><p><code>SendSyncDataQuat(WorldContext, FVector Pos, FQuat Rot)</code> → bool</p></td><td><p><b>1.1.1 新增,推荐</b>。全程 quat 不经 Rotator 规格化 + 发送前半球规整(与上次同半球,dot ≥ 0),防接收端线性插值时头朝向沿长弧转圈</p></td></tr>
<tr><td><p><code>UnityToUEPosition(FVector3)</code> → FVector</p></td><td><p>仅坐标转换</p></td></tr>
</tbody>
</table>
### 4.5 远程玩家:`URemotePlayerSubsystem` / `ARemotePlayerCharacter` / `UBridgeRemotePlayerLibrary`
#### `URemotePlayerSubsystem`
`UTickableWorldSubsystem` — 远程玩家统一管理单例(每 World 一份)。自动订阅 `AYomovGameState::CrossContentPlayers`,负责 spawn / 插值 / 超时清理。
> <b>取实例</b>:C++ `GetWorld()->GetSubsystem<URemotePlayerSubsystem>()`;蓝图 `Get World Subsystem` 节点选 `RemotePlayerSubsystem`。
<table header_row="1">
<colgroup><col width="242"/><col width="248"/><col width="248"/></colgroup>
<thead>
<tr><th><p>方法 / 事件</p></th><th><p>签名</p></th><th><p>说明</p></th></tr>
</thead>
<tbody>
<tr><td><p><code>TrySpawnOrUpdatePlayer</code></p></td><td><p><code>(PlayerID, TeamID, FVector Pos, FQuat Rot, float BodyScale=1.0)</code> → bool</p></td><td><p>按 PlayerID 增量 spawn 或更新(1.2.1;旧版 <code>SpawnOrUpdatePlayer</code> 已弃用)。位置 / 旋转为<b>边界局部坐标</b>;<b>调用方负责本地玩家过滤</b></p></td></tr>
<tr><td><p><code>RemovePlayer</code></p></td><td><p><code>(PlayerID)</code></p></td><td><p>立即销毁指定玩家的 Avatar</p></td></tr>
<tr><td><p><code>ClearAllPlayers</code></p></td><td><p><code>()</code></p></td><td><p>清空所有远程 Avatar</p></td></tr>
<tr><td><p><code>SetAvatarClasses</code></p></td><td><p><code>(InTeamClass, OutTeamClass)</code></p></td><td><p>运行时覆盖 DA 的同队 / 异队 Avatar 类(传 <code>nullptr</code> 恢复读 DA)</p></td></tr>
<tr><td><p><code>OnRemotePlayerSpawned</code></p></td><td><p><code>(PlayerID, PlayerActor*)</code></p></td><td><p>首次 spawn 该 PlayerID 的 Avatar 时广播</p></td></tr>
<tr><td><p><code>OnRemotePlayerUpdate</code></p></td><td><p><code>(PlayerID, PlayerActor*)</code></p></td><td><p>每 Tick 广播位置 / 旋转更新(同队 ~10Hz / 跨组 ~1.5Hz 数据驱动,跨组由客户端航位外推平滑)</p></td></tr>
<tr><td><p><code>OnRemotePlayerRemoved</code></p></td><td><p><code>(PlayerID, PlayerActor*)</code></p></td><td><p>超时清理或主动 <code>RemovePlayer</code> 时广播</p></td></tr>
</tbody>
</table>
> `PlayerActor` 是弱引用,回调里使用前<b>请判空</b>。Avatar 类分流由内部 `ResolveAvatarClass(TeamID)` 自动完成。
> <b>可见性与身高缩放为插件自动生效</b>(每帧 Tick 判定),无内容方 API;配置项在 `DA_DataAsset`(见 03 §3.4 / §3.5)。
#### `ARemotePlayerCharacter`
`ACharacter` — 远程 Avatar <b>推荐基类</b>(L2 层级)。内容方继承此类 + 设 Skeletal Mesh + 设 AnimClass,基类内部按反射设 `Acceleration` 驱动标准 AnimBP 走路动画。
<table header_row="1">
<colgroup><col width="269"/><col width="225"/><col width="301"/></colgroup>
<thead>
<tr><th><p>方法 / 属性</p></th><th><p>签名</p></th><th><p>说明</p></th></tr>
</thead>
<tbody>
<tr><td><p><code>HeadToFootOffset</code></p></td><td><p><code>float</code>(EditAnywhere)</p></td><td><p>远程头显(眼睛)到 Actor 原点(capsule 中心)的 Z 偏移;Subsystem 每帧把目标 Z 减此值让脚着地。默认 = capsule 半高(构造期读)</p></td></tr>
<tr><td><p><code>SetHandTargets</code></p></td><td><p><code>(bLeftTracked, LeftPos, LeftRot, bRightTracked, RightPos, RightRot)</code></p></td><td><p>设置手部 IK 目标(<code>Yomov|RemotePlayer|HandIK</code>)</p></td></tr>
<tr><td><p><code>IsLeftHandTracked</code> / <code>GetLeftHandTarget</code> / <code>GetLeftHandTargetRotation</code> + Right 同</p></td><td><p>—</p></td><td><p>手部 IK 状态查询(BlueprintPure)</p></td></tr>
</tbody>
</table>
#### `IRemoteDrivenActor`(L1 接口)
`BlueprintNativeEvent` 接口 — 非 Character 但需自定义驱动逻辑时实现:
void OnRemoteMove(const FVector& DeltaPosition, float DeltaTime);
#### `UBridgeRemotePlayerLibrary`
`UBlueprintFunctionLibrary` — <b>自有数据源接入用</b>。与 Subsystem 方法一一对应,但走 `WorldContext` 隐式取 World / Subsystem,适合从非 Actor 上下文(静态工具函数、自定义 Subsystem)驱动。
<table header_row="1">
<colgroup><col width="328"/><col width="328"/></colgroup>
<thead>
<tr><th><p>方法</p></th><th><p>说明</p></th></tr>
</thead>
<tbody>
<tr><td><p><code>SpawnOrUpdateRemotePlayer(WorldContextObject, PlayerID, TeamID, Pos, Rot)</code></p></td><td><p>转发到 <code>URemotePlayerSubsystem::SpawnOrUpdatePlayer</code></p></td></tr>
<tr><td><p><code>RemoveRemotePlayer(WorldContextObject, PlayerID)</code></p></td><td><p>转发到 <code>RemovePlayer</code></p></td></tr>
<tr><td><p><code>ClearAllRemotePlayers(WorldContextObject)</code></p></td><td><p>转发到 <code>ClearAllPlayers</code></p></td></tr>
</tbody>
</table>
### 4.6 队伍:`UYomovTeamSubsystem` / `AYomovTeamProperty`
<b>UYomovTeamSubsystem</b>(`UWorldSubsystem`,DS + 客户端均可调用):
<table header_row="1">
<colgroup><col width="328"/><col width="410"/></colgroup>
<thead>
<tr><th><p>方法</p></th><th><p>说明</p></th></tr>
</thead>
<tbody>
<tr><td><p><code>AreOnSameTeam(TeamIDA, TeamIDB)</code> → bool</p></td><td><p>两个 TeamID 是否同队(都非空且相等)。<b>比 </b><b>TeamID == MyTeamID</b><b> 更安全</b>(自动处理空串)</p></td></tr>
<tr><td><p><code>FindTeamProperty(TeamID)</code> → <code>AYomovTeamProperty*</code></p></td><td><p>按 TeamID 查队伍属性(找不到返回 <code>nullptr</code>)。<b>注:注册表仅 DS 端填充,客户端用 </b><b>GetMyTeamProperty</b></p></td></tr>
<tr><td><p><code>GetLocalTeamID()</code> → FString</p></td><td><p>解析本机 TeamID(有 override 用 override,否则取 DA 推导值)</p></td></tr>
<tr><td><p><code>SetLocalTeamIDOverride(TeamID)</code></p></td><td><p>仅当 TeamID <b>不来自 DA</b>(运行时自有源)时,在 <code>Server_Login</code> 前注入。传 <code>""</code> 清除</p></td></tr>
</tbody>
</table>
> <b>多数项目(含自有队伍但 ID 写在 DA)只需配 </b><b>TeamOriginID</b><b>,不必调 </b><b>SetLocalTeamIDOverride</b>。详见 03 §3.3。
<b>AYomovTeamProperty</b>(`AActor`,replicated,每队一个)— 属性与事件见 06 §3.5。
### 4.7 `AYomovPlayerState`
`APlayerState` — 玩家状态复制载体。
<table header_row="1">
<colgroup><col width="320"/><col width="98"/><col width="320"/></colgroup>
<thead>
<tr><th><p>属性(BlueprintReadOnly)</p></th><th><p>类型</p></th><th><p>说明</p></th></tr>
</thead>
<tbody>
<tr><td><p><code>TeamID</code> / <code>ContentID</code> / <code>Nickname</code> / <code>AvatarSkinName</code></p></td><td><p>FString</p></td><td><p>玩家身份信息(权威复制值)</p></td></tr>
<tr><td><p><code>YomovPlayerID</code></p></td><td><p>FString</p></td><td><p>本机玩家 ID(<code>URemotePlayerSubsystem</code> 用它过滤本地玩家)</p></td></tr>
<tr><td><p><code>IsReady</code></p></td><td><p>bool</p></td><td><p>就绪状态</p></td></tr>
<tr><td><p><code>LastBodySyncServerTime</code></p></td><td><p>double</p></td><td><p><b>1.2.3 新增</b>。DS 最近一次收到该玩家上行位姿的服务器时刻(仅本人客户端收到复制;0 = 未收到过)。插件内部上行探活 / 超时踢除用,<b>内容方一般不需要读</b>——语义见 06 §3.6</p></td></tr>
</tbody>
</table>
<table header_row="1">
<colgroup><col width="328"/><col width="328"/></colgroup>
<thead>
<tr><th><p>事件(BlueprintAssignable,<b>1.2.1 新增</b>)</p></th><th><p>参数</p></th></tr>
</thead>
<tbody>
<tr><td><p><code>OnTeamIDChanged</code></p></td><td><p><code>const FString& TeamID</code></p></td></tr>
<tr><td><p><code>OnContentIDChanged</code></p></td><td><p><code>const FString& ContentID</code></p></td></tr>
<tr><td><p><code>OnNicknameChanged</code></p></td><td><p><code>const FString& Nickname</code></p></td></tr>
<tr><td><p><code>OnAvatarSkinNameChanged</code></p></td><td><p><code>const FString& AvatarSkinName</code></p></td></tr>
<tr><td><p><code>OnIsReadyChanged</code></p></td><td><p><code>bool bIsReady</code></p></td></tr>
</tbody>
</table>
> 1.2.1 新增的 5 个委托<b>带新值参数</b>,监听方免回查;事件面暴露方式对齐 `AYomovGameState` 先例。
> ⚠️ <b>listen server 本机玩家本地写属性不触发 OnRep</b>(引擎固有语义)——本机直查属性,不要依赖 OnRep 通知。
### 4.8 场景:`USceneManagerSubsystem` / `UYomovSceneTransitionComponent`
<b>USceneManagerSubsystem</b>(World 子系统):
<table header_row="1">
<colgroup><col width="328"/><col width="328"/><col width="80"/></colgroup>
<thead>
<tr><th><p>方法</p></th><th><p>说明</p></th><th><p>Try 版</p></th></tr>
</thead>
<tbody>
<tr><td><p><code>TryLoadSceneAsync(SceneName)</code> → bool</p></td><td><p>异步加载场景(1.2.1)</p></td><td><p>—</p></td></tr>
<tr><td><p><code>TryUnloadScene(SceneName)</code> → bool</p></td><td><p>卸载场景(1.2.1)</p></td><td><p>—</p></td></tr>
<tr><td><p><code>TryUnloadSceneInstance(SceneName)</code> → bool</p></td><td><p>卸载 <code>LoadLevelInstance</code> 动态实例(1.2.1)</p></td><td><p>—</p></td></tr>
<tr><td><p><code>LoadSceneInstanceAsync(SceneName)</code> → bool</p></td><td><p>动态加载实例(<code>LoadLevelInstance</code> 路径)</p></td><td><p>—</p></td></tr>
<tr><td><p><code>ReloadSceneAsync(SceneName)</code></p></td><td><p>重载场景</p></td><td><p>—</p></td></tr>
<tr><td><p><code>CancelSceneLoading()</code></p></td><td><p>取消加载</p></td><td><p>—</p></td></tr>
<tr><td><p><code>IsLoadingScene()</code> / <code>IsSceneLoaded(SceneName)</code> / <code>IsSceneInstanceLoaded(SceneName)</code></p></td><td><p>状态查询(Pure)</p></td><td><p>—</p></td></tr>
<tr><td><p><code>GetLoadedLevelInstance(SceneName)</code></p></td><td><p>取 <code>ULevelStreamingDynamic*</code>(Pure)</p></td><td><p>—</p></td></tr>
<tr><td><p><code>GetFirstLoadedStreamingLevelName()</code> / <code>IsLevelLoadedAsStreaming(ShortName)</code></p></td><td><p>辅助查询(Pure)</p></td><td><p>—</p></td></tr>
</tbody>
</table>
<b>事件</b>:`OnSceneLoaded(SceneName)` / `OnSceneUnloaded(SceneName)`。
<b>UYomovSceneTransitionComponent</b>(`AYomovManagerActor` 上):`StartCountdown()` / `CancelCountdown()` —— 场景跳转倒计时编排。
### 4.9 叙事:`UYomovNarrativeActorLibrary` / `UActPlotSubsystem` / `UNarrativeDataAsset`
<b>UYomovNarrativeActorLibrary</b>(`UBlueprintFunctionLibrary`)— 按 ID / 名称查找场景内的叙事 Actor:
<table header_row="1">
<colgroup><col width="328"/></colgroup>
<thead>
<tr><th><p>方法</p></th></tr>
</thead>
<tbody>
<tr><td><p><code>FindActDescriptorByID(WorldContext, ActID)</code> / <code>FindActDescriptorByName(WorldContext, ActName)</code> / <code>GetAllActDescriptors(WorldContext)</code></p></td></tr>
<tr><td><p><code>FindPlotBoundaryByID(ActDesc, PlotID)</code> / <code>FindPlotBoundaryByName(ActDesc, PlotName)</code> / <code>GetAllPlotBoundaries(ActDesc)</code></p></td></tr>
<tr><td><p><code>FindPlotBoundaryByIDInWorld(WorldContext, PlotID)</code></p></td></tr>
</tbody>
</table>
<b>UActPlotSubsystem</b>(World 子系统)— 叙事数据加载与索引推进:
<table header_row="1">
<colgroup><col width="328"/><col width="269"/></colgroup>
<thead>
<tr><th><p>方法</p></th><th><p>说明</p></th></tr>
</thead>
<tbody>
<tr><td><p><code>LoadNarrative(UNarrativeDataAsset*)</code> / <code>ClearNarrative()</code></p></td><td><p>加载 / 清除叙事数据</p></td></tr>
<tr><td><p><code>NextAct()</code> / <code>NextPlot()</code> / <code>JumpToAct(int32 ActIndex)</code> → bool</p></td><td><p>索引推进</p></td></tr>
<tr><td><p><code>HasNarrativeLoaded()</code> / <code>GetCurrentActIndex()</code> / <code>GetCurrentPlotIndex()</code></p></td><td><p>状态查询(Pure)</p></td></tr>
</tbody>
</table>
<b>事件</b>:`OnActChanged(ActIndex)` / `OnPlotChanged(ActIndex, PlotIndex)` / `OnNarrativeComplete()`。
<b>UNarrativeDataAsset</b>(DataAsset)— 叙事骨架(见 06 §1.2):
<table header_row="1">
<colgroup><col width="328"/><col width="318"/></colgroup>
<thead>
<tr><th><p>方法</p></th><th><p>说明</p></th></tr>
</thead>
<tbody>
<tr><td><p><code>GetTotalActCount()</code> → int32</p></td><td><p>Act 总数(Pure)</p></td></tr>
<tr><td><p><code>IsValidActIndex(int32)</code> → bool</p></td><td><p>索引校验(Pure)</p></td></tr>
<tr><td><p><code>FindActIndexByName(FString)</code> → int32</p></td><td><p>按 ActName 查索引(Pure)</p></td></tr>
</tbody>
</table>
### 4.10 边界组件族
<table header_row="1">
<colgroup><col width="318"/><col width="93"/><col width="327"/></colgroup>
<thead>
<tr><th><p>组件</p></th><th><p>用途</p></th><th><p>主要方法</p></th></tr>
</thead>
<tbody>
<tr><td><p><code>UBaseBoundaryComponent</code>(抽象基类)</p></td><td><p>共用手册</p></td><td><p><code>Initialize(BoundaryID, Polygon, Height, bWorldSpacePoints)</code>、<code>SetAlpha(float)</code>、<code>SetBoundaryVisible(bool)</code>、<code>SetBoundaryMaterial(UMaterialInterface*)</code></p></td></tr>
<tr><td><p><code>UAnchorBoundaryComponent</code></p></td><td><p>Single 矩形锚点围栏</p></td><td><p><code>IsPointInside(FVector)</code> → bool(<b>BlueprintCallable</b>)、<code>SetAlpha</code>、<code>SetBoundaryMaterial</code></p></td></tr>
<tr><td><p><code>UFixedBoundaryComponent</code></p></td><td><p>纯逻辑矩形边界</p></td><td><p><code>IsPointInside(FVector)</code> → bool</p></td></tr>
<tr><td><p><code>UBoundaryMeshComponent</code></p></td><td><p>边界 mesh 生成</p></td><td><p><code>GenerateBoundaryMesh(Points, Height, BottomOffset=0)</code>、<code>GeneratePlaneMesh(Points, Height)</code>、<code>GetAlpha()</code></p></td></tr>
<tr><td><p><code>URealBoundaryComponent</code> / <code>UObstacleBoundaryComponent</code> / <code>UActAreaBoundaryComponent</code> / <code>UPlotAreaBoundaryComponent</code> / <code>UBestViewAreaBoundaryComponent</code></p></td><td><p>各语义边界</p></td><td><p>继承基类,自身无额外蓝图函数</p></td></tr>
</tbody>
</table>
<b>事件</b>:`OnEnterBoundary` / `OnExitBoundary` / `OnNearBoundary(Distance)`。
> ⚠️ `Initialize` 的 <b>bWorldSpacePoints</b> 参数决定多边形点的坐标系(`true` = 世界坐标 / `false` = 边界局部坐标)。<b>传错会导致边界可见性判定失效</b>,详见 06 §2.1。
### 4.11 报幕:`UAnnouncementManager` / `UCurtainCallManager`
<b>UAnnouncementManager</b>(World 子系统):
<table header_row="1">
<colgroup><col width="328"/><col width="241"/><col width="78"/></colgroup>
<thead>
<tr><th><p>方法</p></th><th><p>说明</p></th><th><p>Try 版</p></th></tr>
</thead>
<tbody>
<tr><td><p><code>TryShowAnnouncement(Content)</code> → bool</p></td><td><p>显示报幕牌(1.2.1)</p></td><td><p>—</p></td></tr>
<tr><td><p><code>ShowAnnouncementAtLocation(Content, WorldLocation)</code></p></td><td><p>在指定世界位置显示</p></td><td><p>—</p></td></tr>
<tr><td><p><code>HideAnnouncement()</code></p></td><td><p>隐藏报幕牌</p></td><td><p>—</p></td></tr>
</tbody>
</table>
<b>事件</b>:`OnAnnouncementShown(Content)` / `OnAnnouncementHidden(Content)`。
<b>UCurtainCallManager</b>(World 子系统):
<table header_row="1">
<colgroup><col width="328"/><col width="256"/><col width="78"/></colgroup>
<thead>
<tr><th><p>方法</p></th><th><p>说明</p></th><th><p>Try 版</p></th></tr>
</thead>
<tbody>
<tr><td><p><code>TryExecuteCurtainCall(Content="", FadeDuration=2.0)</code> → bool</p></td><td><p>执行报幕流程(1.2.1)</p></td><td><p>—</p></td></tr>
<tr><td><p><code>IsExecuting()</code> → bool</p></td><td><p>是否正在执行(Pure)</p></td><td><p>—</p></td></tr>
<tr><td><p><code>EnsureScreenFadeWidget()</code> / <code>GetScreenFadeWidget()</code></p></td><td><p>屏幕淡入淡出控件</p></td><td><p>—</p></td></tr>
</tbody>
</table>
### 4.12 叙事驱动:`UYomovSequencerDirectorComponent` / `AYomovLevelScriptActorBase`
<b>UYomovSequencerDirectorComponent</b>(YMMA 自带,见 06 §1.5):
<table header_row="1">
<colgroup><col width="328"/><col width="328"/></colgroup>
<thead>
<tr><th><p>方法</p></th><th><p>说明</p></th></tr>
</thead>
<tbody>
<tr><td><p><code>IsNarrativeStarted()</code> → bool</p></td><td><p>叙事是否已开始(Pure)</p></td></tr>
<tr><td><p><code>GetLevelSequenceActor()</code></p></td><td><p>取当前接管的 LSA(Pure)</p></td></tr>
<tr><td><p><code>IsSequencePlaying()</code> → bool</p></td><td><p>LevelSequence 是否在播(Pure)</p></td></tr>
</tbody>
</table>
<b>AYomovLevelScriptActorBase</b>(`ALevelScriptActor` 子类)— 时间轨信号的接收层:
<table header_row="1">
<colgroup><col width="328"/><col width="328"/></colgroup>
<thead>
<tr><th><p>方法(<code>YOMOV|Sequencer|Signal</code>)</p></th><th><p>状态</p></th></tr>
</thead>
<tbody>
<tr><td><p><code>YomovPlotTransition()</code></p></td><td><p><b>生效</b>——时间是轨 Event key 的接收函数</p></td></tr>
<tr><td><p><code>YomovEyeClose()</code> / <code>YomovEyeOpen()</code> / <code>YomovOpenComPass()</code> / <code>YomovOpenPlotHide()</code> / <code>YomovOpenQuit()</code></p></td><td><p><b>占位</b>(当前仅打 log,行为后续版本接入)</p></td></tr>
</tbody>
</table>
> 使用方法见 03 §2.4 时间轨三步契约。
### 4.13 配置:`UConfigManagerSubsystem` / `ULaunchParamsHelper`
<b>UConfigManagerSubsystem</b>(`UEngineSubsystem`):
<table header_row="1">
<colgroup><col width="328"/><col width="328"/></colgroup>
<thead>
<tr><th><p>方法</p></th><th><p>说明</p></th></tr>
</thead>
<tbody>
<tr><td><p><code>GetConfigData()</code> → <code>UConfigData*</code></p></td><td><p>取 <code>DA_DataAsset</code> 内容(Pure)</p></td></tr>
<tr><td><p><code>GetCommandLineArgsData()</code> → <code>UCommandLineArgsData*</code></p></td><td><p>取 <code>DA_CommandLineArgs</code> 全部字段(Pure)</p></td></tr>
<tr><td><p><code>LoadConfigFromDataAsset(bSkipBoundaryOverride=false)</code> → bool</p></td><td><p>从 DA 加载</p></td></tr>
<tr><td><p><code>LoadConfigFromCommandLine()</code> → bool</p></td><td><p>从命令行参数加载</p></td></tr>
<tr><td><p><code>LoadConfigFromPICOExtras()</code> → bool</p></td><td><p>从 PICO Intent 加载</p></td></tr>
<tr><td><p><code>ReloadConfig()</code> → bool</p></td><td><p>热重载(等价 Console 命令 <code>Yomov.Config.Reload</code>)</p></td></tr>
<tr><td><p><code>GetRawCommandLineArgs()</code> → FString</p></td><td><p>原始命令行参数字符串(Pure)</p></td></tr>
<tr><td><p><code>GetBuildType()</code> / <code>IsRecord()</code></p></td><td><p>包型 / 录制状态(Pure)</p></td></tr>
</tbody>
</table>
> ⚠️ `LoadConfigFromJSON(ConfigPath)`<b>已弃用且未实现</b>(恒返回 false)——配置正源是 `DA_DataAsset`,改用 `LoadConfigFromDataAsset`。
<b>ULaunchParamsHelper</b>(`UObject` + 静态方法,跨平台读取启播参数):
<table header_row="1">
<colgroup><col width="328"/><col width="328"/></colgroup>
<thead>
<tr><th><p>方法</p></th><th><p>说明</p></th></tr>
</thead>
<tbody>
<tr><td><p><code>HasLaunchParam(Key)</code> → bool</p></td><td><p>参数是否存在</p></td></tr>
<tr><td><p><code>GetLaunchParamString(Key, Default="")</code> / <code>GetLaunchParamInt</code> / <code>GetLaunchParamFloat</code> / <code>GetLaunchParamBool</code></p></td><td><p>通用取值(bool 真值接受 <code>"true"</code> / <code>"1"</code> / <code>"yes"</code>)</p></td></tr>
<tr><td><p><code>GetContentID()</code> / <code>GetTeamID()</code> / <code>GetPlayerID()</code> / <code>GetServerAddress()</code></p></td><td><p>常用参数快捷读取</p></td></tr>
<tr><td><p><code>GetServerPort(DefaultPort=8080)</code> → int32</p></td><td><p>服务器端口</p></td></tr>
</tbody>
</table>
> <b>平台分发</b>:Windows 走命令行(`FParse::Value`),Android 走 Intent Extras。<b>Android 侧反序列化时会跳过 </b><b>jsonData</b>。
### 4.14 `UCoordinateConverter`
`UObject` + 静态方法工具类(<b>不是</b>`UBlueprintFunctionLibrary`,但蓝图调用方式一致):
<table header_row="1">
<colgroup><col width="328"/><col width="328"/></colgroup>
<thead>
<tr><th><p>方法</p></th><th><p>说明</p></th></tr>
</thead>
<tbody>
<tr><td><p><code>ConvertUnityPositionToUE(FVector3)</code> / <code>ConvertUEPositionToUnity(FVector)</code></p></td><td><p>位置转换(含单位 ×100 与轴重标)</p></td></tr>
<tr><td><p><code>ConvertUnityRotationToUE(FVector4)</code> → FRotator / <code>ConvertUERotationToUnity(FRotator)</code></p></td><td><p>旋转转换(四元数以 <code>FVector4(x,y,z,w)</code> 表示)</p></td></tr>
<tr><td><p><code>ConvertUnityQuaternionToUE(FVector4)</code> → FQuat / <code>ConvertUEQuaternionToUnity(FQuat)</code> → FVector4</p></td><td><p>四元数转换(<b>推荐路径</b>,不经 Rotator 规格化)</p></td></tr>
<tr><td><p><code>ConvertUnityToUE(FTransform)</code> / <code>ConvertUEToUnity(FTransform)</code></p></td><td><p>整 Transform 转换</p></td></tr>
</tbody>
</table>
> <b>轴重标约定</b>:`(X, Y, Z) → (Z, X, Y)`;Unity 米 → UE 厘米(×100)。
> ⚠️ <b>Unity → UE 旋转不可逆(DLL 内部实现),roundtrip 测试注定失败——非 bug</b>,生产中只需保证单向转换正确。
### 4.15 虚空与边界效果:`UVoidSpaceManager` / `UBoundaryEffectManager`
<b>UVoidSpaceManager</b>(World 子系统):`EnterVoidSpace()` / `ExitVoidSpace()` / `ReloadConfig()` / `IsInVoidSpace()` → bool。机制见 06 §2.3。
<b>UBoundaryEffectManager</b>(World 子系统):`ReloadConfig()` → bool;以及一批 <b>BlueprintPure 只读 getter</b>(`GetMapBoundaryMaterial` / `GetPlotBoundaryMaterial` / `GetVoidSpackeSkyballMaterial` / `GetVoidSpackeGroundMaterial` / `GetPlotReturnGuideArrowMaterial` / `GetPlotReturnGuideStatuePrefab` / `GetAnnouncementPrefab` / `GetExitIndicatorPrefab` / `GetAnnouncementDefaultText` / `GetVoidSkyLightIntensity` / `GetConfig`)。
> 配置字段与语义见 06 §2.3–§2.5;编辑器改动入口见 09 编辑器工具。
---
## 5. `Try*` 家族对照表(1.2.1)
1.2.1 起动作类方法新增 `Try*` 版本:<b>返回 </b><b>bool</b>(`true` = 已处理 / `false` = 被拒并打日志),让调用方能<b>判错</b>而不是静默失败。
<b>19 个旧函数已标记 </b><b>DeprecatedFunction</b><b>——蓝图里会出现弃用提示,编译与运行不受影响</b>。按提示逐步迁移即可,不必一次性改完。
<table header_row="1">
<colgroup><col width="328"/><col width="328"/></colgroup>
<thead>
<tr><th><p>旧函数(已弃用)</p></th><th><p>新函数(推荐)</p></th></tr>
</thead>
<tbody>
<tr><td><p><code>UYomovBlueprintLibrary::InitializeAndAutoPlay</code></p></td><td><p><code>TryInitializeAndAutoPlay</code></p></td></tr>
<tr><td><p><code>UYomovBlueprintLibrary::TogglePause</code></p></td><td><p><code>TryTogglePause</code></p></td></tr>
<tr><td><p><code>UBridgeSDKBlueprintLibrary::ConnectToBridge</code></p></td><td><p><code>TryConnectToBridge</code></p></td></tr>
<tr><td><p><code>UFlowControllerComponent::Initialize</code></p></td><td><p><code>TryInitialize</code></p></td></tr>
<tr><td><p><code>UFlowControllerComponent::StartPlay</code></p></td><td><p><code>TryStartPlay</code></p></td></tr>
<tr><td><p><code>UFlowControllerComponent::PausePlay</code></p></td><td><p><code>TryPausePlay</code></p></td></tr>
<tr><td><p><code>UFlowControllerComponent::ResumePlay</code></p></td><td><p><code>TryResumePlay</code></p></td></tr>
<tr><td><p><code>UFlowControllerComponent::StopPlay</code></p></td><td><p><code>TryStopPlay</code></p></td></tr>
<tr><td><p><code>UFlowControllerComponent::NextPlot</code></p></td><td><p><code>TryNextPlot</code></p></td></tr>
<tr><td><p><code>USingleModeManager::SwitchToNextScene</code></p></td><td><p><code>TrySwitchToNextScene</code></p></td></tr>
<tr><td><p><code>USingleModeManager::SwitchScene</code></p></td><td><p><code>TrySwitchScene</code></p></td></tr>
<tr><td><p><code>USceneManagerSubsystem::LoadSceneAsync</code></p></td><td><p><code>TryLoadSceneAsync</code></p></td></tr>
<tr><td><p><code>USceneManagerSubsystem::UnloadScene</code></p></td><td><p><code>TryUnloadScene</code></p></td></tr>
<tr><td><p><code>USceneManagerSubsystem::UnloadSceneInstance</code></p></td><td><p><code>TryUnloadSceneInstance</code></p></td></tr>
<tr><td><p><code>UBoundarySubsystem::AddBoundary</code></p></td><td><p><code>TryAddBoundary</code></p></td></tr>
<tr><td><p><code>UAnnouncementManager::ShowAnnouncement</code></p></td><td><p><code>TryShowAnnouncement</code></p></td></tr>
<tr><td><p><code>UCurtainCallManager::ExecuteCurtainCall</code></p></td><td><p><code>TryExecuteCurtainCall</code></p></td></tr>
<tr><td><p><code>URemotePlayerSubsystem::SpawnOrUpdatePlayer</code></p></td><td><p><code>TrySpawnOrUpdatePlayer</code></p></td></tr>
<tr><td><p><code>UConfigManagerSubsystem::LoadConfigFromJSON</code></p></td><td><p><b>无替代</b>——配置正源改用 <code>DA_DataAsset</code>(<code>LoadConfigFromDataAsset</code>)</p></td></tr>
</tbody>
</table>
> <b>尚未提供 </b><b>Try*</b><b> 版本的方法</b>(仍按原签名使用,失败时看日志):`ReloadSceneAsync`、`CancelSceneLoading`、`ShowAnnouncementAtLocation`、`HideAnnouncement`、`LoadSceneInstanceAsync`、`RemovePlayer`、`ClearAllPlayers`、`SetLocalTeamIDOverride`。
---
## 6. 事件委托总表
按来源分组,便于反查:
<table header_row="1">
<colgroup><col width="328"/><col width="296"/><col width="185"/></colgroup>
<thead>
<tr><th><p>来源</p></th><th><p>委托</p></th><th><p>参数</p></th></tr>
</thead>
<tbody>
<tr><td><p><code>UBridgeServerControllerComponent</code></p></td><td><p><code>OnSyncContentDataReceived</code></p></td><td><p><code>const FSyncContentData&</code></p></td></tr>
<tr><td></td><td><p><code>OnRemoteStart</code> / <code>Pause</code> / <code>Resume</code> / <code>Seek</code> / <code>SetHeight</code> / <code>Exit</code></p></td><td><p><code>ContentID</code>, <code>TeamID</code>, <code>ExtraData</code></p></td></tr>
<tr><td><p><code>ABridgeEventReceiver</code></p></td><td><p><code>OnRemote*</code>(6 个)</p></td><td><p><code>ContentID</code>, <code>TeamID</code>, <code>ExtraData</code></p></td></tr>
<tr><td></td><td><p><code>OnBridgeConnectedEvent</code> / <code>OnBridgeDisconnectedEvent</code> / <code>OnBridgeReconnectingEvent</code></p></td><td><p>无参</p></td></tr>
<tr><td><p><code>UFlowControllerComponent</code></p></td><td><p><code>OnFlowStateChanged</code></p></td><td><p><code>EFlowState</code></p></td></tr>
<tr><td></td><td><p><code>OnFlowError</code></p></td><td><p><code>ErrorCode</code>, <code>ErrorMessage</code></p></td></tr>
<tr><td><p><code>URemotePlayerSubsystem</code></p></td><td><p><code>OnRemotePlayerSpawned</code> / <code>Update</code> / <code>Removed</code></p></td><td><p><code>PlayerID</code>, <code>PlayerActor*</code></p></td></tr>
<tr><td><p><code>AYomovTeamProperty</code></p></td><td><p><code>OnPlaybackStateChanged</code></p></td><td><p>无参</p></td></tr>
<tr><td></td><td><p><code>OnStageAreaChanged</code></p></td><td><p><code>Stage</code>, <code>Area</code></p></td></tr>
<tr><td><p><code>AYomovPlayerState</code></p></td><td><p><code>OnTeamIDChanged</code> / <code>OnContentIDChanged</code> / <code>OnNicknameChanged</code> / <code>OnAvatarSkinNameChanged</code></p></td><td><p>对应类型新值</p></td></tr>
<tr><td></td><td><p><code>OnIsReadyChanged</code></p></td><td><p><code>bool bIsReady</code></p></td></tr>
<tr><td><p><code>AYomovGameState</code></p></td><td><p><code>OnCrossContentPlayersUpdated</code> / <code>OnPlaybackStateChanged</code></p></td><td><p>无参</p></td></tr>
<tr><td><p><code>UEventBusSubsystem</code></p></td><td><p>见 §3.4(13 个)</p></td><td><p>—</p></td></tr>
<tr><td><p><code>UActPlotSubsystem</code></p></td><td><p><code>OnActChanged</code> / <code>OnPlotChanged</code> / <code>OnNarrativeComplete</code></p></td><td><p>索引 / 无参</p></td></tr>
<tr><td><p><code>USceneManagerSubsystem</code></p></td><td><p><code>OnSceneLoaded</code> / <code>OnSceneUnloaded</code></p></td><td><p><code>SceneName</code></p></td></tr>
<tr><td><p><code>UAnnouncementManager</code></p></td><td><p><code>OnAnnouncementShown</code> / <code>OnAnnouncementHidden</code></p></td><td><p><code>Content</code></p></td></tr>
<tr><td><p><code>UPathClientSubsystem</code></p></td><td><p><code>OnPathDataLoaded</code> / <code>OnPathDataLoadFailed</code></p></td><td><p>无参 / <code>ErrorMessage</code></p></td></tr>
<tr><td><p>边界组件族</p></td><td><p><code>OnEnterBoundary</code> / <code>OnExitBoundary</code> / <code>OnNearBoundary</code></p></td><td><p>无参 / <code>Distance</code></p></td></tr>
<tr><td><p><code>UYomovSDKSubsystem</code></p></td><td><p><code>OnDataReceived</code> / <code>OnConnected</code> / <code>OnDisconnected</code> / <code>OnError</code></p></td><td><p>字节数组 / 无参 / <code>ErrorMessage</code></p></td></tr>
<tr><td><p><code>UTCPClientSubsystem</code> / <code>UTCPClient</code></p></td><td><p><code>OnDataReceived</code> / <code>OnConnected</code> / <code>OnDisconnected</code> / <code>OnError</code></p></td><td><p>同上</p></td></tr>
<tr><td><p><code>UScreenFadeWidget</code></p></td><td><p><code>OnFadeComplete</code></p></td><td><p>无参</p></td></tr>
</tbody>
</table>
> ⚠️ `UAnchorBoundaryComponent` 与其他边界组件的 `OnEnterBoundary` 等是<b>各自独立声明的同名委托</b>(子类重新声明,不是继承同一个),绑定时注意目标组件类型。
---
## 7. 数据结构
<b>FSyncContentData</b>(msg 501):`ID`, `ContentName`, `Teams`(TArray<FSyncTeamData>), `JsonData`
<b>FSyncTeamData</b>:`ID`, `TeamName`, `CurStage`, `CurArea`, `SpanTime`, `Players`, `ContentID`, `JsonData`
<b>FSyncPlayerData</b>:`ID`, `PrefabName`, `PlayerNick`, `Position`(FVector3), `Rotation`(FYMVector4), `ContentID`, `TeamID`, `TeamName`, `JsonData`
<b>FSyncContentControlData</b>(msg 503):`ContentID`, `ControlType`(int32, 1–6), `ControlData`(TArray<uint8>), `TeamID`
<b>FRemotePlayerData</b>(UE 复制层,存于 `AYomovGameState::CrossContentPlayers`):
USTRUCT(BlueprintType) struct FRemotePlayerData { FString PlayerID; // 玩家 ID FString TeamID; // 所属队伍 FString ContentID; // 所在内容 FString Nickname; // 昵称 FVector Position; // 边界局部坐标(相对 BoundaryRealActor) FQuat Rotation; // 边界局部旋转 FString AvatarSkinName;// Avatar 资源名 float BodyScale; // 身高校准缩放(1.1.1,默认 1.0) };
<b>FYomovBodySyncData</b>:客户端上报的位姿数据(`HeadPosition` 为边界局部坐标)。
<b>FYomovInputContext</b>:本地 Pawn 输入上下文(配 `IYomovPawnInputProvider` 用)。
---
## 8. C++ 接入示例
> 适用于<b>源码包</b>消费方。binary 包消费方跨模块调 UE 业务 API 会 `LNK2019`,请走 02 §5 C API。
### 8.1 订阅播控事件
// MyBusinessComponent.h #pragma once
#include "CoreMinimal.h" #include "Components/ActorComponent.h" #include "GameMode/BridgeServerControllerComponent.h" #include "YomovManagerActor.h" #include "YomovBlueprintLibrary.h" #include "MyBusinessComponent.generated.h"
UCLASS(ClassGroup=(MyProject), meta=(BlueprintSpawnableComponent)) class UMyBusinessComponent : public UActorComponent { GENERATED_BODY() public: virtual void BeginPlay() override; virtual void EndPlay(const EEndPlayReason::Type EndPlayReason) override;
private: UPROPERTY() UBridgeServerControllerComponent* BridgeController_;
UFUNCTION()
void OnRemoteStart(const FString& ContentID, const FString& TeamID, const FString& ExtraData);
UFUNCTION()
void OnRemoteSeek(const FString& ContentID, const FString& TeamID, const FString& ExtraData);
};
// MyBusinessComponent.cpp void UMyBusinessComponent::BeginPlay() { Super::BeginPlay();
if (AYomovManagerActor* Manager = UYomovBlueprintLibrary::GetYomovManagerActor(this))
{
BridgeController_ = Manager->GetBridgeController();
}
if (BridgeController_)
{
// ⚠️ 必须在任何同步广播之前绑定
BridgeController_->OnRemoteStart.AddDynamic(this, &UMyBusinessComponent::OnRemoteStart);
BridgeController_->OnRemoteSeek.AddDynamic(this, &UMyBusinessComponent::OnRemoteSeek);
}
}
void UMyBusinessComponent::EndPlay(const EEndPlayReason::Type EndPlayReason) { if (BridgeController_) { // ⚠️ 反注册,防热重载 / 销毁后的野指针 BridgeController_->OnRemoteStart.RemoveDynamic(this, &UMyBusinessComponent::OnRemoteStart); BridgeController_->OnRemoteSeek.RemoveDynamic(this, &UMyBusinessComponent::OnRemoteSeek); } Super::EndPlay(EndPlayReason); }
### 8.2 响应播控并驱动流程
void UMyBusinessComponent::OnRemoteStart(const FString& ContentID, const FString& TeamID, const FString& ExtraData) { if (UFlowControllerComponent* Flow = UYomovBlueprintLibrary::GetFlowController(this)) { if (!Flow->TryStartPlay()) { UE_LOG(LogTemp, Warning, TEXT("StartPlay rejected — state=%d"), (int32)Flow->GetCurrentState()); } } }
void UMyBusinessComponent::OnRemoteSeek(const FString& ContentID, const FString& TeamID, const FString& ExtraData)
{
// ExtraData = {"stageName":"Act02","areaName":"Plot01"}
TSharedPtr
if (UFlowControllerComponent* Flow = UYomovBlueprintLibrary::GetFlowController(this))
{
Flow->JumpToActAndPlot(StageName, AreaName);
}
}
}
### 8.3 用自有数据源驱动远程 Avatar(替换粒度)
// 自有数据源(如自研多人系统)→ 转成边界局部坐标 → 喂给 Subsystem
void UMyBusinessComponent::OnMyPartyDataUpdated(const FMyPartyPlayer& InPlayer)
{
if (URemotePlayerSubsystem* RemoteSys = GetWorld()->GetSubsystem
### 8.4 监听运行期事件总线
void UMyBusinessComponent::BeginPlay() { Super::BeginPlay();
if (UEventBusSubsystem* Bus = GetWorld()->GetSubsystem<UEventBusSubsystem>())
{
Bus->OnPlotLoaded.AddDynamic(this, &UMyBusinessComponent::HandlePlotLoaded);
Bus->OnNarrativeComplete.AddDynamic(this, &UMyBusinessComponent::HandleNarrativeComplete);
}
}
> ⚠️ <b>EventBus 的委托是只读订阅面</b>——内容方订阅即可,<b>不要主动 Broadcast</b>(会干扰插件内部状态机)。
### 8.5 C++ 侧注意事项
- <b>UObject 指针必须 </b><b>UPROPERTY()</b>(GC-safe);异步回调 / 定时器捕获 `this` 用 `TWeakObjectPtr` + `IsValid` 判断
- <b>AddDynamic</b><b> 前先 </b><b>RemoveDynamic</b>,并在<b>同步广播之前</b>完成绑定
- <b>不受 UActorComponent 生命周期管理的 long-lived 订阅</b>(如 GameInstance 子系统)要在 `Deinitialize` 反注册
- <b>坐标</b>:传给远程玩家接口的位置是<b>边界局部坐标</b>;Unity 坐标先过 `UCoordinateConverter`
- <b>权威判断</b>:DS 相关逻辑用 `HasAuthority()` / `GetNetMode()`,表现层用 `IsLocallyControlled()`