Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 38 ยท C++ Gameplay

Reflection: UPROPERTY, UFUNCTION and UENUM

Learn how Unreal Engine reflection macros expose C++ to the editor and Blueprints. Covers UPROPERTY, UFUNCTION, UENUM and USTRUCT specifiers with practical examples.

Plain C++ has no way to ask "which member variables does this class have?" at run time. Unreal Engine adds that ability with its own reflection system. You mark classes, properties and functions with macros, and the Unreal Header Tool (UHT) reads your headers at build time and generates the metadata. The editor's Details panel, Blueprints, saving and loading, replication and garbage collection all depend on that metadata.

This lesson covers the four macros you will write most often: UPROPERTY, UFUNCTION, UENUM and USTRUCT. As in the rest of this chapter, the C++ is read-only (the engine cannot run on this site) and the runnable blocks are Python stand-ins that model what UHT does.

UPROPERTY: variables the engine can see

A variable without UPROPERTY is invisible to the editor and, for UObject pointers, invisible to the garbage collector. A typical set looks like this:

C++
UCLASS()
class MYGAME_API ACoinPickup : public AActor
{
    GENERATED_BODY()

public:
    // Editable on the class defaults and on each placed instance
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Coin")
    int32 Value = 10;

    // Visible in Details but not editable
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Coin")
    TObjectPtr<UStaticMeshComponent> Mesh;

    // Editable only on the Blueprint class, not on level instances
    UPROPERTY(EditDefaultsOnly, Category = "Coin|Audio")
    TObjectPtr<USoundBase> PickupSound;

    // Not saved, not shown, but still tracked by the garbage collector
    UPROPERTY(Transient)
    TObjectPtr<AActor> LastCollector;
};

The specifiers fall into three groups.

Editing: EditAnywhere (class defaults and instances), EditDefaultsOnly (class defaults only), EditInstanceOnly (placed instances only), VisibleAnywhere (shown, locked), VisibleDefaultsOnly, VisibleInstanceOnly.

Blueprint access: BlueprintReadWrite, BlueprintReadOnly. Private members need meta = (AllowPrivateAccess = "true") to be exposed to Blueprints.

Organization and behavior: Category = "A|B" builds nested groups, meta = (ClampMin = "0", ClampMax = "100") limits editor values, Transient skips saving, SaveGame marks data for save-game archives, Replicated replicates over the network.

UFUNCTION: functions the engine can call

C++
// Callable from any Blueprint graph, shows as a node with an exec pin
UFUNCTION(BlueprintCallable, Category = "Coin")
void Collect(AActor* Collector);

// Pure: no exec pin, no side effects
UFUNCTION(BlueprintPure, Category = "Coin")
int32 GetValue() const { return Value; }

// C++ declares it, Blueprint (or C++ via _Implementation) defines it
UFUNCTION(BlueprintImplementableEvent, Category = "Coin")
void OnCollected();

// C++ default body plus an optional Blueprint override
UFUNCTION(BlueprintNativeEvent, Category = "Coin")
void PlayEffects();

For a BlueprintNativeEvent you write the body in a function named PlayEffects_Implementation; the generated PlayEffects calls into Blueprint if it is overridden and into your C++ otherwise. Other useful specifiers: Exec (console commands on certain classes), CallInEditor (adds a button in Details), and Server, Client, NetMulticast for networking.

UENUM and USTRUCT

C++
UENUM(BlueprintType)
enum class ECoinKind : uint8
{
    Bronze UMETA(DisplayName = "Bronze Coin"),
    Silver,
    Gold
};

USTRUCT(BlueprintType)
struct FCoinStats
{
    GENERATED_BODY()

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    ECoinKind Kind = ECoinKind::Bronze;

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    int32 Value = 1;
};

Enums exposed to Blueprints must be uint8-based. A USTRUCT does not derive from UObject, so it is cheap to copy, but it needs GENERATED_BODY() too.

What UHT does, modelled in Python

UHT scans for the macro, reads the next declaration and writes a table of metadata. The stand-in below parses a tiny header and builds the same kind of table. It is a teaching model, not the real tool.

Python Stand-in: a mini Unreal Header Tool

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Choosing the right specifier

A reliable rule: start as locked down as possible and open up only when needed.

You want Use
Designers tweak the value per placed instance EditAnywhere
Value is set once in a Blueprint class EditDefaultsOnly
Show a component reference but never change it VisibleAnywhere
Blueprint graphs read it BlueprintReadOnly
Blueprint graphs change it BlueprintReadWrite
Blueprint implements the behavior BlueprintImplementableEvent
Python Stand-in: validate specifier combinations

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Common mistakes

  • Missing UPROPERTY on a UObject*. The garbage collector does not see the pointer and may free the object while you still hold it. See Memory and garbage collection.
  • Changing a header and expecting Live Coding to apply it. Changing reflected members (adding or removing UPROPERTY entries) needs a full editor restart and build, not Live Coding.
  • Forgetting Category. Blueprint-exposed members without a category give a UHT error.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which specifier lets designers change a value on each placed Actor in the level, but also on the class defaults?

    EditAnywhere allows editing on class defaults and on instances. EditDefaultsOnly limits it to class defaults.
  2. 2. What does a BlueprintNativeEvent require in C++?

    UHT generates the dispatcher and you write the C++ default in FunctionName_Implementation.
  3. 3. Which tool generates the reflection metadata at build time?

    UHT reads macros such as UCLASS and UPROPERTY and writes .generated.h and .gen.cpp files.
  4. 4. Why must a UObject pointer member be marked UPROPERTY?

    Only reflected references are traced by the garbage collector; an unmarked pointer can dangle.

Summary

  • Reflection macros let the editor, Blueprints, serialization and garbage collection see your C++.
  • UPROPERTY controls editing (Edit*, Visible*), Blueprint access and organization.
  • UFUNCTION exposes functions: BlueprintCallable, BlueprintPure, BlueprintImplementableEvent, BlueprintNativeEvent.
  • UENUM needs a uint8 base for Blueprints; USTRUCT types need GENERATED_BODY().
  • Use the most restrictive specifier that works.

Next: Input and Character Movement