# 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.