Multiplayer Desyncs：修复破坏状态的 Unreal Engine RPC Replication Issue

每个多人游戏独立开发者都经历过 netcode 背叛他们的时刻。你发起了一个 Run on Server RPC 来装备武器。服务器日志确认武器已装备。服务器的碰撞体显示你处于瞄准姿态。但在客户端屏幕上呢？你的角色只是以默认的 idle 姿势站在那里，对状态更改完全没有反应。

当你的武器装备逻辑、瞄准状态、背包交互和合成系统突然在客户端停止更新时，恐慌随之而来。你可能会发现将 RPC 切换为 Multicast 就能神奇地修复这些视觉 bug。

千万不要停留在 Multicast 上。

使用 Multicast 来修复持久状态（persistent state）bug 只是治标不治本，最终会摧毁游戏的网络性能，并毁掉后加入玩家（late-joining）的游戏体验。在这篇深度解析中，我们将揭开臭名昭著的 unreal engine rpc replication issue 的根源，解释为什么你的服务器状态忽略了客户端，并使用 C++ 构建一个坚不可摧的 server-authoritative 状态同步架构。

Multicast 陷阱：为什么它“奏效”（以及为什么它会毁掉你的游戏）

当开发者遇到这个 bug 时，思路通常是这样的：

1. 客户端调用 Server_EquipWeapon()。
2. 服务器装备武器。
3. 客户端视觉效果未更新。
4. 将 Server_EquipWeapon() 改为调用 Multicast_EquipWeapon()。
5. 客户端视觉效果更新了！Bug 修复了，对吧？

错误。要理解原因，你必须明白 RPCs (Remote Procedure Calls) 和 Property Replication 之间的本质区别。

RPC 是瞬时的网络事件。它就像是对虚空的一次呐喊。如果 Multicast 触发时玩家在 network cull distance 内，他们会听到呐喊并播放装备动画。

但如果玩家在 10 秒后加入服务器会怎样？如果玩家在 5,000 Unreal Units 之外，走进 relevancy range 并看到你的角色会怎样？因为 Multicast 已经在过去触发过了，新客户端永远不会收到该事件。他们会看到你的角色拿着隐形武器，以 idle 姿势滑行，同时从胸口射出子弹。

Multicast 仅适用于瞬时的、非游戏关键的事件：爆炸视觉效果、音效或装饰性的粒子特效。

对于任何随时间持久存在的内容——比如你拿着什么武器、是否在瞄准、或者背包里有什么——你必须使用 Property Replication。

根源：为什么它突然坏了？

如果你的 Run on Server RPC 之前工作正常，但突然在多个系统（武器、瞄准、合成）中失效，你可能是以下三种架构变动的受害者：

1. Listen Server 与 Dedicated Server 的幻象

如果你之前在编辑器（PIE）中使用 Listen Server 进行测试，主机玩家既是客户端也是服务器。主机执行的 "Run on Server" RPC 会立即更新本地视觉状态，因为主机就是服务器。当你最终切换到 Dedicated Server 测试（或作为客户端 2 测试）时，幻象破灭了。服务器更新了其隔离的内存，而客户端被抛在了后面。

2. ActorComponent Ownership 损坏

如果你最近将背包或武器逻辑重构到了 UActorComponent 类中，你可能破坏了同步链。只有当客户端拥有（owns）该 Actor 时，才能从客户端调用 RPC。如果你的组件是动态生成的，并且没有通过 SetOwner(PlayerController) 明确分配所有者，服务器将直接丢弃 RPC 或无法将状态同步回来。我们在 Multiplayer Inventory Nightmares Fixing Swapped Actorcomponent Owners In Unreal Engine 指南中详细介绍了这种架构噩梦。

3. 绕过本地状态

此前，你的客户端输入事件可能在调用 Server RPC 之前设置了本地的 bIsAiming 布尔值。如果你将代码重构为纯粹的 “Server Authoritative”（等待服务器决定状态），但忘记将该状态同步回客户端，你的客户端将永久等待一个永远不会到来的更新。

分步教程：构建坚不可摧的状态同步

要修复这个 unreal engine rpc replication issue，我们必须从 RPC 驱动的架构过渡到使用 RepNotifies 的状态驱动架构。

以下是如何正确实现一个无缝更新客户端的 server-authoritative 武器装备和瞄准系统。

第 1 步：使用 RepNotifies 定义同步属性

与其信任 RPC 来触发动画，不如声明持久变量。当服务器更改这些变量时，Unreal 的 Net Driver 会自动将其同步到客户端。通过附加 ReplicatedUsing 函数（即 RepNotify），我们可以在客户端获知状态更改的确切时刻触发动画。

在你的角色头文件 (.h) 中：

UCLASS()
class MYGAME_API AMyCharacter : public ACharacter
{
    GENERATED_BODY()

public:
    AMyCharacter();

    // 持久状态。同步到所有客户端。
    UPROPERTY(ReplicatedUsing = OnRep_EquippedWeapon)
    AWeapon* EquippedWeapon;

    UPROPERTY(ReplicatedUsing = OnRep_IsAiming)
    bool bIsAiming;

    // RepNotify 函数。当服务器更新变量时在客户端运行。
    UFUNCTION()
    void OnRep_EquippedWeapon();

    UFUNCTION()
    void OnRep_IsAiming();

    // 请求状态更改的 Server RPC
    UFUNCTION(Server, Reliable, WithValidation)
    void Server_EquipWeapon(AWeapon* NewWeapon);

    UFUNCTION(Server, Reliable, WithValidation)
    void Server_SetAiming(bool bWantsToAim);

    // 核心同步设置
    virtual void GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const override;
};

第 2 步：实现 Server RPC 和同步规则

在 .cpp 文件中，你必须在 GetLifetimeReplicatedProps 中注册这些变量。然后，定义 Server RPC 以仅更新权威状态。

#include "MyCharacter.h"
#include "Net/UnrealNetwork.h"

void AMyCharacter::GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const
{
    Super::GetLifetimeReplicatedProps(OutLifetimeProps);

    // 将这些变量同步到所有连接的客户端
    DOREPLIFETIME(AMyCharacter, EquippedWeapon);
    DOREPLIFETIME(AMyCharacter, bIsAiming);
}

// --- 瞄准逻辑 ---

bool AMyCharacter::Server_SetAiming_Validate(bool bWantsToAim)
{
    // 反作弊：确保玩家被允许瞄准（例如：未死亡）
    return !bIsDead;
}

void AMyCharacter::Server_SetAiming_Implementation(bool bWantsToAim)
{
    bIsAiming = bWantsToAim;
    
    // 关键：在 C++ 中，RepNotifies 不会在服务器上自动运行。
    // 如果服务器也是玩家（Listen Server），我们必须手动调用它。
    if (GetNetMode() != NM_DedicatedServer)
    {
        OnRep_IsAiming();
    }
}

第 3 步：实现用于视觉更新的 RepNotifies

这是编写动画逻辑、UI 更新和模型挂载的地方。由于这依赖于同步状态，后加入的玩家在角色对他们变得可见（relevant）时，会自动触发此逻辑。

void AMyCharacter::OnRep_IsAiming()
{
    if (UAnimInstance* AnimInst = GetMesh()->GetAnimInstance())
    {
        if (UMyAnimInstance* MyAnim = Cast<UMyAnimInstance>(AnimInst))
        { 
            MyAnim->bIsAiming = bIsAiming;
        }
    }

    GetCharacterMovement()->MaxWalkSpeed = bIsAiming ? 300.f : 600.f;
}

void AMyCharacter::OnRep_EquippedWeapon()
{
    if (EquippedWeapon)
    {
        EquippedWeapon->AttachToComponent(GetMesh(), FAttachmentTransformRules::SnapToTargetNotIncludingScale, FName("WeaponSocket"));
        PlayAnimMontage(EquipMontage);
    }
}

专业进阶：Client-Side Prediction

如果你只实现上述内容，你会注意到一个新问题：Input Latency。如果玩家有 100ms 延迟，他们按下瞄准键后，需要 200ms 才能看到角色动作。这在现代射击游戏中体验极差。

为了解决这个问题，我们实现 Client-Side Prediction。客户端立即在视觉上模拟状态更改，同时向服务器请求许可。

void AMyCharacter::StartAiming()
{
    // 1. 立即进行本地预测（玩家零延迟感）
    bIsAiming = true;
    OnRep_IsAiming(); 

    // 2. 告知服务器使其正式生效
    if (!HasAuthority())
    {
        Server_SetAiming(true);
    }
}

如果服务器拒绝（例如服务器知道玩家在 50ms 前被击晕了），同步的 bIsAiming 将保持为 false，客户端将无缝回滚状态。这是稳健多人架构的基础，正如我们在 The Unreal Engine Multiplayer Sync Bug Ruining Your World States And How To Fix It 中讨论的概念。

扩展到比赛之外：持久化玩家状态

修复游戏内同步可确保服务器和客户端在比赛期间达成一致。但当比赛结束或服务器关闭时，那些同步良好的背包和武器数据该怎么办？

如果你希望玩家保留他们合成的武器，这些状态需要离开 Unreal Engine 实例并存储在安全的数据库中。自行构建这些（负载均衡、数据库分片、REST APIs）通常需要 4-6 周。使用 horizOn，这些后端服务是预配置的。你可以直接从服务器将玩家数据持久化到云端。

Unreal Engine 同步的 5 个最佳实践

1. 永远不要对持久状态使用 Multicast： 如果变量描述的是世界状态（背包、武器、血量），它必须是同步属性。Multicast 仅用于“触发即忘”的视觉效果。
2. 在服务器上手动调用 RepNotifies： 在 C++ 中，OnRep_ 函数不会在服务器上自动触发。如果是 Listen Server，必须手动调用。
3. 验证你的 Server RPC： 永远不要信任客户端。使用 _Validate 检查状态更改是否逻辑可行。
4. 注意 NetUpdateFrequency： 如果视觉状态随机滞后，检查 Actor 的更新频率是否成为瓶颈。
5. 检查组件所有权： 从 UActorComponent 调用 Server RPC 时，确保组件已设置同步且其所属 Actor 被 APlayerController 拥有。

停止与 Net Driver 搏斗

Unreal 的同步系统非常强大，但如果你试图绕过它的规则，它也是毫不留情的。当客户端状态停止更新时，抵制滥用 Multicast 的冲动。遵循权威路径：客户端请求，服务器裁定，属性同步。

准备好提升你的多人游戏了吗？停止担心后端管理。免费试用 horizOn，立即为你的玩家提供持久进度和无缝匹配。