Ue Networking Replication

UE Networking & Replication

Target engine: UE 5.8. APIs below are verified against the 5.8 headers; older forms are listed under "Deprecated — do not use".

Server-authoritative replication for actors, components and subobjects. Core APIs live in the Engine module (GameFramework/Actor.h, Engine/NetDriver.h, Net/UnrealNetwork.h) and the NetCore module (Net/Core/PushModel/PushModel.h, Net/Serialization/FastArraySerializer.h). ELifetimeCondition and REPNOTIFY_* come from CoreUObject (UObject/CoreNetTypes.h). Optional systems: the Iris replication system (IrisCore module, SetupIrisSupport(Target) in Build.cs) and the ReplicationGraph plugin (Beta in 5.8, Build.cs module ReplicationGraph).

Context

Read .agents/ue-project-context.md if it exists (module names, conventions, enabled plugins, GAS/networking setup). Do not stop if it is missing.

Identify the area from the request and the codebase. Ask only when two plausible readings would produce different code.

Worked end-to-end examples: replication patterns. RPC selection tables and verbatim engine RPC declarations: RPC decision guide.

Net Roles, Net Modes and Authority

ENetRole is declared in Engine/Classes/Engine/EngineTypes.h; the accessors are on AActor.

ROLE_None            // not replicated
ROLE_SimulatedProxy  // remote copy driven by replicated state
ROLE_AutonomousProxy // remote copy of the locally controlled pawn/controller
ROLE_Authority       // owns and may mutate this actor

From GameFramework/Actor.h:

ENetRole GetLocalRole() const;
ENetRole GetRemoteRole() const;
bool HasAuthority() const;
ENetMode GetNetMode() const;
bool IsNetMode(ENetMode Mode) const;

ENetMode (Engine/Classes/Engine/EngineBaseTypes.h): NM_Standalone, NM_DedicatedServer, NM_ListenServer, NM_Client. Every mode below NM_Client is a server.

On a listen server the host is ROLE_Authority and locally controlled: use APawn::IsLocallyControlled() to skip host-only or client-only paths.

Property Replication

// MyReplicatedActor.h
#pragma once

#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "MyReplicatedActor.generated.h"

UCLASS()
class MYGAME_API AMyReplicatedActor : public AActor
{
    GENERATED_BODY()

public:
    AMyReplicatedActor();

    virtual void GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const override;

protected:
    UPROPERTY(ReplicatedUsing = OnRep_Health)
    float Health = 100.f;

    UPROPERTY(Replicated)
    int32 TeamId = 0;

    UFUNCTION()
    void OnRep_Health(float PreviousHealth);
};

// MyReplicatedActor.cpp
#include "MyReplicatedActor.h"
#include "Net/UnrealNetwork.h"

AMyReplicatedActor::AMyReplicatedActor()
{
    bReplicates = true;                     // or SetReplicates(true) at runtime
    SetReplicateMovement(true);
    SetNetUpdateFrequency(10.f);            // replication considerations per second
    SetMinNetUpdateFrequency(2.f);          // throttled floor when nothing changes
    SetNetCullDistanceSquared(225000000.f); // 150 m squared
    NetPriority = 1.f;                      // still a public field in 5.8
}

void AMyReplicatedActor::GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const
{
    Super::GetLifetimeReplicatedProps(OutLifetimeProps); // never omit
    DOREPLIFETIME(AMyReplicatedActor, Health);
    DOREPLIFETIME_CONDITION(AMyReplicatedActor, TeamId, COND_InitialOnly);
}

void AMyReplicatedActor::OnRep_Health(float PreviousHealth)
{
    // Clients only. Must be idempotent: relevancy changes re-fire it.
}

Rules:

• OnRep_ must be a UFUNCTION(). Its optional single parameter is the previous value and must match the property type.
• Only the authority may write a replicated property. OnRep_ does not fire on the machine that made the change.
• UPROPERTY(NotReplicated) inside a replicated struct excludes a member.
• FVector_NetQuantize / _NetQuantize10 / _NetQuantize100 / _NetQuantizeNormal (Engine/NetSerialization.h) cut world-position bandwidth: 0, 1 and 2 decimal places, and 16 bits per component for normals.
• FRepMovement (Engine/Classes/Engine/ReplicatedState.h) carries location/rotation/velocity when SetReplicateMovement(true); override virtual void OnRep_ReplicatedMovement() to post-process it. UCharacterMovementComponent replicates moves itself — see ue-character-movement.
• On the first bunch for a connection, every eligible property is sent at once. Keep initial state small and push spawn-only data behind COND_InitialOnly.

Macros (Net/UnrealNetwork.h): DOREPLIFETIME, DOREPLIFETIME_CONDITION, DOREPLIFETIME_CONDITION_NOTIFY, DOREPLIFETIME_WITH_PARAMS, DOREPLIFETIME_WITH_PARAMS_FAST, DOREPLIFETIME_WITH_PARAMS_FAST_STATIC_ARRAY, DOREPLIFETIME_ACTIVE_OVERRIDE, DOREPLIFETIME_ACTIVE_OVERRIDE_FAST, DISABLE_REPLICATED_PROPERTY.

FDoRepLifetimeParams (Net/UnrealNetwork.h) is the struct behind the _WITH_PARAMS forms:

ELifetimeCondition Condition = COND_None;
ELifetimeRepNotifyCondition RepNotifyCondition = REPNOTIFY_OnChanged; // or REPNOTIFY_Always
bool bIsPushBased = false;

Lifetime Conditions

Full ELifetimeCondition enum, CoreUObject/Public/UObject/CoreNetTypes.h:

COND_NetGroup pairs with UE::Net::FNetConditionGroupManager (Net/Core/Misc/NetConditionGroupManager.h, module NetCore), reached through UNetworkSubsystem::GetNetConditionGroupManager() (Net/Subsystems/NetworkSubsystem.h):

#include "Net/Core/Misc/NetConditionGroupManager.h"
#include "Net/Subsystems/NetworkSubsystem.h"

AddReplicatedSubObject(MySubObject, COND_NetGroup); // on the owning actor/component
UNetworkSubsystem* NetSubsystem = GetWorld()->GetSubsystem<UNetworkSubsystem>();
NetSubsystem->GetNetConditionGroupManager().RegisterSubObjectInGroup(MySubObject, FName("RedTeam"));
MyPlayerController->IncludeInNetConditionGroup(FName("RedTeam"));

UE::Net::NetGroupOwner and UE::Net::NetGroupReplay are engine-managed groups; do not add a player controller to them. APlayerController also exposes RemoveFromNetConditionGroup, IsMemberOfNetConditionGroup and GetNetConditionGroups.

Push Model

Push model removes the per-frame memcmp of replicated properties: the property is only compared when you mark it dirty. It works with the classic net driver and with Iris — it is not an Iris feature.

// MyPushActor.cpp
#include "MyPushActor.h"
#include "Net/UnrealNetwork.h"
#include "Net/Core/PushModel/PushModel.h"

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

    FDoRepLifetimeParams Params;
    Params.bIsPushBased = true;
    Params.Condition = COND_OwnerOnly;
    DOREPLIFETIME_WITH_PARAMS_FAST(AMyPushActor, Ammo, Params);
}

void AMyPushActor::ConsumeAmmo(int32 Count)
{
    if (!HasAuthority())
    {
        return;
    }
    Ammo -= Count;
    MARK_PROPERTY_DIRTY_FROM_NAME(AMyPushActor, Ammo, this);
}

• MARK_PROPERTY_DIRTY_FROM_NAME(ClassName, PropertyName, Object) is the preferred marker. Static arrays use MARK_PROPERTY_DIRTY_FROM_NAME_STATIC_ARRAY_INDEX(ClassName, PropertyName, ArrayIndex, Object) or MARK_PROPERTY_DIRTY_FROM_NAME_STATIC_ARRAY(ClassName, PropertyName, Object).
• Opt in twice: bWithPushModel = true; in the game/server *.Target.cs (defaults to true only for Editor targets, TargetRules.cs:1524) and Net.IsPushModelEnabled=1 (defaults to false, PushModel.cpp:434). Until both are on, properties are compared as usual.
• The macros compile to nothing when WITH_PUSH_MODEL is off, so the code is always safe to ship (exception: the no-push MARK_PROPERTY_DIRTY_FROM_NAME_STATIC_ARRAY stub takes 4 arguments, PushModel.h:489, so the 3-argument form fails to compile there).
• A struct property mutated by reference needs an accessor that marks it dirty before handing out the reference.
• With push model enabled, forgetting one marker means the property silently stops replicating — this is the main cost of opting in.

Fast Array Serialization

FFastArraySerializer sends only changed items instead of the whole array.

#include "Net/Serialization/FastArraySerializer.h"   // module NetCore

Item struct derives from FFastArraySerializerItem and may implement any of:

void PreReplicatedRemove(const struct FMyItemArray& InArraySerializer);
void PostReplicatedAdd(const struct FMyItemArray& InArraySerializer);
void PostReplicatedChange(const struct FMyItemArray& InArraySerializer);

The array struct derives from FFastArraySerializer, implements NetDeltaSerialize via FastArrayDeltaSerialize<ItemType, ArrayType>(Items, DeltaParms, *this), and needs TStructOpsTypeTraits<...> { WithNetDeltaSerializer = true }. It may also implement the array-level receive hook:

void PostReplicatedReceive(const FFastArraySerializer::FPostReplicatedReceiveParameters& Parameters);

FPostReplicatedReceiveParameters::OldArraySize is the size before the update, which makes this the right place for "the whole list changed, rebuild the UI" work.

Dirty rules — both are mandatory, and both are common sources of "my array does not replicate":

• MarkItemDirty(Item) after adding or mutating an item.
• MarkArrayDirty() after removing an item (it also invalidates the ID map).

Full inventory implementation: replication patterns, Pattern 3.

Remote Procedure Calls

UFUNCTION network specifiers (UObject/ObjectMacros.h): Server, Client, NetMulticast, Reliable, Unreliable, WithValidation, BlueprintAuthorityOnly, BlueprintCosmetic. Reliable/Unreliable are only valid together with Server, Client or NetMulticast.

// Client calls, server executes. WithValidation generates the _Validate pair.
UFUNCTION(Server, Reliable, WithValidation)
void ServerFireWeapon(FVector_NetQuantize Origin, FVector_NetQuantizeNormal Direction);

// Server calls, the owning client executes.
UFUNCTION(Client, Reliable)
void ClientShowKillConfirm(int32 VictimId);

// Server calls, server and every client with this actor relevant execute.
UFUNCTION(NetMulticast, Unreliable)
void MulticastPlayHitEffect(FVector_NetQuantize ImpactPoint);

You write _Implementation bodies; with WithValidation you also write _Validate, and returning false disconnects the caller.

Decision tables, reliability matrices and verbatim PlayerController.h declarations: RPC decision guide.

Ownership, Relevancy and Dormancy

Weapon->SetOwner(OwningPlayerController);   // server only; drives RPC routing and COND_OwnerOnly

Relevancy fields and hooks on AActor:

bAlwaysRelevant = true;       // ignore distance culling
bOnlyRelevantToOwner = true;  // owner connection only

virtual bool IsNetRelevantFor(const AActor* RealViewer, const AActor* ViewTarget, const FVector& SrcLocation) const override;
virtual float GetNetPriority(const FVector& ViewPos, const FVector& ViewDir, AActor* Viewer, AActor* ViewTarget, UActorChannel* InChannel, float Time, bool bLowBandwidth) override;

SetNetCullDistanceSquared() sets the squared radius; NetPriority breaks ties when bandwidth saturates; GetReplayPriority() does the same for replay recording.

Dormancy (ENetDormancy in EngineTypes.h: DORM_Never, DORM_Awake, DORM_DormantAll, DORM_DormantPartial, DORM_Initial):

NetDormancy = DORM_Initial;        // constructor: map-placed actors start dormant
SetNetDormancy(DORM_DormantAll);   // runtime
FlushNetDormancy();                // push one update, then return to dormant

A waking dormant actor is diffed against the replicator the connection kept when it went dormant (DataChannel.cpp:2510-2519), so normally only changes are sent; an actor whose channel closed on relevancy gets a full initial bunch when it re-enters range, which fires its OnRep_s again. Write OnRep_ handlers that tolerate repeats.