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

The event bus supports supertypes. For example, ChangeBlockEvent.All extends ChangeBlockEvent. Therefore, a plugin could listen to ChangeBlockEvent and still receive ChangeBlockEvent.Alls. However, a plugin listening to just ChangeBlockEvent.All would not be notified of other types of ChangeBlockEvent.

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

To register event listeners annotated by @Listener that are not in the main plugin class, you can use EventManager#registerListeners(PluginContainer, Object), which accepts a reference to the plugin and an instance of the class containing the event listeners.

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.eventManager().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.All> {

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

Ejemplo: Registrar Dinámicamente el Detector de Eventos

EventListener<ChangeBlockEvent.All> listener = new ExampleListener();
EventListenerRegistration registeration = EventListenerRegistration
    .builder(ChangeBlockEvent.All.class)
    .listener(listener)
    .plugin(pluginContainer)
    .build();
Sponge.eventManager().registerListener(registeration);

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.eventManager().unregisterListeners(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).

RefreshGameEvent

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 refresh actions. What constitutes as a “refresh action” is purely up to the plugin to decide. The RefreshGameEvent will fire when a player executes the /sponge plugins refresh command. The event is not necessarily limited to reloading configuration.

import org.spongepowered.api.event.lifecycle.RefreshGameEvent;

@Listener
public void refresh(GameRefreshEvent event) {
    // Do refresh 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.eventManager().post(theEventObject);

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