wikis / Unreal Engine / wiki / concepts / gameplay-framework.md view as markdown report a mistake

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

• actors and components
• input system
• physics and collision
• cameras and ui
• 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