多队伍道具与交互同步
插件版本 1.2.3 | 文档版本 1.2.3 | UE 5.3-5.7 面向读者:需要在一个 DS 上承载多支队伍、并让同队玩家共同操作道具的接入开发 适用场景:同队玩家之间需要同步道具状态/移动;异队玩家互不可见、互不干扰 本篇方案不需要修改 SDK、不需要重新打包插件,按蓝图配置即可
目录
-
- 先确认三个前提
-
- 原理(30 秒版)
-
- 配置步骤
-
- 两个典型交互示例
-
- 验证清单
-
- 边界与限制
-
- 常见问题排查
-
- 与现有文档的关系
0. 先确认三个前提
前提 | 怎么确认 | |
|---|---|---|
1 | 道具由 DS 动态 spawn,每队一套 | spawn 逻辑在 |
2 | 道具蓝图开启 | 道具蓝图 → Class Defaults → Replication → |
3 | 道具类没有自己重写 | 若父类是自己项目的 C++ 类且重写了该函数,本方案不生效(需调用 Super,或等待 SDK 后续版本提供基类) |
为什么必须是 DS spawn:在 SDK 标准多人流程下,叙事场景由客户端
LoadLevelInstance动态加载,DS 不加载这些场景。摆在场景关卡里的道具在 DS 上不存在;每个客户端各自加载一份实例,同队两个玩家也不是同一个对象——没有"一份权威 Actor"可供同队同步。 如果玩家的操作触发道具生成,也要通过 Pawn / PlayerController 的 Server RPC 在 DS 上 spawn,不能在客户端直接 spawn。
1. 原理(30 秒版)
-
UE 的属性复制、Actor 生成/销毁、
NetMulticast都按 Actor 的网络相关性(Network Relevancy) 路由;相关性的判断函数是AActor::IsNetRelevantFor。 -
SDK 的
AYomovTeamProperty(每队一个,DS 在玩家登录时创建)已经实现了"只对同队客户端相关"。 -
引擎默认的
IsNetRelevantFor在bNetUseOwnerRelevancy = true时,会直接使用 Owner 的相关性。 -
因此:把每队道具的 Owner 设为该队的 TeamProperty,道具就自动只复制给同队客户端。
效果:
通道 | 结果 |
|---|---|
Actor 生成/销毁 | 异队客户端根本不会创建这个道具 |
属性复制 | 只到同队客户端 |
| 只到同队客户端 |
Server RPC | 不受影响,但必须放在玩家 Pawn/PC 上(见 §2.4) |
2. 配置步骤
2.1 道具蓝图类默认值
打开道具蓝图 → Class Defaults → Replication:
属性 | 值 | 说明 |
|---|---|---|
| ✓ | 必须开启 |
| ✓ | 核心开关,让相关性跟随 Owner |
| ✗ | 开了会覆盖队伍过滤,异队也能收到 |
| ✗ | 不能开;本方案用的是 Owner 相关性,不是"仅 Owner" |
| ✗ | DS 动态 spawn 的道具建议关闭 |
| 按需 | 道具用 |
| 10–30 | 按交互频率调整;默认 100 偏高 |
| 2 | 保持默认即可 |
⚠️ Owner 被 TeamProperty 占用:道具自己的"归属玩家 / 抓取者 / 使用中玩家"请另存为独立变量,不要复用
Owner,否则会破坏相关性。
2.2 DS 侧:按队伍 spawn
① 获取该队伍的 TeamProperty
Get Yomov Team Subsystem → Find Team Property (TeamID)
项 | 说明 |
|---|---|
|
|
调用时机 | 该队至少一名玩家 |
调用端 | 仅 DS(Authority 分支) |
② spawn 并立刻设置 Owner(同一帧)
[Server] 队伍就绪(TeamProperty 非空)
├─ Spawn Actor from Class(PropClass, 该队伍场景中的位置)
│ └─ 若节点有 Owner 引脚:直接填 TeamProperty
├─ 若无 Owner 引脚:spawn 后立即 Set Owner = TeamProperty
└─(可选)设置道具的 TeamID 复制变量,便于调试与服务器校验
要点:
-
每队一套,不要跨队共用同一个 Actor。
-
spawn 位置数据必须 DS 可得(DataAsset / 配置表 / 服务器侧数据),不要从"只在客户端加载的场景"里读取。
-
只在 Authority 分支 spawn,避免出现"服务器一份 + 客户端本地又一份"的重复。
-
若使用
Spawn Actor Deferred,在Finish Spawning之前设置 Owner。
2.3 状态同步
数据类型 | 做法 |
|---|---|
持久状态(开关、归属、进度、激活状态) | 道具蓝图的 Replicated 变量 + RepNotify |
位置 / 旋转 | 开启 |
瞬时表现(音效、粒子、高亮) |
|
⚠️ 不要用 Multicast 承载持久状态:中途加入的同队玩家收不到历史 RPC,会看到错误状态。持久状态放复制属性,late join 会通过初始复制拿到当前值并触发 OnRep。 可靠 Multicast 在"通道尚未关闭"的短暂窗口内可能发到当前不相关的连接。持久状态用复制属性,瞬时表现用 Unreliable Multicast。
2.4 交互 RPC
不要把 Server RPC 放在道具上。
道具的 Owner 是 TeamProperty(不是玩家 PlayerController),GetNetConnection() 为空,客户端调用道具上的 Server RPC 会被服务器丢弃(日志通常出现 No owning connection for actor ...)。
正确做法:RPC 放在玩家自己的 Pawn 或 PlayerController 上,道具作为参数传入。
客户端蓝图(Pawn 或 PlayerController):
Custom Event(Replication = Run on Server,Reliable)
参数:
├─ TargetProp (Actor) 目标道具
├─ EventName (Name) 交互类型,如 "Grab" / "Release" / "Activate"
└─ Payload (String / Transform / Vector,按需)
服务器端校验(同一个事件):
1. IsValid(TargetProp)
2. TargetProp.GetOwner() == Find Team Property(本玩家 TeamID)
3. (可选)距离校验:玩家与道具距离 <= MaxInteractDistance
4. 通过 → 修改道具的复制状态 / 位置
-
第 2 步是最强的同队校验:Owner 就是本队 TeamProperty。
-
本玩家 TeamID 从
YomovPlayerState.TeamID读取;为空(未登录)直接拒绝。 -
修改后由复制自动只回到同队客户端。
3. 两个典型交互示例
3.1 抓取 / 移动道具
-
客户端按下抓取 → 本地播表现(可选)→
ServerInteract(Prop, "Grab", ...)。 -
服务器校验同队 + 距离 → 记录抓取者(Replicated 变量)→ 接收客户端的目标 Transform(低频,不要每帧 RPC)→
SetActorLocation/SetActorRotation。 -
同队其他玩家通过复制看到移动;异队完全看不到。
-
松开 →
ServerInteract(Prop, "Release", ...)→ 清抓取者。
服务端不要给道具开刚体物理,原因见 §5。
3.2 开关 / 激活类
-
客户端
ServerInteract(Prop, "Activate", "")。 -
服务器校验同队 → 把
bActivated置true(Replicated + RepNotify)。 -
同队客户端 OnRep 后播特效 / 换材质;异队客户端没有这个 Actor。
4. 验证清单
场景 | 预期 | |
|---|---|---|
1 | A 队两名玩家 | 都能看到同一道具;A 移动后两人看到同步 |
2 | B 队玩家 | 看不到 A 队道具;对 A 队道具的交互 RPC 被服务器拒绝 |
3 | 中途加入 A 队 | 能看到道具当前状态(不依赖历史 RPC) |
4 | 换队 | 道具按新队伍的相关性出现 / 消失 |
5 | 断线重连 | 重新登录后恢复同队可见;1.2.3 起同时按场景级对齐队伍进度(见 06 §1.6) |
测试环境:
-
推荐 DS + 两台客户端(不同 TeamID,如两台头显或两个打包客户端)。
-
⚠️ PIE 注意:默认
DA_DataAsset的TeamOriginID对所有 PIE 客户端相同,两个 PIE 客户端会落在同一队。需要模拟两队时:-
用测试蓝图在不同客户端调
SetLocalTeamIDOverride(必须在Server_Login之前),或 -
直接用两个打包客户端,分别配不同的 TeamOriginID / 启动参数。
-
5. 边界与限制
-
物理:网络隔离开的是消息,不是物理世界。DS 上两队道具仍在同一个物理世界;如果服务端开刚体物理且两组道具坐标重叠,会互相碰撞、推挤。建议服务端道具保持 kinematic,只做 Transform 权威;客户端表现层可自行处理。
-
关卡摆放道具不适用:见 §0。必须是 DS 动态 spawn。
-
Owner 被占用:道具自身逻辑不要复用
Owner,另存变量。 -
道具类重写 IsNetRelevantFor:本方案依赖引擎默认实现;若父类重写且不调 Super,队伍过滤不生效。
-
距离:Owner relevancy 不走距离剔除,同队玩家再远也会同步。如果需要在队内做距离裁剪,需要 C++ 自定义相关性(当前 binary 包不开放)。
-
Server RPC 必须在 Pawn/PC:道具无 owner connection。
-
性能:相关性检查按 Actor × 连接执行;道具数量很大时建议开 Dormancy、降低
Net Update Frequency。
6. 常见问题排查
现象 | 优先检查 |
|---|---|
异队能看到道具 |
|
道具完全不复制 |
|
只有某一个玩家能看到道具 | 误开了 |
道具上的 Server RPC 不触发 | 把 RPC 移到 Pawn / PlayerController;道具 Owner 是 TeamProperty,本身没有 owner connection |
同队玩家看不到彼此的道具移动 | 是否开了 |
late join 看不到状态 | 状态是否放在 Multicast 而不是复制属性 |
换队后道具还在 | 道具是否仍指向旧队伍的 TeamProperty;换队后需要重新归属 / 重建道具 |
道具生成在错误位置 | DS 侧的 spawn 位置数据是否与客户端场景一致(同一张图、同一原点) |
7. 与现有文档的关系
-
06 §3.5 提到"不要改
IsNetRelevantFor"——那句话针对 远程玩家 Avatar 的显隐,不是说道具不能做队伍隔离。本方案不改任何虚函数,用的是引擎自带的 Owner relevancy。 -
队伍查询 API(
AreOnSameTeam/FindTeamProperty/GetMyTeamProperty)见 07 §4.6。 -
TeamID 推导链路与边界坐标一致性见 03 §3.3。
📷 【截图待补】 道具蓝图 Class Defaults 中 Replication 各项的配置示例 📷 【截图待补】 DS 侧 spawn + Set Owner 的蓝图节点示例 📷 【截图待补】 Pawn 上 Run on Server 自定义事件 + 服务器同队校验的蓝图示例