Event API Reference/de

Mit Minecraft 1.1 wurde ein neues Event System in die Bukkit API eingebaut. Dieses neue System ist einfacher, schneller und insgesamt besser als das Alte.

Video Tutorial

Wenn du lieber in einem Video sehen willst, wie das neue Event System funktioniert, schaue hier nach: here. (Momentan leider nur in Englisch)

Einstieg

Um diesen Teil einfach zu gestalten werden wir mit einem PlayerLoginEvent arbeiten. Fangen wir an, eine Funktion zu entwickeln:

Neue Funktionen entwickeln

Wie früher benötigen wir eine Funktion, um auf ein auftretendes Event zu reagieren:

public void onPlayerLogin(PlayerLoginEvent event) {
    // Dein Code hier...
}

Allerdings brauchen wir, im Unterschied zu früher, einen Event Handler.

EventHandler

Die "EventHandler" Klasse ist eine Anmerkung, welche über unsere Funktion geschrieben werden muss.

In unserem Beispiel sieht das folgendermaßen aus:

@EventHandler // EventPriority.NORMAL by default

Diese Anmerkung markiert unserere Funktion, als einen EventHandler mit der Priörität NORMAL.

Um die Priorität unseres EventHandlers zu bestimmen, können wir ihm eine EventPriority zuweisen:

@EventHandler(priority = EventPriority.HIGHEST) // EventHandler hat höchste Priorität
@EventHandler(priority = EventPriority.LOW) // EventHandler hat niedrige Priorität

So würde die mit dem EventHandler versehene Funktion in unserem Plugin aussehen:

@EventHandler
public void onPlayerLogin(PlayerLoginEvent event) {
    // Dein Code hier...
}

Listener hinzufügen

Anders als zuvor müssen wir das Interface Listener implementieren und nicht mehr vom PlayerListener erben.

Dementsprechend sollte unsere Klasse folgendermaßen aussehen:

public class myPlayerListener implements Listener {
    @EventHandler
    public void onPlayerLogin(PlayerLoginEvent event) {
        // Dein Code hier...
    }
}

Auch könnte es interessant sein zu wissen, dass der Name der Funktion (onPlayerLogin) keine Rolle mehr spielt. Man kann die Funktion nach den eigenen Vorlieben bennenen.

Aber woran erkennt Bukkit dann, welches Ereigniss von der Funktion bearbeitet wird? Es erkennt es an dem Ereigniss, in unserem Fall: PlayerLoginEvent.

Note: Man muss ein bestimmtes Event angeben oder Bukkit wird die Funktion nicht registrieren

Konfiguration des EventHandlers

Der EventHandler kann verschiedene Eigenschaften haben:

Typ	Name	Standardwert	Beschreibung	Werte
EventPriority	priority	EventPriority.NORMAL	Legt die Priorität fest	EventPriority.MONITOR EventPriority.HIGHEST EventPriority.HIGH EventPriority.NORMAL EventPriority.LOW EventPriority.LOWEST
boolean	ignoreCancelled	false	Wenn es auf true gestellt ist, werden abgebrochene Ereignisse nicht bearbeitet	true false

Events Registrieren

Um Functionen zu registrieren, muss, wie zuvor erwähnt, die Klasse mit den EventHandler den Listener implementieren.

import org.bukkit.event.Listener;

public class LoginListener implements Listener {
}

In der Hauptklasse von deinem Plugin muss nur noch die Event Klasse registriert weren:

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

Beispiel Listener

Dieser Listener besteht aus zwei EventHandler. Bei einem wurde die Priorität HIGH gesetzt, beim anderen 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) {
        // Tu was...
    }

    @EventHandler(priority = EventPriority.HIGH)
    public void highLogin(PlayerLoginEvent event) {
        // Tu was...
    }
}

Events im Plugin registrieren

Die registerEvents funktion benötigt einen Listener und ein Plugin. Zum Glück haben wir bereits ein LoginListener. Jetzt geht es nur um das LoginPlugin!

import org.bukkit.plugin.java.JavaPlugin;

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

Events mit Plugins als Listener registrieren

Anstatt eine neue Klasse für die Events anzulegen, kannst du das auch in deiner eigentlichen Klasse reinschreiben, wie in diesem Beispiel:

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) {
        // Tu was...
    }
}

Events im Listener registrieren

Es gibt viele Möglichkeiten, Events zu registrieren. Hier ist ein Beispiel wo du diese in der Listener Klasse registrierst:

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) {
        // Tu was...
    }

    @EventHandler(priority = EventPriority.HIGH)
    public void highLogin(PlayerLoginEvent event) {
        // Tu was...
    }
}

Das LoginPlugin würde so aussehen:

import org.bukkit.plugin.java.JavaPlugin;

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

Persönliche Events erstellen

Persönliche Events sind besser wie nie zuvor! Du musst nicht mehr überprüfen, ob es deine Events sint, da sie es immer sein werden! Du kannst das selbe System wie Bukkit verwenden, ohne dass die Leistung beeinträchtigt wird.

Es gibt zwei (2) Sachen, die du dir merken musst, wenn du persönliche Events erstellst. Sie heißen "extend Event" und "static handlers". Mit static handlers musst du folgenden Code in dein Event schreiben:

private static final HandlerList handlers = new HandlerList();

public HandlerList getHandlers() {
    return handlers;
}

public static HandlerList getHandlerList() {
    return handlers;
}

Dieser Code setzt die EventHandler sogar in dein Event ein. Daraus folgt eine höhere Geschwindigkeit und hält die Events auseinander.

Beispiel zu einem persönlichen Event

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

Persönliches Event aufrufen

Ein Event aufzurufen funktioniert wie zuvor:

// Neues Event laden bzw. erstellen
CustomEvent event = new CustomEvent("Beispiel Nachricht");
// Event aufrufen
Bukkit.getServer().getPluginManager().callEvent(event);
// Jetzt kommt das Event
Bukkit.getServer().broadcastMessage(event.getMessage());

Auf ein persönliches Event hören

Wie hört man auf ein persönliches Event? Einfach, genau wie man ein normales Event hört!

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

public class CustomListener implements Listener {
    @EventHandler
    public void normalLogin(CustomEvent event) {
        // Tue etwas...
    }
}