Event API Reference

This page is part of the official Bukkit Documentation This page has been accepted and included in the official Bukkit Documentation. You can discuss discrepancies, issues, or errors in the article on its Talk page.

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 function

Setting up the function

Like before, you need a function to listen to the event:

public void onPlayerLogin(PlayerLoginEvent event) {
    // Your code here...
}

Now, we need the Event Handler.

EventHandler

The "EventHandler" class is an Annotation, which goes just above your function. 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.

Note: You must specify a specific event or Bukkit will not register it

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	EventPriority.MONITOR EventPriority.HIGHEST EventPriority.HIGH EventPriority.NORMAL EventPriority.LOW EventPriority.LOWEST
boolean	ignoreCancelled	false	If set to true, your function will not get the event if the event has been cancelled	true false

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