/ue-cpp-foundations

UE C++ Foundations

Target engine: UE 5.8. APIs below are verified against the 5.8 headers; older forms are listed under "Deprecated — do not use".

This skill covers the C++ layer every Unreal module is built on: reflection macros (UCLASS, UPROPERTY, UFUNCTION, USTRUCT, UENUM, UINTERFACE), containers, delegates, string types, object lifetime and garbage collection, CDO access, and the subsystem family. All of it lives in the Core, CoreUObject and Engine modules (PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine" });). Editor subsystems additionally need EditorSubsystem and UnrealEd in an editor-only module.

Context

Read .agents/ue-project-context.md if it exists (module names, conventions, enabled plugins, GAS/networking setup). Do not stop if it is missing.

Identify the area from the request and the codebase. Ask only when two plausible readings would produce different code.

Reflection Macros

Every reflected type has GENERATED_BODY() as the first line of its body and #include "TypeName.generated.h" as the last include of its header. Every UCLASS in a game module carries the module API macro (MYGAME_API). Specifier parsing is case-insensitive (engine headers use both config=Game and Config=Game). Complete specifier and meta= tables: references/property-specifiers.md.

UCLASS

UPROPERTY

// MyCharacter.h
#pragma once
#include "CoreMinimal.h"
#include "GameFramework/Character.h"
#include "MyCharacter.generated.h"

class UStaticMeshComponent;
class UStaticMesh;

UCLASS(Blueprintable)
class MYGAME_API AMyCharacter : public ACharacter
{
    GENERATED_BODY()
public:
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Stats", meta=(ClampMin="1.0"))
    float MaxHealth = 100.f;

    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category="Stats")
    float CurrentHealth = 100.f;

    UPROPERTY(Transient)
    TObjectPtr<UStaticMeshComponent> CachedMesh;     // not serialized, still GC-tracked

    UPROPERTY(EditDefaultsOnly, Category="Config")
    TSubclassOf<AActor> ProjectileClass;             // class reference restricted to AActor subclasses
    UPROPERTY(EditDefaultsOnly, Category="Config")
    TSoftObjectPtr<UStaticMesh> LazyMesh;            // path reference; load on demand

    UFUNCTION(BlueprintNativeEvent, Category="Combat")
    void OnDamageTaken(float Amount);
    virtual void OnDamageTaken_Implementation(float Amount);
};

UFUNCTION

// MyCharacter.cpp — the only body a BlueprintNativeEvent gets in C++
void AMyCharacter::OnDamageTaken_Implementation(float Amount) { CurrentHealth = FMath::Max(0.f, CurrentHealth - Amount); }

Function libraries, latent and async nodes, WorldContext/DefaultToSelf/ExpandEnumAsExecs and the rest of the Blueprint-facing meta= keys: ue-blueprint-cpp-interop.

USTRUCT, UENUM, UINTERFACE

// MyTypes.h
#pragma once
#include "CoreMinimal.h"
#include "MyTypes.generated.h"

USTRUCT(BlueprintType)
struct MYGAME_API FMyWeaponStats
{
    GENERATED_BODY()

    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Weapon")
    float BaseDamage = 10.f;

    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Weapon")
    float FireRate = 0.5f;
};

UENUM(BlueprintType)
enum class EMyWeaponState : uint8      // Blueprint-visible enums are enum class : uint8
{
    Idle,
    Firing    UMETA(DisplayName="Firing Weapon"),
    MAX       UMETA(Hidden)
};

• A UDataTable row type is a USTRUCT deriving from FTableRowBase (Engine/DataTable.h); see ue-data-assets-tables.
• Initialize every USTRUCT member in-class; reflected structs are value types copied freely by the engine.
• A polymorphic struct value (any USTRUCT derived from a base) is stored as FInstancedStruct or typed TInstancedStruct<FMyBase> (StructUtils/InstancedStruct.h, module CoreUObject).
• UINTERFACE pairs a UMyThing : UInterface stub with an IMyThing class; specifier table and a native example are in references/property-specifiers.md. Blueprint-implementable interfaces belong to ue-blueprint-cpp-interop.

Containers

Full API, iteration and performance notes: references/container-patterns.md. Containers of UObject pointers are GC-tracked only as UPROPERTY() TArray<TObjectPtr<T>> (likewise TMap/TSet).

TArray<FString> Names;
Names.Add(TEXT("Alpha"));
Names.Emplace(TEXT("Beta"));                       // construct in place
Names.Reserve(100);                                // pre-size before a known number of Adds
int32 Idx = Names.Find(TEXT("Beta"));              // INDEX_NONE if absent
FString* Ptr = Names.FindByPredicate([](const FString& S) { return S.StartsWith(TEXT("A")); });
Names.Sort([](const FString& A, const FString& B) { return A.Len() < B.Len(); });
Names.Remove(TEXT("Alpha"));                       // order-preserving, O(n)
Names.RemoveAtSwap(0);                             // O(1), reorders
for (int32 i = Names.Num() - 1; i >= 0; --i) { if (Names[i].IsEmpty()) { Names.RemoveAt(i); } }  // never mutate inside ranged-for

TMap<FName, int32> ItemCounts;
int32& Count = ItemCounts.FindOrAdd(FName("Sword"));  // inserts default if absent
int32* Found = ItemCounts.Find(FName("Axe"));         // nullptr if absent
for (const TPair<FName, int32>& Pair : ItemCounts) { UE_LOG(LogMyGame, Log, TEXT("%s x%d"), *Pair.Key.ToString(), Pair.Value); }

TSet<FName> Tags;
Tags.Add(FName("Flying"));
bool bFlying = Tags.Contains(FName("Flying"));     // hashed, no duplicates

TOptional<float> MaybeHP;
float Safe = MaybeHP.Get(0.f);                     // default when unset

TVariant

#include "Misc/TVariant.h"
#include <type_traits>

TVariant<int32, float, FString> Value;             // first type must be default-constructible (or use FEmptyVariantState)
Value.Set<FString>(TEXT("Hello"));
if (const FString* Str = Value.TryGet<FString>()) { UE_LOG(LogMyGame, Log, TEXT("%s"), **Str); }

Visit([](auto& Held)                               // one generic lambda; branch with if constexpr
{
    using HeldType = std::decay_t<decltype(Held)>;
    if constexpr (std::is_same_v<HeldType, FString>) { UE_LOG(LogMyGame, Log, TEXT("%s"), *Held); }
}, Value);

Delegates

All declaration macros, binding methods and payload rules: references/delegate-patterns.md.

// MyHealthComponent.h — delegate types are declared at file scope, above the UCLASS
DECLARE_MULTICAST_DELEGATE_TwoParams(FOnMyHealthChangedNative, float /*Current*/, float /*Max*/);
DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FOnMyHealthChanged, float, CurrentHealth, float, MaxHealth);

// in UMyHealthComponent : public UActorComponent
UPROPERTY(BlueprintAssignable, Category="Health")
FOnMyHealthChanged OnHealthChanged;               // dynamic: needs UPROPERTY, params need names
FOnMyHealthChangedNative OnHealthChangedNative;   // native: no reflection, cheaper to broadcast

// in AMyListenerActor : public AActor
UFUNCTION()                                       // AddDynamic targets must be UFUNCTIONs
void HandleHealthChanged(float CurrentHealth, float MaxHealth);
void HandleHealthChangedNative(float Current, float Max);
UPROPERTY() TObjectPtr<UMyHealthComponent> Health;
FDelegateHandle NativeHandle;

// AMyListenerActor.cpp — bind in BeginPlay (after Super::), unbind in EndPlay (before Super::)
Health->OnHealthChanged.AddDynamic(this, &AMyListenerActor::HandleHealthChanged);
NativeHandle = Health->OnHealthChangedNative.AddUObject(this, &AMyListenerActor::HandleHealthChangedNative);
// EndPlay: guard with IsValid(Health) first
Health->OnHealthChanged.RemoveDynamic(this, &AMyListenerActor::HandleHealthChanged);
Health->OnHealthChangedNative.Remove(NativeHandle);

The owner broadcasts with OnHealthChanged.Broadcast(CurrentHealth, MaxHealth);. Both classes in full: references/delegate-patterns.md.

Single delegates bind with BindUObject, BindSP, BindRaw, BindStatic, BindLambda, BindWeakLambda(this, ...) and fire with ExecuteIfBound(...). For a lambda that captures this, prefer AddWeakLambda/BindWeakLambda so the binding dies with the object.

String Types

float Health = 42.f; int32 Current = 3; int32 Max = 5;

FName   Tag(TEXT("Weapon.Rifle"));
FString S    = Tag.ToString();
FName   Back = FName(*S);
FString Msg  = FString::Printf(TEXT("HP: %.1f (%d/%d)"), Health, Current, Max);
int32 Parsed = FCString::Atoi(TEXT("42"));

#define LOCTEXT_NAMESPACE "MyGame"
FText Label = LOCTEXT("RifleName", "Assault Rifle");
FText Fmt   = FText::Format(LOCTEXT("HPFmt", "HP: {0}/{1}"), FText::AsNumber(Current), FText::AsNumber(Max));
#undef LOCTEXT_NAMESPACE
FText Other = NSLOCTEXT("MyGame", "Key", "Text");   // no #define needed
FText Raw   = FText::FromString(S);                 // not localized; runtime-generated text only

Object Lifetime and Pointers

The garbage collector keeps alive every UObject reachable from a root through reflected (UPROPERTY) references, FGCObject referencers, TStrongObjectPtr and rooted objects. A pointer the GC cannot see may dangle.

// Reflected members: TObjectPtr — GC-tracked, access-tracked in the editor, used like a raw pointer
UPROPERTY() TObjectPtr<UStaticMeshComponent> MeshComp;

// Legacy APIs that want raw pointers
void FillObjects(TArray<UObject*>& Out);
TArray<TObjectPtr<UObject>> Objects;
FillObjects(MutableView(Objects));                       // temporary TArray<UObject*>& view; ToRawPtr(Ptr) for a single read-only copy

// Non-owning reference: TWeakObjectPtr becomes null once the object is destroyed or collected
TWeakObjectPtr<AMyCharacter> WeakTarget;
if (AMyCharacter* Target = WeakTarget.Get()) { Target->OnDamageTaken(5.f); }

// Keep-alive from non-reflected code: scoped root instead of AddToRoot()/RemoveFromRoot()
TStrongObjectPtr<UMyDataObject> Pinned(NewObject<UMyDataObject>());

// Plain C++ types only: never wrap a UObject in TSharedPtr/TUniquePtr
struct FMyData { int32 Score = 0; };
TSharedPtr<FMyData> Data = MakeShared<FMyData>();
TWeakPtr<FMyData>   WeakData = Data;                     // Pin() returns a TSharedPtr if still alive

Non-UObject classes that hold UObjects derive from FGCObject and report them through TObjectPtr members; the raw UObject* overloads of AddReferencedObject(s) are deprecated and unsafe with incremental GC.

#include "UObject/GCObject.h"

class FMyManager : public FGCObject
{
public:
    virtual void AddReferencedObjects(FReferenceCollector& Collector) override { Collector.AddReferencedObject(ManagedObject); }
    virtual FString GetReferencerName() const override { return TEXT("FMyManager"); }
private:
    TObjectPtr<UMyDataObject> ManagedObject;   // TObjectPtr<T>& overload; raw UObject* is deprecated
};

CDO Access and Non-Null Parameters

#include "Misc/NotNull.h"

const UMyDataObject* Defaults = GetDefault<UMyDataObject>();        // class default object, read-only
UMyDataObject*       Settings = GetMutableDefault<UMyDataObject>(); // settings-style objects
UClass* SomeClass = AMyCharacter::StaticClass();
const AMyCharacter* ClassCDO = SomeClass->GetDefaultObject<AMyCharacter>();  // CDO of a runtime UClass

// TNotNull<T*>: caller cannot pass null; checked at the call site in Debug/Development, a plain pointer in Test and Shipping
void RegisterOwner(TNotNull<AActor*> Owner);
void RegisterOwner(TNotNull<AActor*> Owner)
{
    Owner->SetActorHiddenInGame(false);   // no null check needed inside
}

UClass::ClassDefaultObject is deprecated for direct access. TNotNull<T*> converts implicitly to T*; keep T* where null is a meaningful value.

Subsystems

Auto-instanced singletons owned by an engine object; no manual rooting. Override Initialize(FSubsystemCollectionBase&)/Deinitialize(); call Collection.InitializeDependency<UMyOtherSubsystem>() inside Initialize when ordering matters; return false from ShouldCreateSubsystem(UObject* Outer) const to opt out.

// MyInventorySubsystem.h
#pragma once
#include "CoreMinimal.h"
#include "Subsystems/GameInstanceSubsystem.h"
#include "MyInventorySubsystem.generated.h"

UCLASS()
class MYGAME_API UMyInventorySubsystem : public UGameInstanceSubsystem
{
    GENERATED_BODY()
public:
    virtual void Initialize(FSubsystemCollectionBase& Collection) override;
    virtual void Deinitialize() override;

    UFUNCTION(BlueprintCallable, Category="Inventory")
    void AddItem(FName ItemID, int32 Count);
private:
    TMap<FName, int32> Inventory;
};

// A ticking world subsystem adds these; Initialize/Deinitialize must call Super:: (the base registers the ticker)
UCLASS()
class MYGAME_API UMyTickableSubsystem : public UTickableWorldSubsystem
{
    GENERATED_BODY()
public:
    virtual void Tick(float DeltaTime) override;
    virtual TStatId GetStatId() const override { RETURN_QUICK_DECLARE_CYCLE_STAT(UMyTickableSubsystem, STATGROUP_Tickables); }
    virtual bool DoesSupportWorldType(const EWorldType::Type WorldType) const override;  // e.g. Game and PIE only
};

// Access from an AActor member function
UMyInventorySubsystem* Inv = GetGameInstance()->GetSubsystem<UMyInventorySubsystem>();
UMyTickableSubsystem*  Tck = GetWorld()->GetSubsystem<UMyTickableSubsystem>();
APlayerController*     PC  = GetWorld()->GetFirstPlayerController();
UMyUISubsystem*        UI  = ULocalPlayer::GetSubsystemFromController<UMyUISubsystem>(PC);   // null-safe
UMyEngineSubsystem*    Eng = GEngine->GetEngineSubsystem<UMyEngineSubsystem>();

UWorldSubsystem also offers PostInitialize(), OnWorldBeginPlay(UWorld& InWorld), OnWorldEndPlay(UWorld& InWorld) and OnWorldComponentsUpdated(UWorld& World) overrides; ULocalPlayerSubsystem::GetLocalPlayer<T>() and UGameInstanceSubsystem::GetGameInstance() return the owner.

Replicated Properties

Both the specifier and the GetLifetimeReplicatedProps entry are required. Conditions (COND_*), RPC rules, push model and Iris: ue-networking-replication.

// MyReplicatedActor.h
#pragma once
#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "MyReplicatedActor.generated.h"

UCLASS()
class MYGAME_API AMyReplicatedActor : public AActor
{
    GENERATED_BODY()
public:
    AMyReplicatedActor() { bReplicates = true; }
    virtual void GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const override;
protected:
    UPROPERTY(ReplicatedUsing=OnRep_Health)
    float Health = 100.f;

    UFUNCTION()
    void OnRep_Health();                 // runs on clients after Health changes
};

// MyReplicatedActor.cpp
#include "MyReplicatedActor.h"
#include "Net/UnrealNetwork.h"          // required for DOREPLIFETIME

void AMyReplicatedActor::GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const
{
    Super::GetLifetimeReplicatedProps(OutLifetimeProps);
    DOREPLIFETIME(AMyReplicatedActor, Health);
}

void AMyReplicatedActor::OnRep_Health() {}

Logging

DECLARE_LOG_CATEGORY_EXTERN(LogMyGame, Log, All);   // MyGame.h (module header)
DEFINE_LOG_CATEGORY(LogMyGame);                     // MyGame.cpp
UE_LOG(LogMyGame, Warning, TEXT("HP low: %.1f"), 12.5f);

Verbosities (Logging/LogVerbosity.h): Fatal, Error, Warning, Display, Log, Verbose, VeryVerbose. Display prints to the console and the log file; Log goes to the log file only. Shipping builds compile UE_LOG out unless the target sets bUseLoggingInShipping = true. Categories, structured logging (UE_LOGFMT), runtime verbosity control and profiling: ue-testing-debugging.

Conditional Compilation Guards

#if WITH_EDITORONLY_DATA
    UPROPERTY(EditAnywhere, Category="Debug")
    bool bShowDebugSpheres = false;                 // reflected editor-only data
#endif
#if WITH_EDITOR
    virtual void PostEditChangeProperty(FPropertyChangedEvent& PropertyChangedEvent) override;   // editor-only code
#endif
#if !UE_BUILD_SHIPPING
    void DrawDebugInfo();                           // Debug, Development and Test only
#endif

Deprecated — do not use

Common Mistakes

Raw UObject* member without UPROPERTY — dangling after GC:

UMyDataObject* Obj;                        // WRONG: invisible to GC
UPROPERTY() TObjectPtr<UMyDataObject> Obj; // RIGHT

Mutating a TArray inside ranged-for — iterator invalidation:

TArray<AActor*> Actors;
for (AActor* A : Actors) { Actors.Remove(A); }                                                      // WRONG
for (int32 i = Actors.Num() - 1; i >= 0; --i) { if (!IsValid(Actors[i])) { Actors.RemoveAt(i); } }  // RIGHT

TSharedPtr around a UObject — two owners, one crash: UObjects are owned by the GC; use TObjectPtr, TWeakObjectPtr or TStrongObjectPtr.

.generated.h not the last include, or MYGAME_API missing: UnrealHeaderTool rejects the header; the missing API macro surfaces later as LNK2019 from other modules.

AddDynamic bound to a non-UFUNCTION: the reflection lookup fails at runtime and the handler never runs; mark it UFUNCTION().

UPROPERTY/UFUNCTION written above a .cpp definition: UnrealHeaderTool only parses headers; the macro is silently ignored. Put it on the declaration inside the class body.

BlueprintNativeEvent without Name_Implementation: unresolved external at link time. Declare virtual void Name_Implementation(...) and define it.

UTickableWorldSubsystem::Initialize/Deinitialize override without Super::: the tickable registration lives in the base implementation; the subsystem never ticks.

Reading ClassDefaultObject directly: deprecated and about to become private; use GetDefault<T>().

Log verbosity "not showing up": Log is file-only by design; use Display for console output.

Related Skills

• ue-actor-component-architecture — AActor/UActorComponent lifecycle, spawning, tick groups, component setup
• ue-module-build-system — Build.cs, module dependencies, API export macros, include paths, PCH
• ue-testing-debugging — log categories and verbosity, structured logging, automation tests, profiling
• ue-networking-replication — DOREPLIFETIME conditions, RPC rules, push model, Iris
• ue-blueprint-cpp-interop — UBlueprintFunctionLibrary, latent and async actions, Blueprint-implementable
• Also relevant: ue-data-assets-tables, ue-animation-system, ue-async-threading, ue-audio-system, ue-editor-tools, ue-gameplay-abilities, ue-gameplay-framework, ue-gameplay-tags-messaging, ue-input-system, ue-mass-entity, ue-materials-rendering, ue-serialization-savegames, ue-state-trees, ue-ui-umg-slate, ue-world-level-streaming