Unreal C++ Gameplay
Write correct UE5 gameplay C++: the reflection macros that connect C++ to the editor and
Blueprints, the Gameplay Framework class roles, and module dependencies. Targets UE 5.8.
When to use
- Use when creating C++ gameplay classes (
AActor, APawn, ACharacter, AGameModeBase,
UActorComponent), exposing properties/functions with UPROPERTY/UFUNCTION, setting up a
GameMode's default classes, or adding a module dependency in *.Build.cs.
- Use when the project has a
Source/ tree with *.h/*.cpp using UCLASS, and *.Build.cs.
When not to use: designer-facing visual logic → unreal-blueprints. Player input
binding details → unreal-enhanced-input. AI logic → unreal-behavior-trees. This skill owns
the C++ class/reflection foundation those build on.
Core workflow
- Name with the right prefix.
A = Actor-derived, U = UObject/component-derived,
F = plain struct, E = enum, I = interface. The prefix must match the base class.
- Declare the class with reflection macros.
UCLASS() above the class, GENERATED_BODY()
as the first line in the body, and #include "ClassName.generated.h" as the last
include in the header.
- Expose data with
UPROPERTY (editor/Blueprint visibility and garbage-collection
tracking) and behaviour with UFUNCTION (BlueprintCallable, etc.).
- Create components in the constructor with
CreateDefaultSubobject<T>(TEXT("Name")) and
set the RootComponent.
- Know the framework roles:
AGameModeBase sets the rules + default classes; APawn/
ACharacter is the controllable body; APlayerController is the player's will;
UActorComponent is reusable behaviour.
- Add module dependencies to
*.Build.cs (e.g. EnhancedInput) or unresolved-symbol
link errors follow.
- Verify by compiling (Live Coding
Ctrl+Alt+F11 from the editor, or a full build from
the IDE with the editor closed) and checking the class/properties appear in the editor. For
automation tests, run headless with
UnrealEditor-Cmd <Project>.uproject -ExecCmds="Automation RunTest MyGame;Quit"
(RunTest takes a test name, a dotted prefix, or Group:<name>).
Patterns
1. Minimal Actor class (header + source)
// Pickup.h
#pragma once
#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "Pickup.generated.h" // MUST be the last include
UCLASS()
class MYGAME_API APickup : public AActor // MYGAME_API = your module's export macro
{
GENERATED_BODY()
public:
APickup();
// EditAnywhere = tweak per-instance & on the CDO; BlueprintReadWrite = BP get/set.
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Pickup")
int32 ScoreValue = 10;
// UPROPERTY on a UObject* pointer is what keeps it from being garbage-collected.
UPROPERTY(VisibleAnywhere)
TObjectPtr<UStaticMeshComponent> Mesh; // UE5: TObjectPtr instead of raw UStaticMeshComponent*
UFUNCTION(BlueprintCallable, Category = "Pickup")
void Collect();
protected:
virtual void BeginPlay() override;
};
// Pickup.cpp
#include "Pickup.h"
#include "Components/StaticMeshComponent.h"
APickup::APickup()
{
Mesh = CreateDefaultSubobject<UStaticMeshComponent>(TEXT("Mesh"));
RootComponent = Mesh; // the mesh is this actor's root
}
void APickup::BeginPlay() { Super::BeginPlay(); } // always call Super
void APickup::Collect() { Destroy(); }
2. GameMode wiring its default classes
// MyGameMode.cpp — set in the constructor so the engine spawns your classes.
AMyGameMode::AMyGameMode()
{
DefaultPawnClass = AMyCharacter::StaticClass();
PlayerControllerClass = AMyPlayerController::StaticClass();
}
3. Module dependency in Build.cs
// MyGame.Build.cs
PublicDependencyModuleNames.AddRange(new string[]
{
"Core", "CoreUObject", "Engine", "InputCore", "EnhancedInput"
});
Pitfalls
generated.h not last / missing — compile errors like "Cannot find generated header" or
"Expected an include". It must be the final include in the header.
- Forgetting
GENERATED_BODY() — UHT (Unreal Header Tool) errors; it must be the first
thing inside the class body.
- Raw
UObject* without UPROPERTY — the garbage collector doesn't see it and may destroy
it out from under you. Track every UObject pointer with UPROPERTY (use TObjectPtr in UE5).
- Header/UPROPERTY edits with Live Coding — function-body edits are reliable. Structural
changes (new functions, new
UPROPERTYs) rely on Object Reinstancing, which is on by default
but less stable; code that caches pointers to reinstanced objects must refresh them. If the
editor or Blueprints misbehave after such a change, close the editor and build from the IDE.
- Wrong class prefix — naming an Actor
UFoo (or a component AFoo) breaks UHT; match the
prefix to the base type.
- Unresolved external symbol at link — the module providing the API isn't in
Build.cs
PublicDependencyModuleNames.
- Not calling
Super:: in overridden BeginPlay/Tick/etc. skips engine setup.
References
- For
UActorComponent creation/attachment, the UPROPERTY garbage-collection ownership rules
(TObjectPtr, TArray<TObjectPtr<>>, TWeakObjectPtr, holding UObjects from plain C++
classes), and a replication primer, read
references/components-and-gc.md.
- Primary docs: "Unreal Engine CPP Quick Start" and "Gameplay Framework"
(
https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-framework-in-unreal-engine).
Related skills
unreal-blueprints — exposing C++ to designers; BP/C++ interop.
unreal-enhanced-input — binding input in a C++ Pawn/Character.
unreal-behavior-trees — C++ AI tasks driven from a behaviour tree.
1---2name: unreal-cpp-gameplay3description: >4 Write Unreal Engine 5 C++ gameplay code: the UCLASS/UPROPERTY/UFUNCTION reflection macros,5 the Gameplay Framework (GameMode, Pawn, Character, PlayerController, Actor components), and6 the module Build.cs. Use when writing or debugging UE C++, deriving from AActor/ACharacter/7 AGameModeBase, exposing properties to the editor or Blueprints, or when the user mentions8 Unreal C++, UCLASS, GENERATED_BODY, GameMode, ACharacter, or .Build.cs.9metadata:10 source: https://skillmd.com/skills/junmystery/unreal-cpp-gameplay11---1213# Unreal C++ Gameplay1415Write correct UE5 gameplay C++: the reflection macros that connect C++ to the editor and16Blueprints, the Gameplay Framework class roles, and module dependencies. Targets **UE 5.8**.1718## When to use1920- Use when creating C++ gameplay classes (`AActor`, `APawn`, `ACharacter`, `AGameModeBase`,21 `UActorComponent`), exposing properties/functions with `UPROPERTY`/`UFUNCTION`, setting up a22 GameMode's default classes, or adding a module dependency in `*.Build.cs`.23- Use when the project has a `Source/` tree with `*.h`/`*.cpp` using `UCLASS`, and `*.Build.cs`.2425**When *not* to use:** designer-facing visual logic → `unreal-blueprints`. Player input26binding details → `unreal-enhanced-input`. AI logic → `unreal-behavior-trees`. This skill owns27the C++ class/reflection foundation those build on.2829## Core workflow30311. **Name with the right prefix.** `A` = Actor-derived, `U` = `UObject`/component-derived,32 `F` = plain struct, `E` = enum, `I` = interface. The prefix must match the base class.332. **Declare the class with reflection macros.** `UCLASS()` above the class, `GENERATED_BODY()`34 as the first line in the body, and `#include "ClassName.generated.h"` as the **last**35 include in the header.363. **Expose data with `UPROPERTY`** (editor/Blueprint visibility *and* garbage-collection37 tracking) and behaviour with `UFUNCTION` (`BlueprintCallable`, etc.).384. **Create components in the constructor** with `CreateDefaultSubobject<T>(TEXT("Name"))` and39 set the `RootComponent`.405. **Know the framework roles:** `AGameModeBase` sets the rules + default classes; `APawn`/41 `ACharacter` is the controllable body; `APlayerController` is the player's will;42 `UActorComponent` is reusable behaviour.436. **Add module dependencies** to `*.Build.cs` (e.g. `EnhancedInput`) or unresolved-symbol44 link errors follow.457. **Verify** by compiling (Live Coding `Ctrl+Alt+F11` from the editor, or a full build from46 the IDE with the editor closed) and checking the class/properties appear in the editor. For47 automation tests, run headless with48 `UnrealEditor-Cmd <Project>.uproject -ExecCmds="Automation RunTest MyGame;Quit"`49 (`RunTest` takes a test name, a dotted prefix, or `Group:<name>`).5051## Patterns5253### 1. Minimal Actor class (header + source)5455```cpp56// Pickup.h57#pragma once58#include "CoreMinimal.h"59#include "GameFramework/Actor.h"60#include "Pickup.generated.h" // MUST be the last include6162UCLASS()63class MYGAME_API APickup : public AActor // MYGAME_API = your module's export macro64{65 GENERATED_BODY()66public:67 APickup();6869 // EditAnywhere = tweak per-instance & on the CDO; BlueprintReadWrite = BP get/set.70 UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Pickup")71 int32 ScoreValue = 10;7273 // UPROPERTY on a UObject* pointer is what keeps it from being garbage-collected.74 UPROPERTY(VisibleAnywhere)75 TObjectPtr<UStaticMeshComponent> Mesh; // UE5: TObjectPtr instead of raw UStaticMeshComponent*7677 UFUNCTION(BlueprintCallable, Category = "Pickup")78 void Collect();7980protected:81 virtual void BeginPlay() override;82};83```8485```cpp86// Pickup.cpp87#include "Pickup.h"88#include "Components/StaticMeshComponent.h"8990APickup::APickup()91{92 Mesh = CreateDefaultSubobject<UStaticMeshComponent>(TEXT("Mesh"));93 RootComponent = Mesh; // the mesh is this actor's root94}9596void APickup::BeginPlay() { Super::BeginPlay(); } // always call Super97void APickup::Collect() { Destroy(); }98```99100### 2. GameMode wiring its default classes101102```cpp103// MyGameMode.cpp — set in the constructor so the engine spawns your classes.104AMyGameMode::AMyGameMode()105{106 DefaultPawnClass = AMyCharacter::StaticClass();107 PlayerControllerClass = AMyPlayerController::StaticClass();108}109```110111### 3. Module dependency in Build.cs112113```csharp114// MyGame.Build.cs115PublicDependencyModuleNames.AddRange(new string[]116{117 "Core", "CoreUObject", "Engine", "InputCore", "EnhancedInput"118});119```120121## Pitfalls122123- **`generated.h` not last / missing** — compile errors like "Cannot find generated header" or124 "Expected an include". It must be the final include in the header.125- **Forgetting `GENERATED_BODY()`** — UHT (Unreal Header Tool) errors; it must be the first126 thing inside the class body.127- **Raw `UObject*` without `UPROPERTY`** — the garbage collector doesn't see it and may destroy128 it out from under you. Track every UObject pointer with `UPROPERTY` (use `TObjectPtr` in UE5).129- **Header/UPROPERTY edits with Live Coding** — function-body edits are reliable. Structural130 changes (new functions, new `UPROPERTY`s) rely on Object Reinstancing, which is on by default131 but less stable; code that caches pointers to reinstanced objects must refresh them. If the132 editor or Blueprints misbehave after such a change, close the editor and build from the IDE.133- **Wrong class prefix** — naming an Actor `UFoo` (or a component `AFoo`) breaks UHT; match the134 prefix to the base type.135- **Unresolved external symbol at link** — the module providing the API isn't in `Build.cs`136 `PublicDependencyModuleNames`.137- **Not calling `Super::`** in overridden `BeginPlay`/`Tick`/etc. skips engine setup.138139## References140141- For `UActorComponent` creation/attachment, the `UPROPERTY` garbage-collection ownership rules142 (`TObjectPtr`, `TArray<TObjectPtr<>>`, `TWeakObjectPtr`, holding UObjects from plain C++143 classes), and a replication primer, read144 `references/components-and-gc.md`.145- Primary docs: "Unreal Engine CPP Quick Start" and "Gameplay Framework"146 (`https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-framework-in-unreal-engine`).147148## Related skills149150- `unreal-blueprints` — exposing C++ to designers; BP/C++ interop.151- `unreal-enhanced-input` — binding input in a C++ Pawn/Character.152- `unreal-behavior-trees` — C++ AI tasks driven from a behaviour tree.