Event API Reference/ru

С версии Minecraft 1.1 в Bukkit API была введена новая система событий. Эта система проще, быстрее, и более разносторонняя. Для более детальной информации читайте далее.

Видео-инструкция

Если вы сначала хотите посмотреть видео-инструкцию, используйте эту ссылку.

Основы

Чтобы оставить эту часть простой, сейчас будем работать только с событием PlayerLoginEvent. Давайте начнём с установки этой функции.

Установка функции

Для начала вам нужна функция для регистрации события:

public void onPlayerLogin(PlayerLoginEvent event) 
{
    // Ваш код
}

Далее вам понадобится обработчик событий.

Обработчик событий

Класс "EventHandler" — аннотация, которая идёт выше вашей функции. Выглядит это следующим образом:

@EventHandler // EventPriority.NORMAL - стандартный приоритет

Это помечает вашу функцию как обработчик события со стандартным приоритетом.

Контроллер обработчиков событий использует приоритет обработчика для управления последовательностью выполнения событий. Выглядит следующим образом:

@EventHandler(priority = EventPriority.HIGHEST) // Задаёт вашему обработчику наивысший приоритет
@EventHandler(priority = EventPriority.LOW) // Задаёт низкий приоритет

Пример того, как это должно выглядеть в вашем классе:

@EventHandler
public void onPlayerLogin(PlayerLoginEvent event) {
    // Ваш код
}

Добавляем обработчик события

В отличие от старых версий, где вам нужно было расширять класс классом PlayerListener, теперь достаточно реализовать интерфейс Listener.

Вот то, каким образом ваш класс может выглядеть в данный момент:

public class myPlayerListener implements Listener {
    @EventHandler
    public void onPlayerLogin(PlayerLoginEvent event) {
        // Ваш код
    }
}

Важно запомнить, что название функции более не имеет значения, вы можете назвать функцию так, как захотите.

Вы можете спросить: "Как Bukkit знает, какой тип события он обрабатывает?". Он читает то, что вы принимаете в качестве параметра. Пример: PlayerLoginEvent.

Note: Вы должны выбрать определённое принимаемое событие, иначе Bukkit не будет его обрабатывать

Настройки EventHandler

Обработчик событий может указывать на разные параметры. В данный момент вы можете указать:

Тип	Имя	По умолчанию	Описание	Значения
EventPriority	priority	EventPriority.NORMAL	Устанавливает приоритет вашего регистратора	EventPriority.MONITOR EventPriority.HIGHEST EventPriority.HIGH EventPriority.NORMAL EventPriority.LOW EventPriority.LOWEST
boolean	ignoreCancelled	false	Если установить значение True, то ваш метод не получит событие, если то было отменено.	true false

Регистрация события

Для регистрации ваших функций, класс, содержащий EventHandler'ы, должен быть унаследован от класса Listener.

import org.bukkit.event.Listener;

public class LoginListener implements Listener 
{
    // Ваш код
}

Для регистрации его в менеджере плагинов нужно лишь передать регистратору событий слушатель и сам плагин.

getServer().getPluginManager().registerEvents(Listener, Plugin);

Пример

Этот слушатель содержит два EventHandler'а. Приоритет одного выставлен на HIGH, а другого на NORMAL.

import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.player.PlayerLoginEvent;

public class LoginListener implements Listener 
{
    @EventHandler
    public void normalLogin(PlayerLoginEvent event) 
    {
        // Ваш код
    }

    @EventHandler(priority = EventPriority.HIGH)
    public void highLogin(PlayerLoginEvent event) 
    {
        // Ваш код
    }
}

Регистрация события в плагине

Функция registerEvents требует слушатель и плагин. К счастью, у нас уже есть LoginListener. Теперь перейдём к LoginPlugin:

import org.bukkit.plugin.java.JavaPlugin;
public class LoginPlugin extends JavaPlugin 
{
    public void onEnable() 
    {
        getServer().getPluginManager().registerEvents(new LoginListener(), this);
    }
}

Регистрация события в плагине, реализованном как слушатель

Вы можете регистрировать события в главном классе, например:

import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.player.PlayerLoginEvent;

public class LoginPlugin extends JavaPlugin implements Listener 
{
    public void onEnable() 
    {
        getServer().getPluginManager().registerEvents(this, this);
    }

    @EventHandler
    public void normalLogin(PlayerLoginEvent event) 
    {
        // Ваш код
    }
}

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

Есть достаточно много способов зарегистрировать ваше событие, например:

import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.player.PlayerLoginEvent;

public class LoginListener implements Listener 
{
    public LoginListener(LoginPlugin plugin) 
    {
        plugin.getServer().getPluginManager().registerEvents(this, plugin);
    }

    @EventHandler
    public void normalLogin(PlayerLoginEvent event) 
    {
        // Ваш код
    }

    @EventHandler(priority = EventPriority.HIGH)
    public void highLogin(PlayerLoginEvent event) 
    {
        // Ваш код
    }
}

Плагин входа может выглядеть так:

import org.bukkit.plugin.java.JavaPlugin;

public class LoginPlugin extends JavaPlugin 
{
    public void onEnable() 
    {
        new LoginListener(this);
    }
}

Создание собственных событий

Собственные события теперь намного круче, чем раньше! Больше не нужно проверять, чьими являются события, они всегда будут вашими! Вы можете использовать ту же систему, которую использует Bukkit без потери производительности.

Есть две вещи, которые стоит помнить, когда вы создаёте собственное событие. Есть расширение событий и статические обработчики. Со статическими обработчиками, вам необходимо использовать следующий код для вашего собственного события:

private static final HandlerList handlers = new HandlerList();

public HandlerList getHandlers() 
{
    return handlers;
}

public static HandlerList getHandlerList() 
{
    return handlers;
}

Этот код позволяет обработчикам событий находиться внутри самого события. Большая скорость и содержит события полностью разделенными.

Custom Event Example

import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;

public class CustomEvent extends Event {
    private static final HandlerList handlers = new HandlerList();
    private String message;

    public CustomEvent(String example) {
        message = example;
    }

    public String getMessage() {
        return message;
    }

    public HandlerList getHandlers() {
        return handlers;
    }

    public static HandlerList getHandlerList() {
        return handlers;
    }
}

Вызов собственного события

Вызов события такой же, как и прежде:

// Создаём событие
CustomEvent event = new CustomEvent("Sample Message");
// Вызываем событие
Bukkit.getServer().getPluginManager().callEvent(event);
// Выполняем событие
Bukkit.getServer().broadcastMessage(event.getMessage());

Прослушивание собственного события

Обрабатывать собственное событие следует так же, как и прослушивание обычного события:

import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;

public class CustomListener implements Listener {
    @EventHandler
    public void normalLogin(CustomEvent event) {
        // Ваш код
    }
}