Home › Unreal Engine (C++) › Unreal Engine multiplayer AGENTS.md

Unreal Engine multiplayer AGENTS.md

AGENTS.md for Unreal Engine 5 multiplayer: authority, replication, RPCs, prediction, and testing with multiple clients.

AGENTS.mdUnreal Engine (C++)

Copy AGENTS.md

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

# AGENTS.md: Unreal multiplayer (UE5)

## Mental model
- The server is authoritative. Clients request actions; the server validates, changes state, and replicates the result.
- Know where each class lives: GameMode (server only), GameState (all), PlayerController (owning client + server), PlayerState (all), Pawn/Character (all, owned by a controller).

## Replication rules
- Actors that replicate set `bReplicates = true` (and `SetReplicateMovement(true)` if needed).
- Replicated properties: `UPROPERTY(ReplicatedUsing=OnRep_Health)` + register in `GetLifetimeReplicatedProps` with `DOREPLIFETIME` (or `DOREPLIFETIME_CONDITION(..., COND_OwnerOnly)`). Put cosmetic reactions in `OnRep_` functions, and call them manually on the server if it needs the same effect.
- Change replicated state only where `HasAuthority()` is true.
- RPCs: `UFUNCTION(Server, Reliable)` for important requests, `Unreliable` for frequent cosmetic ones; `Client` RPCs for owner-only feedback; `NetMulticast` sparingly (cosmetic events). Implement `_Implementation`; validate inputs on the server (rate, range, ownership).
- Server RPCs only work on actors the client owns (its PlayerController, Pawn, or owned actors).
- Never trust client-provided damage, positions, or inventory changes.
- Use Character Movement's built-in prediction; for abilities use GAS prediction instead of custom hacks.
- Keep replication cheap: replicate state, not events; use `NetUpdateFrequency`, relevancy, and dormancy for many actors. Use Iris/push-model only if the project enabled it.

## Testing
Play In Editor with 2+ clients and "Play As Listen Server"/dedicated server, plus network emulation (lag, packet loss). Check the log for replication warnings.