gamedev-skills/awesome-gamedev-agent-skills / skills/unreal/unreal-cpp-gameplay
unreal-cpp-gameplay
VerifiedUnreal Engine 5 (UE 5.8) C++ gameplay code: UCLASS and UPROPERTY reflection, the Gameplay Framework, GC-safe pointers, Build.cs and command-line builds. Use for GENERATED_BODY, Live Coding, "unresolved external symbol" or UHT errors. Not for Blueprints (`unreal-blueprints`), Enhanced Input (`unreal-enhanced-input`) or packaging (`unreal-packaging`); engine source builds are out of scope.
Unreal C++ Gameplay
Write UE5 gameplay C++ that compiles the first time, survives garbage collection and is testable from a terminal. Targets UE 5.8.
When to use
- Creating or fixing C++ gameplay classes (
AActor,APawn,ACharacter,AGameModeBase,UActorComponent), reflection macros, or a module's*.Build.cs. - Diagnosing compile, UHT, linker or Live Coding problems, and crashes from freed
UObjects. - Writing C++ automation tests and running them headless.
When not to use: designer-facing visual logic → unreal-blueprints. Input assets and
bindings → unreal-enhanced-input. Behavior Trees and EQS → unreal-behavior-trees. Cooking
and packaging → unreal-packaging. Building Unreal Engine itself from source is not covered;
follow Epic's source-build instructions for the engine's GitHub repository.
Workflow
- Read the project.
EngineAssociationin the.uprojectgives the engine version; theModuleslist andSource/<Module>/<Module>.Build.csgive module names and dependencies; existing base classes inSource/tell you what to extend. Match the existing API macro (MYGAME_API) and folder layout (Public/,Private/). - Declare reflected types correctly. The prefix matches the base (
Aactors,UotherUObjects and components,Fstructs,Eenums,Iinterfaces).GENERATED_BODY()is the first line in the body and#include "Name.generated.h"is the last include. - Make every
UObjectpointer GC-visible. Members that hold aUObjectareUPROPERTY()withTObjectPtr<T>; non-owning references areTWeakObjectPtr<T>. This is the most common source of random crashes. - Create default components in the constructor with
CreateDefaultSubobject, attach withSetupAttachment, and setRootComponent. Runtime components useNewObjectplusRegisterComponent. - Put logic where the framework expects it. Rules and default classes in the GameMode (server only), per-player state in PlayerState, input and UI ownership in the PlayerController, the body in the Pawn or Character, reusable behavior in components.
- Add module dependencies to
PublicDependencyModuleNames(orPrivate...when only the.cppfiles use them) whenever you include another module's headers, for exampleEnhancedInput,AIModule,Niagara,UMG. - Build and test from the command line (see Verify). Use Live Coding (Ctrl+Alt+F11) only for function-body edits while the editor is open.
Patterns
Reflected actor with a GC-safe component
// Pickup.h
#pragma once
#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "Pickup.generated.h" // last include
UCLASS()
class MYGAME_API APickup : public AActor
{
GENERATED_BODY()
public:
APickup();
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Pickup")
int32 ScoreValue = 10;
UFUNCTION(BlueprintCallable, Category = "Pickup")
void Collect();
protected:
UPROPERTY(VisibleAnywhere)
TObjectPtr<UStaticMeshComponent> Mesh; // UPROPERTY keeps it alive and visible to the editor
};
A C++ automation test
// Source/MyGame/Private/Tests/ScoreTests.cpp
#include "Misc/AutomationTest.h"
#if WITH_DEV_AUTOMATION_TESTS
IMPLEMENT_SIMPLE_AUTOMATION_TEST(FScoreAddsTest, "MyGame.Score.Adds",
EAutomationTestFlags::EditorContext | EAutomationTestFlags::ProductFilter)
bool FScoreAddsTest::RunTest(const FString& Parameters)
{
FScoreBoard Board; // plain logic: no world needed
Board.Add(10);
TestEqual(TEXT("score after one add"), Board.Total(), 10);
return true; // failed Test* calls still mark the test failed
}
#endif
Keep testable rules in plain structs or functions so most tests need no world; use functional tests in a test map for behavior that needs actors.
Verify
Say which of these you ran and paste the relevant result lines; "it should compile" is not a check.
- Compile the editor target with the editor closed:
Engine/Build/BatchFiles/Build.bat <Project>Editor Win64 Development -Project="<abs path>.uproject" -WaitMutex(Linux:Engine/Build/BatchFiles/Linux/Build.sh <Project>Editor Linux Development ...; macOS:Engine/Build/BatchFiles/Mac/Build.sh <Project>Editor Mac Development ...). Fix every error and every warning in files you touched. - Run the tests headless:
UnrealEditor-Cmd <Project>.uproject -ExecCmds="Automation RunTest MyGame;Quit" -unattended -nullrhi -nosplash -ReportExportPath="<dir>".RunTesttakes a full name, a dotted prefix,Test1+Test2, orGroup:<name>. Read the JSON report or theTest Completedlines in the log, and confirm the expected tests ran: a wrong filter runs nothing and still looks clean. - When behavior needs a person, ask the user to open the editor, check that the new class and its properties appear, run PIE, and report the Output Log lines for your category.
- Optional: with Epic's
unreal-mcpskill connected to a running editor, its testing toolset can discover and run automation tests and return detailed results.
Gotchas
- "Cannot open include file ...generated.h" or UHT errors: the generated include isn't
last,
GENERATED_BODY()is missing, or the file was added while the editor ran and project files weren't regenerated. - Unresolved external symbol: the module that defines the symbol isn't in
Build.cs. Find the header's path underEngine/Source/orEngine/Plugins/to get the module name. - Random crash on a pointer that "was valid": a raw
UObject*member withoutUPROPERTY, or a container of them, so GC freed the object.IsValid()on a dangling raw pointer does not save you. - Live Coding after header changes: new
UPROPERTYs or functions rely on Object Reinstancing, which is on by default but less reliable; pointers cached to reinstanced objects go stale. If the editor or Blueprints misbehave afterwards, close the editor and do a full build. - Building from the IDE or command line while the editor runs: with Live Coding active the build is refused or fights the editor's loaded modules. Close the editor first, or compile through Live Coding.
CreateDefaultSubobjectoutside the constructor: asserts. At runtime useNewObjectandRegisterComponent, otherwise the component never ticks or renders.- Overrides that skip
Super::(BeginPlay,Tick,EndPlay,GetLifetimeReplicatedProps) silently skip engine setup. - GameMode logic on a client: the GameMode exists only on the server. Use GameState or PlayerState for data clients must see.
References
- Read
references/components-and-gc.mdwhen creating or attaching components at runtime, choosing betweenTObjectPtr,TWeakObjectPtr,TStrongObjectPtrandFGCObject, addingUSTRUCT/UENUMdata, or replicating a property withOnRep_. - Epic docs: Gameplay Framework, Write C++ Tests, Run Automation Tests.
Related skills
unreal-blueprints: exposing C++ to designers.unreal-enhanced-input: binding input in a C++ Pawn or Character.unreal-behavior-trees: AIControllers and custom BT nodes.unreal-packaging: cooking and shipping the build.
Version notes
Last verified: 2026-11-11.
- Current release: UE 5.8 (5.8.4 hotfix, October 2026); UE 5.9 is in Preview.
- 5.8 Windows toolchain: Visual Studio 2022 17.14 or newer (2026 recommended), MSVC 14.38
minimum (14.50 recommended), Windows SDK 10.0.22621.0 minimum. 5.8.4 added Visual Studio
2026
.slnxsolution support. - 5.8 macOS: Xcode 15.2 minimum (15.4 or newer recommended). Linux: clang 20.1.8.
- 5.9 Preview adds the Modular Test Framework for scoped plugin tests.
- Sources: UE 5.8 release notes, Platform SDK Upgrades, 5.8.4 hotfix announcement and 5.8.4 summary, UE 5.9 Preview release notes, Write C++ Tests.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |