游戏引擎 / 系统课时
开启Actor属性复制
开启Actor属性复制
当生命值、开关状态或目标阶段需要让多个客户端看到同一结果时,应把它们作为服务器权威属性进行复制。本课用一个可直接放进关卡的 Actor 演示 bReplicates、ReplicatedUsing 与 DOREPLIFETIME 如何协同工作,并验证客户端确实收到更新。
学习目标
- 为 Actor 开启网络复制并注册需要同步的属性
- 使用
ReplicatedUsing与OnRep在客户端响应新值 - 在 PIE 中验证服务器修改会传播到相关客户端
属性复制需要同时满足三件事
一个 C++ 属性不会因为写了 UPROPERTY() 就自动同步。要让它进入复制流程,需要同时满足 Actor 会复制、属性被标记为可复制,以及 GetLifetimeReplicatedProps 中注册了该属性。
属性复制的方向是服务器到客户端。服务器修改权威值后,网络复制系统会把变化发送给相关连接;客户端收到新值后,再执行对应的 OnRep 回调。客户端自己改本地副本,并不会反向写回服务器。

写一个最小可验证Actor
下面示例创建 AReplicatedStatusActor。把类编译后放进地图,启动多人 PIE。服务器在 BeginPlay 两秒后把 Health 从 100 改为 75,客户端副本收到新值后触发 OnRep_Health。
ReplicatedStatusActor.h:
#pragma once
#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "ReplicatedStatusActor.generated.h"
UCLASS()
class AReplicatedStatusActor : public AActor
{
GENERATED_BODY()
public:
AReplicatedStatusActor();
protected:
virtual void BeginPlay() override;
UPROPERTY(ReplicatedUsing=OnRep_Health, VisibleAnywhere, Category="Network")
float Health = 100.0f;
UFUNCTION()
void OnRep_Health();
void SetHealth(float NewHealth);
void ApplyDemoHealth();
virtual void GetLifetimeReplicatedProps(
TArray<FLifetimeProperty>& OutLifetimeProps
) const override;
};ReplicatedStatusActor.cpp:
#include "ReplicatedStatusActor.h"
#include "Net/UnrealNetwork.h"
#include "TimerManager.h"
AReplicatedStatusActor::AReplicatedStatusActor()
{
bReplicates = true;
}
void AReplicatedStatusActor::BeginPlay()
{
Super::BeginPlay();
if (HasAuthority())
{
FTimerHandle TimerHandle;
GetWorldTimerManager().SetTimer(
TimerHandle,
this,
&AReplicatedStatusActor::ApplyDemoHealth,
2.0f,
false
);
}
}
void AReplicatedStatusActor::ApplyDemoHealth()
{
SetHealth(75.0f);
}
void AReplicatedStatusActor::SetHealth(float NewHealth)
{
if (!HasAuthority())
{
return;
}
Health = FMath::Clamp(NewHealth, 0.0f, 100.0f);
UE_LOG(LogTemp, Log, TEXT("[Server] Health = %.1f"), Health);
}
void AReplicatedStatusActor::OnRep_Health()
{
UE_LOG(LogTemp, Log, TEXT("[Client] Health = %.1f"), Health);
}
void AReplicatedStatusActor::GetLifetimeReplicatedProps(
TArray<FLifetimeProperty>& OutLifetimeProps
) const
{
Super::GetLifetimeReplicatedProps(OutLifetimeProps);
DOREPLIFETIME(AReplicatedStatusActor, Health);
}预期输出:服务器修改属性时出现一条服务器日志,每个收到该 Actor 更新的客户端会出现客户端日志。PIE 实例数量不同,客户端日志条数也会不同。
[Server] Health = 75.0
[Client] Health = 75.0在PIE里确认复制真的生效
将 Actor 放进测试地图后,把 PIE 的玩家数量设置为至少 2,并使用网络多人模式运行。等待两秒,再查看各实例输出日志。服务器应先打印 75,相关客户端随后打印由 OnRep_Health 产生的 75。
如果服务器日志存在而客户端没有 OnRep_Health,优先检查 bReplicates、DOREPLIFETIME 是否缺失,以及 Actor 是否对该连接具有网络相关性。动态 Actor 还应由服务器生成;只在某个客户端本地生成的对象不会自动变成其他机器上的同一个网络 Actor。
复制属性的边界
属性复制适合“需要保持当前值”的状态,例如生命值、门是否开启、队伍编号。客户端晚加入或 Actor 重新变得相关时,仍可以获得服务器当前状态。一次性的声音、粒子触发等瞬时事件则不应仅靠一个长期状态值表达。
不要为了让客户端修改服务器状态而直接写复制属性。正确做法是由 Owning Client 发送 Server RPC 请求,服务器验证后再修改权威属性;修改后的结果再通过复制回到客户端。这样才能同时保留安全边界、状态一致性和迟到客户端的恢复能力。