Custom Item Interactions

This page covers how to breathe life into your custom items. While basic items are great for simple resources or food, you will often want your items to interact dynamically with the world—like a sword that sets enemies on fire, or a tool that triggers magic spells.

To achieve this, you must extend the base Item class and override its provided event methods.

ActionResult: ActionResult decides whether or not the underlying server event should be cancelled; it can be used to prevent vanilla damage, stop block breaking, and more.
ActionResult.PASS-> Allows the event to proceed un-interrupted.
ActionResult.CANCEL-> Cancels the event behind the scenes (event.setCancelled(true)).

Overridable Events

The Item class provides a wide array of overridable events so you can add precise functionality to your items.

Method	Information	Return
`onMine`	Called when the player mines a block.	`ActionResult`
`onHit`	Called when the player hits an entity.	`ActionResult`
`onUseOn`	Called when the player `Right-Click`s a block or an entity.	`ActionResult`
`onUse`	Called when the player uses an item (`Right-Click`s air, eats food, etc).	`ActionResult`
`onInventoryTick`	Called every tick while the item is inside the player's inventory.	`void`
`onSlotChange`	Called when the item's position within the player's inventory changes.	`void`
`onClick`	Called when the player clicks the item inside an inventory GUI.	`ActionResult`
`onDrop`	Called when the player drops the item.	`ActionResult`
`onPickup`	Called when the player picks up the item.	`ActionResult`
`onSwapHand`	Called when the player swaps the item from/into their offhand.	`ActionResult`
`onAnvil`	Called when the item is placed inside an anvil.	`ActionResult`
`onCraft`	Called when a player crafts this item.	`void`

Example: The `onHit` event

Let's say you want to make a specialized weapon that sets the target on fire when hit. Instead of registering it inline, you would create a custom Item class.

First, we set up the item's base stats in the constructor:

public final class FireSword extends Item {
    public FireSword(Key id) {
        super(id);
        // Set texture, durability, and damage
        setData(new ItemModel(NamespacedKey.minecraft("iron_sword")));
        setData(new MaxDurability(120));
        setData(new WeaponComponent(Weapon.weapon()
            .itemDamagePerAttack(3)
            .build()));
        
        createTooltip(tooltip);
        updateTooltip();
    }

    // Next, we will override onHit here
}

Then, we override the onHit event inside that same class and inflict fire on the target entity:

    @Override
    public ActionResult onHit(LivingEntity source, Entity target) {
        // Set target on fire for 3 seconds (20 ticks per second)
        target.setFireTicks(20 * 3);
        
        // We pass the event so normal weapon damage still applies
        return ActionResult.PASS;
    }

As usual, register the item in your main registry class and launch the server. As you can see, hitting an entity successfully sets it ablaze.

05 June 2026

Custom Item Interactions

Overridable Events

Example: The onHit event

Example: The `onHit` event