delegates-and-events

name	delegates-and-events
description	Wire up callbacks and events in Unreal C++ using delegates — single-cast (DECLARE_DELEGATE, DECLARE_DELEGATE_RetVal, payload variables), multicast (DECLARE_MULTICAST_DELEGATE, DECLARE_TS_MULTICAST_DELEGATE), and dynamic (DECLARE_DYNAMIC_MULTICAST_DELEGATE, BlueprintAssignable, AddDynamic, RemoveDynamic). Covers all binding forms (BindUObject, AddUObject, BindLambda, AddWeakLambda, BindRaw, AddSP), execution (Execute, ExecuteIfBound, Broadcast), FDelegateHandle lifetime management, safe unbinding, and DECLARE_EVENT. Use when implementing the observer pattern, exposing C++ events to Blueprints, decoupling game systems, binding overlap/hit/ability callbacks, or debugging delegate crashes and silent no-ops.
metadata	{"engine-version":"5.8","category":"cpp-foundations"}

Delegates & events

Delegates are Unreal's type-safe function-pointer/observer system. There are three families — pick the right one before writing any binding code, because they differ in Blueprint visibility, binding API, and serialization capability.

When to use this skill

• One object needs to notify others when something happens (observer pattern).
• Exposing a C++ event that Blueprints can subscribe to (BlueprintAssignable).
• Decoupling systems: broadcast an event instead of calling a known class directly.
• Binding to overlap/hit/ability completion callbacks that require UFUNCTION.
• Crashes or silent no-ops from bad binding types, destroyed objects, or wrong macros.

The three families

Family	Macro prefix	Listeners	Blueprint?	Return value?
Single-cast	DECLARE_DELEGATE*	exactly one	no	yes (_RetVal)
Multicast	DECLARE_MULTICAST_DELEGATE*	many	no	no
Dynamic multicast	DECLARE_DYNAMIC_MULTICAST_DELEGATE*	many	yes	no

The decisive rule: if Blueprints need to subscribe, use dynamic multicast. For C++-only events with many listeners use multicast. For a single required callback (possibly with a return value) use single-cast. For a stored callable that isn't an event at all, use TFunction<Ret(Args...)>.

Suffixes encode the signature: _OneParam, _TwoParams, _RetVal_OneParam, etc. The delegate system supports up to 9 parameters and up to 4 payload variables (non-dynamic only). Dynamic delegate params must be named in the macro.

Declaring

// C++-only multicast — no Blueprint access
DECLARE_MULTICAST_DELEGATE_OneParam(FOnHealthChanged, float /*NewHealth*/);

// Dynamic multicast — Blueprint-assignable, params must be named
DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FOnDiedSignature, AActor*, Killer);

// Single-cast with return value — only one binding, can return bool
DECLARE_DELEGATE_RetVal_OneParam(bool, FCanInteract, AActor* /*Instigator*/);

Declare at global scope, namespace, or class scope — not inside a function body.

Expose as class members with the correct UPROPERTY specifier:

UCLASS()
class MYGAME_API UHealthComponent : public UActorComponent
{
    GENERATED_BODY()
public:
    // C++-only: no UPROPERTY needed; bind from C++ with AddUObject/AddLambda
    FOnHealthChanged OnHealthChanged;

    // Blueprint-assignable: MUST be UPROPERTY(BlueprintAssignable)
    UPROPERTY(BlueprintAssignable, Category="Health")
    FOnDiedSignature OnDied;
};

Binding

C++-only delegates (single-cast and multicast)

// Single-cast: bind to a UObject member function (weak ref — safe if object dies)
Delegate.BindUObject(this, &AMyClass::MyMethod);

// Single-cast: bind a lambda with no lifetime guard (unbind manually before capture dies)
Delegate.BindLambda([](float V){ /* no object captured — always safe */ });

// Single-cast: bind a lambda guarded by a UObject weak ref (safe — skipped if dead)
Delegate.BindWeakLambda(this, [this](float V){ Use(V); });

// Multicast: bind to a UObject member (weak ref — auto-skipped on GC)
FDelegateHandle H2 = Multi.AddUObject(this, &AMyHud::HandleHealthChanged);

// Multicast: bind a lambda guarded by a UObject weak ref
FDelegateHandle H3 = Multi.AddWeakLambda(this, [this](float V){ Use(V); });

// Multicast: bare lambda — no lifetime guard; MUST remove before capture dies
FDelegateHandle H4 = Multi.AddLambda([](float V){ /* no this captured */ });

Dynamic delegates — AddDynamic / BindDynamic

Dynamic delegates only accept UFUNCTION-marked methods. Use the macro wrappers which auto-generate the function name string at compile time:

// The handler MUST be a UFUNCTION() with the exact parameter signature
UFUNCTION()
void HandleDied(AActor* Killer);

// In BeginPlay or equivalent — AddDynamic wraps AddDynamic() macro internally
Health->OnDied.AddDynamic(this, &AMyHud::HandleDied);

Executing and broadcasting

// Multicast and dynamic multicast — Broadcast() to all bound listeners
OnHealthChanged.Broadcast(NewHealth);

// Single-cast — always check before calling Execute
if (CanInteract.IsBound())
{
    bool bOk = CanInteract.Execute(Instigator);
}
// Or use the safe form (no-op if unbound; cannot return a value)
CanInteract.ExecuteIfBound(Instigator);

• Broadcast is always safe to call even with zero bindings.
• Execute asserts if unbound — use only when you guarantee a binding exists.
• Multicast delegates cannot have return values; remove _RetVal from the macro.

Payload variables

Non-dynamic delegates can bake extra arguments into the binding at bind time. These extra arguments are appended after the delegate's declared parameters:

DECLARE_DELEGATE_OneParam(FOnTick, float /*DeltaTime*/);

FOnTick D;
int32 MyId = 7;
// MyMethod signature: void MyMethod(float DeltaTime, int32 Id)
D.BindUObject(this, &AMyActor::MyMethod, MyId);
D.Execute(DeltaSeconds);  // calls MyMethod(DeltaSeconds, 7)

Payloads work with Bind*/Add* — up to four additional variables.

Unbinding and lifetime

// Multicast: remove one binding by handle
Multi.Remove(Handle);

// Multicast: remove all bindings for one object
Multi.RemoveAll(this);

// Dynamic multicast: remove a specific binding
Health->OnDied.RemoveDynamic(this, &AMyHud::HandleDied);

// Single-cast: unbind
Delegate.Unbind();

// Multicast: remove everything
Multi.Clear();

Lifetime rules by binding type:

Binding	Tracks lifetime?	Action on dead object
AddUObject / BindUObject	yes (weak UObject ptr)	binding skipped, auto-compacted
AddDynamic / BindDynamic	yes (weak UObject ptr)	binding skipped
AddWeakLambda / BindWeakLambda	yes (weak UObject ptr)	lambda not called
AddSP / BindSP	yes (weak shared ptr)	binding skipped
AddLambda / BindLambda	no	crash if capture is dead
AddRaw / BindRaw	no	crash if object is dead

For AddLambda and AddRaw, store the returned FDelegateHandle and call Remove(Handle) in EndPlay or the destructor — before any captured object dies.

DECLARE_EVENT (legacy)

DECLARE_EVENT(OwnerType, EventName) creates a TMulticastDelegate subclass whose Broadcast is only accessible to OwnerType (friend). It is marked deprecated in the source comment (DelegateCombinations.h:30) — prefer plain DECLARE_MULTICAST_DELEGATE with a private broadcast method for the same encapsulation pattern.

Thread-safe multicast

DECLARE_TS_MULTICAST_DELEGATE* produces a TMulticastDelegate parameterized with FDefaultTSDelegateUserPolicy — the invocation list is guarded by a read-write lock. Use it when bindings are added/removed or broadcast from multiple threads. The per-binding callbacks themselves are not thread-safe; synchronize their bodies separately. (DelegateCombinations.h:26)

Decision guide

Need	Solution
Blueprints subscribe	DECLARE_DYNAMIC_MULTICAST_DELEGATE* + UPROPERTY(BlueprintAssignable)
C++-only, many listeners	DECLARE_MULTICAST_DELEGATE*
One handler, possible return value	DECLARE_DELEGATE* or DECLARE_DELEGATE_RetVal*
Stored callable (not an event)	TFunction<Ret(Args...)> or TUniqueFunction
Cross-thread broadcasting	DECLARE_TS_MULTICAST_DELEGATE*

Gotchas

• AddDynamic target is not a UFUNCTION — compile or registration error; the bound function must be UFUNCTION() with the exact declared signature.
• AddLambda / AddRaw capturing this without removing before destruction — the broadcast will crash. Store the handle and call Remove(Handle) in EndPlay.
• Execute on an unbound single-cast delegate — asserts. Always IsBound() first or use ExecuteIfBound.
• Dynamic multicast, not multicast, for Blueprints — DECLARE_MULTICAST_DELEGATE is never BlueprintAssignable; only DECLARE_DYNAMIC_MULTICAST_DELEGATE is.
• Param count/type mismatch with the _NParams suffix — will not compile.
• Dynamic param names not provided — dynamic macros require a name for each param; omitting them is a compile error.
• Modifying the invocation list during Broadcast — adding/removing from inside a handler is deferred until broadcast completes; the delegate handles this safely.
• DECLARE_EVENT for new code — the source marks it deprecated; use plain multicast with a friend access pattern instead.

References & source material

Engine source (UE 5.8, under Engine/Source/Runtime/Core/Public/):

• Delegates/DelegateCombinations.h — all DECLARE_* macros: single-cast:20, multicast:23, TS multicast:26, event:32, dynamic:35, dynamic multicast:38.
• Delegates/Delegate.h — TDelegate/TMulticastDelegate concepts, binding table, payload variable documentation; UE_PRIVATE_DECLARE_DELEGATE:205, UE_PRIVATE_DECLARE_MULTICAST_DELEGATE:209, UE_PRIVATE_DECLARE_EVENT:221, UE_PRIVATE_DECLARE_DYNAMIC_DELEGATE:231, UE_PRIVATE_DECLARE_DYNAMIC_MULTICAST_DELEGATE:239. (The old FUNC_DECLARE_* forms are deprecated in 5.8, :247–:252.)
• Delegates/DelegateSignatureImpl.inl — TDelegateRegistration/TDelegate:327, BindLambda:138, BindWeakLambda:163, BindUObject:288; TMulticastDelegateRegistration:743, AddLambda:823, AddWeakLambda:853, AddUObject:1020, Remove:1062, TMulticastDelegate::Broadcast:1133, TDynamicDelegate:1161, TDynamicMulticastDelegate:1288 (renamed from TBaseDynamicDelegate/ TBaseDynamicMulticastDelegate in 5.8).
• Delegates/MulticastDelegateBase.h — TMulticastDelegateBase, Clear:119, IsBound:131, RemoveAll:173.
• Delegates/IDelegateInstance.h — FDelegateHandle:15 (the handle type returned by Add*; stores a uint64 ID for O(N) lookup/removal).
• Templates/Function.h — TFunction<Ret(Args...)> / TUniqueFunction for stored callables that are not event delegates.

Official docs (UE 5.8):

• Delegates (single-cast) — https://dev.epicgames.com/documentation/unreal-engine/delegates-and-lambda-functions-in-unreal-engine
• Multicast Delegates — https://dev.epicgames.com/documentation/unreal-engine/multicast-delegates-in-unreal-engine
• Dynamic Delegates — https://dev.epicgames.com/documentation/unreal-engine/dynamic-delegates-in-unreal-engine

Deep-dive references in this skill:

• references/delegate-types-matrix.md — full macro-to-type mapping, param/payload limits, TS variant, event pattern.
• references/binding-and-lifetime.md — every binding form, safety guarantees, payload syntax, FDelegateHandle patterns.
• references/dynamic-and-blueprint.md — dynamic delegate mechanics, AddDynamic/RemoveDynamic, Blueprint event dispatcher wiring, UDELEGATE specifier, serialization notes.