UGantryMessageSubsystem

#include "Messages/GantryMessageSubsystem.h"

Sends messages on gameplay-tag channels, so one part of the game can tell others that something happened without either side knowing the other.

A game mode announces that a goal was scored. The HUD shows it, a DLC pack's new round reacts to it, and a stats tracker counts it. None of them holds a reference to another: they only share the channel's tag and the message's struct.

• A channel is any gameplay tag your game chooses, such as MyGame.Message.GoalScored.
• A message is any struct, such as an S_GoalScored with the scoring team and player.
• A listener on a channel can also hear every channel under it (Partial match): a listener on MyGame.Message hears MyGame.Message.GoalScored too.

Gantry defines no channels and no message types; your game adds its own.

In Blueprint

To send, get the Gantry Message Subsystem and call Broadcast Message. Pick the channel and connect any struct to Message.

To listen, add a Listen For Messages node, for example in a HUD widget's Construct event. Set Channel, and set Payload Type to the struct you expect. On Message Received fires for every message. In it, call Get Payload on the node's Async Action pin with a variable of your struct type, and Get Payload fills it in. The listener stops when the object that started it is destroyed, or when you call Cancel on the Async Action.

In C++

FMyGoalScored Message;
Message.Team = ScoringTeam;
UGantryMessageSubsystem::Get(this)->BroadcastMessage(TAG_MyGame_Message_GoalScored, Message);

ListenerHandle = UGantryMessageSubsystem::Get(this)->RegisterListener<FMyGoalScored>(
    TAG_MyGame_Message_GoalScored,
    [this](FGameplayTag Channel, const FMyGoalScored& Message) { ShowGoal(Message); },
    EGantryTagMatch::Exact, this);

Pass an Owner (the last argument) and the listener ends with that object. Otherwise keep the handle and call Unregister on it when you are done.

Rules

• Delivery is immediate: Broadcast Message calls every listener before it returns. Listeners on the exact channel come first, in the order they started listening, then Partial listeners on each channel above it.
• A listener is skipped, with a warning in the log, when the struct sent is not the struct it expects (or a child of it).
• Messages stay on this machine. Nothing is replicated: send your own RPC or replicated property when other machines need to know.
• There is one subsystem per game instance, so listeners last across map changes until they are removed or their owner is gone.

Hooks

A hook is a channel whose listeners can change what happens: the game runs it where it is about to do something, and acts on what comes back. Listeners get the payload itself, highest priority first, and can change it, mark it handled, or cancel it (which stops the rest).

FMyDamage Damage{ Amount, Instigator };
const FGantryHookResult Result = Gantry::RunHook(this, TAG_MyGame_Hook_Damage, Damage);
if (!Result.bCancelled) { ApplyDamage(Damage.Amount); }

Handle = Subsystem->RegisterHookListener<FMyDamage>(TAG_MyGame_Hook_Damage,
    [](FGantryMessageRouter::FHookCall& Call, FMyDamage& Damage) { Damage.Amount *= 0.5f; },
    10, EGantryTagMatch::Exact, this);   // priority 10: before the default 0

In Blueprint: Run Hook (on this subsystem) with a struct variable, which comes back changed; and Listen For Hook, whose On Hook can Get Hook Payload, Set Hook Payload, Mark Handled or Cancel Hook.

Declared channels

The channels a game offers (to its own systems and to side-loaded content) are declared in the channel registry (FGantryChannelRegistry): a Channel Set listed in Project Settings > Plugins > Gantry Core, code, or an experience's Declare Channels stage. Declaring puts a channel in the API manifest; with Warn On Undeclared Channels on, using an undeclared channel (or the wrong payload or kind, or a deprecated one) is a warning.

Sends a message, any struct, to everyone listening on Channel, and to Partial listeners on the channels above it.

Every listener is called before this returns.

Runs a hook: its listeners, highest priority first, may change Payload, mark it handled or cancel it.

Every listener has run (or one cancelled) before this returns.

Stops a listener, so it hears no more messages.

Safe to call on an empty handle.

virtual void UGantryMessageSubsystem::Deinitialize() override

Drops every listener.

int32 UGantryMessageSubsystem::BroadcastMessage(FGameplayTag Channel, const T &Message)

Sends a message of struct type T to everyone listening on Channel, and to Partial listeners on the channels above it.

Returns: How many listeners heard it.

FGantryMessageListenerHandle UGantryMessageSubsystem::RegisterListener(FGameplayTag Channel, TFunction< void(FGameplayTag, const T &)> &&Callback, EGantryTagMatch Match=EGantryTagMatch::Exact, const UObject *Owner=nullptr)

Listens on Channel for messages of type T (or a child of it).

Returns: A handle to remove the listener with.

FGantryMessageListenerHandle UGantryMessageSubsystem::RegisterListenerInternal(FGameplayTag Channel, const UScriptStruct *Type, EGantryTagMatch Match, const UObject *Owner, FGantryMessageRouter::FCallback Callback)

Listens on Channel for messages of a struct type given at run time, or of any type.

Returns: A handle to remove the listener with.

int32 UGantryMessageSubsystem::BroadcastMessageInternal(FGameplayTag Channel, const UScriptStruct *Type, const void *Payload)

Sends a message given as a struct type and a pointer to it, for when the type is known only at run time.

Returns: How many listeners heard it.

UGantryMessageSubsystem::DECLARE_FUNCTION(execK2_BroadcastMessage)

Broadcast Message's custom thunk: reads the struct the Blueprint passed in place of Message.

void UGantryMessageSubsystem::RemoveListener(FGameplayTag Channel, int32 Id)

Removes a listener by channel and id.

FGantryMessageListenerHandle::Unregister calls this.

FGantryHookResult UGantryMessageSubsystem::RunHook(FGameplayTag Channel, T &Payload)

Runs a hook with a payload of struct type T, changed in place by its listeners.

Returns: How many listeners ran, and whether one handled or cancelled it.

FGantryMessageListenerHandle UGantryMessageSubsystem::RegisterHookListener(FGameplayTag Channel, TFunction< void(FGantryMessageRouter::FHookCall &, T &)> &&Callback, int32 Priority=0, EGantryTagMatch Match=EGantryTagMatch::Exact, const UObject *Owner=nullptr)

Listens for a hook whose payload is of type T (or a child of it).

Returns: A handle to remove the listener with.

FGantryHookResult UGantryMessageSubsystem::RunHookInternal(FGameplayTag Channel, const UScriptStruct *Type, void *Payload)

Runs a hook given its payload's struct type at run time.

FGantryMessageListenerHandle UGantryMessageSubsystem::RegisterHookListenerInternal(FGameplayTag Channel, const UScriptStruct *Type, EGantryTagMatch Match, int32 Priority, const UObject *Owner, FGantryMessageRouter::FHookCallback Callback)

Listens for a hook given the payload's struct type at run time (null for any).

UGantryMessageSubsystem::DECLARE_FUNCTION(execK2_RunHook)

Run Hook's custom thunk: passes the Blueprint's struct variable itself to the listeners.

void UGantryMessageSubsystem::RemoveHookListener(FGameplayTag Channel, int32 Id)

Removes a hook listener by channel and id.

FGantryMessageListenerHandle::Unregister calls this.

FGantryMessageRouter & UGantryMessageSubsystem::GetRouter()

The router underneath, for tests and tools.

static UGantryMessageSubsystem * UGantryMessageSubsystem::Get(const UObject *WorldContextObject)

The subsystem of a world context's game instance.

Returns: The subsystem, or null outside a game instance.