Unreal Gameplay Framework, Replication & Packaging

Unreal Gameplay Framework and Packaging

Unreal Engine provides a gameplay framework: a set of classes with defined responsibilities — who owns the rules, who represents the player, what is replicated to clients, what persists between levels. Teams that follow it get multiplayer, level transitions, and input handling with relatively little code; teams that fight it end up with rules on clients, state that vanishes on travel, and logic that works in the editor but not online.

Shipping adds a second layer of surprises. A packaged build is cooked, stripped of editor-only code, and loads only the assets that were cooked — so missing soft references, editor-only dependencies, and configuration differences appear only after packaging. This page covers the framework's responsibilities, replication basics, asset references, and how to package and diagnose builds.

TL;DR

GameMode holds rules on the server only; GameState and PlayerState replicate shared state to everyone.
PlayerController represents the player's intent and input; Pawns/Characters are the bodies it possesses.
The server is authoritative: replicate properties (with RepNotify), call Server RPCs for requests, and validate everything.
Use Enhanced Input for input and consider the Gameplay Ability System for abilities, effects, and attributes.
Prefer soft references and the Asset Manager for large or optional content; make sure everything needed is cooked.
Package with BuildCookRun, test Development and Shipping builds, and read packaged logs and crash reports when behavior differs from the editor.

Quick Example

A replicated health component: only the server changes health, clients react through RepNotify:

Packaging a Shipping build from the command line:

Core Concepts

Framework Classes

A common error is putting rules or shared state in the GameMode and reading it from clients, where it does not exist.

Replication

The server is authoritative. Clients send requests; the server decides and replicates results.

Reliable RPCs are guaranteed but can back up under load; use unreliable for frequent cosmetic events. Ownership decides which client may call Server RPCs on an actor, and relevancy and priority decide which actors replicate to which clients. See Multiplayer Netcode.

Input and Abilities

Enhanced Input maps physical inputs to input actions through mapping contexts, supporting remapping and context changes. The Gameplay Ability System (GAS) provides abilities, gameplay effects, attributes, tags, and prediction — powerful for games with many abilities and status effects, with a learning curve that pays off at scale.

Asset References

Hard-reference chains can load half the game when one Blueprint loads. Soft references fix memory but must be included in cooking — through the Asset Manager, primary asset rules, or directories to cook — or they will be missing in packaged builds. Use the Reference Viewer and Size Map to inspect dependencies. See Game Asset Pipelines.

Packaging and Diagnostics

When something works in the editor but not in a packaged build, check:

Missing cooked assets: soft references or dynamically loaded paths not cooked.
Editor-only code: logic inside WITH_EDITOR blocks or editor-only modules.
Configuration: settings in editor-only config files or platform-specific .ini overrides.
Plugins not enabled for the target platform.
Logs and crashes: the packaged game writes logs to its Saved/Logs folder; archive symbols to symbolicate crash reports.

Automate packaging in CI with BuildGraph or RunUAT and run smoke tests on packaged builds. See Game Builds, Distribution, and Live Operations.

Best Practices

Put Logic Where the Framework Expects It

Rules in GameMode, shared state in GameState and PlayerState, intent in PlayerController, behavior in components.

Keep the Server Authoritative

Change gameplay state only on the server, validate RPC inputs, and use RepNotify for client reactions.

Manage References Deliberately

Prefer soft references for heavy content, audit hard-reference chains, and configure cooking rules.

Package Early and Often

Build and test packaged Development and Shipping builds continuously, not just before release.

Common Mistakes

Reading GameMode on Clients

Trusting Client RPCs

Soft References Not Cooked

FAQ

What is the difference between GameMode and GameState?

GameMode defines the rules and exists only on the server. GameState holds match state that is replicated to all clients so everyone can read it.

How does replication work in Unreal?

The server owns gameplay state; properties marked as replicated are sent to relevant clients when they change, RepNotify functions run on clients when values arrive, and RPCs send requests and events between server and clients.

What is the Gameplay Ability System?

An Unreal framework for abilities, gameplay effects, attributes, and tags with network prediction, commonly used in games with many abilities and status effects.

Why does my game work in the editor but not when packaged?

Often because assets referenced softly or by path were not cooked, editor-only code or configuration was used, or a plugin is not enabled for the platform. Check packaged logs and cooking rules.

What is BuildCookRun?

An Unreal Automation Tool command that compiles, cooks content, stages, packages, and optionally archives and runs a build for a target platform and configuration.