Unreal

Unreal Engine 5 (Blueprint + C++)

Build and debug UE5 games with the grain of the engine: the Gameplay Framework for structure, reflection macros so C++ and Blueprint see the same types, Enhanced Input for controls, UMG for UI, Paper2D for 2D — and a clean Blueprint↔C++ boundary so either can call the other. Hands 3D-only concerns (shaders, physics, netcode, shipping) to the siblings below.

Version contract — read first

Target Unreal Engine 5.x (patterns valid 5.3+; current stable UE 5.8, the last UE5 line before UE6). Emit modern UE5 APIs only. Never emit these deprecated / legacy patterns:

Blueprint vs C++ — and the hybrid. Blueprint: designer-facing tweaks, per-level scripting, UI wiring, rapid iteration, one-off actors. C++: core systems, performance-critical/tick-heavy code, base classes, math, anything you want unit-tested or diffable in git. Default to the hybrid: write the base class in C++ (UCLASS(Blueprintable)), expose tunables with UPROPERTY(EditAnywhere, BlueprintReadWrite) and hooks with BlueprintImplementableEvent / BlueprintNativeEvent, then create a Blueprint subclass for designers to set defaults, wire assets, and script the specifics — C++ speed and testability with Blueprint iteration.

Gameplay Framework — who owns what

Rule of thumb: transient input/camera → PlayerController; persistent per-player data → PlayerState; match rules → GameMode (server); shared world state → GameState. Full responsibilities and a spawn-order diagram → references/gameplay-framework.md.

Actor lifecycle, components & attachment

Order for a spawned/placed Actor: constructor (set defaults, create subobjects — never gameplay logic) → PostInitializeComponents → BeginPlay (world is live; safe to start logic) → Tick(DeltaSeconds) each frame (only if enabled) → EndPlay / Destroyed (release).

AMyActor::AMyActor()
{
    PrimaryActorTick.bCanEverTick = false;                         // opt in only if you truly tick
    RootComponent = CreateDefaultSubobject<USceneComponent>(TEXT("Root"));
    Mesh = CreateDefaultSubobject<UStaticMeshComponent>(TEXT("Mesh"));
    Mesh->SetupAttachment(RootComponent);                          // attach in the CONSTRUCTOR
}
void AMyActor::BeginPlay() { Super::BeginPlay(); /* start logic here, not in ctor */ }

• Create components with CreateDefaultSubobject<T>(TEXT("Name")) in the constructor; store them in a UPROPERTY() TObjectPtr<T> so they're kept alive and visible.
• Attach in the constructor with SetupAttachment; at runtime use AttachToComponent(Parent, FAttachmentTransformRules::SnapToTargetNotIncludingScale).
• Prefer timers over tick for periodic work: GetWorldTimerManager().SetTimer(Handle, this, &AMyActor::Fn, 1.f, true);

Reflection macros & garbage collection

Macros register types with Unreal Header Tool (UHT) so they get GC, serialization, editor, and Blueprint support. Put GENERATED_BODY() first inside the class.

UENUM(BlueprintType)
enum class ETeam : uint8 { Red, Blue };

USTRUCT(BlueprintType)                       // value type, visible to BP; no GC of itself
struct FLoadout { GENERATED_BODY()
    UPROPERTY(EditAnywhere, BlueprintReadWrite) int32 Ammo = 30;
};

UCLASS(Blueprintable)                        // Blueprintable = can be subclassed in BP
class MYGAME_API AWeapon : public AActor {
    GENERATED_BODY()
public:
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Combat") float Damage = 10.f;
    UPROPERTY(VisibleAnywhere) TObjectPtr<UStaticMeshComponent> Mesh;   // GC-tracked ref
    UFUNCTION(BlueprintCallable, Category="Combat") void Fire();
};

Common UPROPERTY specifiers: EditAnywhere (edit on instances + defaults), EditDefaultsOnly (class defaults only), VisibleAnywhere (read-only in editor); BlueprintReadWrite (get + set in BP) vs BlueprintReadOnly (get only); always give a Category.

Garbage collection — the #1 gotcha. The GC frees any UObject that no reachable UPROPERTY points to. A UObject reference stored without UPROPERTY() is invisible to GC: it will be collected out from under you and the pointer dangles/crashes. So:

• Store every long-lived UObject/AActor reference in a UPROPERTY() TObjectPtr<T>.
• For a non-owning "might already be dead" reference (don't keep it alive, must null-check), use TWeakObjectPtr<T> and .IsValid().
• Never new/delete a UObject — spawn Actors with SpawnActor<T>() and create other UObjects with NewObject<T>(); the GC owns their lifetime. new/delete and smart pointers apply only to non-UObject C++ types.

Delegates & events

// Dynamic multicast = Blueprint-assignable + serializable. Params need a typed macro variant.
DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FOnHealthChanged, float, NewHealth);

UPROPERTY(BlueprintAssignable, Category="Events")     // shows as a red event node in BP
FOnHealthChanged OnHealthChanged;

// C++ side: bind and fire.
OnHealthChanged.AddDynamic(this, &AMyActor::HandleHealth);   // dynamic → AddDynamic + UFUNCTION
OnHealthChanged.Broadcast(NewHealth);

Use a dynamic multicast delegate whenever Blueprint must bind to the event (BlueprintAssignable); its handler must be a UFUNCTION. Use a plain DECLARE_MULTICAST_DELEGATE… (bind with AddUObject/AddLambda) only for C++-to-C++ events that never touch Blueprint. Overlap/hit events (OnComponentBeginOverlap, OnActorHit) are already dynamic multicast — bind with AddDynamic.

Blueprint ↔ C++ parity

Same graph, two languages. Left = the Blueprint node; right = the C++ that does the same thing.

Expose C++ → Blueprint:

UFUNCTION(BlueprintCallable, Category="X") void DoThing();     // callable node (has exec pins)
UFUNCTION(BlueprintPure,     Category="X") int32 GetScore() const;  // pure node (no exec pins)
UPROPERTY(EditAnywhere, BlueprintReadWrite) float Speed = 600.f;    // exposed variable

Call Blueprint ← C++ (the hybrid hooks — declare in C++, implement/override in the BP subclass):

// No C++ body — Blueprint provides the whole implementation. C++ just calls OnScored().
UFUNCTION(BlueprintImplementableEvent) void OnScored(int32 Points);

// C++ gives a default; Blueprint may override. Implement the C++ default in OnDamaged_Implementation.
UFUNCTION(BlueprintNativeEvent) void OnDamaged(float Amount);
void AMyActor::OnDamaged_Implementation(float Amount) { Health -= Amount; }
// Call the event from C++ by its plain name: OnScored(10);  OnDamaged(5.f);

Mapping table (every specifier), full expose/override examples, and the C++-base-+-BP-subclass workflow → references/blueprint-cpp-parity.md.