unreal-cpp-gameplay
Write Unreal Engine 5 C++ gameplay code: the UCLASS/UPROPERTY/UFUNCTION reflection macros, the Gameplay Framework (GameMode, Pawn, Character, PlayerController, Actor components), and the module Build.cs. Use when writing or debugging UE C++, deriving from AActor/ACharacter/ AGame
Install
npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills/tree/main/skills/unreal/unreal-cpp-gameplay
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install gamedev-skills-awesome-gamedev-agent-skills@llmmart
git clone https://github.com/gamedev-skills/awesome-gamedev-agent-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole gamedev-skills/awesome-gamedev-agent-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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 withUPROPERTY/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/*.cppusingUCLASS, 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 withUFUNCTION(BlueprintCallable, etc.). - Create components in the constructor with
CreateDefaultSubobject<T>(TEXT("Name"))and set theRootComponent. - Know the framework roles:
AGameModeBasesets the rules + default classes;APawn/ACharacteris the controllable body;APlayerControlleris the player's will;UActorComponentis reusable behaviour. - Add module dependencies to
*.Build.cs(e.g.EnhancedInput) or unresolved-symbol link errors follow. - Verify by compiling (Live Coding
Ctrl+Alt+F11from 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 withUnrealEditor-Cmd <Project>.uproject -ExecCmds="Automation RunTest MyGame;Quit"(RunTesttakes a test name, a dotted prefix, orGroup:<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.hnot 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*withoutUPROPERTY— the garbage collector doesn't see it and may destroy it out from under you. Track every UObject pointer withUPROPERTY(useTObjectPtrin 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 componentAFoo) breaks UHT; match the prefix to the base type. - Unresolved external symbol at link — the module providing the API isn't in
Build.csPublicDependencyModuleNames. - Not calling
Super::in overriddenBeginPlay/Tick/etc. skips engine setup.
References
- For
UActorComponentcreation/attachment, theUPROPERTYgarbage-collection ownership rules (TObjectPtr,TArray<TObjectPtr<>>,TWeakObjectPtr, holding UObjects from plain C++ classes), and a replication primer, readreferences/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.
Files (awesome-gamedev-agent-skills)
-
references
-
components-and-gc.md 4.3 KB
Loading…
-
-
SKILL.md 6.2 KB
--- name: unreal-cpp-gameplay description: > Write Unreal Engine 5 C++ gameplay code: the UCLASS/UPROPERTY/UFUNCTION reflection macros, the Gameplay Framework (GameMode, Pawn, Character, PlayerController, Actor components), and the module Build.cs. Use when writing or debugging UE C++, deriving from AActor/ACharacter/ AGameModeBase, exposing properties to the editor or Blueprints, or when the user mentions Unreal C++, UCLASS, GENERATED_BODY, GameMode, ACharacter, or .Build.cs. --- # 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 1. **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. 2. **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. 3. **Expose data with `UPROPERTY`** (editor/Blueprint visibility *and* garbage-collection tracking) and behaviour with `UFUNCTION` (`BlueprintCallable`, etc.). 4. **Create components in the constructor** with `CreateDefaultSubobject<T>(TEXT("Name"))` and set the `RootComponent`. 5. **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. 6. **Add module dependencies** to `*.Build.cs` (e.g. `EnhancedInput`) or unresolved-symbol link errors follow. 7. **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) ```cpp // 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; }; ``` ```cpp // 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 ```cpp // 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 ```csharp // 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 `UPROPERTY`s) 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.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.