跳到主要内容

多队伍道具与交互同步

插件版本 1.2.3 | 文档版本 1.2.3 | UE 5.3-5.7 面向读者:需要在一个 DS 上承载多支队伍、并让同队玩家共同操作道具的接入开发 适用场景:同队玩家之间需要同步道具状态/移动;异队玩家互不可见、互不干扰 本篇方案不需要修改 SDK、不需要重新打包插件,按蓝图配置即可


目录​

    1. 先确认三个前提
    1. 原理(30 秒版)
    1. 配置步骤
    1. 两个典型交互示例
    1. 验证清单
    1. 边界与限制
    1. 常见问题排查
    1. 与现有文档的关系

0. 先确认三个前提​

前提

怎么确认

1

道具由 DS 动态 spawn,每队一套

spawn 逻辑在 Switch Has Authority 的 Authority 分支,或 GameMode 等仅服务器执行的蓝图里;客户端不能本地 spawn

2

道具蓝图开启 Replicates

道具蓝图 → Class Defaults → Replication → Replicates ✓

3

道具类没有自己重写 IsNetRelevantFor

若父类是自己项目的 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 生成/销毁

异队客户端根本不会创建这个道具

属性复制

只到同队客户端

NetMulticast

只到同队客户端

Server RPC

不受影响,但必须放在玩家 Pawn/PC 上(见 §2.4)


2. 配置步骤​

2.1 道具蓝图类默认值​

打开道具蓝图 → Class Defaults → Replication:

属性

值

说明

Replicates

✓

必须开启

Net Use Owner Relevancy

✓

核心开关,让相关性跟随 Owner

Always Relevant

✗

开了会覆盖队伍过滤,异队也能收到

Only Relevant to Owner

✗

不能开;本方案用的是 Owner 相关性,不是"仅 Owner"

Net Load on Client

✗

DS 动态 spawn 的道具建议关闭

Replicate Movement

按需

道具用 SetActorLocation / SetActorRotation 移动时开启

Net Update Frequency

10–30

按交互频率调整;默认 100 偏高

Min Net Update Frequency

2

保持默认即可

⚠️ Owner 被 TeamProperty 占用:道具自己的"归属玩家 / 抓取者 / 使用中玩家"请另存为独立变量,不要复用 Owner,否则会破坏相关性。

2.2 DS 侧:按队伍 spawn​

① 获取该队伍的 TeamProperty

Get Yomov Team Subsystem → Find Team Property (TeamID)

项

说明

TeamID 来源

YomovPlayerState.TeamID(蓝图可直接读),或内容自有队伍 ID(必须与 PlayerState.TeamID 一致)

调用时机

该队至少一名玩家 Server_Login 成功之后;Find Team Property 返回 null 说明队伍尚未就绪,延迟 0.2s 重试

调用端

仅 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

位置 / 旋转

开启 Replicate Movement;或自定义 Replicated Transform 变量 + 客户端插值

瞬时表现(音效、粒子、高亮)

NetMulticast(自动只到同队客户端)

⚠️ 不要用 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 抓取 / 移动道具​

  1. 客户端按下抓取 → 本地播表现(可选)→ ServerInteract(Prop, "Grab", ...)。

  2. 服务器校验同队 + 距离 → 记录抓取者(Replicated 变量)→ 接收客户端的目标 Transform(低频,不要每帧 RPC)→ SetActorLocation / SetActorRotation。

  3. 同队其他玩家通过复制看到移动;异队完全看不到。

  4. 松开 → ServerInteract(Prop, "Release", ...) → 清抓取者。

服务端不要给道具开刚体物理,原因见 §5。

3.2 开关 / 激活类​

  1. 客户端 ServerInteract(Prop, "Activate", "")。

  2. 服务器校验同队 → 把 bActivated 置 true(Replicated + RepNotify)。

  3. 同队客户端 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. 边界与限制​

  1. 物理:网络隔离开的是消息,不是物理世界。DS 上两队道具仍在同一个物理世界;如果服务端开刚体物理且两组道具坐标重叠,会互相碰撞、推挤。建议服务端道具保持 kinematic,只做 Transform 权威;客户端表现层可自行处理。

  2. 关卡摆放道具不适用:见 §0。必须是 DS 动态 spawn。

  3. Owner 被占用:道具自身逻辑不要复用 Owner,另存变量。

  4. 道具类重写 IsNetRelevantFor:本方案依赖引擎默认实现;若父类重写且不调 Super,队伍过滤不生效。

  5. 距离:Owner relevancy 不走距离剔除,同队玩家再远也会同步。如果需要在队内做距离裁剪,需要 C++ 自定义相关性(当前 binary 包不开放)。

  6. Server RPC 必须在 Pawn/PC:道具无 owner connection。

  7. 性能:相关性检查按 Actor × 连接执行;道具数量很大时建议开 Dormancy、降低 Net Update Frequency。


6. 常见问题排查​

现象

优先检查

异队能看到道具

Owner 是否设成 TeamProperty(不能为 null);Net Use Owner Relevancy 是否 ✓;Always Relevant 是否误开;spawn 后 Owner 是否在第一帧就设好

道具完全不复制

Replicates 是否 ✓;是否在 DS 的 Authority 分支 spawn(客户端本地 spawn 不会复制)

只有某一个玩家能看到道具

误开了 Only Relevant to Owner,或 Owner 被设成了玩家 PlayerController(owner 例外会让该玩家恒可见)

道具上的 Server RPC 不触发

把 RPC 移到 Pawn / PlayerController;道具 Owner 是 TeamProperty,本身没有 owner connection

同队玩家看不到彼此的道具移动

是否开了 Replicate Movement;或自定义 Transform 是否用了 Replicated 变量;是否只改了本地

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 自定义事件 + 服务器同队校验的蓝图示例