Nasłuchiwacze wydarzeń

In order to listen for an event, an event listener must be registered. This is done by making a method with any name, defining the first parameter to be the desired event type, and then affixing the Listener annotation to the method, as illustrated below.

import org.spongepowered.api.event.Listener;

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

In addition, the class containing these methods must be registered with the event manager:

Wskazówka

For event listeners on your main plugin class (annotated by Plugin), you do not need to register the object for events as Sponge will do it automatically.

Informacja

Event bus obsługuje supertypy. Dla przykładu, ChangeBlockEvent.All dziedziczy ChangeBlockEvent. Z tego powodu, plugin mógłby nasłuchiwać na ChangeBlockEvent i dalej otrzymywać ChangeBlockEvent.All. Jednakże, plugin nasłuchujący tylko na ChangeBlockEvent.All nie zostanie poinformowany o innych typach ChangeBlockEvent.

Rejestrowanie i wyrejestrowywanie detektorów zdarzeń

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.

Example: Registering Event Listeners in Other Classes

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());

Dynamiczne rejestrowanie detektorów zdarzeń

Some plugins (such as scripting plugins) may wish to dynamically register an event listener. In that case the event listener is not a method annotated with @Listener, but rather a class implementing the EventListener interface. This event listener can then be registered by calling EventManager#registerListener, which accepts a reference to the plugin as the first argument, the Class of events handled as the second argument, and the listener itself as the final argument. Optionally, you can specify an Order to run the event listener in as the third argument or a boolean value as the fourth argument (before the instance of the listener) which determines whether to call the listener before other server modifications.

Przykład: Implementowanie 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 {
        [...]
    }
}

Example: Dynamically Registering the Event Listener

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

Wskazówka

For event listeners created with the @Listener annotation, the order of the execution can be configured (see also About @Listener). For dynamically registered listeners this is possible by passing an Order to the third argument the EventManager#registerListener method.

Unregistering Event Listeners

Aby wyrejestrować pojedynczy event listener, możesz użyć metody EventManager#unregisterListeners(Object), która przyjmuje instancję klasy zawierającą event listenery.

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

Alternatywnie, możesz użyć EventManager#unregisterPluginListeners(Object), przesyłając referencje do pluginu, aby wyrejestrować wszystkie event listenery dla tego pluginu. Zauważ, że usunie to wszystkie event listenery pluginu, w tym te, zarejestrowane adnotacją @Listener.

PluginContainer plugin = ...;
Sponge.eventManager().unregisterListeners(plugin);

O @Listener

The @Listener annotation has a few configurable fields:

• 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 określa czy event listener powinien zostać wywołany przed innymi modyfikacjami serwerowymi takimi jak mody Forge. Domyślnie ustawione jest to na false.

Domyślnie, @Listener jest skonfigurowany tak, że Twój event listener nie zostanie wywoływany, jeśli dany event można anulować i został anulowany (np. przez inny plugin).

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
}

Note that this is different for what generally is considered a «reload», as the event is purely all callback for plugins and does not do any reloading on its own.

Wywoływanie zdarzeń

To dispatch an event, you need an object that implements the Event interface.

You can fire events using the event bus (EventManager):

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

Metoda zwraca true, jeśli zdarzenie zostało anulowane, false, jeśli nie.