🪞 Lesson 2.2: The Reflection System — UCLASS, USTRUCT, UENUM

What Reflection Means

Reflection is a program's ability to examine its own structure at runtime: to ask "what class is this object? what properties does it have? what functions can I call by name?" Languages like C# and Java have this built in. Standard C++ does not — once compiled, a C++ type's names and structure are erased; there's just memory and machine code.

Unreal needs reflection badly. The editor must draw a property panel from a class it didn't know about at compile time. A save file must serialize objects by walking their properties. Blueprint must call C++ functions by name. Networking must know which properties to replicate. None of that is possible without runtime type information.

The Unreal Header Tool

The Unreal Header Tool (UHT) runs as part of every build, before the C++ compiler. It scans your headers for reflection macros and generates a companion file — the .generated.h you always include last — plus a .gen.cpp that registers your types.

At runtime, the result is that every reflected class has a corresponding UClass object describing it — its name, parent, properties, and functions. You can retrieve it with UMyActor::StaticClass(), and the engine uses it constantly under the hood.

UCLASS, USTRUCT, UENUM

Three macros mark the three kinds of reflected type. Each pairs with a body macro.

UCLASS — reflected classes (usually UObject-derived)

UCLASS()
class MYPROJECT_API AEnemy : public AActor
{
    GENERATED_BODY()   // required inside every UCLASS

public:
    UPROPERTY(EditAnywhere, Category = "Enemy")
    float MaxHealth = 100.0f;
};

USTRUCT — reflected plain-data structs

USTRUCT(BlueprintType)   // BlueprintType: usable as a Blueprint variable/pin
struct FDamageInfo
{
    GENERATED_BODY()     // structs use the SAME body macro

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    float Amount = 0.0f;

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    FName DamageType;
};

UENUM — reflected enumerations

UENUM(BlueprintType)
enum class EWeaponType : uint8   // uint8 base is required for BlueprintType enums
{
    Pistol   UMETA(DisplayName = "Pistol"),
    Rifle    UMETA(DisplayName = "Rifle"),
    Shotgun  UMETA(DisplayName = "Shotgun")
};

Cast and the Type System

Because reflection records each object's real class, Unreal can offer a safe runtime cast — Cast<T>. It converts a base pointer to a derived type only if the object truly is that type; otherwise it returns nullptr. No crash, no undefined behavior.

AActor* HitActor = /* something we got from a trace or overlap */;

// Is this actor actually an AEnemy? Cast tells us safely.
if (AEnemy* Enemy = Cast<AEnemy>(HitActor))
{
    // Inside this block, Enemy is a valid AEnemy* — use its API freely.
    Enemy->TakeDamage(25.0f);
}
// If HitActor wasn't an AEnemy, Cast returned nullptr and we skip the block.

The same type info powers IsA(), StaticClass(), class-based spawning, and the "class picker" dropdowns you see in the editor — all of it reading the UClass data UHT generated.

What Reflection Unlocks

Everything distinctive about Unreal C++ traces back to reflection. Four big systems depend on it:

💬 The payoff mindset: when you write UPROPERTY(EditAnywhere, Replicated), you're not "configuring a variable" — you're registering it with the editor and the network system simultaneously. Reflection is the shared substrate.

Hands-on Exercise & Quiz

UENUM(BlueprintType)
enum class EPickupKind : uint8
{
    Health, Ammo, Coin
};

USTRUCT(BlueprintType)
struct FPickupEffect
{
    GENERATED_BODY()

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    EPickupKind Kind = EPickupKind::Health;

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    int32 Amount = 25;
};

UCLASS()
class MYPROJECT_API APickup : public AActor
{
    GENERATED_BODY()

public:
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Pickup")
    FPickupEffect Effect;
};

Summary

📚 Additional Resources

• Reflection System (Epic)
• Unreal Header Tool (Epic)

🚀 What's Next?

You've seen the macros; next we go deep on the two that shape your everyday code the most — the specifiers inside UPROPERTY and UFUNCTION that decide exactly how your members surface to the editor, Blueprint, and beyond.