Menu
Lumberyard
Developer Guide (Version 1.11)

Event Bus (EBus)

Event buses (EBuses) are a general-purpose communication system that Lumberyard uses to dispatch notifications and receive requests. EBuses are configurable and support many different use cases. For examples of EBus usage, see Usage and Examples. For in-depth information about EBuses, see Event Buses in Depth. For C++ API reference documentation on the core EBus code, see the EBus API Reference in the Amazon Lumberyard C++ API Reference.

How Components Use EBuses

Components commonly use EBuses in two ways: to dispatch events or to handle requests. A bus that dispatches events is a notification bus. A bus that receives requests is a request bus. Some components provide one type of bus, and some components provide both types. Some components do not provide an EBus at all. You use the EBus class for both EBus types, but you configure the EBuses differently. The following sections show how to set up and configure notification buses, event handlers, and request buses.

Notification Buses

Notification buses dispatch events. The events are received by handlers, which implement a function to handle the event. Handlers first connect to the bus. When the bus dispatches an event, the handler's function executes. This section shows how to set up a notification bus to dispatch an event and a handler to receive the event.

Setting up a Notification Bus

To set up a bus to dispatch events

  1. Define a class that inherits from EBusTraits. This class will be the interface for the EBus.

  2. Override individual EBusTraits properties to define the behavior of your bus. Three EBusTraits that notification buses commonly override are AddressPolicy, which defines how many addresses the EBus contains, HandlerPolicy, which describes how many handlers can connect to each address, and BusIdType, which is the type of ID that is used to address the EBus if addresses are used. For example, notification buses often need to have multiple addresses, with the addresses identified by entity ID. To do so, they override the default AddressPolicy with EBusAddressPolicy::ById and set the BusIdType to EntityId.

  3. Declare a function for each event that the EBus will dispatch. Handler classes will implement these functions to handle the events.

  4. Declare an EBus that takes your class as a template parameter.

  5. Send events. The function that you use to send the event depends on which addresses you want to send the event to, whether to return a value, the order in which to call the handlers, and whether to queue the event.

    • To send an event to all handlers connected to the EBus, use Broadcast(). If an EBus has multiple addresses, you can use Event() to send the event only to handlers connected at the specified ID. For performance-critical code, you can avoid an address lookup by using Event() variants that take a pointer instead of an ID.

    • If an event returns a value, use BroadcastResult() or EventResult() to get the result.

    • If you want handlers to receive the events in reverse order, use BroadcastReverse() or EventReverse().

    • To send events asynchronously, queue the event. Queued events are not executed until the queue is flushed. To support queuing, set the EnableEventQueue trait. To queue events, use QueueBroadcast() or QueueEvent(). To flush the event queue, use ExecuteQueuedEvents().

Setting up a Handler

To enable a handler class to handle the events dispatched by a notification bus

  1. Derive your handler class from <BusName>::Handler. For example, a class that needs to handle tick requests should derive from TickRequestBus::Handler.

  2. Implement the EBus interface to define how the handler class should handle the events. In the tick bus example, a handler class would implement OnTick().

  3. Connect and disconnect from the bus at the appropriate places within your handler class's code. Use <BusName>:Handler::BusConnect() to connect to the bus and <BusName>:Handler::BusDisconnect() to disconnect from the bus. If the handler class is a component, connect to the bus in Activate() and disconnect from the bus in Deactivate(). Non-components typically connect in the constructor and disconnect in the destructor.

Request Buses

A request bus receives and handles requests. Typically, only one class handles requests for a request bus.

Setting up a Request Bus

The first several steps for setting up a request bus are similar to setting up a notification bus. After that you also need to implement the handlers for handling the requests.

To set up a request bus

  1. Define a class that inherits from EBusTraits. This class will be the interface for requests made to the EBus.

  2. Override individual EBusTraits properties to define the behavior of your bus. Two EBusTraits that request buses commonly override are AddressPolicy, which defines how many addresses the EBus contains, and HandlerPolicy, which describes how many handlers can connect to each address. For example, because there is typically only one handler class for each request bus, request buses typically override the default handler policy with EBusHandlerPolicy::Single.

  3. Declare a function for each event that the handler class will receive requests about. These are the functions that other classes will use to make requests of the handler class.

  4. Declare an EBus that takes your class as a template parameter.

  5. Implement a handler for the events as described in the previous section Setting up a Handler.