[Tutorial] Adding custom events!

So early on in my Bukkit life I wanted to add a custom event but all the tutorials I came across were either outdated or confused me and today I was working on events and decided that it would be a good idea to make a tutorial. So here goes nothing!

Whats a custom event good for?
Well, a custom event can be used for 1. Easy implementation of features from things that may be modified from multiple locations such as, in a magic plugin, casting a spell and draining mana. Maybe you would want to do something like send the player a message with how much mana they have left or maybe you want to check if the player is allowed to cast the spell and cancel the event if they aren't allowed to. It is also useful if you want to allow other plugin developers to hook into your plugin like if you were making an economy plugin and wanted other devs to do stuff when someone purchased something.

Making your event's class
The first thing you want to do is decide what information you want to store in your event such as, in the event of a player casting a spell, the spell that was cast and the player who cast it. Then you want to decide if your event should be cancellable. Cancellable means that the outcome of the event can be changed so if you were to cancel the spell cast event it would prevent the spell from being cast.

So to make a new event, create a new class that extends Event. If you want your class to be cancellable, then implement Cancellable. Add all the un-implemented methods.

Show Spoiler Hide Spoiler

Code:

import org.bukkit.event.Cancellable;
 
import org.bukkit.event.Event;
 
public class SpellCastEvent extends Event implements Cancellable {
 
@Override
public boolean isCancelled() {
    return false;
}
 
@Override
public void setCancelled(boolean arg0) {
}
 
@Override
public HandlerList getHandlers() {
    return null;
}
 
}

Now you will want to create a constructor for the class. For the parameters of the constructor you want to have all of the things such as the player who cast the spell and the spell that was cast etc. You can have whatever arguments you want to! For each of the parameters, you will want to have a private variable to save them to. You should also have a private boolean to store if the event is cancelled if you are implementing Cancellable.

Show Spoiler Hide Spoiler

Code:

private Player player;
private String spell;
private boolean isCancelled;
 
public SpellCastEvent(Player player, String spell) {
    this.player = player;
    this.spell = spell;
    this.isCancelled = false;
}
 
public Player getPlayer() {
    return this.player;
}
 
public String getSpell() {
    return this.spell;
}

If you are implementing Cancellable, you will also want to edit the isCancelled and setCancelled methods:

Show Spoiler Hide Spoiler

Code:

@Override
public boolean isCancelled() {
    return this.isCancelled;
}
 
@Override
public void setCancelled(boolean arg0) {
    this.isCancelled = arg0;
}

Now on to the stuff that will probably make no sense. There is something called a handler list that's purpose is to annoy everyone who is trying to make events. There is an actual purpose but it is very complicated and beyond the scope of this tutorial. So to deal with handlers you will want to add the code below to your event class. Without this code, any listener listening for the event will cause your plugin to crash!

Show Spoiler Hide Spoiler

Code:

 
private static final HandlerList handlers = new HandlerList();
 
@Override
public HandlerList getHandlers() {
    return handlers;
}
 
public static HandlerList getHandlerList() {
    return handlers;
}

Now that is about it for the event class!

Calling your event
Calling your event is very simple. You just have to make and store an instance of the event (like this: 'SpellCastEvent event = new SpellCastEvent(player, label);'). You then call the event with Bukkit.getPluginManager().callEvent(event). You can then check if the event is cancelled by simply calling event.isCancelled().

Show Spoiler Hide Spoiler

Code:

 
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (sender instanceof Player) {
    Player player = (Player) sender;
    SpellCastEvent event = new SpellCastEvent(player, label);
    Bukkit.getPluginManager().callEvent(event);
 
    if (event.isCancelled()) {
        player.sendMessage("You can't cast the spell!");
    } else {
        player.sendMessage("You have cast a spell!");
    }
}

Now you're all done! Your event can be listened for just like any event and by any plugin. Hope this helped.

 

Minnymin3 This thread is duplicated and a tutorial also exists in the bukkit wiki! See this thread: http://forums.bukkit.org/threads/tutorial-custom-events.174562/

 

I did not notice that Bukkit had one on the wiki
But as I said at the start of the tutorial I wanted to make a more clear tutorial as when I was starting out I found the tutorials on the forums annoying and hard to follow.