Trabajo con el sistema de bus de eventos (EBus)

Los buses de eventos (EBuses) son un sistema de comunicación de carácter general que Lumberyard utiliza para enviar notificaciones y recibir solicitudes. Los EBuses se pueden configurar y admiten varios casos de uso diferentes.

Para interactuar con el motor u otros componentes en Lumberyard, incluya el encabezado de API o el EBus del sistema o del componente en su código. A continuación, realice llamadas a los EBuses expuestos. Con este enfoque, puede sustituir las API del sistema de nivel de motor con las implementaciones que defina en una gema. Por ejemplo, podría sustituir el sistema de audio de Lumberyard con su propio controlador de EBus. Esto le ofrecería un control total de audio sin tener que recompilar el motor.

Para consultar ejemplos de uso de EBus, consulte Uso y ejemplos.

Para obtener información detallada sobre EBuses, incluidos diagramas conceptuales, consulte Buses de eventos en profundidad.

Para consultar la documentación de referencia de la API de C++ sobre el código de EBus de núcleo, consulte laReferencia de la API de EBusen laReferencia de la API de C++ de Amazon.

Cómo los componentes utilizan los EBuses

Por lo general, los componentes utilizan los EBuses de dos formas: para enviar eventos o para gestionar solicitudes. Un bus que envía eventos es un bus de notification. Un bus que recibe solicitudes es un bus de request. Algunos componentes proporcionan un único tipo de bus, mientras que otros componentes proporcionan ambos tipos. Algunos componentes no proporcionan ningún EBus en absoluto. La clase de EBus se utilizan en ambos tipos de EBus, pero los Ebuses se configuran de forma diferente. En las secciones siguientes se muestra cómo instalar y configurar buses de notificación, controladores de eventos y buses de solicitud.

Buses de notificación

Los buses de notificación envían eventos. Los eventos son recibidos por controladores que, a su vez, implementan una función para gestionar el evento. Los controladores se conectan primero al bus. Cuando el bus envía un evento, la función del controlador se ejecuta. En esta sección se muestra cómo configurar un bus de notificación para enviar un evento, y cómo configurar el controlador para recibir eventos.

Configuración de un bus de notificación

Para configurar un bus para enviar eventos

1. Defina una clase que herede de EBusTraits. Esta clase será la interfaz del EBus.

2. Anule las propiedades individuales de EBusTraits para definir el comportamiento de su bus. Por lo general, los buses de notificación anulan los tres EBusTraits siguientes: AddressPolicy, que define cuántas direcciones contiene el EBus; HandlerPolicy, que describe cuántos controladores pueden establecer conexión con cada dirección y BusIdType, que es el tipo de ID que se utiliza para abordar los EBus si se usan direcciones. Por ejemplo, los buses de notificación a menudo necesitan disponer de varias direcciones, con las direcciones identificadas mediante el ID de entidad. Para ello, anulan la AddressPolicy predeterminada con EBusAddressPolicy::ById y establecen el BusIdType en EntityId.

3. Declare una función para cada evento que el EBus enviará. Las clases de controlador implementarán estas funciones para controlar los eventos.

4. Declare un EBus que tome su clase como parámetro de plantilla.

5. Envíe eventos. La función que utilice para enviar el evento depende de a qué direcciones desea enviar el evento, si desea devolver un valor, el orden en el que llamar a los controladores y si desea poner en cola el evento.

   • Para enviar un evento a todos los controladores conectados al EBus, utilice Broadcast(). Si una EBus tiene varias direcciones, puede utilizar Event() para enviar el evento únicamente a los controladores conectados al ID especificado En el caso de código fundamental para el desempeño, puede evitar una búsqueda de direcciones utilizando variantes de Event() que tomen un puntero en lugar de un ID.

   • Si un evento devuelve un valor, utilice BroadcastResult() o EventResult() para obtener el resultado.

   • Si quiere que los controladores reciban los eventos en orden inverso, utilice BroadcastReverse() o EventReverse().

   • Para enviar eventos de forma asíncrona, ponga en cola el evento. Los eventos en cola no se ejecutan hasta que se vacía la cola. Para admitir las colas, establezca el rasgo EnableEventQueue. Para poner en cola los eventos, utilice QueueBroadcast() o QueueEvent(). Para vaciar la cola, utilice ExecuteQueuedEvents().

Configuración de un controlador

Para habilitar una clase de controladores para controlar los eventos enviados por un bus de notificación

1. Genere su clase de controlador a partir <BusName>::Handler. Por ejemplo, una clase que deba controlar solicitudes de tic debe derivarse de TickRequestBus::Handler.

2. Implemente la interfaz de EBus para definir cómo la clase de controlador debe controlar los eventos. En el ejemplo del bus de ciclos, una clase de controlador implementaría OnTick().

3. Establezca conexión con el bus y desconéctese de él en los lugares adecuados del código de su clase de controlador. Utilice <BusName>:Handler::BusConnect() para establecer conexión con el bus y <BusName>:Handler::BusDisconnect() para desconectarse del bus. Si la clase de controlador es un componente, establezca conexión con el bus Activate() y desconéctese de este en Deactivate(). Normalmente, los elementos que no son componentes establecen conexión en el constructor y se desconectan en el destructor.

Buses de solicitud

Un bus de solicitud recibe y controla las solicitudes. Normalmente, solo una sola clase controla las solicitudes de un bus de solicitud.

Configuración de un bus de solicitud

Varios de los primeros pasos de configuración de un bus de solicitud son iguales que los de configuración de un bus de notificación. Después, solo tiene que implementar los controladores para controlar las solicitudes.

Para configurar un bus de solicitud

1. Defina una clase que herede de EBusTraits. Esta clase será la interfaz de las solicitudes realizadas al EBus.

2. Anule las propiedades individuales de EBusTraits para definir el comportamiento de su bus. Por lo general, los buses de solicitud anulan los dos EBusTraits siguientes: AddressPolicy, que define cuántas direcciones contiene el EBus y HandlerPolicy, que describe cuántos controladores pueden establecer conexión con cada dirección. Por ejemplo, ya que normalmente solo hay una clase de controlador para cada bus de solicitud, los buses de solicitud normalmente anulan la política de controlador predeterminada con EBusHandlerPolicy::Single.

3. Declare una función por cada evento sobre el que la clase de controlador recibirá solicitudes. Estas son las funciones que las demás clases utilizarán para realizar solicitudes de la clase de controlador.

4. Declare un EBus que tome su clase como parámetro de plantilla.

5. Implemente un controlador para los eventos tal y como se describe en la sección anterior Configuración de un controlador.