Triggers

Item triggers let an item run actions when configured events occur, such as interaction, combat, projectile, item operation, block, login, or command-give events. They are useful for scrolls, potions, quest items, right-click skill items, and passive equipment effects.

Configuration format

Triggers live under the actions block of an item definition. Each trigger name maps to an action list:

id: town_scroll
item:
  source: minecraft-paper
  components:
    custom_name: "<aqua>Town Scroll</aqua>"
actions:
  right_click:
    - 'sendmessage text="<green>Teleporting to town.</green>"'
    - "playsound sound=minecraft:entity.enderman.teleport volume=1 pitch=1"
  consume:
    - "playsound sound=minecraft:entity.player.burp volume=1 pitch=1"

Action syntax is documented in the CoreLib action system.

Trigger reference

Interaction

Trigger	When it fires	Context variables
right_click	Player right-clicks air or a block.	—
right_click_air	Player right-clicks air.	—
right_click_block	Player right-clicks a block.	—
left_click	Player left-clicks air or a block, and when attacking an entity.	target, damage when attacking an entity
left_click_air	Player left-clicks air.	—
left_click_entity	Player attacks an entity.	target, damage
shift_left_click	Shift + left-click on air or a block.	—
shift_right_click	Shift + right-click on air or a block.	—

Combat

Trigger	When it fires	Context variables
attack	Player hits an entity.	target, damage
damaged_by_entity	Player is damaged by an entity.	attacker, damage
damaged	Player takes damage from a non-entity source (fall, fire, and so on).	damage
kill_entity	Player kills a non-player entity.	target
kill_player	Player kills a player.	target
death	Player dies.	—

attack, kill_entity, kill_player, and damaged resolve against the player's main-hand item. Melee attacks, projectiles fired by the player, and lethal damage attributed to the player all count as player attacks.

Projectiles

Trigger	When it fires	Context variables
shoot_bow	Player shoots a bow.	projectile_type
shoot_trident	Player throws a trident.	projectile_type
arrow_hit	Arrow hits an entity.	projectile_type
arrow_land	Arrow does not hit an entity.	projectile_type
trident_hit	Trident hits an entity.	projectile_type
trident_land	Trident does not hit an entity.	projectile_type

Projectile triggers read the player's current main-hand item on impact, so switching items after firing may no longer match the launching item.

Item operations

Trigger	When it fires	Context variables
drop	Player drops the item.	—
shift_drop	Shift + drop.	—
swap_hand	Player swaps main/off hand.	—
shift_swap_hand	Shift + swap hands.	—
consume	Item is consumed (food/potion).	consumed_item

drop, swap_hand, place_block, and consume resolve against the item involved in the event rather than the current main-hand item.

Blocks

Trigger	When it fires	Context variables
break_block	Player breaks a block.	block
place_block	Player places a block.	block

Other

Trigger	When it fires	Context variables
sneak	Player starts sneaking (does not fire on release).	—
teleport	Player teleports.	—
login	Player joins.	—
give	Item is given via /ei give.	amount

Context variables

Trigger context variables are referenced as %variable% in action text and parameters:

actions:
  attack:
    - 'sendmessage text="Hit %target% for %damage% damage"'
  kill_entity:
    - 'sendmessage text="Killed %target%"'

Every trigger injects these base variables:

Variable	Description
player	Player name.
item_id	Item definition ID.
item_trigger	Trigger name.
item_name	Item display name.

Conditions and disabled state

An item definition's condition is evaluated before each trigger. When it fails, the trigger does not run, on_fail.message is sent, and on_fail.actions execute; when it passes, on_pass.actions execute.

When an item has repair enabled and the held item is in the disabled state (durability depleted), its triggers do not run. See Item Repair.

Examples

Life-steal weapon

id: vampire_blade
item:
  source: minecraft-netherite_sword
  components:
    custom_name: "<dark_red>Vampire Blade</dark_red>"
actions:
  attack:
    - 'sendmessage text="<red>Dealt %damage% damage to %target%.</red>"'
  kill_entity:
    - 'sendmessage text="<red>Soul drained: %target%</red>"'

Consumable

id: health_potion_large
item:
  source: minecraft-potion
  components:
    custom_name: "<red>Large Health Potion</red>"
actions:
  consume:
    - "playsound sound=minecraft:entity.generic.drink volume=1 pitch=1"
    - 'sendmessage text="<green>You drank %item_name%.</green>"'