Event priorities and canceling

On a real server, many plugins listen to the same events. On this page you will learn the order in which their handlers run, how canceling really works, how to skip events another plugin already canceled, and how to handle damage, projectiles and async events safely. You will build SpawnGuard, a plugin that protects the area around spawn.

One event, many listeners

In Events and listeners you wrote handlers that run when something happens. Your plugin is rarely alone, though. When Steve breaks a block, a protection plugin wants to check whether he is allowed to, a jobs plugin wants to pay him, and a logging plugin wants to record it. Every one of them has a handler for the same BlockBreakEvent.

Paper calls all of those handlers one after another, passing the same event object along. Each handler can read it and change it. That raises two questions:

• Who goes first? If the protection plugin cancels the break, the jobs plugin should know before it pays out.
• Who has the final say? If two plugins change the same thing, the later change wins.

The answer to both is the event priority.

The six priorities

Every handler has one of six priorities. Paper runs all LOWEST handlers first, then all LOW handlers, and so on, with MONITOR handlers last:

The names trip everyone up at first: HIGHEST sounds like "goes first", but it means "most important, so it decides last". Think of it as "who gets the last word".

You choose the priority inside the @EventHandler annotation:

1@EventHandler(priority = EventPriority.LOW)2public void onBreak(BlockBreakEvent event) {3    event.setCancelled(true);4}

EventPriority lives in org.bukkit.event; IntelliJ adds the import when you press Alt+Enter. Inside one priority level the order between plugins is not something you can rely on, so never write code that needs to run "just before" another plugin's NORMAL handler. Pick a different level instead.

How canceling really works

Events that can be stopped implement the Cancellable interface. You already met its main method, setCancelled(true). Here is the surprising part:

That has three consequences:

1. Later handlers can see that an event was canceled by asking event.isCancelled().
2. Later handlers can un-cancel it with setCancelled(false). A HIGHEST handler could allow a break that a LOW protection handler blocked. This is legal, but it overrides other plugins' decisions, so do it only on purpose, for example in a plugin whose whole job is to make exceptions.
3. Handlers that do not care about canceled events must say so, or they react to actions that never happen. That is what ignoreCancelled is for.

ignoreCancelled = true

Imagine a plugin that pays players a coin for every block they break, written without thinking about canceling. Spawn is protected, so the blocks there never break, but the payment handler still runs for every attempt. Players stand at spawn and click the same block all day, getting paid for nothing.

The fix is one setting:

1@EventHandler(ignoreCancelled = true)2public void onBreak(BlockBreakEvent event) {3    event.getPlayer().sendRichMessage("<gold>+1 coin");4}

With ignoreCancelled = true, Paper skips this handler whenever the event is already canceled when its turn comes. You can combine both settings: @EventHandler(priority = EventPriority.HIGH, ignoreCancelled = true).

Not every event can be canceled. PlayerJoinEvent and PlayerQuitEvent cannot, because there is nothing left to stop. If event.setCancelled is not offered by autocomplete, the event is not cancelable. The Event Finder marks the ones that are.

Building SpawnGuard

SpawnGuard uses three listeners at three different priorities, which is exactly how separate plugins share an event on a real server:

• GuardListener at LOW protects a square of 61 by 61 blocks around the world spawn: no breaking, no placing, no damage to players.
• BlockCounterListener at NORMAL counts blocks players break and congratulates them every 100. It uses ignoreCancelled, so protected blocks do not count.
• AuditListener at MONITOR writes every break attempt at spawn to the console, with the final result.

First, a small helper class answers one question: is this location inside the zone?

1package com.example.eventprioritiescancelzone;2 3import org.bukkit.Location;4import org.bukkit.World;5 6public final class SpawnZone {7 18    private final int radius;9 10    public SpawnZone(int radius) {11        this.radius = radius;12    }13 14    public boolean contains(Location location) {15        World world = location.getWorld();216        if (world == null || world.getEnvironment() != World.Environment.NORMAL) {17            return false;18        }319        Location spawn = world.getSpawnLocation();420        return Math.abs(location.getBlockX() - spawn.getBlockX()) <= radius21            && Math.abs(location.getBlockZ() - spawn.getBlockZ()) <= radius;22    }23}

The guard: cancel early

127@EventHandler(priority = EventPriority.LOW)28public void onBreak(BlockBreakEvent event) {29    Player player = event.getPlayer();230    if (!zone.contains(event.getBlock().getLocation()) || player.hasPermission(BYPASS)) {31        return;32    }333    event.setCancelled(true);434    player.sendActionBar(PROTECTED);35}

The onPlace handler is the same idea for BlockPlaceEvent. When a player without the bypass permission tries to build at spawn, this appears above their hotbar:

The counter: skip what was canceled

1package com.example.eventprioritiescancelzone;2 3import java.util.HashMap;4import java.util.Map;5import java.util.UUID;6import net.kyori.adventure.text.minimessage.tag.resolver.Placeholder;7import org.bukkit.entity.Player;8import org.bukkit.event.EventHandler;9import org.bukkit.event.Listener;10import org.bukkit.event.block.BlockBreakEvent;11 12public final class BlockCounterListener implements Listener {13 14    private static final int ANNOUNCE_EVERY = 100;15 16    private final Map<UUID, Integer> blocksBroken = new HashMap<>();17 118    @EventHandler(ignoreCancelled = true)19    public void onBreak(BlockBreakEvent event) {20        Player player = event.getPlayer();221        int total = blocksBroken.merge(player.getUniqueId(), 1, Integer::sum);322        if (total % ANNOUNCE_EVERY == 0) {23            player.sendRichMessage("<green>You have broken <total> blocks this session!",24                Placeholder.unparsed("total", String.valueOf(total)));25        }26    }27}

The auditor: read the final result

1package com.example.eventprioritiescancelzone;2 3import java.util.logging.Logger;4import org.bukkit.block.Block;5import org.bukkit.event.EventHandler;6import org.bukkit.event.EventPriority;7import org.bukkit.event.Listener;8import org.bukkit.event.block.BlockBreakEvent;9 10public final class AuditListener implements Listener {11 12    private final SpawnZone zone;113    private final Logger logger;14 15    public AuditListener(SpawnZone zone, Logger logger) {16        this.zone = zone;17        this.logger = logger;18    }19 220    @EventHandler(priority = EventPriority.MONITOR)21    public void onBreakResult(BlockBreakEvent event) {22        Block block = event.getBlock();23        if (!zone.contains(block.getLocation())) {24            return;25        }326        String result = event.isCancelled() ? "blocked" : "allowed";427        logger.info(event.getPlayer().getName() + " tried to break " + block.getType()28            + " at " + block.getX() + " " + block.getY() + " " + block.getZ() + ": " + result);29    }30}

The main class wires it together. All three listeners get the same SpawnZone object:

1package com.example.eventprioritiescancelzone;2 3import org.bukkit.plugin.PluginManager;4import org.bukkit.plugin.java.JavaPlugin;5 6public final class SpawnGuardPlugin extends JavaPlugin {7 8    private static final int ZONE_RADIUS = 30;9 10    @Override11    public void onEnable() {12        SpawnZone zone = new SpawnZone(ZONE_RADIUS);113        AuditListener auditListener = new AuditListener(zone, getLogger());14 15        PluginManager pluginManager = getServer().getPluginManager();216        pluginManager.registerEvents(new GuardListener(zone), this);17        pluginManager.registerEvents(new BlockCounterListener(), this);18        pluginManager.registerEvents(auditListener, this);19 320        registerCommand("guardlog", "Turns the spawn break log on or off", new GuardLogCommand(this, auditListener));21    }22}

Here is the console when Steve (no permission) and Jace (an operator) each break a block at spawn:

[15:20:41 INFO]: [SpawnGuard] Steve tried to break GRASS_BLOCK at 3 64 -7: blocked[15:20:55 INFO]: [SpawnGuard] Jace tried to break GRASS_BLOCK at 5 64 -2: allowed

Jace's break was allowed, so his block also counts toward his total in BlockCounterListener. Steve's did not.

Which priority should I use?

Ask what your handler does:

When in doubt, use the default NORMAL. Most handlers never need anything else.

Event inheritance: damage, attackers and projectiles

Events are Java classes, and some of them extend others. Damage is the most important example:

• EntityDamageEvent fires for all damage: falls, fire, drowning, lava, mobs and players.
• EntityDamageByEntityEvent extends EntityDamageEvent. It fires when an entity caused the damage, and adds getDamager(): the zombie, the player or the arrow that hit.

A handler for the parent event runs for the child events too. GuardListener's damage handler listens to EntityDamageEvent, so it protects players at spawn from every kind of damage at once:

47@EventHandler(priority = EventPriority.LOW)148public void onDamage(EntityDamageEvent event) {249    if (!(event.getEntity() instanceof Player victim) || !zone.contains(victim.getLocation())) {50        return;51    }352    event.setCancelled(true);453    if (event instanceof EntityDamageByEntityEvent byEntity) {54        Player attacker = attackingPlayer(byEntity);55        if (attacker != null) {556            attacker.sendRichMessage("<red>No fighting at spawn.");57        }58    }59}

Who attacked? getDamager() is the entity that touched the victim. For a sword hit that is the player, but for a bow shot it is the arrow. To find the player behind a projectile, ask the projectile for its shooter:

61private static Player attackingPlayer(EntityDamageByEntityEvent event) {162    Entity damager = event.getDamager();263    if (damager instanceof Player player) {64        return player;65    }366    if (damager instanceof Projectile projectile && projectile.getShooter() instanceof Player shooter) {67        return shooter;68    }469    return null;70}

Unregistering listeners

Usually a listener stays registered until your plugin is disabled, and then Paper removes it for you. Sometimes you want to switch one off while the server runs. HandlerList.unregisterAll(listener) removes every handler of that one listener object from every event:

1package com.example.eventprioritiescancelzone;2 3import io.papermc.paper.command.brigadier.BasicCommand;4import io.papermc.paper.command.brigadier.CommandSourceStack;5import org.bukkit.command.CommandSender;6import org.bukkit.event.HandlerList;7 8public final class GuardLogCommand implements BasicCommand {9 10    private final SpawnGuardPlugin plugin;111    private final AuditListener auditListener;212    private boolean logging = true;13 14    public GuardLogCommand(SpawnGuardPlugin plugin, AuditListener auditListener) {15        this.plugin = plugin;16        this.auditListener = auditListener;17    }18 19    @Override20    public void execute(CommandSourceStack source, String[] args) {21        CommandSender sender = source.getSender();22        if (logging) {323            HandlerList.unregisterAll(auditListener);24            logging = false;25            sender.sendRichMessage("<yellow>Spawn break log is now <red>off</red>.");26        } else {427            plugin.getServer().getPluginManager().registerEvents(auditListener, plugin);28            logging = true;29            sender.sendRichMessage("<yellow>Spawn break log is now <green>on</green>.");30        }31    }32 33    @Override34    public String permission() {535        return "spawnguard.admin";36    }37}

Other ways you will see: HandlerList.unregisterAll(plugin) removes all of a plugin's listeners, and BlockBreakEvent.getHandlerList().unregister(listener) removes a listener from just one event. Often an even simpler design is a boolean field that the handler checks with a guard clause, and the listener stays registered.

Async events

Most events fire on the server's main thread, the one that runs the game 20 times a second. A few fire on a different thread so slow work in them cannot freeze the game. Their names start with Async, and event.isAsynchronous() returns true for them. Two of them you will use often:

• AsyncChatEvent: a player sent a chat message.
• AsyncPlayerPreLoginEvent: a player is connecting, before they enter the world.

The rule for async handlers: you may read the event, check your own thread-safe data and send messages, but you must not touch the world. No blocks, no entities, no inventories, no teleporting, no spawning. The game is changing those on the main thread at the same moment. Paper often stops you with an IllegalStateException that mentions "async", and when it does not, you get rare, random bugs that are very hard to find.

When an async handler needs to change the world, it hands that job back to the main thread with the scheduler. Say "thunder" in chat with this plugin and lightning strikes next to you:

1package com.example.eventprioritiescancelasync;2 3import io.papermc.paper.event.player.AsyncChatEvent;24import net.kyori.adventure.text.serializer.plain.PlainTextComponentSerializer;5import org.bukkit.entity.Player;6import org.bukkit.event.EventHandler;7import org.bukkit.event.Listener;8 9public final class ThunderListener implements Listener {10 11    private final ThunderChatPlugin plugin;12 13    public ThunderListener(ThunderChatPlugin plugin) {14        this.plugin = plugin;15    }16 117    @EventHandler(ignoreCancelled = true)18    public void onChat(AsyncChatEvent event) {19        String text = PlainTextComponentSerializer.plainText().serialize(event.message());20        if (!text.equalsIgnoreCase("thunder")) {21            return;22        }23        Player player = event.getPlayer();324        plugin.getServer().getScheduler().runTask(plugin, () -> {425            if (player.isOnline()) {526                player.getWorld().strikeLightningEffect(player.getLocation());27            }28        });29    }30}

AsyncPlayerPreLoginEvent is not cancelable at all. To refuse a player, you call disallow with a reason and a message they see on the disconnect screen. Because it is async, this is also the right place for slow checks, such as asking a database whether someone is banned.

1package com.example.eventprioritiescancelasync;2 3import java.util.Set;4import net.kyori.adventure.text.Component;5import net.kyori.adventure.text.format.NamedTextColor;6import org.bukkit.event.EventHandler;7import org.bukkit.event.Listener;8import org.bukkit.event.player.AsyncPlayerPreLoginEvent;9 10public final class MaintenanceListener implements Listener {11 112    private static final Set<String> TESTERS = Set.of("Jace", "Steve");13 14    @EventHandler15    public void onPreLogin(AsyncPlayerPreLoginEvent event) {216        if (TESTERS.contains(event.getName())) {17            return;18        }319        event.disallow(AsyncPlayerPreLoginEvent.Result.KICK_WHITELIST,20            Component.text("The server is in maintenance. Try again soon!", NamedTextColor.GOLD));21    }22}

Threads, performance and lag explains threads in depth, and Timing and tasks covers runTask and its friends.

Mistakes to avoid

• Rewarding canceled actions. Add ignoreCancelled = true to handlers that give something.
• Changing an event at MONITOR. Plugins rely on MONITOR being the final, unchanged result. Use HIGHEST if you really need the last word.
• Thinking setCancelled(true) stops the other handlers. It only sets a flag; everything after you still runs.
• Forgetting projectiles. A "no PvP" check that only looks for instanceof Player lets players shoot each other with bows.
• Touching the world in an async event. Hop to the main thread with runTask first.
• Unregistering a new object. HandlerList.unregisterAll(new MyListener()) does nothing. Keep the registered object.

1@EventHandler2public void onBreak(BlockBreakEvent event) {3    if (event.getBlock().getType() == Material.STONE) {4        event.getPlayer().giveExp(1);5    }6}

1package com.example.eventprioritiescancelexercise;2 3import org.bukkit.Material;4import org.bukkit.event.EventHandler;5import org.bukkit.event.EventPriority;6import org.bukkit.event.Listener;7import org.bukkit.event.block.BlockBreakEvent;8 9public final class MinerXpListener implements Listener {10 11    private static final int XP_PER_STONE = 1;12 113    @EventHandler(priority = EventPriority.HIGH, ignoreCancelled = true)14    public void onBreak(BlockBreakEvent event) {215        if (event.getBlock().getType() != Material.STONE) {16            return;17        }18        event.getPlayer().giveExp(XP_PER_STONE);19    }20}

1@EventHandler(priority = EventPriority.LOW)2public void onBucket(PlayerBucketEmptyEvent event) {3    if (zone.contains(event.getBlock().getLocation()) && !event.getPlayer().hasPermission(BYPASS)) {4        event.setCancelled(true);5    }6}

Download SpawnGuard to try it on your test server, or open it in the Compile Lab.

Recap

• All handlers for an event run in priority order: LOWEST, LOW, NORMAL, HIGH, HIGHEST, MONITOR. The default is NORMAL.
• Later handlers have more say. MONITOR only reads and never changes anything.
• setCancelled(true) sets a flag; later handlers still run and can read it with isCancelled().
• ignoreCancelled = true skips your handler for events that are already canceled.
• Listening to a parent event like EntityDamageEvent also catches its children; use instanceof to tell them apart, and ask projectiles for their shooter.
• HandlerList.unregisterAll(listener) switches a registered listener off.
• In async events, never touch the world; hop back with runTask.

Quick quiz

Next steps

• Making your own events: fire events that other code can listen to, cancel and react to.
• Permissions: more about bypass permissions like spawnguard.bypass.
• Event Finder: find the event behind any idea, with a "Cancelable" badge.