Trabajar con el sistema de bus de eventos (EBus)

Los buses de eventos (EBuses) son un sistema de comunicación de propósito general que Lumberyard utiliza para enviar notificaciones y recibir solicitudes. Los EBuses son configurables y admiten muchos casos de uso diferentes.

Para interactuar con el motor u otros componentes en Lumberyard, incluye el componente o El encabezado EBus o API del sistema en el código. A continuación, realice llamadas a los EBuses expuestos. Con esto puede reemplazar el motor–nivele las API del sistema con implementaciones que defina en una gema. Por ejemplo, podría sustituir Lumberyarddel sistema de audio de con su propio controlador de EBus. Esto le daría un control completo sobre el audio sin tener que volver a compilar el del motor.

Para ver 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 obtener documentación de referencia de la API de C++ sobre el código EBus principal, consulte la Referencia de la API de EBus en el Referencia de la API de C++ de Amazon Lumberyard.

Cómo utilizan los componentes Buses electrónicos

Los componentes suelen utilizar EBuses de dos formas: para enviar eventos o para gestionar solicitudes. Un bus que envía eventos es un notification del autobús. Un bus que recibe es una request del autobús. Algunos componentes proporcionan un tipo de bus, y algunos componentes proporcionan ambos tipos. Algunos componentes no proporcionan un EBus en absoluto. Usted utilice la clase EBus para ambos tipos de EBus, pero configure los EBuses de forma diferente. El las siguientes secciones muestran cómo configurar y configurar buses de notificación, controladores de eventos, y solicitar autobuses.

Notificación Autobuses

Los buses de notificación envían eventos. Los controladores reciben los eventos, lo que implemente una función para gestionar el evento. Los controladores se conectan primero al bus. Cuando el El bus de envía un evento , la función del controlador ejecuta. Esta sección muestra cómo establecer un bus de notificación para enviar un evento y un controlador para recibir el evento.

Configuración de un Bus de notificación

Para configurar un bus para enviar eventos

1. Definir una clase que herede de EBusTraits. Esta clase será la interfaz para Bus electrónico.

2. Anular individual EBusTraits las propiedades para definir el del bus. Tres EBusTraits que los buses de notificación suelen anularse AddressPolicy, que define cuántos direcciones que contiene el EBus, HandlerPolicy, que describe cómo muchos controladores pueden conectarse a cada dirección, y BusIdType, que es el tipo de ID que se utiliza para dirigir el EBus si se utilizan direcciones. Por ejemplo, los buses de notificación a menudo necesitan tener varias direcciones, con las direcciones identificadas por el ID de entidad. Para ello, anulan el valor predeterminado AddressPolicy con EBusAddressPolicy::ById y establece el BusIdType de EntityId.

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

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

5. Enviar eventos. La función que se utiliza para enviar el evento depende de direcciones a las que desea enviar el evento, si desea devolver un valor, el orden en el que llamar a los controladores y si se debe poner en cola el evento.

   • Para enviar un evento a todos los controladores conectados al EBus, utilice Broadcast(). Si un EBus tiene varias direcciones, puedes utilizar Event() para enviar el evento solamente a los controladores conectados con el ID especificado. Para aplicaciones de rendimiento código, puedes evitar una búsqueda de direcciones utilizando Event() variantes que toman un puntero en lugar de un ID.

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

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

   • Para enviar eventos de forma asíncrona, ponga en cola el evento. Los eventos en cola son no se ejecuta hasta que la cola se vacía. Para admitir la puesta en cola, establezca la opción EnableEventQueue característica. Para poner en cola eventos, usar QueueBroadcast() o bien QueueEvent(). Para vaciar la cola de eventos, utilice ExecuteQueuedEvents().

Configuración de un controlador

Para habilitar una clase de controlador para gestionar los eventos enviados por una notificación autobús

1. Obtener la clase de controlador de <BusName>::Handler. Por ejemplo, una clase que necesita gestionar solicitudes de ciclos debe derivarse de TickRequestBus::Handler.

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

3. Conéctese y desconecte del autobús en los lugares apropiados dentro de su del código de la clase de controlador. Uso <BusName>:Handler::BusConnect() para conectarse al bus y <BusName>:Handler::BusDisconnect() para desconectarse del bus. Si la clase de controlador es un componente, conéctese a el bus en Activate() y desconectar del bus en Deactivate(). Los no componentes normalmente se conectan en el constructor y desconecte en el destructor.

[EMPTY] Autobuses

Un bus de solicitud recibe y gestiona las solicitudes. Normalmente, solo una clase gestiona para un bus de solicitud.

Configuración de una solicitud [EMPTY]

Los primeros pasos para configurar un bus de solicitud son similares a configurar un del bus de notificación. Después de eso, también tendrá que implementar los controladores para gestionar las solicitudes.

Para configurar un bus de solicitud

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

2. Anular individual EBusTraits las propiedades para definir el del bus. Dos EBusTraits que solicitan autobuses suelen anularse AddressPolicy, que define cuántos direcciones que contiene el EBus, y HandlerPolicy, que describe cuántos controladores se pueden conectar a cada dirección. Por ejemplo, porque hay normalmente solo una clase de controlador para cada bus de solicitud, buses de solicitud normalmente anulan la política de controlador predeterminada con EBusHandlerPolicy::Single.

3. Declare una función para cada evento que recibirá la clase de controlador sobre. Estas son las funciones que otras clases utilizarán para de la clase de controlador.

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

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