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

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

import org.spongepowered.api.event.Listener;

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

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

Совет

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

Примечание

Шина событий поддерживает супертипы. Например, :javadoc:`ChangeBlockEvent.Break` наследует ChangeBlockEvent. Таким образом, плагин может слушать ChangeBlockEvent и все равно обрабатывать ChangeBlockEvent.Break. Однако плагин, прослушивающий только ChangeBlockEvent.Break, не будет уведомлен о других типах ChangeBlockEvent.

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

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.

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

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

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

Некоторые плагины (таких как скриптовые плагины) могут захотеть динамически регистрировать слушателя событий. В этом случае слушатель событий - это не метод с аннотацией @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.All> {

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

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

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

Совет

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

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

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

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

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

PluginContainer plugin = ...;
Sponge.eventManager().unregisterListeners(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 настроен так, что ваш слушатели событий не будут вызываться, если событие отменяемое и было отменено (например, другим плагином).

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
}

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

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

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

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

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

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