Advanced Modding - Event Handler


I want to show you how to create an Event Handler to add functionalities to common events in Minecraft.


3/10 - Relatively Easy


Nothing but a working Mod.

Forge Version

This Tutorial was created with Forge for Minecraft 1.8. If anything doesn't work with other versions, please contact me!

Creating an Event Handler

How does Minecraft work: Event Handler

Event Handlers are a functionality added by Minecraft Forge to allow mod creators to execute their own code when certain events in Minecraft happen. Once an event handler class is registered, Forge searches for methods with the @SubscribeEvent annotation. When a method is found, Forge checks if it has one single argument which is a subclass of the Event class. If this is true, the corresponding event class is modified so that it calls the found method. Thus, the Event Handlers don't slow Minecraft down that much because they are just like normal Java methods being called.

Minecraft Forge has two event buses. One that is created by the Forge Mod Loader (FML) and the other one that is created by Minecraft Forge. Both need to be used sometimes, but basically they are similar. Its also no problem to register an event handler on both buses.

Any class can be an Event Handler, but it is a good coding style if you create a special class for event handling.

Also, it's useful to differentiate between common and client event handlers.

Here, I'll create a new class named EventHandlerCommon.
package com.bedrockminer.tutorial.event;

public class EventHandlerCommon {


This class will be our Event Handler.

To allow it to handle events, we need to add a new method to it.

Here, I want to handle the PlayerPickupXpEvent, so our method gets this as an argument. An event handler method may only have the event as it's argument. Nothing else is allowed.

Note that the method's name does not matter at all.

Finally, we add the @SubscribeEvent annotation to mark the method as an event handler method:
public class EventHandlerCommon {

    public void onPlayerPickupXP(PlayerPickupXpEvent e) {

It is possible to assign a certain priority to the event handler method. This can be used to make an event handler run later or sooner than others.

I'll explain this with an example:

Imagine, you want to add an event when the player dies and drops his items (PlayerDropsEvent).

  • If you want to add a gravestone that collects the Items the player dropped, you should make your event handler method run last, because other Mods may want to change the drops before they are all packed into a grave.
  • One of those Mods may be the one which allows the player to keep certain valuable items. This event handler method should run first, otherwise another Mod may have removed the Items before they can be returned to the player.
  • If you just want to spread redstone wires or particles as blood, your event handler method can run anytime.

To define a certain priority for your event handler method, you need to add an argument to the annotation:
public class EventHandlerCommon {

    @SubscribeEvent(priority = EventPriority.NORMAL)
    public void onPlayerPickupXP(PlayerPickupXpEvent e) {

There are five different priorities, namely HIGHEST, HIGH, NORMAL, LOW and LOWEST. HIGHEST runs first, LOWEST last. If multiple event handler methods have the same priority, they are sorted by their modids. Thus, the mod "AutoCrafter" would be called before the mod "YoutubeCraft" if their event handler methods had the same priority (Don't know if those mods really exist :) ).

If you don't add the priority, the NORMAL priority will be used, so basically the assignment above is useless.

Now, what can we do with those event handler methods?

Our method here is called every time a player picks up an xp-orb, so why don't we just double the amount of xp he receives?
public class EventHandlerCommon {

    @SubscribeEvent(priority = EventPriority.NORMAL)
    public void onPlayerPickupXP(PlayerPickupXpEvent e) {
        e.orb.xpValue *= 2;

The event has several properties that can be used in the behaviour you want to add.

This event, for instance, provides an instance of the XP orb named orb and the player that picked up the orb (instance is named player).

With this Event Handler, every xp orb would give the player twice as much xp as before.

But... we need to register the Event Handler first.

Therefore, we go into our CommonProxy (because its a common event handler) and add this line to the init method:
MinecraftForge.EVENT_BUS.register(new EventHandlerCommon());

This registers the Event Handler with the Minecraft Forge event bus.


To find out whether an event is fired on the Minecraft Forge or on the FML event bus, you need to take a look where the event is located. Forge events always have a package path starting with net.minecraftforge.event, while events fired on the FML bus are located in net.minecraftforge.fml.

If you had an Event Handler that uses methods from the FML bus as well, you could register it like this:
EventHandlerCommon handler = new EventHandlerCommon();

Some events can be canceled. If this is the case, the event has the annotation @Cancelable.

Here is an example on how to cancel an event:
public void onEntityGetHurt(LivingHurtEvent e) {
    if (e.entity instanceof EntityPlayer)

This event disables damage completely for every player (however, you'll still hear the sound and be knocked back).


There are also events that have a result. They have the @HasResult annotation. If an event has a result, you can set the result using setResult(Result r). You can get the previously set result by invoking getResult(). Result is an enum which can have the values ALLOW, DEFAULT or DENY. It depends on the event how results are handled, you need to check the Javadoc for the corresponding event.

Speaking of Javadoc, most of the events are well-documented and can easily be understood by reading the Javadoc.

List of Events

To get a list of the available events, you can open the Event class (net.minecraftforge.fml.common.eventhandler.Event), select the class header and press Ctrl + T in Eclipse. This opens the Type Hierarchy, where you can see every class that extends Event.

Here, I've listed the Events available in Minecraft Forge To find out what exactly a certain event does, you can open the class in Eclipse (Ctrl + Shift + T - "Open Type" to open the class) and read the Javadoc. Events marked with (fml) are fired on the FML event bus, Events with (client) are client side only and need an Event Handler that is registered from the Client Proxy.

Event List - Show

You can download the code used in this tutorial as a .zip file from here.

Recommended tutorials to continue with

Advanced Modding:

Comments and Questions:

If you want to report modding problems, please make sure to include the code in a pastebin link or something else! Don't just write "It doesn't work", otherwise your post will be deleted. For more complicated problems, please use the troubleshooter form.