104 added, 40 removed. Audit A to A.
---
name: unreal-multiplayer
group: Unreal
description: >-
Build Actor replication, GameMode/GameState architecture and server-authoritative gameplay. Use
when building Unreal networking, actor replication, or RPCs.
---
- # Unreal Multiplayer
- Build Actor replication, GameMode/GameState architecture and server-authoritative gameplay..
+ # unreal-multiplayer
- ## Process
+ ## Core Philosophy
+ Unreal Engine was built from its inception in 1998 as a multiplayer tournament engine. Networking in Unreal is deeply opinionated: it centers around a strict **Server-Authoritative Client-Server architecture** orchestrated by the GameMode, GameState, PlayerState, and PlayerController classes. The server runs the definitive physical simulation; clients are visual and audio playback terminals that send player intent. Master Unreal multiplayer by understanding the Actor Replication lifecycle, property replication with `DOREPLIFETIME`, and the strict division between Multicast, Client, and Server RPCs.
- 1. **Intake & Scope Definition**
- - Identify specific objectives, inputs, constraints, and operational context.
- - Inspect existing project documentation, configurations, or relevant repository assets.
+ ---
- 2. **Analysis & Strategic Formulation**
- - Evaluate options against best practices, security posture, and domain requirements.
- - Deconstruct complex components into discrete, actionable phases.
+ ## 4-Step Unreal Multiplayer Architecture
- 3. **Execution & Synthesis**
- - Produce structured, production-grade deliverables matching the required format.
- - Ground all recommendations in concrete project evidence rather than abstract generalities.
+ ### Step 1: The Core Gameplay Framework Classes
+ 1. **GameMode (Server Only)**:
+ - Exists exclusively on the authoritative server. Defines match rules, win conditions, player spawning (`SpawnDefaultPawnAtTransform`), and score tracking. Never replicated to clients.
+ 2. **GameState (Server $\to$ All Clients)**:
+ - Replicated to all machines. Tracks match state (Round time, Team scores, Match phase: *WaitingToStart, InProgress, PostMatch*).
+ 3. **PlayerState (Server $\to$ All Clients)**:
+ - Replicated to all machines. Tracks individual player attributes (Player Name, Ping, Kills, Current Score).
+ 4. **PlayerController (Server $\leftrightarrow$ Owning Client)**:
+ - Exists on the server and the *specific owning client*. Handles input translation, UI HUD management, and secure Server RPC communication.
- 4. **Review & Refinement**
- - Validate against the verification checklist and domain edge cases.
- - Highlight open questions, explicit trade-offs, and next milestones.
+ ### Step 2: Actor & Property Replication (`DOREPLIFETIME`)
+ 1. **Actor Replication Setup**:
+ - `bReplicates = true` in constructor.
+ - `SetReplicateMovement(true)` for physical actors.
+ 2. **Replicated Properties (`ReplicatedUsing`)**:
+ - Replicate variables using `UPROPERTY(ReplicatedUsing = OnRep_Health)`.
+ - Implement `GetLifetimeReplicatedProps`:
+ ```cpp
+ void ACharacterBase::GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const {
+ Super::GetLifetimeReplicatedProps(OutLifetimeProps);
+ DOREPLIFETIME(ACharacterBase, Health);
+ DOREPLIFETIME_CONDITION(ACharacterBase, SecretInventory, COND_OwnerOnly);
+ }
+ ```
+ 3. **RepNotify Functions**:
+ - `OnRep_Health()` executes automatically on clients whenever the server updates `Health`.
- ## Deliverable & Output Format
+ ### Step 3: Remote Procedure Call (RPC) Classification
+ 1. **Server RPC (`Server, Reliable, WithValidation`)**:
+ - Called by Owning Client $\to$ Executed on Server.
+ - Must implement `_Validate` (Security gate) and `_Implementation`:
+ ```cpp
+ bool AWeapon::ServerFire_Validate(FVector AimDir) { return AimDir.IsNormalized(); }
+ void AWeapon::ServerFire_Implementation(FVector AimDir) { /* Authoritative Fire */ }
+ ```
+ 2. **Client RPC (`Client, Reliable`)**:
+ - Called by Server $\to$ Executed on Owning Client only (e.g. *ClientShowHitMarker*).
+ 3. **NetMulticast RPC (`NetMulticast, Unreliable`)**:
+ - Called by Server $\to$ Executed on Server and *all* simulated clients (e.g. *MulticastPlayExplosionFX*).
- ### 📋 Executive Summary
- - **Objective:** Key goal addressed
- - **Status:** Complete / Action Required
- - **Primary Recommendation:** Core actionable conclusion
+ ### Step 4: Network Relevancy & Dormancy Optimization
+ 1. **Network Relevancy (`IsNetRelevantFor`)**:
+ - Actors beyond view distance or hidden behind terrain are not replicated to distant clients, conserving network bandwidth.
+ 2. **Net Dormancy (`DORM_DormantAll`)**:
+ - Static or rarely changing world actors (chests, switches) are set dormant until an event wakes them up, saving server tick budget.
- ### 🛠️ Detailed Implementation / Analysis
- - Concrete technical, operational, or strategic specifications.
- - Clear code, configuration, or documentation blocks where applicable.
+ ---
- ### 📌 Decisions & Next Steps
- - [ ] Immediate action items with designated owners.
- - [ ] Required dependencies or prerequisite milestones.
+ ## Deliverable Format: Authoritative Server-Validated Weapon Firing (C++)
- ## Instructions & Operating Rules
+ ```cpp
+ // Weapon.h
+ #pragma once
+ #include "CoreMinimal.h"
+ #include "GameFramework/Actor.h"
+ #include "Weapon.generated.h"
- - Lead directly with actionable findings and structured results.
- - Never introduce speculative abstractions or unrequested complexity.
- - Maintain consistency with existing architecture and naming conventions.
- - Provide explicit rationales for non-obvious trade-offs.
+ UCLASS()
+ class AWeapon : public AActor {
+ GENERATED_BODY()
- ## Verification & Quality Checklist
+ public:
+ AWeapon();
- - [ ] Deliverable directly satisfies all stated user requirements and criteria.
- - [ ] Edge cases, boundary conditions, and error states are addressed.
- - [ ] Output contains zero placeholder tokens, broken references, or unverified claims.
- - [ ] All cross-references and formatting comply with repository conventions.
+ UPROPERTY(ReplicatedUsing = OnRep_AmmoCount, BlueprintReadOnly)
+ int32 AmmoCount;
- ## Anti-Patterns & Constraints
+ UFUNCTION()
+ void OnRep_AmmoCount();
- - **NEVER** output generic boilerplate without grounding in specific project inputs.
- - **NEVER** silently omit unresolved contradictions or unverified assumptions.
- - **NEVER** make unrequested modifications outside the stated deliverable boundary.
+ UFUNCTION(Server, Reliable, WithValidation)
+ void ServerFire(FVector_NetQuantize TraceStart, FVector_NetQuantizeNormal AimDir);
+
+ UFUNCTION(NetMulticast, Unreliable)
+ void MulticastSpawnMuzzleFX();
+
+ protected:
+ virtual void GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const override;
+ };
+ ```
+
+ ---
+
+ ## Worked Example: Mitigating Dedicated Server Bandwidth Saturation
+
+ - **Context**: A 32-player Unreal shooter was experiencing severe packet drops and server tick degradation down to 14 Hz during firefights.
+ - **Diagnosis**: Using `NetProfile` and `Network Insights`, engineers discovered weapon firing was using `Reliable` NetMulticast RPCs and replicating unquantized 64-bit vector coordinates 30 times per second.
+ - **Optimization**:
+ 1. Converted `FVector` to `FVector_NetQuantize` (16-bit integer compression).
+ 2. Changed cosmetic FX RPCs from `Reliable` to `Unreliable`.
+ 3. Activated Net Dormancy on 800 static interactive loot containers in the map.
+ - **Outcome**: Server bandwidth per client decreased by 68%; server tick rate stabilized at 60 Hz.
+
+ ---
+
+ ## Verification Checklist
+
+ - [ ] GameMode contains zero client-side logic and is never accessed from client HUDs.
+ - [ ] All Server RPCs implement `_Validate()` security checks to prevent packet injection.
+ - [ ] `DOREPLIFETIME_CONDITION` used to prevent sending private data (e.g. inventory) to non-owners.
+ - [ ] Cosmetic effects transmitted via `Unreliable` Multicast RPCs.
+ - [ ] Net Relevancy distance and Net Dormancy configured for large maps.
+
+ ---
+
+ ## Anti-Patterns
+
+ - **Calling Server RPCs on Un-Owned Actors**: Invoking a Server RPC from a client on an Actor that is not possessed or owned by that client's PlayerController (fails silently).
+ - **Using Reliable RPCs for Frequent Ticks**: Marking high-frequency weapon fire or footstep RPCs as `Reliable`, causing TCP-style packet queues when latency spikes.
+ - **Accessing `AGameMode` on Clients**: Writing `GetWorld()->GetAuthGameMode()` inside client UI widgets, which returns `nullptr` on non-server machines.