Trigger Atom Reference

Belongs to: Action System　·　Related: Handlers · Cooldown / Cost / Conditions

The trigger atom decides "what the player does to trigger the action". It is filled in at trigger.atom. This page lists every built-in atom by category (sourced from TriggerType / TriggerSpec).

📋 Want a copy-and-use minimal YAML for each category of trigger? See Trigger Hands-On Examples.

Syntax recap:

trigger:
  atom: left_click        # single atom
# or
trigger:
  sequence: [sneak_down, left_click, left_click]   # sequence combo
  window: 450             # inter-step window (milliseconds), default 450

---

Click Category

Atom	When it triggers
right_click	Right-click air or block
left_click	Left-click air (swing / attack entity)
shift_right_click	Sneak + right-click
shift_left_click	Sneak + left-click
right_click_air	Right-click air only
right_click_block	Right-click block only
left_click_air	Left-click air only
left_click_block	Left-click block only

Sneak / Crouch Category

Atom	When it triggers
shift_toggle (aliases sneak / crouch)	Sneak on or off
double_shift_toggle	Double-tap sneak (450ms window)
sneak_down	Sneak pressed (can be a sequence start)
sneak_start	Sneak turned on
sneak_stop	Sneak turned off

Movement Category

Atom	When it triggers
sprint / sprint_start / sprint_stop	Sprint (toggle / on / off)
glide (aliases fly / gliding) / glide_start / glide_stop	Elytra gliding
swim	In water
climb	Climbing ladder / vine
jump	Jump
teleport	Teleport
respawn	Respawn after death
fall_damage (alias fall_hurt)	Take fall damage

Item Management Category

Atom	When it triggers
equip (aliases wear / hold)	Placed into a hand slot
unequip (alias remove_equip)	Removed from hand
swap_hand	Main/off hand swap
consume (aliases eat / drink)	Eat / drink
drop (alias discard)	Drop
pickup	Pick up
item_break	Tool / item breaks

Block / Placement Category

Atom	When it triggers
place_block	Place block
break_block	Mine / break block
use_on_block	Right-click block
bow_shoot (aliases shoot / arrow_shoot)	Release a bow arrow
crossbow_shoot	Release a crossbow bolt
trident_throw	Throw trident
fish (aliases fishing / hook)	Fishing event

Inventory / Crafting Category

Atom	When it triggers
inventory_click (aliases gui_click / container_click)	Click an inventory slot
inventory_open / inventory_close	Open / close container
inventory_drag	Drag item
inventory_transfer (alias shift_click)	Shift-click
inventory_swap (alias number_key)	Number-key item swap
inventory_double_click (alias collect)	Double-click slot
craft	Complete a craft
anvil_use / enchant / grindstone_use / smithing / loom_use / stonecutter_use	Various workstation uses

Entity Interaction Category

Atom	When it triggers
interact_entity (alias interact)	Right-click a creature
interact_at_entity	Right-click a specific point on an entity
interact_villager (alias trade)	Trade with a villager
entity_target (alias mob_target)	An entity targets the player
entity_tame / entity_breed / entity_shear / entity_milk	Tame / breed / shear / milk
entity_saddle / entity_leash / entity_unleash	Saddle / leash / unleash
vehicle_enter (aliases mount / ride) / vehicle_exit (alias dismount) / vehicle_move	Vehicle enter/exit / move

Combat / Damage Category

Atom	When it triggers
on_damage (alias combat_damage)	Deal damage to an entity
on_hit (alias combat_hit)	Take damage (non-lethal)
on_kill (alias kill_event)	Kill an entity
melee_hit	Hit by melee
projectile_hit (alias arrow_hit)	Hit by a projectile
critical_hit (alias crit)	Critical hit
block (alias parry)	Shield block
dodge	Dodge
heal (alias heal_others) / receive_heal (alias healed)	Heal others / be healed
death (alias player_death)	Player death
kill_player / kill_entity	PvP kill / PvE kill

Damage Source Breakdown (when hit)

contact_fire / contact_lava / entity_drown / entity_starve / entity_freeze / entity_poison / entity_wither / magic_damage, etc., correspond to specific damage causes.

Status Effect Category

entity_glow / entity_silence / entity_levitate / entity_explode (alias explosion) / entity_ignite (alias ignite) / entity_extinguish (aliases water / extinguish).

Environment Category

Atom	When it triggers
area_enter (aliases region_enter / zone_enter) / area_exit	Enter / exit a region (works with the region system)
weather_change (alias weather)	Weather change
time_change (aliases time / day_change)	Day/night change
day (aliases sunrise / morning) / night (aliases sunset / evening)	Sunrise / sunset
stand_on_block	Stand on a specific block
enter_liquid / exit_liquid	Enter / exit liquid
enter_portal (aliases portal_enter / nether_portal) / exit_portal	Enter / exit a portal

Server Event Category

Atom	When it triggers
join (aliases player_join / login) / quit (aliases player_quit / logout)	Player join / leave server
world_change (alias dimension_change)	Switch dimension
biome_change (alias enter_biome)	Enter a biome
entity_spawn (aliases spawn / mob_spawn) / entity_death (alias mob_death) / entity_remove (alias despawn)	Entity spawn / death / removal

Special

Atom	Description
tick (aliases periodic / interval)	Periodic trigger (configure the interval with the tick: field, not atom)
custom	User-defined trigger (fallback)

---

About Aliases

Each atom may have multiple aliases; any of them works (e.g. right_click can also be written as one of its aliases). The system resolves them via TriggerCatalog.

---

Sequence Combos (Sequence)

Arrange multiple atoms in order in sequence; the player must complete them one after another within window milliseconds:

combo_attack:
  trigger:
    sequence:
      - sneak_down
      - left_click
      - left_click
    window: 500
  cooldown: 3s
  refs:
    - handler: qi:message
      payload: "Combo!"

• State is tracked by TriggerSequenceTracker per (player, item, binding).
• Sneak atom normalization: shift / sneak / sneak_down → sneak_down; shift_up / sneak_up → sneak_up.

See Cooldown / Cost / Conditions / Combos for details.

---

Next Steps

• Handlers: what to execute after a trigger fires
• Cooldown / Cost / Conditions: restrict triggers