minecraft
Auditeurs d'événement à Bukkit

Créer un écouteur d'événement

Pour enregistrer vos méthodes, la classe contenant le ou les gestionnaires d'événements doit implémenter l'interface Listener.

import org.bukkit.event.Listener;

public final class ListenerClass implements Listener {
}

Vous devez enregistrer l'écouteur d'événement en ajoutant l'appel suivant à votre méthode onEnable dans la classe qui étend JavaPlugin:

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

Pour écouter un événement donné dans votre classe d'écouteur, vous devez créer une méthode avec l'annotation @EventHandler sur la méthode. Le type d'événement est spécifié par le Type dans le seul argument de la méthode. La méthode peut être nommée comme vous le souhaitez.

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!");
    }
}

Paramètres EventHandler

L'annotation org.bukkit.event.EventHandler accepte quelques paramètres.

priority - Indique la priorité de votre écouteur. Il y a six priorités différentes, dans l'ordre d'exécution: LOWEST, LOW, NORMAL [défaut], HIGH, HIGHEST, MONITOR. Ces constantes font référence à l' org.bukkit.event.EventPriority .

Si vous voulez changer le résultat d'un événement, choisissez très soigneusement de LOWEST à HIGHEST. Suggestions de plug-ins de protection généralisés sur LOWEST, plug-ins plus spécifiques sur NORMAL, et remplacement des plug-ins sur HIGH. Si vous souhaitez agir lorsqu'un événement se produit, mais ne changez pas le résultat, utilisez MONITOR.

Remarque: la priorité MONITOR ne doit être utilisée que pour la lecture. Cette priorité est utile pour consigner les plug-ins afin de voir les résultats d'un événement et la modification des valeurs peut interférer avec ces types de plug-ins.

ignoreCancelled - Un booléen qui indique si votre auditeur doit ou non tirer si l'événement a été annulé avant que ce soit le tour de l'auditeur de gérer l'événement. Faux par défaut.

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
    }
}

Création d'événements personnalisés

Parfois, vous devez créer votre propre événement, un autre que les autres plug-ins peuvent écouter (Vault, parmi d'autres, fait cela) et même annuler. L'API d'événement de Bukkit permet cela. Tout ce que vous devez faire est de faire une nouvelle classe, faites prolonger l' Event , ajoutez les gestionnaires et les attributs nécessaires à votre événement (comme joueur ou un message).

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

Appel de votre événement personnalisé

Vous contrôlez la création et l'appel de vos événements, à vous de choisir. Voici un exemple

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

Rappelez-vous: vous contrôlez vos événements. Si vous ne l'appelez pas et agissez en conséquence, cela n'arrive pas!

Écouter un événement personnalisé

L'écoute d'un événement personnalisé est identique à l'écoute d'un événement 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
    }
}

Rendre votre CustomEvent annulable

Si vous souhaitez que votre événement soit annulable, ajoutez simplement des implements Cancellable , boolean cancelled et un getter et un 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;
    }
}

Ensuite, vous devriez vérifier si un plug-in a annulé l'événement personnalisé.

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

Désinscription d'événements ou d'auditeurs

Vous pouvez désinscrire des événements individuels, des classes entières d'écoute ou tous les événements enregistrés par votre plugin ou même par d'autres plugins!

Annuler l'enregistrement d'un événement spécifique

Chaque classe d'événement a la méthode statique getHandlerList (), appelez cela et vous pouvez ensuite utiliser la méthode .unregister ().

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

Vous savez maintenant pourquoi vous aurez besoin de getHandlerList () dans vos événements personnalisés.

Annuler l'enregistrement de tous les événements

En utilisant la classe HandlerList et sa méthode statique unregisterAll (), vous pouvez facilement désinscrire les événements des classes d'écoute ou des plug-ins.

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