Using the Event API - Historical

Applied By The_Doctor_123: Mar 12, 2015 at 3:32 AM

Using the Event API

Using the Event API


One of the best features of using Spigot is the ability to intercept a wide range of events. This tutorial will demonstrate how to get started on listening to and intercepting events.

1) Creating your First Listener

1.1) Create a new Spigot project
Or use an existing project.
1.2) Create a new class
Name this class whatever you wish, keeping in mind that this class will listen to events.
1.3) Preparing your listener
Listeners must implement the org.bukkit.event.Listener interface. Your listener class should now look like so:
Code (PHP):
import org.bukkit.event.Listener;

public class MyListener implements Listener
{

}
1.4) Registering your listener
It is now necessary to register an instance of this class so Spigot is able to pass events to your plugin. A common area to create a new instance of your listener and register it is in your onEnable() method in your main class. Example:
Code (PHP):
@Override
public void onEnable()
{
    getServer().getPluginManager().registerEvents(new MyListener(), this);
}
You are now ready to proceed to add events to your listener.
1.5) Listening to events
To listen to any given event in your listener class, you must create a method with the org.bukkit.event.EventHandler annotation attached and the event is specified by the type in the method's argument. The method may be named whatever you wish. Example:
Code (PHP):
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerJoinEvent;

public class MyListener implements Listener
{
     @EventHandler
     public void onPlayerJoin(PlayerJoinEvent event)
     {

     }
}
This method will fire whenever a player joins the server. Let's make this broadcast a greeting to the whole server:
Code (PHP):
import org.bukkit.Bukkit;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerJoinEvent;

public class MyListener implements Listener
{
     @EventHandler
     public void onPlayerJoin(PlayerJoinEvent event)
     {
         Bukkit.broadcastMessage("Welcome to the server!");
     }
}
1.6) Manipulating events
You may modify what happens with most events and also obtain information about the given event. These functions are stored in the Event object in your method. Let's modify the message that is broadcasted when a player joins the server:
Code (PHP):
import org.bukkit.Bukkit;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerJoinEvent;

public class MyListener implements Listener
{
     @EventHandler
     public void onPlayerJoin(PlayerJoinEvent event)
     {
         event.setJoinMessage("Welcome, " + event.getPlayer().getName() + "!");
     }
}
1.7) What can I listen to?
Browse through the org.bukkit.event package for a full list of events you can listen to. See the Spigot JavaDocs.

2) Advanced Functions

2.1) EventHandler parameters
The org.bukkit.event.EventHandler annotation accepts a couple parameters.

priority - Indicates the priority of your listener. There are the six different priorities, in order of execution: HIGHEST, HIGH, NORMAL[default], LOW, LOWEST, MONITOR. These constants refer to the org.bukkit.event.EventPriority enum.

Note: The MONITOR priority should only be used for reading only. This priority is useful for logging plugins to see the results of an event and modifying values may interfere with those types of plugins.

ignoreCancelled - A boolean which indicates whether or not your listener should fire if the event has been cancelled before it is the listener's turn to handle the event. False by default.

Example:
Code (PHP):
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.Listener;
import org.bukkit.event.player.AsyncPlayerChatEvent;

public class MyListener implements Listener
{
     // Executes before the second method because it has a much higher priority.
     @EventHandler (priority = EventPriority.HIGHEST)
     public void onPlayerChat1(AsyncPlayerChatEvent event)
     {
         event.setCancelled(true);
     }

     // Will not execute unless another listener with a mid-priority has uncancelled the event.
     @EventHandler (priority = EventPriority.LOWEST, ignoreCancelled = true)
     public void onPlayerChat2(AsyncPlayerChatEvent event)
     {
         System.out.println("This shouldn't be executing.");
     }
}
2.2) Unregistering a listener
Unfortunately, unregistering a listener isn't as straight-forward as registering, though it is not difficult at all. This is how it is done:
Code (PHP):
// import org.bukkit.event.HandlerList
HandlerList.unregisterAll(Listener);