Passing Payloads through Delegate Parameters

Configure delegate signatures to pass custom data payloads, allowing listeners to receive relevant context from the event broadcaster.

In this lesson, you will learn how to enrich your event broadcasts by passing specific data payloads through delegate parameters so listeners can act on meaningful context.

Why Context Matters

So far, we have used delegates to signal that "something happened." However, often the listener needs to know what that something was. For instance, if an AHealthComponent broadcasts an OnHealthChanged event, the UI needs to know the new health value, and a sound effect actor needs to know how much damage was dealt. Instead of making the listener query the broadcaster—which leads to tight coupling—we can "push" the necessary data directly into the delegate signature.

Configuring the Payload

To pass a payload, you simply add parameters to your delegate declaration. When you broadcast the event, you include the values that correspond to those parameters. The Unreal Engine macro handles the heavy lifting of routing these arguments to every bound function.

Here is how you define and use a multi-cast delegate with a custom payload:

// 1. Define the delegate signature with parameters
DECLARE_MULTICAST_DELEGATE_TwoParams(FOnHealthChanged, float NewHealth, float DamageTaken);

class AHealthComponent : public UActorComponent
{
public:
    // 2. Expose the delegate
    FOnHealthChanged OnHealthChanged;

    void TakeDamage(float Amount)
    {
        CurrentHealth -= Amount;

        // 3. Broadcast with the payload
        OnHealthChanged.Broadcast(CurrentHealth, Amount);
    }
};

The Listener’s Perspective

When a listener binds a function to this delegate, that function must match the signature exactly. If your delegate expects two float parameters, your bound function must accept two float parameters:

void UMyUIWidget::HandleHealthChanged(float NewHealth, float DamageTaken)
{
    // Now you have the context to update the health bar 
    // or play a damage animation based on the DamageTaken value.
}

By defining these payloads, you turn your delegates from simple "notifications" into robust communication channels. The broadcaster doesn't need to know who is listening or what they do with the data; it simply provides the relevant context, and the subscribers handle the rest.

Key Takeaway: Adding parameters to your delegate signature allows you to broadcast specific data payloads, enabling loose coupling while ensuring your listeners have all the context they need to react appropriately.