Event API Reference

This page has been suggested for inclusion in the Official Documentation This page has been marked for inclusion in the Bukkit Offical Documentation section, Docs. You can deliberate about it's inclusion on it's 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

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

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