Messaging


The messaging system allows for simple decoupling of components using either queued or immediate messages. Many standard messages are defined for different standard functions such as when you purchase an item or when the number of players lives changes. You can also define your own message types for different purposes.

The messaging system is integrated into the rest of the framework through GameManager.Messenger, and so you should add the GameManager (API) component to your scene. You can also create your own Messenger instances if you have other needs as it will function independently also.

Listening for Messages

You can call the functions AddListener<MessageType>(handler) and RemoveListener< MessageType>(handler) to add and remove listeners for specific message types where you pass as a parameter the method that should receive messages. The method you pass should take a single parameter of type BaseMessage which you can cast to the registered type, and return a bool indicating whether the message was processed.

When a message of the given type is ready for sending then your method will be called passing in the message which will be a subclass of BaseMessage that is ready for casting to the registered type and process as required.

e.g.

To listen for multiple message types, just add multiple AddListener and RemoveListener calls as appropriate.

Note: It is vital that every AddListener call is paired with a corresponding RemoveListener to avoid possible problems. Also GameManager also provides SafeAddListener and SafeRemoveListener methods that are probably preferable to the above, both as a shorthand and that also validate that both GameManager and the Messaging system are initialised.

For instances like the above where you only need a simple component that subscribes to messages and then takes action upon these, there is also provided an abstract class RunOnMessage<T> that you can inherit from (where T is the message type you are interested in). Several components such as ShowLives, ShowHealthImage and more use this to be able to update the display automatically when things change without needing to constantly poll for changes which adds a large overhead.To any class that inherits from RunOnMessage<T> you can add the RunOnMessageAttribute. You might have different requirements as to when your component subscribes and unsubscribes to the message (Awake, Start, OnEnable, OnDisable, OnDestroy). Adding the RunOnMessageAttribute lets you control this behaviour).

The below shows the above example rewritten using the RunOnMessage component.

Submitting Messages

All messages you submit must inherit from BaseMessage. BaseMessage contains the following properties:

  • Name – The name of this message, derived from the type (readonly).
  • SendMode – How to send messages (SendToAll, SendToFirst).

To create a new message just create a new subclass of BaseMessage. You can include any additional parameters that you might need to pass

e.g.

You can then submit messages to any listeners through either the QueueMessage or TriggerMessage methods.

QueueMessage is the preferred way of sending messages as it allows for features such as batching, throttling etc. Messages sent with QueueMessage will be placed in a queue and sent by GameManager in its next Update loop.

TriggerMessage can also be used for sending and will send the message immediately to all registered listeners and should be used for messages that need immediate processing.

e.g.

Available Messages

Below is a complete list of the standard messages that are currently available. Click on any of the names below for further information

Audio

Billing

Facebook

GameStructure – Game

GameStructure – GameItem

GameStructure – Levels

GameStructure – Player

Localisation

See also

If you have any thoughts or suggestions on improvements or additions to the Messaging features then please let us know!