Triggers

EmakiItem items support the triggers below, each with its firing condition, injected context variables, and item-definition syntax. A trigger makes the item run actions automatically at a given moment, which is what you use for scrolls, potions, quest items, right-click skill items, and passive equipment effects

Configuration format

Write triggers 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, damage (always 0)
kill_player	Player kills a player	target, damage (always 0)
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

Armor pieces receive these combat triggers too: 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

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

Note that 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 whatever is in your main hand right now

WARNING

Write trigger names 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

As soon as a trigger fires, its variables are injected into the action context; reference them as %variable% in action text and parameters:

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

These base variables are injected by every trigger:

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

Conditions and disabled state

The item definition's condition is recalculated before each trigger runs. 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 your main-hand 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>"'