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

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

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

О @Listener

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

order является приоритетом, в котором должны выполняться слушатели событий. Смотрите перечисления Order в SpongeAPI, чтобы узнать доступные параметры.
beforeModifications указывает, должен ли слушатель событий вызываться перед другими модами сервера, такими как моды Forge. По умолчанию установлено значение false.

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

GameReloadEvent

Для того, чтобы все плагины не добавляли собственную команду перезагрузки плагина, Sponge предоставляет встроенное событие, которое будет прослушиваться и обрабатываться, выполняя любые действия по перезагрузке. Функционал который предоставляет „перезагрузку“, зависит только от плагина. GameReloadEvent сработает, когда игрок выполнит команду перезагрузки /sponge plugins reload. Событие не обязано ограничивается перезагрузкой конфигурации.

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

It is possible to generate instances of built-in events with the static SpongeEventFactory. The events created by the SpongeEventFactory are then passed to EventManager#post(Event).

Пример: Вызов LightningEvent

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

LightningEvent lightningEvent = SpongeEventFactory.createLightningEvent(Cause.source(plugin).build());
Sponge.getEventManager().post(lightningEvent);

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

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