0 The Message System

Messaging is at the core of any component-based system. Rather than directly calling other component's methods, you send messages to a postal address instead. If there happens to be a component listening to these messages from that address, it will receive them.

All this functionality is offered by the PostOffice class. This class works at a very low level. It doesn't know about the Guay Framework or Unity. It just knows about addresses and message ids.

To listen to a specific message, you provide an address, a message identifier and a message callback. The callback will be called whenever someone sends that message to that address.

public void Subscribe( object _address, string _message, MessageCallback _callback )
{
    ....
}

Likewise, to send a message you call the following method specifying an address, a message id and a list of parameters:

public void Send( object _address, string _message, params object[] _params )
{
    ...
}

You can also can broadcast a message through the method:

public void Broadcast( string _message, params object[] _params )
{
    ...
}

Let's see an example:

public class Player
{
    public Player()
    {
        ExampleApp.PostOffice.Subscribe( 
            "gameAddress",
            "gameStart",
            ( _event, _params ) =>
            {
                Debug.WriteLine( "The game has started!!" );
            } );
    }
}
 
public class Game
{
    public void Start()
    {
        ExampleApp.PostOffice.Send( "gameAddress", "gameStart" );
    }
}
 
public class ExampleApp
{
    private static PostOffice mPostOffice;
    
    /// <summary>
    /// Retrieves the post office
    /// </summary>
    public static PostOffice PostOffice
    {
        get { return mPostOffice ?? (mPostOffice = new PostOffice( false )); }
    }
 
    public ExampleApp()
    {
        // a game is created
        var game = new Game();
        
        // player is created. it will subscribe to the "gameStart" message
        var player = new Player();
        
        // the game starts, sending the "gameStart" message to the address "gameAddress",
        // the message will be queued.
        game.Start();
    }
 
    public void Update()
    {
        // once per frame, the post office is updated, delivering all queued messages.
        // Player will get the "gameStart" message
        PostOffice.Update();
    }
}

This example shows what working with the typical message system looks like. However, this class is not directly exposed to the game code. Instead, the Guay Framework makes use of the PostOffice class internally, presenting a Unity-friendly interface which makes messaging really easy to use from scripts. You can find more information about this in the description of the GuayScript script.