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:
    - 'send_message text="<green>Teleporting to town.</green>"'
    - "play_sound sound=minecraft:entity.enderman.teleport volume=1 pitch=1"
  consume:
    - "play_sound sound=minecraft:entity.player.burp volume=1 pitch=1"

NOTE

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
damage_dealt	Damage dealt by the player has been resolved (final damage greater than 0).	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 resolves 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.

damage_dealt is dispatched at MONITOR priority and only fires when the final damage is greater than 0, so it sees the damage value after other plugins have modified it.

Besides the main-hand weapon, damage_dealt, kill_entity, and kill_player are also dispatched across armor slots (skipping main hand and off hand); damaged and damaged_by_entity are likewise dispatched across the remaining equipment slots (skipping main hand). The extra dispatch requires the definition's equip_slot to be something other than all and to match the slot the item actually occupies, which means armor pieces receive these combat triggers too.

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_item	Player drops the item.	—
shift_drop_item	Shift + drop.	—
swap_items	Player swaps main/off hand.	—
shift_swap_items	Shift + swap hands.	—
consume	Item is consumed (food/potion).	consumed_item

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

WARNING

Trigger names must match exactly; the plugin provides no aliases. Keys under actions are only lowercased with spaces replaced by underscores, and unregistered names are silently ignored without a warning.

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:
    - 'send_message text="Hit %target% for %damage% damage"'
  kill_entity:
    - 'send_message 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:
    - 'send_message text="<red>Dealt %damage% damage to %target%.</red>"'
  kill_entity:
    - 'send_message 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:
    - "play_sound sound=minecraft:entity.generic.drink volume=1 pitch=1"
    - 'send_message text="<green>You drank %item_name%.</green>"'