Event Bus

Table of Contents

• Events
• EventBus
• Subscribing and Unsubscribing to an Event
  • Subscribe
  • Unsubscribe
• Callbacks
• Publishing an Event
  • Inline
  • By instantiation
• Creating Custom Events
  • Sample Custom Event
  • Subscribing to a Custom Event

The Astra.Utils.EventBus is an implementation of the publisher/subscriber paradigm which facilitates clean decoupled communication between components. Astra uses the EventBus for UI events in the Character Editor, you are welcome to use and extend on top of this yourself.

Events

Astra.Utils.Events is a central location wherein various core events and their payload configurations are defined. If you need to add an event, define it here using an existing event as a reference.

EventBus

The Astra.Utils.EventBus instantiates a static EventBus object which maintains a collection of Subscriptions, objects which represent the association between an event, a subscriber, and the subscriber's callback method to be invoked upon event publication. In publisher-subscriber patterns this is sometimes also referred to as a broker. A new Subscription is created and added to the collection when the Subscribe method is called.

Subscribing and Unsubscribing to an Event

Subscribe

Use Astra.Utils.EventBus.Subscribe to receive a callback when an event is triggered such as a button click on UI element or an asset of has been loaded.

Invoking the Astra.Utils.EventBus.Subscribe method creates a Astra.Utils.EventBus.Subscription representing the association between a given event, subscriber, and callback.

Type parameters:

1. TBusEvent: Type of event to which to subscribe
2. TSubscriber: Type of subscriber

Parameters:

1. callback: Callback to be invoked on publication of given event
2. subscriber: A reference to the subscribing Object

void Start()
{
    // Bind the method HandleOnAvatarLoaded so it will be invoked when event Events.AvatarLoadedEvent is triggered by a publisher
    // the second parameter as "this" provides the subscriber preventing duplicate subscriptions
    EventBus.Subscribe<Events.AvatarLoadedEvent, AstraManager>(HandleOnAvatarLoaded, this);
}

Unsubscribe

Astra.Utils.EventBus.Unsubscribe allows you to remove your callback from the watched event.

Note: To avoid memory issues, make sure that objects unsubscribe before they are destroyed, sleep, etc.

Type parameters:

1. TBusEvent: Type of event to which to unsubscribe

1. TSubscriber: Type of subscriber

Parameters:

1. subscriber: A reference to the subscribing Object

void OnDestroy()
{
    // Removes all bound callbacks against our subscriber, "this".
    // NOTE: it is very important to pair your Subscribe with Unsubscribe
    EventBus.Unsubscribe<Events.AvatarLoadedEvent, AstraManager>(this);
}

Callbacks

// Our method that is triggered whenever the publisher trips the AvatarLoadedEvent
// each event is a class type containing custom data specific to the event
void HandleOnAvatarLoaded(Events.AvatarLoadedEvent eventItem) 
{
    Debug.Log("OnAvatarLoaded handler invoked!");
    var avatarItem = eventItem.payload.GetResult();
    Debug.Log("Avatar: " + avatarItem.AstraGuid);
}

Publishing an Event

Payload data can be configured inline or by instantiating a new event and passing it into the Publish method.

Inline

EventBus.Publish(new Events.AvatarLoadedEvent() { payload = param });

By instantiation

// instantiate new BusEvent
Events.AvatarLoadedEvent eventPayload = new Events.AvatarLoadedEvent(param, this);
// publish
EventBus.Publish(eventPayload);

Creating Custom Events

You can create you own events and make use of the EventBus. All you need to do is create a struct or class that extends Astra.Utils.Events.BusEvent and defines a payload property or a Astra.Utils.Events.PayloadEvent.

You can then publish in any place when you want your event to trigger.

You can see an example of a custom event in the Assets/Astra/Examples/Events directory.

Sample Custom Event

using UnityEngine;
using Astra.Utils;
 
namespace Astra.Examples
{
 
    // A component that will publish the seconds since application start roughly every second
    public class EventSecondsPublisher : MonoBehaviour 
    {
 
        // Holds the current time since the application began, created roughly every second
        public class OnSecondsEvent : Events.BusEvent
        {
            public float payload;
        }
 
 
        // Internally tracks the time since the application began to ensure frequency is about every 1 second
        private float _lastTime = 0;
 
        void Update()
        {
            // Fire our event after at least 1 second has passed since the previous event
            var delta = Time.realtimeSinceStartup - _lastTime;
            if(delta > 1.0f)
            {
                _lastTime = Time.realtimeSinceStartup;
                EventBus.Publish<OnSecondsEvent>(new OnSecondsEvent() { payload = _lastTime });
            }
        }
    }
 
}

Subscribing to a Custom Event

using UnityEngine;
using Astra.Utils;
 
namespace Astra.Examples 
{
 
    // Receives an event when loaded with the current number of seconds since the application began.
    // Try toggling the component on and off or deleting it in the scene and observe the console output.
    public class EventSecondsSubscriber : MonoBehaviour
    {
        void OnEnable()
        {
            EventBus.Subscribe<EventSecondsPublisher.OnSecondsEvent,EventSecondsSubscriber>(GetTime,this);
        }
 
        private void GetTime(EventSecondsPublisher.OnSecondsEvent e)
        {
            Debug.Log("Seconds: " + e.payload);
        }
 
        void OnDisable()
        {
            EventBus.Unsubscribe<EventSecondsPublisher.OnSecondsEvent,EventSecondsSubscriber>(this);
        }
    }
 
}