Detectores de Eventos

Con el fin de detectar un evento, un detector de evento debe ser registrado. Esto se hace realizando un método con cualquier nombre, definiendo el primer parámetro para ser el tipo de evento deseado y luego fijando la anotación :javadoc:`Detector` al método, es mostrado a continuación.

import org.spongepowered.api.event.Listener;

@Listener
public void onSomeEvent(SomeEvent event) {
    // Do something with the event
}

Adicionalmente, la clase que contiene estos métodos debe ser registrada con el administrador de evento:

Truco

Para detectores de eventos en su clase de complemento principal (anotada por Plugin), no necesita registrar el objeto para eventos ya que Sponge lo hará automáticamente.

Nota

El bus de evento admite supertipos. Por ejemplo, ChangeBlockEvent.Break se extiende de ChangeBlockEvent. Por lo tanto, un complemento podría detectar ChangeBlockEvent y todavía recibir ChangeBlockEvent.Breaks. Sin embargo, un plugin que solo detecta ChangeBlockEvent.Break no sería notificado de otros tipos de ChangeBlockEvent.

Registro y Anulación de Registro de Detectores de Evento

Para registrar detectores de evento anotados por @Listener que no están en la clase de complemento principal, puede utilizar EventManager#registerListeners(Object, Object), que acepta una referencia al complemento y una instancia de la clase que contiene los detectores de eventos.

Ejemplo: Registro de Detectores de Eventos en Otras Clases

import org.spongepowered.api.Sponge;

public class ExampleListener {

    @Listener
    public void onSomeEvent(SomeEvent event) {
        // Do something with the event
    }
}

Sponge.getEventManager().registerListeners(this, new ExampleListener());

Registrar Dinámicamente Detectores de Eventos

Algunos complementos (como los complementos de scripting) pueden desear registrar dinámicamente un detector de eventos. En ese caso, el detector de eventos no es un método anotado con @Listener, sino más bien una clase que implementa la interfaz EventListener. Este detector de eventos puede luego ser registrado llamando a EventManager#registerListener, que acepta una referencia al complemento como el primer argumento, la `` Clase`` de eventos manejados como el segundo argumento y el propio detector como el argumento final. Opcionalmente, puede especificar un :javadoc:`Orden` para ejecutar el detector de eventos como el tercer argumento o un valor boolean como el cuarto argumento (antes de la instancia del detector) que determina si se debe llamar al detector antes de otras modificaciones del servidor.

Ejemplo: Implementación de EventListener

import org.spongepowered.api.event.EventListener;
import org.spongepowered.api.event.block.ChangeBlockEvent;

public class ExampleListener implements EventListener<ChangeBlockEvent.Break> {

    @Override
    public void handle(ChangeBlockEvent.Break event) throws Exception {
        [...]
    }
}

Ejemplo: Registrar Dinámicamente el Detector de Eventos

EventListener<ChangeBlockEvent.Break> listener = new ExampleListener();
Sponge.getEventManager().registerListener(this, ChangeBlockEvent.Break.class, listener);

Truco

Para detectores de eventos creados con la anotación @Listener, el orden de la ejecución puede ser configurado (vea también About @Listener). Para registrar dinámicamente detectores de eventos, esto es posible al pasar un Orden al tercer argumento del método EventManager#registerListener.

Anulación de Registro de Detectores de Eventos

Para anular el registro de un único detector de eventos, puede utilizar el método EventManager#unregisterListeners(Object), que acepta una instancia de la clase que contiene los detectores de eventos.

EventListener listener = ...;
Sponge.getEventManager().unregisterListeners(listener);

Alternativamente, puede utilizar EventManager#unregisterPluginListeners(Object), pasando una referencia al complemento, para anular el registro todos los detectores de eventos asociados con ese complemento. Tenga en cuenta que esto eliminará todos los detectores de eventos de plugin, incluyendo esos registros con anotaciones @Listener.

PluginContainer plugin = ...;
Sponge.getEventManager().unregisterPluginListeners(plugin);

Acerca de @Listener

La anotación @Listener tiene unos pocos campos configurables:

order is the priority in which the event listener is to be run. See the Order enum in SpongeAPI to see the available options.
beforeModifications especifica si el detector de evento debería ser llamado antes de otras modificaciones del servidor, como modificaciones de Forge. Por defecto, esto es establecido como falso.

Por defecto, @Listener es configurado así que su detector de eventos no será llamado si el evento en cuestión es cancelable y ha sido cancelado (como por otro complemento).

GameReloadEvent

To prevent all plugins providing their own reload commands, Sponge provides a built-in callback for plugins to listen to, and when executed, perform any reloading actions. What constitutes as a “reloading action” is purely up to the plugin to decide. The GameReloadEvent will fire when a player executes the /sponge plugins reload command. The event is not necessarily limited to reloading configuration.

import org.spongepowered.api.event.game.GameReloadEvent;

@Listener
public void reload(GameReloadEvent event) {
    // Do reload stuff
}

Tenga en cuenta que esto es diferente de lo que generalmente es considerado una “recarga”, ya que el evento es puramente de retrollamada y no realiza ninguna recarga por sí misma.

Disparar Eventos

Para enviar un evento, necesita un objeto que implemente la interfaz :javadoc:`Evento`.

Puede disparar eventos utilizando el bus de evento (EventManager):

boolean cancelled = Sponge.getEventManager().post(theEventObject);

El método devuelve verdadero si el evento fue cancelado, falso si no es así.

Disparar Eventos de Sponge

Es posible generar instancias de eventos incorporados con la SpongeEventFactory estática. Esta clase es generada automáticamente por lo que no hay Javadocs. Utilice la autocompletación de su IDE para listar los métodos existentes. Los eventos creados por la SpongeEventFactory son pasados luego al EventManager#post(Event).

Ejemplo: Disparar el LightningEvent

import org.spongepowered.api.event.action.LightningEvent;
import org.spongepowered.api.event.cause.Cause;
import org.spongepowered.api.event.cause.EventContext;
import org.spongepowered.api.event.cause.EventContextKeys;
import org.spongepowered.api.event.SpongeEventFactory;

PluginContainer plugin = ...;
EventContext eventContext = EventContext.builder().add(EventContextKeys.PLUGIN, plugin).build();

LightningEvent lightningEvent = SpongeEventFactory.createLightningEventPre(Cause.of(eventContext, plugin));
Sponge.getEventManager().post(lightningEvent);

Advertencia

Una :javadoc:`Causa` nunca puede estar vacía. Por lo menos debe incluir el contenedor de su complemento.