Making your own events

Paper's events tell your plugin what happens in the game. Your own events let your plugin tell other code what happens in your plugin: "this player just joined for the first time", "this player reached a diamond milestone". On this page you will write two custom events, fire them, listen to them, and make one that listeners can cancel and change.

Why make your own events?

Imagine you want three things to happen when a brand new player joins: they get a starter kit, everyone sees a welcome announcement, and later maybe a tutorial starts. You could put all three in one big PlayerJoinEvent handler. It works, but the handler grows with every feature, and every feature has to repeat the "is this the first join?" check.

A custom event splits the job in two:

• One place decides that something happened, and announces it by firing the event.
• Any number of listeners react, each in its own small class, without knowing about each other.

Programmers call this decoupling: the parts of your plugin depend on the event, not on each other. Adding a fourth feature means adding one more listener, and nothing else changes. It also opens your plugin to other plugins: they can listen to your events exactly like they listen to Paper's, and even cancel or change them. That is how big plugins such as economy, protection and minigame plugins let others build on top of them.

Your first custom event

The FirstJoin plugin fires a PlayerFirstJoinEvent whenever a player joins the server for the very first time. An event is a normal Java class with a few required parts. Here is all of it:

1package com.example.customeventsfirst;2 3import org.bukkit.entity.Player;4import org.bukkit.event.Event;5import org.bukkit.event.HandlerList;6 17public final class PlayerFirstJoinEvent extends Event {8 29    private static final HandlerList HANDLERS = new HandlerList();10 311    private final Player player;12 413    public PlayerFirstJoinEvent(Player player) {14        this.player = player;15    }16 517    public Player getPlayer() {18        return player;19    }20 21    @Override622    public HandlerList getHandlers() {23        return HANDLERS;24    }25 726    public static HandlerList getHandlerList() {27        return HANDLERS;28    }29}

Every custom event has this same skeleton. The only parts that change from event to event are the class name and the information it carries. The handler-list part is boilerplate: copy it as it is.

Firing the event

An event does nothing until something fires it. This listener watches Paper's PlayerJoinEvent and fires the custom event for first joins only:

1package com.example.customeventsfirst;2 3import org.bukkit.entity.Player;4import org.bukkit.event.EventHandler;5import org.bukkit.event.Listener;6import org.bukkit.event.player.PlayerJoinEvent;7 8public final class FirstJoinDetector implements Listener {9 10    @EventHandler111    public void onJoin(PlayerJoinEvent event) {12        Player player = event.getPlayer();213        if (player.hasPlayedBefore()) {14            return;15        }316        PlayerFirstJoinEvent firstJoin = new PlayerFirstJoinEvent(player);417        firstJoin.callEvent();18    }19}

callEvent() is a Paper shortcut. In older code you will see the same thing written as Bukkit.getPluginManager().callEvent(firstJoin); both do the same job.

Listening to it

Listening to a custom event is exactly the same as listening to a Paper event. The parameter type is your event class:

1package com.example.customeventsfirst;2 3import org.bukkit.Material;4import org.bukkit.entity.Player;5import org.bukkit.event.EventHandler;6import org.bukkit.event.Listener;7import org.bukkit.inventory.ItemStack;8 9public final class StarterKitListener implements Listener {10 11    @EventHandler112    public void onFirstJoin(PlayerFirstJoinEvent event) {213        Player player = event.getPlayer();314        player.getInventory().addItem(ItemStack.of(Material.STONE_SWORD), ItemStack.of(Material.BREAD, 8));15        player.sendRichMessage("<green>Here is a starter kit. Good luck out there!");16    }17}

1package com.example.customeventsfirst;2 3import net.kyori.adventure.text.minimessage.MiniMessage;4import net.kyori.adventure.text.minimessage.tag.resolver.Placeholder;5import org.bukkit.Bukkit;6import org.bukkit.event.EventHandler;7import org.bukkit.event.Listener;8 9public final class FirstJoinAnnouncer implements Listener {10 11    @EventHandler12    public void onFirstJoin(PlayerFirstJoinEvent event) {113        Bukkit.broadcast(MiniMessage.miniMessage().deserialize(14            "<gold>Everyone welcome <yellow><name></yellow>, who just joined for the first time!",215            Placeholder.unparsed("name", event.getPlayer().getName())));16    }17}

Neither listener knows about the other, or about how "first join" is detected. The main class registers all three listeners like any others:

1package com.example.customeventsfirst;2 3import org.bukkit.plugin.PluginManager;4import org.bukkit.plugin.java.JavaPlugin;5 6public final class FirstJoinPlugin extends JavaPlugin {7 8    @Override9    public void onEnable() {10        PluginManager pluginManager = getServer().getPluginManager();111        pluginManager.registerEvents(new FirstJoinDetector(), this);212        pluginManager.registerEvents(new StarterKitListener(), this);13        pluginManager.registerEvents(new FirstJoinAnnouncer(), this);14    }15}

When Alex joins for the first time, everyone sees the announcement, and Alex also gets the kit message:

Events that can be canceled and changed

The most useful custom events fire before your plugin does something, so listeners get a say. Paper's own BlockBreakEvent works this way: it fires before the block breaks, and listeners can cancel it. Your events can work the same way.

The DiamondMilestones plugin counts diamond ores each player mines. Every 10 ores, it wants to give the player experience and announce it. Before it does, it fires a DiamondMilestoneEvent, so that:

• a listener can cancel the milestone (no rewards in creative mode),
• a listener can change the reward (double experience for VIPs),
• a listener can add something (a bonus diamond every 50 ores),
• and other plugins can do the same without touching your code.

The template project example-events in paper-templates contains a smaller version of this event, if you want to compare.

1package com.example.customeventsmilestone;2 3import org.bukkit.entity.Player;4import org.bukkit.event.Cancellable;5import org.bukkit.event.HandlerList;6import org.bukkit.event.player.PlayerEvent;7 18public final class DiamondMilestoneEvent extends PlayerEvent implements Cancellable {9 10    private static final HandlerList HANDLERS = new HandlerList();11 212    private final int total;313    private int rewardXp;414    private boolean canceled;15 16    public DiamondMilestoneEvent(Player player, int total, int rewardXp) {517        super(player);18        this.total = total;19        this.rewardXp = rewardXp;20    }21 22    public int getTotal() {23        return total;24    }25 26    public int getRewardXp() {27        return rewardXp;28    }29 630    public void setRewardXp(int rewardXp) {31        this.rewardXp = Math.max(0, rewardXp);32    }33 34    @Override735    public boolean isCancelled() {36        return canceled;37    }38 39    @Override840    public void setCancelled(boolean cancel) {41        this.canceled = cancel;42    }43 44    @Override45    public HandlerList getHandlers() {46        return HANDLERS;47    }48 949    public static HandlerList getHandlerList() {50        return HANDLERS;51    }52}

Firing it and acting on the answer

For a cancelable event, callEvent() returns an answer: true if the event was not canceled, false if a listener canceled it. The firing code then does its job only when allowed, and reads back any values listeners changed:

125@EventHandler(ignoreCancelled = true)26public void onBreak(BlockBreakEvent event) {27    if (!DIAMOND_ORES.contains(event.getBlock().getType())) {28        return;29    }30    Player player = event.getPlayer();231    int total = diamondsMined.merge(player.getUniqueId(), 1, Integer::sum);332    if (total % MILESTONE_EVERY != 0) {33        return;34    }35 436    DiamondMilestoneEvent milestone = new DiamondMilestoneEvent(player, total, total * XP_PER_DIAMOND);537    if (!milestone.callEvent()) {38        return;39    }40 641    player.giveExp(milestone.getRewardXp());742    Bukkit.broadcast(MiniMessage.miniMessage().deserialize(43        "<aqua><name></aqua> <gray>mined <white><total></white> diamond ores and earned <green><xp> XP</green>!",44        Placeholder.unparsed("name", player.getName()),45        Placeholder.unparsed("total", String.valueOf(total)),46        Placeholder.unparsed("xp", String.valueOf(milestone.getRewardXp()))));47}

The listeners

Each listener is tiny and does one thing. The first one cancels:

1package com.example.customeventsmilestone;2 3import org.bukkit.GameMode;4import org.bukkit.event.EventHandler;5import org.bukkit.event.EventPriority;6import org.bukkit.event.Listener;7 8public final class NoCreativeListener implements Listener {9 110    @EventHandler(priority = EventPriority.LOW)11    public void onMilestone(DiamondMilestoneEvent event) {212        if (event.getPlayer().getGameMode() == GameMode.CREATIVE) {313            event.setCancelled(true);14        }15    }16}

The second one changes the reward:

1package com.example.customeventsmilestone;2 3import org.bukkit.event.EventHandler;4import org.bukkit.event.Listener;5 6public final class VipBonusListener implements Listener {7 18    @EventHandler(ignoreCancelled = true)9    public void onMilestone(DiamondMilestoneEvent event) {210        if (event.getPlayer().hasPermission("milestones.vip")) {311            event.setRewardXp(event.getRewardXp() * 2);12            event.getPlayer().sendRichMessage("<gold>VIP bonus: double experience!");13        }14    }15}

A VIP reaching 20 diamond ores sees this. The broadcast shows the doubled reward because MiningListener reads it after the listeners ran:

Designing good events

• Name it after what happened, ending in Event: PlayerFirstJoinEvent, DiamondMilestoneEvent, ShopPurchaseEvent.
• Fire it before the action if listeners should be able to stop or change it, and make it Cancellable. Fire it after the action if it is only news, like "a player finished a parkour run".
• Carry everything a listener needs: the player, the amounts, the item. Listeners should not have to look things up in your plugin's internals.
• Make fields final unless listeners are meant to change them, and check values in setters.
• Always read changeable values back after callEvent(), and always respect the answer.

Async custom events

Most events are fired on the main thread. If your plugin does slow work on another thread, such as loading a player's data from a database, and wants to fire an event from there, the event must say that it is asynchronous. You do that by passing true to the parent constructor:

1public PlayerDataLoadedEvent(UUID playerId) {2    super(true);3    this.playerId = playerId;4}

The rest of the class looks exactly like PlayerFirstJoinEvent. The rules are strict, and Paper checks them: an async event must be fired from a thread that is not the main thread, and a normal event must be fired from the main thread. Getting it wrong throws an IllegalStateException. Firing an async event looks like this:

1getServer().getScheduler().runTaskAsynchronously(this, () -> {2    new PlayerDataLoadedEvent(playerId).callEvent();3});

Listeners of async events follow the same rules as listeners of AsyncChatEvent: no touching the world without hopping back to the main thread first. Most plugins never need an async event; reach for one only when you are already working off the main thread. Threads, performance and lag explains threads.

Letting other plugins listen

Another plugin can listen to DiamondMilestoneEvent just like you do. It needs two things:

1. Your plugin's classes when it compiles, added as a compileOnly dependency, the same way you depend on the Paper API. For a jar you share directly, that can be as simple as compileOnly(files("libs/custom-events-milestone-1.0.0.jar")) in its build.gradle.kts.
2. depend: [DiamondMilestones] (or softdepend) in its plugin.yml, so Paper loads your plugin first. See plugin.yml explained.

Then it writes a normal @EventHandler for your event. Because the other plugin builds against your event class, renaming the class or its methods later breaks every plugin that uses it. Treat your event classes as a promise. Working with other plugins covers sharing an API in more detail.

Mistakes to avoid

• Forgetting the static getHandlerList(). It compiles, then fails when a listener registers.
• Creating a new HandlerList in getHandlers(), such as return new HandlerList();. Paper would find an empty list every time and nobody would hear the event. Always return the one static field.
• Ignoring the result of callEvent() on a cancelable event. If you reward the player anyway, canceling does nothing.
• Using the original value instead of the event's after firing, which throws away every listener's change.
• Firing an async event from the main thread, or a normal event from an async task. Paper throws an exception.
• Firing events in a tight loop. Every call runs every listener. Fire on meaningful moments, like a milestone, not on every tick.

1package com.example.customeventsmilestone;2 3import org.bukkit.Material;4import org.bukkit.entity.Player;5import org.bukkit.event.EventHandler;6import org.bukkit.event.EventPriority;7import org.bukkit.event.Listener;8import org.bukkit.inventory.ItemStack;9 10public final class JackpotListener implements Listener {11 12    private static final int JACKPOT_EVERY = 50;13 114    @EventHandler(priority = EventPriority.HIGH, ignoreCancelled = true)15    public void onMilestone(DiamondMilestoneEvent event) {216        if (event.getTotal() % JACKPOT_EVERY != 0) {17            return;18        }19        Player player = event.getPlayer();320        player.getInventory().addItem(ItemStack.of(Material.DIAMOND));21        player.sendRichMessage("<aqua>Jackpot! Here is a bonus diamond.");22    }23}

1package com.example.customeventsexercise;2 3import org.bukkit.entity.Player;4import org.bukkit.event.Cancellable;5import org.bukkit.event.Event;6import org.bukkit.event.HandlerList;7 18public final class PlayerFirstJoinEvent extends Event implements Cancellable {9 10    private static final HandlerList HANDLERS = new HandlerList();11 12    private final Player player;213    private boolean canceled;14 15    public PlayerFirstJoinEvent(Player player) {16        this.player = player;17    }18 19    public Player getPlayer() {20        return player;21    }22 23    @Override24    public boolean isCancelled() {25        return canceled;26    }27 28    @Override329    public void setCancelled(boolean cancel) {30        this.canceled = cancel;31    }32 33    @Override34    public HandlerList getHandlers() {35        return HANDLERS;36    }37 38    public static HandlerList getHandlerList() {39        return HANDLERS;40    }41}

10@EventHandler11public void onJoin(PlayerJoinEvent event) {12    Player player = event.getPlayer();13    if (player.hasPlayedBefore()) {14        return;15    }116    if (!new PlayerFirstJoinEvent(player).callEvent()) {17        player.sendRichMessage("<gray>Welcome, staff member. No starter kit for you.");18    }19}

19@EventHandler(priority = EventPriority.LOW)10public void onFirstJoin(PlayerFirstJoinEvent event) {11    if (event.getPlayer().hasPermission("firstjoin.staff")) {12        event.setCancelled(true);13    }14}

111@EventHandler(ignoreCancelled = true)

Download DiamondMilestones or download FirstJoin to try them on your test server.

Recap

• Custom events let one part of your code announce something and any number of listeners react, in your plugin or in others.
• An event class extends Event (or a parent like PlayerEvent), has a static HandlerList, and returns it from both getHandlers() and the static getHandlerList().
• Fire an event with event.callEvent(); listen to it with a normal @EventHandler.
• Implement Cancellable to let listeners cancel; callEvent() then returns false when canceled, and you must respect it.
• Setters let listeners change values; read them back after firing.
• Async events pass true to super(...) and must be fired off the main thread.

Quick quiz

Next steps

• Commands, part 1: let players run your code with /commands.
• Organizing a bigger plugin: events are one of the best tools for keeping features apart.
• Working with other plugins: listen to other plugins' events and share your own API.