Ouvintes de eventos em Bukkit

Criando um ouvinte de evento

Para registrar seus métodos, a classe que contém o(s) EventHandler(es) deve implementar a interface Listener.

import org.bukkit.event.Listener;

public final class ListenerClass implements Listener {
}

Você precisa registrar o ouvinte de eventos adicionando a seguinte chamada ao seu método onEnable na classe que estende o JavaPlugin:

getServer().getPluginManager().registerEvents(new ListenerClass(), this);

Para ouvir qualquer evento em sua classe de ouvinte, você deve criar um método com a anotação @EventHandler no método. O tipo de evento é especificado pelo Type no único argumento do método. O método pode ser nomeado como você desejar.

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

public class ListenerClass implements Listener {
    @EventHandler
    public void onPlayerLogin(PlayerLoginEvent event) {
        event.getPlayer().sendMessage("Welcome to the server!");
    }
}

Parâmetros do EventHandler

A anotação org.bukkit.event.EventHandler aceita alguns parâmetros.

prioridade - Indica a prioridade do seu ouvinte. Existem seis prioridades diferentes, em ordem de execução: LOWEST,LOW,NORMAL[padrão],HIGH,HIGHEST,MONITOR. Essas constantes referem-se à enumeração org.bukkit.event.EventPriority.

Se você quiser alterar o resultado de um evento, escolha com muito cuidado de MAIS BAIXO para MAIS ALTO. Plugins de proteção generalizada sugeridos em MAIS BAIXO, plugins mais específicos em NORMAL e plugins de substituição em ALTO. Se você quiser agir quando um evento acontecer, mas não alterar o resultado, use MONITOR.

Observação: A prioridade MONITOR deve ser usada apenas para leitura. Essa prioridade é útil para plug-ins de log para ver os resultados de um evento e a modificação de valores pode interferir nesses tipos de plug-ins.

ignoreCancelled - Um booleano que indica se seu listener deve ou não disparar se o evento foi cancelado antes da vez do listener lidar com o evento. Falso por padrão.

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

public final class LoginListener implements Listener {
    @EventHandler
    public void normalLogin(PlayerLoginEvent event) {
        // Some code here
    }    

    @EventHandler(priority = EventPriority.HIGH)
    public void highLogin(PlayerLoginEvent event) {
        // Some code here
    }
}

Criando eventos personalizados

Às vezes você precisa criar seu próprio evento, um que outros plugins possam ouvir (o Vault, entre outros plugins, faz isso) e até mesmo cancelar. A API de eventos do Bukkit permite que isso seja possível. Tudo o que você precisa fazer é criar uma nova classe, estender Event, adicionar os manipuladores e os atributos que seu evento precisa (como Player ou mensagem).

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

public final 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;
    }
}

Chamando seu evento personalizado

Você está no controle de criar e chamar seus eventos, onde você chama é completamente com você. Aqui está um exemplo

// Create the event here
CustomEvent event = new CustomEvent("Sample Message");
// Call the event
Bukkit.getServer().getPluginManager().callEvent(event);
Bukkit.getServer().broadcastMessage(event.getMessage());

Lembre-se: você está no controle de seus eventos. Se você não chamar e agir de acordo com isso, isso não acontece!

Ouvindo um evento personalizado

Ouvir um evento personalizado é o mesmo que ouvir um evento normal.

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

public final class CustomListener implements Listener {
    
    @EventHandler
    public void onCustomEvent(CustomEvent event) {
    // Some code here
    }
}

Tornando seu CustomEvent cancelável

Se você quiser tornar seu evento cancelável, basta adicionar implements Cancellable, boolean cancelled e um getter e setter:

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

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

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

    public String getMessage() {
        return message;
    }

    public boolean isCancelled() {
        return cancelled;
    }

    public void setCancelled(boolean cancel) {
        cancelled = cancel;
    }

    public HandlerList getHandlers() {
        return handlers;
    }

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

Depois, você verificaria se um plug-in cancelou o evento personalizado.

// Create the event here
CustomEvent event = new CustomEvent("Sample Message");
// Call the event
Bukkit.getServer().getPluginManager().callEvent(event);
// Check if the event is not cancelled
if (!event.isCancelled()) {
    Bukkit.getServer().broadcastMessage(event.getMessage());
}

Cancelando o registro de eventos ou ouvintes

Você pode cancelar o registro de eventos individuais, classes inteiras de ouvintes ou todos os eventos registrados pelo seu plugin ou até mesmo por outros plugins!

Cancelar registro de evento específico

Cada classe de evento tem o método estático getHandlerList(), chame-o e então você pode usar o método .unregister().

PlayerInteractEvent.getHandlerList().unregister(plugin);
// this will unregister all PlayerInteractEvent instances from the plugin
// you can also specify a listener class instead of plugin.

Agora você sabe por que precisará do getHandlerList() em seus eventos personalizados.

Cancelar o registro de todos os eventos

Usando a classe HandlerList e seu método estático unregisterAll(), você pode facilmente cancelar o registro de eventos de classes de ouvintes ou plugins.

HandlerList.unregisterAll(plugin);
// this will unregister all events from the specified plugin
// you can also specify a listener class instead of plugin.