---
title: "The Gameplay Framework"
type: concept
tags: [gameplay-framework, gamemode, playercontroller, pawn, replication]
created: 2026-07-17
updated: 2026-07-17
sources: ["raw/gameplay/gameplay-framework-in-unreal-engine.md", "raw/gameplay/game-mode-and-game-state-in-unreal-engine.md", "raw/gameplay/actors-in-unreal-engine.md", "raw/gameplay/controllers-in-unreal-engine.md"]
confidence: high
---

# The Gameplay Framework

## Definition

The Gameplay Framework is Unreal Engine's collection of cooperating classes that
provide a modular foundation for building a gameplay experience. You pick and
choose the elements right for your game, knowing these classes are designed to
work with and complement one another. Together they define who runs the rules
(the game mode), what the shared and per-player state is (game state and player
state), how a player is represented (a controller possessing a pawn), and what
persists across levels (the game instance).

## How It Works

The classes come to life in a specific order and with distinct lifetimes and
replication behavior:

- **Game Instance** is instantiated on engine launch and remains active until
  the engine shuts down. It is a manager class with no physical presence in the
  game; it tracks data and runs code. It is **not replicated** and exists
  independently on the server and every client. Anything that must persist
  between level loads (for example, a save game system) belongs here. It also
  manages any number of **game instance subsystems** (such as the Online
  Subsystems) that share its lifetime.
- **Game Mode** is instantiated immediately after the level loads and the world
  is created. It is a server-based manager class inherited from the Actor class,
  is the first actor to instantiate on level load, and can be set on a
  map-by-map basis. It sits at the heart of the framework, managing the rules and
  structure of a session and spawning the remaining framework actors — first the
  game state and player state. It is **not persistent across levels**.
- **Game State** and **Player State** are non-physical actors that track the
  state of the game and of individual players, respectively. Both **replicate**
  their state between the authoritative server and all connected clients. Game
  state holds data relevant to all players (team scores, objectives, and a list
  of all players and their player states); player state holds data relevant to
  one player (health, ammo count, inventory). One game state is created by the
  game mode; a player state is created for each player as they join.
- A **player** primarily consists of a **controller** and a **pawn**. The game
  mode spawns players when they join.

Controllers are non-physical actors that possess a pawn to control its actions,
using the `Possess` function and relinquishing it with `Unpossess`. There is by
default a one-to-one relationship between a controller and a pawn. A
`PlayerController` processes input from a human, displays heads-up information,
and possesses physical representations; an `AIController` possesses pawns and
dictates their actions using AI such as behavior trees, state trees, and
navigation. Controllers receive notifications for many events occurring on the
pawn they control, letting them intercept and supersede the pawn's default
behavior.

The **pawn** is the physical manifestation of the player in the world and is the
base class for any actor controllable by a player or AI. Pawns are built from
actor components such as a collision component, static mesh component, and
movement component. The **character** is a pawn-derived subclass adding
feature-rich components: a character movement component, skeletal mesh component,
and capsule component.

Every one of these is an **Actor** (`AActor` in C++) — any object placeable in a
level, supporting translation, rotation, and scaling, spawnable and destroyable
through gameplay code. Actors are containers for **components** and are the unit
of network **replication** for both property values and function calls. The
**World** is the top-level object representing the map in which actors and
components exist, holding the persistent level plus the game state, game mode,
and lists of pawns and controllers currently on the map.

## Key Parameters

- **`AActor`** — base class of all Actors; parent of Pawn, Controller, Game Mode,
  Game State, Player State, HUD, Camera, and more.
- **`AGameModeBase`** — base class for all game modes; the streamlined default in
  new code projects. Common overrides include `InitGame`, `PreLogin`,
  `PostLogin`, `HandleStartingNewPlayer`, `RestartPlayer`,
  `SpawnDefaultPawnAtTransform`, and `Logout`.
- **`AGameMode`** — subclass of `AGameModeBase` adding a match state machine for
  multiplayer; pair it with `AGameState`.
- **`AGameStateBase`** — base game state; exposes `GetServerWorldTimeSeconds`,
  the `PlayerArray` of all `APlayerState` objects, and `HasBegunPlay`.
- **Player State** — per-player data (`APlayerState`), created per player on join.
- **Game Instance** / **Game Instance Subsystem** — engine-lifetime managers;
  not replicated.
- **HUD** — base object for elements overlaid on the screen; every
  human-controlled player has its own instance drawing to its viewport.
- **Gameplay Statics** — static class for common game functions (playing sounds,
  spawning actors, applying damage, getting the player pawn or player controller).

## When To Use

Use the Gameplay Framework as the backbone of essentially any UE game. Reach for
the **game mode** to define rules (player counts, spawn/respawn behavior,
pausing, level transitions) and to specify which pawn, HUD, controller,
spectator, game state, and player state classes to use. Store globally-visible,
game-wide, changing data on the **game state**; store per-player data on the
**player state**. Put anything that must survive level travel on the **game
instance**. Most classes can be customized in C++, Blueprint, or a combination.

## Risks & Pitfalls

- **The game mode exists only on the server** and is not replicated. Clients see
  only the stock class, not the live instance or its variables. Route
  client-visible information through the replicated game state instead.
- Because the game mode is created on level load, it is **not persistent across
  levels** — do not store cross-level data there; use the game instance.
- Don't keep player-specific data (like one player's score) on the game state;
  the player state handles that more cleanly.
- If you inherit from `AGameMode` for match-state behavior, remember to also
  inherit your game state from `AGameState`.

## Related Concepts

- [[concepts/actors-and-components]]
- [[concepts/input-system]]
- [[concepts/physics-and-collision]]
- [[concepts/cameras-and-ui]]
- [[syntheses/choosing-gameplay-systems]]

## Sources

- raw/gameplay/gameplay-framework-in-unreal-engine.md
- raw/gameplay/game-mode-and-game-state-in-unreal-engine.md
- raw/gameplay/actors-in-unreal-engine.md
- raw/gameplay/controllers-in-unreal-engine.md