在虚幻引擎多人游戏中实现网络复制、RPC…

为 UE 多人游戏配置 Actor 属性复制、RPC、所有权、相关性与客户端预测，确保服务器权威与状态同步。

适用场景

解决思路

1. 先读取 `.agents/ue-project-context.md` 了解项目的多人配置（服务器拓扑、玩家数、需复制的类、自定义 net driver）；若文件不存在，则询问：服务器拓扑（dedicated/listen/P2P）、每会话最大玩家数、哪些 actor 或 component 需要复制数据、是否使用 GAS。
2. 理解网络角色模型：服务器是游戏状态的唯一权威来源，客户端本地预测并与服务器修正进行对账；每个 actor 在每台机器上都有 local role 和 remote role（ROLE_Authority、ROLE_AutonomousProxy、ROLE_SimulatedProxy、ROLE_None）。
3. 使用 `GetLocalRole()`、`GetRemoteRole()`、`HasAuthority()` 判断当前机器的角色与权限；注意 listen-server 主机同时是 ROLE_Authority 且本地控制，用 `IsLocallyControlled()` 区分应跳过主机玩家的逻辑。
4. 在 Actor 构造函数中设置复制：`bReplicates = true`、`SetReplicateMovement(true)`、`SetNetUpdateFrequency(10.f)`、`SetMinNetUpdateFrequency(2.f)`、`NetPriority = 1.0f`；需要时用 `SetNetCullDistanceSquared`。
5. 对于使用 UCharacterMovementComponent 的角色，设置 `SetReplicateMovement(false)`，因为 CMC 通过 `FSavedMove_Character` 自行做基于预测的复制与服务器对账，绕过 FRepMovement。
6. 声明可复制属性：`UPROPERTY(Replicated)` 或 `UPROPERTY(ReplicatedUsing = OnRep_State)`，并为 OnRep 函数声明 `UFUNCTION()`（旧值作为可选参数传入）。
7. 重写 `GetLifetimeReplicatedProps`，务必先调用 `Super::GetLifetimeReplicatedProps(OutLifetimeProps)`，再用 `DOREPLIFETIME` 或 `DOREPLIFETIME_CONDITION` 注册每个属性。
8. 按用途选择复制条件：`COND_None`（所有）、`COND_OwnerOnly`（私有玩家数据如背包、货币）、`COND_SkipOwner`、`COND_SimulatedOnly`、`COND_AutonomousOnly`、`COND_InitialOnly`（不可变生成数据如队伍、角色类）、`COND_Custom`。
9. 注意初始复制突发：客户端首次加入或 actor 首次变为相关时，所有可复制属性会无视条件一次性发送（`COND_InitialOnly` 仅在此触发一次）；保持初始状态紧凑以减少带宽。
10. 对于大数组，使用 `FFastArraySerializer` 实现仅增量复制，避免普通 `TArray` 在任意变更时发送整个数组。
11. 对于自定义结构体，在 `USTRUCT` 上实现 `NetSerialize` 并添加 `TStructOpsTypeTraits` 且 `WithNetSerializer = true`；用 `FVector_NetQuantize10`（0.1 cm 精度）替代原始 `FVector` 以减半位置带宽。
12. 编写 RPC：Server RPC 用 `UFUNCTION(Server, Reliable, WithValidation)`（状态变更必须带 WithValidation），Client RPC 用 `UFUNCTION(Client, Reliable)`，NetMulticast 用 `UFUNCTION(NetMulticast, Unreliable)`；实现函数以 `_Implementation` 结尾，带验证的 Server RPC 还需 `_Validate`（返回 false 踢出客户端）。
13. 按语义选择可靠性：Reliable 用于状态变更动作（购买、生成、占有），Unreliable 用于高频装饰性效果。
14. 遵守 RPC 所有权规则：Server RPC 必须在所有权链通向调用客户端 `APlayerController` 的 actor 上调用；Client RPC 必须在拥有 `NetConnection` 的玩家所拥有的 actor 上调用；在无所有权 actor 上调用会被静默丢弃。
15. RPC 参数只使用可网络寻址类型：基本类型（int32、float、FString、FVector）、已复制的 `UObject*` 指针（未复制则到达时为 nullptr）、`USTRUCT(BlueprintType)` 结构体；非复制 UObject* 会变为 nullptr，应传 ID 并在远端查找；超过 1 KB 的负载改用可复制属性；TArray/TMap 参数可用但注意带宽。
16. 在服务器上调用 `SetOwner(PlayerController)` 控制 RPC 路由与 `COND_OwnerOnly`；使用 `bAlwaysRelevant`、`bOnlyRelevantToOwner` 或重写 `IsNetRelevantFor` 实现自定义相关性（如基于队伍）。
17. 对很少变化的 actor 使用休眠：`SetNetDormancy(DORM_DormantAll)` 停止复制，`FlushNetDormancy()` 发送一次更新后回到休眠。
18. 设计 `OnRep_` 函数为幂等，因为 actor 移出 `NetCullDistanceSquared` 后再进入范围会被视为新的相关性事件，再次发送初始突发并以当前服务器状态触发所有 OnRep；休眠 actor 被唤醒时也会一次性刷新所有脏属性。
19. 复制子对象：UE 5.1+ 启用 `bReplicateUsingRegisteredSubObjectList = true`（现为默认），在服务器 `BeginPlay` 调用 `AddReplicatedSubObject`（或 `AddActorComponentReplicatedSubObject`），在 `EndPlay` 调用 `RemoveReplicatedSubObject`；旧 API 则重写 `ReplicateSubobjects` 并调用 `Channel->ReplicateSubobject`。
20. 实现客户端预测（非移动、非 GAS 系统）：客户端本地立即应用效果并调用 Server RPC 请求确认；服务器验证后应用权威效果并广播，或调用 Client RPC 通知预测失败以回滚。
21. 服务器拒绝预测时平滑视觉修正：在 2-3 帧内插值到修正位置而非瞬移；UCharacterMovementComponent 通过 `NetworkSmoothingMode`（Linear、Exponential、Disabled）自动处理。
22. 注意预测适用范围：只有 UCharacterMovementComponent 和 GAS（UAbilitySystemComponent 配合 FPredictionKey）有引擎管理的预测与回滚；原始 `UPROPERTY(Replicated)` 属性没有内置预测，本地写入会被服务器复制值覆盖且无回滚，应使用本地变量做视觉预测并在 `OnRep_` 中应用权威值。
23. 使用 GAS 时理解 FPredictionKey：客户端通过 `FPredictionKey::CreateNewPredictionKey` 生成，嵌入 Server RPC，服务器应用 GameplayEffect 或激活能力时匹配；预测无效时客户端上所有带该 key 的 GameplayEffect 和属性变更自动回滚；通常由 `UAbilitySystemComponent::TryActivateAbility` 管理生命周期，自定义 `UGameplayAbility` 子类需要作用域预测窗口时用 `FScopedPredictionWindow`。
24. 按 Actor 复制设置清单逐项检查：构造函数中 `bReplicates = true`；设置 NetUpdateFrequency/MinNetUpdateFrequency；声明所有 Replicated/ReplicatedUsing 属性；重写 GetLifetimeReplicatedProps 并先调用 Super；为每个属性使用 DOREPLIFETIME/DOREPLIFETIME_CONDITION；OnRep 函数声明为 UFUNCTION() 并实现；Server RPC 带 WithValidation 并实现 _Validate；NetMulticast/Client RPC 调用处用 HasAuthority() 保护；子对象通过 AddReplicatedSubObject 或 ReplicateSubobjects 注册；生成拥有 actor 后在服务器调用 SetOwner()；很少更新的 actor 设置 DORM_DormantAll。
25. 对于 50+ 连接的大规模场景，使用 UReplicationGraph 替代默认逐连接逐 actor 相关性检查：在 Build.cs 添加 "ReplicationGraph"，在 DefaultEngine.ini 的 `[/Script/OnlineSubsystemUtils.IpNetDriver]` 设置 `ReplicationDriverClassName`，重写 `InitGlobalActorClassSettings`、`InitGlobalGraphNodes`、`InitConnectionGraphNodes`；使用 `UReplicationGraphNode_GridSpatialization2D`（空间）、`UReplicationGraphNode_AlwaysRelevant`（GameState、管理器）、`UReplicationGraphNode_AlwaysRelevant_ForConnection`（PlayerController、PlayerState、HUD）、`UReplicationGraphNode_ActorList`（自定义列表）。
26. 避免常见错误：修改状态前加 `if (!HasAuthority()) return;`；Server RPC 必须带 WithValidation 并在 _Validate 中校验；Client/NetMulticast 只能从服务器调用并用 HasAuthority() 保护；可复制组件上的大数组用 FFastArraySerializer；GetLifetimeReplicatedProps 必须先调用 Super 否则父类属性被静默丢弃；RPC 参数不传非复制 UObject*（传 ID 远端查找）；持久状态用 UPROPERTY(Replicated) 而非 NetMulticast（否则后加入客户端错过）；只复制游戏关键状态，装饰性数据客户端本地推导。
27. 注意 APlayerController 复制范围：它只存在于服务器和拥有它的客户端，不在其他客户端上；面向所有客户端的数据放在 APawn 或 APlayerState 上；用 `APlayerController::GetNetConnection()` 获取 UNetConnection 做所有权检查、RPC 路由和断线检测（绑定 `AGameModeBase::OnLogout` 或检查 `NetConnection->GetConnectionState() == USOCK_Closed` / `IsClosingOrClosed()`，不要轮询 NetConnection）；连接作用域的 Client RPC（HUD 更新、语音、关卡流送通知）用 APlayerController，世界可见状态用 APawn 或 APlayerState。

适用边界 · 注意事项

• 项目不是虚幻引擎或不做多人网络复制时
• 只需要单机/本地多人（NM_Standalone）且无服务器权威同步需求时
• 使用 GAS 网络功能时应参考 ue-gameplay-abilities 技能获取完整 GAS 网络细节