Event Finder

Paper has 460 events, and you need to know which one to listen for. Type what you want in plain English, like "when a player dies" or "right click", and this tool finds the event, explains it, and gives you code you can paste into your plugin.

What an event is, in one minute

Your plugin cannot watch the server all day. Instead, Paper tells your plugin when something happens. Each thing that happens becomes an event, which is a small object that carries the details: who joined, which block broke, how much damage was dealt. You write an event handler in a listener class, and Paper calls it for you.

The hard part for a beginner is the first step: out of 460 events, which one is the right one? That is the question this page answers.

The Event Finder

Type in the search box, or pick a category. Press a result to open it. You can also share a result: open it, press Copy link to this event and send the link to a friend.

How to read a result

• The sentence under the name says exactly when Paper fires the event. If it does not describe your situation, it is the wrong event.
• Cancelable means you can stop the thing from happening. Inside your handler, call event.setCancelled(true). Events without this badge are announcements: you can react, but you cannot undo them. Read about it in Event priorities and canceling.
• Async means Paper fires the event on a different thread, not on the main server thread. Be careful there, because most of the game is not safe to touch from another thread. See Threads, performance and lag and use the scheduler to get back to the main thread.
• Paper-only means the event lives in a Paper package. It works on Paper but not on plain Spigot servers.
• Deprecated means the authors replaced the event with a better one. The card names the replacement, and the finder hides deprecated events until you ask for them.
• Key methods are the questions you can ask the event, such as getPlayer() or getBlock(). Methods that start with set change the outcome.
• Where it comes from shows the superclass chain. An event inherits every method of its parents, which is why a block event can answer getBlock().

Using the code

1. Find your event and copy the code

   Open the card and press Copy code. The snippet starts with the import lines, so IntelliJ knows which classes you mean. Choose Full class if you want a whole new listener file.

2. Put the method in a listener class

   Paste the method into a class that has implements Listener. Our Events and listeners chapter builds one from scratch.

3. Register the listener

   Writing the class is not enough. In onEnable() you must tell Paper about it with getServer().getPluginManager().registerEvents(new YourListener(), this). Forgetting this line is the number one reason a listener "does nothing".

4. Fill in your own logic

   The snippet shows how to read the event and, for cancelable events, how to cancel it. Replace those lines with your idea. For example, check a permission first, and only then cancel.

Mistakes beginners make with events

• Importing the wrong class. Some names exist twice, such as BellRingEvent and EntityKnockbackEvent. IntelliJ may offer both. The finder lists them separately and shows the full package; pick the one that is not deprecated.
• Doing heavy work in events that fire constantly. PlayerMoveEvent, BlockPhysicsEvent and the tick events fire many times per second. Return early, and never read files or call a database there.
• Forgetting that some events fire twice. PlayerInteractEvent fires once for each hand, so check event.getHand().
• Trusting a click in an inventory. InventoryClickEvent fires for every inventory, including the player's own. Always check which inventory was clicked before you cancel anything.
• Listening to an abstract parent. Classes such as PlayerEvent or BlockEvent are shared parents. You cannot listen to most of them. Pick a specific event.

If you cannot find your event

Try different words: "join", "login" and "connect" all lead to the same events. Try the name of the thing, such as "furnace" or "villager". If nothing fits, the thing you want might not have its own event. Then listen to the closest event and check details inside your handler, or read Making your own events.