The Gameplay Framework

2. Designed for Multiplayer From Day One

Unreal's gameplay framework descends directly from Unreal Tournament — a competitive online shooter. Its networking model was baked in from the start, and it shapes the design of every class on this page, even if your game is single-player. Three rules explain it:

Rule 1 — the server is the authority

One machine — the server — owns the true state of the game. Clients are, in effect, sophisticated viewers: they render the replicated state they receive and send input. A client never decides "I hit him for 50 damage"; it asks, and the server decides. This is what stops cheating and keeps every player's world consistent. Single-player and play-in-editor are just a listen server with one local player — the same machinery runs, with the network latency set to zero. That's why the framework looks identical either way, and why netcode bugs hide until you actually test with two clients.

Rule 2 — replication flows one way: server → clients

Actors and properties marked for replication are copied from the server to clients, automatically, whenever they change. Clients cannot push a replicated value back — if a client writes to a replicated variable, only its local copy changes, and the next server update overwrites it.

Rule 3 — RPCs are the only conversation across the wire

Besides replicated state, the only way code on one machine can make something happen on another is a remote procedure call — a UFUNCTION tagged with where it should run:

// Replicated state: server writes, every client receives. One-way.
UPROPERTY(Replicated)               // or ReplicatedUsing=OnRep_Health for a change callback
float Health;

// RPCs — the three directions:
UFUNCTION(Server, Reliable)         // client asks the server to do something
void ServerFireWeapon();

UFUNCTION(Client, Reliable)         // server tells one owning client something private
void ClientShowHitMarker();

UFUNCTION(NetMulticast, Unreliable) // server broadcasts a cosmetic event to everyone
void MulticastPlayExplosion();

Now the framework's class splits stop looking arbitrary and start looking inevitable:

• GameMode is server-only because it is the authority: it holds the rules, spawn logic, and win conditions — exactly the things clients must never be able to read or tamper with.
• GameState and PlayerState exist purely as the replicated, readable mirrors of the facts clients do need — the scoreboard, the timer, everyone's names. They are the GameMode's public noticeboard.
• PlayerController is each player's private channel: it exists on the owning client and the server, and nowhere else. It's where input becomes Server RPCs, and where the server sends private replies.

3. The Cast at a Glance

The reference table. Each class gets a deeper section below; the "Exists on" column is the one to memorise.

The order these objects get created in — and where in that sequence your players spawn — is charted in the Execution Order guide §11.

4. GameMode & GameState — Rules vs Scoreboard

AGameModeBase is the referee. It runs only on the server and answers the authority-only questions: may this player join (PreLogin)? What pawn class do they get, and where does it spawn (RestartPlayer, spawn points)? Has someone won? It's also the registry for the rest of the cast — one GameMode subclass picks the whole team:

AMyGameMode::AMyGameMode()
{
    DefaultPawnClass      = AMyCharacter::StaticClass();
    PlayerControllerClass = AMyPlayerController::StaticClass();
    GameStateClass        = AMyGameState::StaticClass();
    PlayerStateClass      = AMyPlayerState::StaticClass();
    HUDClass              = AMyHUD::StaticClass();
}

Which GameMode runs is set in Project Settings → Maps & Modes (the default) or overridden per-map in World Settings — which is how your menu level runs a different GameMode than your gameplay levels.

AGameStateBase is the scoreboard: the GameMode's decisions, published. It replicates to every client and carries the match facts everyone renders — elapsed time, match phase, team scores — plus PlayerArray, the replicated list of every player's PlayerState (the only way a client can enumerate who's in the match). It also provides server-synchronised time via GetServerWorldTimeSeconds(). The division of labour: GameMode decides, GameState displays.

5. PlayerController & PlayerState — One Human, Two Objects

Each human connected to the game is represented by a pair of actors that both outlive any particular pawn: a private one and a public one.

APlayerController is the player's will — the persistent, private half:

• Turns input into actions, owns the camera (PlayerCameraManager), and is the usual owner of UMG widgets — HUD and menus are per-player concerns.
• Exists only on the owning client and the server. Other players' machines have no copy of your controller at all — you cannot iterate "all PlayerControllers" on a client and expect more than your own.
• Is the client's voice: gameplay requests travel as Server RPCs on the PlayerController (or on the pawn it owns), because it's the actor the connection owns.
• Survives pawn death. When your character dies, the controller stays connected and simply possesses the next body (§6).

APlayerState is the player's public record — the replicated half everyone can see:

• Name (GetPlayerName()), score, ping, team — the scoreboard row for one player.
• Replicated to every client, and listed for everyone in GameState->PlayerArray.
• The right home for any per-player fact that must survive respawns and be visible to other players: kills, deaths, character selection, ready status.

One more split-screen wrinkle: on a single machine, each local human is a ULocalPlayer (owned by the GameInstance) that pairs up with one PlayerController in the current world. You'll mostly meet it as the thing CreateWidget and Enhanced Input subsystems hang off.

6. Pawns and Possession

A APawn is a body: an actor that can be possessed by a controller and driven around the world. The controller–pawn split is the framework's cleanest idea — the mind is persistent, the body is disposable:

// Respawn, on the server: new body, same mind.
APawn* NewPawn = GetWorld()->SpawnActor<APawn>(PawnClass, SpawnTransform);
Controller->Possess(NewPawn);   // old pawn (if any) is unpossessed first

• Possession is a server decision — Possess() only works with authority. The GameMode's RestartPlayer() does exactly the snippet above for you at spawn time.
• NPCs use the same machinery with an AAIController possessing the pawn instead of a player.
• The pawn replicates to everyone (people need to see your character), but only the owning client sends input for it. Whether to derive from Pawn or ACharacter — which adds walking, jumping and networked movement — is covered in Core Classes §6.

The exact callback sequence when possession happens (and which side each callback runs on) is charted in the Execution Order guide §12.

7. GameInstance & World — The Containers

UGameInstance is the outermost box: one per running process, created before any level and destroyed only when the game quits. Everything else on this page is torn down and rebuilt when you change levels — the GameInstance is what survives the trip. That makes it the home for settings, the party you formed in the menu, save-game handles, and long-lived services. For those services, prefer subclassing UGameInstanceSubsystem over stuffing the GameInstance itself — subsystems are auto-created per GameInstance and keep systems decoupled. Note it is local: the server and every client each have their own, and nothing in it replicates.

UWorld is the loaded map: the container all the framework actors live in (GameMode, controllers, states, pawns — everything except GameInstance). One world is current at a time in a running game, but more exist than you'd think: the editor viewport is a world, and each play-in-editor client is another. That's why engine code is scrupulous about GetWorld() instead of any global — "which world am I in?" has more than one answer, especially during PIE. Level travel replaces the current world wholesale; anything you need on the far side goes in the GameInstance.

8. Where Should This Variable Live?

The practical payoff of the whole framework. Classify the fact, and the class picks itself:

9. Common Gotchas