This page is part of the official Bukkit Documentation
|
As of Minecraft 1.1, there has been a new event system introduced to the Bukkit API. This new system is simpler, quicker, and better all-around. Keep reading for more details!
Video Tutorial
If you would prefer to watch a video tutorial version of this, please click here.
The Basics
To keep this section simple, we're going to only work with PlayerLoginEvent. Lets start with setting up the method
Setting up the Method
Like before, you need a method to listen to the event:
public void onPlayerLogin(PlayerLoginEvent event) { // Your code here... }
Before this method is invoked by Bukkit when the "PlayerLoginEvent" is fired, we need to annotate it.
EventHandler
The "EventHandler" class is an Annotation, which goes just above your method. It looks like this:
@EventHandler // EventPriority.NORMAL by default
This marks your function as an EventHandler with the EventPriority NORMAL.
The EventHandler can take an EventPriority to specify the priority of the function. This looks like so:
@EventHandler(priority = EventPriority.HIGHEST) // Makes your event Highest priority @EventHandler(priority = EventPriority.LOW) // Makes your event Low priority
Here's what it would look like in your class:
@EventHandler public void onPlayerLogin(PlayerLoginEvent event) { // Your code here... }
Adding the listener
Unlike before, where you needed to extend "PlayerListener", you now need to implement "Listener".
Here is what your class might look like at the moment:
public class MyPlayerListener implements Listener { @EventHandler public void onPlayerLogin(PlayerLoginEvent event) { // Your code here... } }
It might be worth mentioning that the name of the function (onPlayerLogin) no longer matters. You can now call the function anything you want inside your listener.
You may be wondering.. "How does Bukkit know which event to listen to?" It reads that from the event you specify. From the above example: PlayerLoginEvent
.
EventHandler Settings
The event handler can specify various things. At the moment you can specify:
Type | Name | Default | Description | Values |
---|---|---|---|---|
EventPriority | priority | EventPriority.NORMAL | Sets the priority of your listener |
|
boolean | ignoreCancelled | false | If set to true, your function will not get the event if the event has been cancelled |
|
Event Priorities
There are six priorities in Bukkit
- EventPriority.HIGHEST
- EventPriority.HIGH
- EventPriority.NORMAL
- EventPriority.LOW
- EventPriority.LOWEST
- EventPriority.MONITOR
They are called in the following order
- EventPriority.LOWEST
- EventPriority.LOW
- EventPriority.NORMAL
- EventPriority.HIGH
- EventPriority.HIGHEST
- EventPriority.MONITOR
Every plugin gets a say in what happens, and every plugin must get a chance to know the outcome of an event. So, we pass events to plugins even after they've been cancelled. A plugin can actually uncancel an event after another plugin cancelled it. This is where priorities become really important.
Let's say a BLOCK_PLACE event is being handled. The lowest priority listener is called to get its say in whether it should be cancelled or not. Then the low priority listener is called to see if it wants to override the lowest, etc. Eventually it hits monitor, and at this point nothing should change the outcome of the event. Monitor should be used to see the outcome of an event, without changing any aspect of it. If we have three plugins enabled; one is a basic area protection plugin, one is a fancy plugin using signs, and another is a logging plugin. The protection plugin listens on Priority.LOWEST. It says they can't place blocks in this area, and cancels the event. The fancy sign plugin listens on Priority.NORMAL. It says they can place signs here, and uncancels the event. The log plugin listens on Priority.MONITOR. It sees that the event was actually allowed, and logs it.
if you want to change the outcome of an event, choose very carefully from LOWEST to HIGHEST. Suggested generalized protection plugins on lowest, more specific plugins on normal, and override plugins on high. If you want to act when an event happens, but not change the outcome, use monitor. It's really really important that you use monitor, or an event might get cancelled after you've acted from it, and it's even more important that you don't change the outcome of the event on monitor or it'll break other plugins.
Registering Events
To register your functions, the class containing the EventHandler(s) must implement the Listener class.
import org.bukkit.event.Listener; public class LoginListener implements Listener { }
You only need to provide a plugin and a listener to register them in the PluginManager.
getServer().getPluginManager().registerEvents(Listener, Plugin);
Example Listener
This listener contains two EventHandlers. One listening on HIGH, and one on 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) { // Some code here } @EventHandler(priority = EventPriority.HIGH) public void highLogin(PlayerLoginEvent event) { // Some code here } }
Registering Events in Plugin
The registerEvents function requires a listener and a plugin. Luckily, we already have our LoginListener. Now for the LoginPlugin!
import org.bukkit.plugin.java.JavaPlugin; public final class LoginPlugin extends JavaPlugin { public void onEnable() { getServer().getPluginManager().registerEvents(new LoginListener(), this); } }
Registering Events with Plugin as Listener
You could even have the events in the main class, for example:
import org.bukkit.plugin.java.JavaPlugin; import org.bukkit.event.Listener; import org.bukkit.event.EventHandler; import org.bukkit.event.player.PlayerLoginEvent; public final class LoginPlugin extends JavaPlugin implements Listener { public void onEnable() { getServer().getPluginManager().registerEvents(this, this); } @EventHandler public void normalLogin(PlayerLoginEvent event) { // Some code here } }
Registering Events in your Listener
There are many ways to register your events. Here's an example where you register them in your listener class.
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) { // Some code here } @EventHandler(priority = EventPriority.HIGH) public void highLogin(PlayerLoginEvent event) { // Some code here } }
The LoginPlugin would look like this:
import org.bukkit.plugin.java.JavaPlugin; public class LoginPlugin extends JavaPlugin { public void onEnable() { new LoginListener(this); } }
Un-registering events or listeners
You can unregister individual events, entire listener classes or all events registered by your plugin or even by other plugins!
Un-register specific event
Each event class has the getHandlerList() static method, call that and then you can use .unregister() method. Example:
PlayerInteractEvent.getHandlerList().unregister(plugin); // this will unregister all PlayerInteractEvent instances from the plugin // you can also specify a listener class instead of plugin.
Now you know why you'll need the getHandlerList() in your custom events.
Un-register all events
Using the HandlerList class and its unregisterAll() static method you can easily unregister events from listener classes or plugins. Example:
HandlerList.unregisterAll(plugin); // this will unregister all events from the specified plugin // you can also specify a listener class instead of plugin.
Creating Custom Events
Custom events are better than ever! No longer do you have to check if the events are yours, they always will be! You can use the same system that Bukkit uses without ruining performance.
There are two (2) things to keep in mind when you create a Custom Event. They are "extend Event" and "static handlers." With static handlers, you must input the following code into your custom event:
private static final HandlerList handlers = new HandlerList(); public HandlerList getHandlers() { return handlers; } public static HandlerList getHandlerList() { return handlers; }
This block of code makes the EventHandlers actually contained inside of your event. Improving speed, and keeping the events completely separated.
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; } }
Calling a Custom Event
Calling the event would be the same as before:
// Create the event here CustomEvent event = new CustomEvent("Sample Message"); // Call the event Bukkit.getServer().getPluginManager().callEvent(event); // Now you do the event Bukkit.getServer().broadcastMessage(event.getMessage());
Listening to a Custom Event
How do you listen to a custom event you say? Simple, the same way as listening to a normal event!
import org.bukkit.event.Listener; import org.bukkit.event.EventHandler; public class CustomListener implements Listener { @EventHandler public void normalLogin(CustomEvent event) { // Some code here } }
Language | English • беларуская • Deutsch • español • suomi • français • italiano • 한국어 • Nederlands • norsk • polski • português • русский • lietuvių • čeština |
---|