Tutorial: Using the GameplayMessageSystem

A short tutorial demonstrating how to utilize the GameplayMessageSystem in C++ and Blueprint

Updated 3 months ago Edit Page Revisions
ProgrammingBlueprintsGameplayMessageSystemTutorial

Using the GameplayMessageSystem

This tutorial is intended to demonstrate the basics of how to Broadcast and Listen for messages using the GameplayMessageSystem.

For more information about the technical concepts & benefits of this system, please see the GameplayMessageSystem overview page.

To successfully follow this tutorial you will want to ensure that your project has the GameplayMessageSubsystem enabled.

image

Using the GameplayMessageSystem in Blueprint

This is a very simple overview demonstrating how to utilize the GameplayMessageSubsystem in Blueprint. This overview shows how to get the Subsystem, Broadcast a Message, and Listen for a message.

Get the GameplayMessageSubsystem

The singleton instance of the Subsystem can be retrieved in Blueprint as so.

  1. RMB in an Event Graph & Type GetGameplayMessageSubsystem to filter the Blueprint Search
  2. Select GameplayMessageSubsystem node from the available option(s)
Get the GameplayMessageSubsystem
image
image

Broadcast a Message

  1. Drag-off the GameplayMessageSubsystem Instance Pin & Type Broadcast to filter the Blueprint Search
  2. Select Broadcast Message from the available options
  3. Choose a GameplayTag for the Broadcast's Channel
    • Note: Any GameplayTag will work, but you should probably use one specifically created for this type of Message
  4. Create and Connect a Structure to the Message pin
    • Note: Any Structure should work, but it is recommended to use a custom Structure specifically created for this type of Message, containing only the data you know you will need to transmit to Listeners
Broadcast a Message
image
image

Register a Listener

  1. RMB in an Event Graph & Type Listen for to filter the Blueprint Search
  2. Select Listen for Gameplay Messages from the available options
  3. Choose a GameplayTag for the Listener's Channel
    • Note: Must correspond to the expected Broadcast Channel
  4. Choose a Payload Type
    • This should be the same Structure used by your Broadcast node
  5. (Optional) Choose a MatchType.
    • MatchType determines whether the Listener listens for the exact Channel GameplayTag, or whether it will match other GameplayTags (ex. any GameplayTag children)

Pay attention to the execution pins coming out of this node.

  • The On Message Received execution pin is the logic that will be executed when the Message is received
  • The top-most execution pin is used for continuing the synchronous execution of Blueprint logic
Register a Listener
image
image

Using the GameplayMessageSystem in C++

This is a very simple overview demonstrating how to utilize the GameplayMessageSubsystem in C++. This overview shows how to get the Subsystem, Broadcast a Message, and Listen for a message.

Include the GameplayMessageSystem

In any class where you Broadcast or Listen for messages, or otherwise interact with the GameplayMessageSystem, you will want to include the following header:

#include "GameFramework/GameplayMessageSubsystem.h"

Get the GameplayMessageSubsystem

The singleton instance of the Subsystem can be retrieved in C++ as so:

// Get the instance of this subsystem
UGameplayMessageSubsystem& MessageSubsystem = UGameplayMessageSubsystem::Get(this);

Broadcast a Message

We can broadcast a message from within C++ utilizing the following pattern:

UGameplayMessageSubsystem& MessageSubsystem = UGameplayMessageSubsystem::Get(this);

FGameplayTag ChannelTag; // You will need to assign this value as appropriate for your code
FGameMessage OutgoingMessage; // You will need to define the structure and fill out any members with data as appropriate for your code

MessageSystem.BroadcastMessage(ChannelTag, OutgoingMessage);

Register a Listener

We can listen for a message from within C++ utilizing the following pattern:

UGameplayMessageSubsystem& MessageSubsystem = UGameplayMessageSubsystem::Get(this);

FGameplayTag ChannelTag; // You will need to assign this value as appropriate for your code
ListenerHandle = MessageSubsystem.RegisterListener(ChannelTag, this, &UMyClass::CallbackFunction);

/*---------------------------------------------------------------------*/

// Your class will also need a Callback Function defined as below

UMyClass::CallbackFunction(FGameplayTag InChannel, const FGameMessage& InMessage)
{
    // Perform gameplay logic here
}