Слушатели событий

Чтобы прослушать событие, слушатель события должен быть зарегистрирован. Это делается путем создания метода с любым именем, определяя первый параметр как желаемый тип события, а затем прикрепляя аннотацию Listener к методу, как показано ниже.

import org.spongepowered.api.event.Listener;

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

Кроме того, класс, содержащий эти методы, должен быть зарегистрирован в менеджере событий:

Совет

Для слушателей событий в вашем главном классе плагина (с аннотацией Plugin) вам не нужно регистрировать слушатель событий, так как Sponge сделает это автоматически.

Примечание

Шина событий поддерживает супертипы. Например, ChangeBlockEvent.Break наследует ChangeBlockEvent. Поэтому плагин может прослушивать ChangeBlockEvent и все равно получать ChangeBlockEvent.Break. Однако плагин, который прослушивает только ChangeBlockEvent.Break, не будет уведомлен о других типах ChangeBlockEvent.

Регистрация и отмена регистрации слушателей событий

Для регистрации слушателей событий, с аннотацией @Listener, которые не входят в основной класс плагина, вы можете использовать метод EventManager#registerListeners(Object, Object), который принимает ссылку на плагин и экземпляр класса, содержащий слушателей событий.

Пример: Регистрация слушателей событий в других классах

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

Динамическая регистрация слушателей событий

Некоторые плагины (таких как скриптовые плагины) могут захотеть динамически регистрировать слушателя событий. В этом случае слушатель событий - это не метод с аннотацией @Listener, а скорее класс, реализующий интерфейс EventListener. Этот слушатель событий может быть зарегистрирован путем вызова EventManager#registerListener, который принимает ссылку на плагин в качестве первого аргумента, Class события, как второй аргумент, а самого слушателя в качестве последнего аргумента. При желании вы можете указать Order для запуска слушателя событий в качестве третьего аргумента или логическое значение в качестве четвертого аргумента (перед экземпляром слушателя), которое определяет, следует ли вызывать слушателя до других модификаций сервера.

Пример: Реализация 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 {
        [...]
    }
}

Пример: Динамическая регистрация слушателя событий

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

Совет

Для слушателей событий, созданных с помощью аннотации @Listener, можно настроить порядок выполнения (см. также`О @Listener`_). Для динамически зарегистрированных слушателей это возможно, используя метод EventManager#registerListener, передавая третьим аргументом Order.

Отмена регистрации слушателей событий

Чтобы отменить регистрацию одного слушателя событий, вы можете использовать метод EventManager#unregisterListeners(Object), который принимает экземпляр класса, содержащего слушателей событий.

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

Кроме того, вы можете использовать EventManager#unregisterPluginListeners(Object), передавая ссылку на плагин, чтобы отменить регистрацию всех слушателей событий, связанных с этим плагином. Обратите внимание, что это удалит все слушатели событий плагина, включая те, которые зарегистрированы с аннотациями @Listener.

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

О @Listener

У аннотации @Listener имеется несколько настраиваемых полей:

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 указывает, должен ли слушатель событий вызываться перед другими модами сервера, такими как моды Forge. По умолчанию установлено значение false.

По умолчанию @Listener настроен так, что ваш слушатели событий не будут вызываться, если событие отменяемое и было отменено (например, другим плагином).

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
}

Обратите внимание, что это отличается от того, что обычно считается „перезагрузкой“, поскольку событие является просто вызовом для плагинов и не выполняет никакой перезагрузки самостоятельно.

Вызов событий

Чтобы отправить событие, вам нужен объект, который реализует интерфейс Event.

Вы можете „бросить“ события с использованием шины событий (EventManager):

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

Метод возвращает true, если событие было отменено, иначе возвращает false.

Вызов встроенных событий Sponge

Можно создавать экземпляры встроенных событий со статическим SpongeEventFactory. Этот класс автоматически генерируется, поэтому не имеет документации. Используйте автодополнение IDE для просмотра существующих методов. События, созданные SpongeEventFactory, затем передаются в EventManager#post(Event).

Пример: Вызов 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);

Предупреждение

Cause никогда не может быть пустой. По крайней мере, она должена содержать ваш плагин-контейнер.