Skip to main content

Triggers

A trigger is the event that makes an ability run. Every enchant, set, or crystal declares exactly one trigger with the trigger: key, and it answers a single question: "when should this fire?"

enchant:
  trigger: ATTACK     # fire when the wearer lands a melee hit
  levels:
    1:
      chance: 30
      effects:
        - { POTION: { effect: POISON, level: 1, duration: 60 } }

Triggers take no arguments — you just name one. The hard part is picking the right one, so the table below explains each in plain words.

What the columns mean​

  • Side — which "team" of the combat fold the trigger belongs to:
    • Attack — fires when you are dealing damage. Use these for offensive effects (extra damage, debuffs on your victim).
    • Defense — fires when you are taking damage. Use these for retaliation, shielding, escape.
    • Neutral — not tied to combat at all (mining, eating, a repeating timer, etc.).
  • Held item — Yes means the trigger looks at the item in your hand (tools, weapons used by hand). When this is the case, the enchant only counts when that item is held.
  • Scans armour — Yes means the engine checks your worn equipment for this enchant, so it can fire from armor (and held gear). This is how passive armor enchants and most combat enchants work.
  • Needs target — Yes means the event must involve another entity (a victim or attacker). Triggers without a target fire on you/your location alone.

:::tip Match the trigger to the side of your effect Defensive effects (GUARD, KNOCKBACK_CONTROL on yourself, retaliation DAMAGE) belong on a DEFENSE trigger; offensive ones belong on ATTACK. Putting a retaliation effect on ATTACK (or vice-versa) is the most common reason an enchant "does nothing." :::

:::note PASSIVE vs REPEATING Both are always-on while the item is worn, but they differ:

  • PASSIVE is a continuous state — best for effects that are a condition (a permanent potion buff, a HEALTH bump). The engine keeps them applied while worn and cleans them up on unequip.
  • REPEATING runs on a fixed timer — best for periodic upkeep (top up a buff, lay a WALKER platform, refresh KEEP_ON_DEATH). repeat: N is the period in ticks; repeat-delay: D moves the first run to D ticks after equip instead of a full period out, so an upkeep ability can start straight away without shortening the loop. :::
TriggerSideWhen does it fire?Held itemScans armourNeeds target
ATTACKAttackYou land a melee hit on a living target.—YesYes
BOWAttackYour fired arrow hits a target (the hit, not the shot).—YesYes
TRIDENTAttackYour thrown/melee trident hits a target.—YesYes
KILLAttackYour hit kills the target.—YesYes
BOW_FIREAttackYou release a bow shot (the moment the arrow leaves).—Yes—
DEFENSEDefenseSomething deals damage to you.—YesYes
FALLDefenseYou take fall damage.—Yes—
FIREDefenseYou take fire/burning damage.—Yes—
PASSIVENeutralAlways on while the item is worn (no event needed).—Yes—
MINENeutralYou break a block while mining.—Yes—
DEATHNeutralYou die.—Yes—
HELDNeutralThe item is in your hand (held), checked continuously.Yes——
BREAKNeutralYou break a block with this held item.Yes——
ITEM_DAMAGENeutralThis held item loses durability.—Yes—
EATNeutralYou finish eating/drinking while holding this item.—Yes—
FISHINGNeutralYou reel in a catch with this fishing rod.Yes——
INTERACTNeutralYou right- or left-click with this held item.Yes——
INTERACT_LEFTNeutralYou left-click with this held item.Yes——
INTERACT_RIGHTNeutralYou right-click with this held item.Yes——
REPEATINGNeutralOn a fixed timer while worn (good for always-on upkeep effects).—Yes—
COMMANDNeutralFired explicitly by a command, not a game event.—Yes—
IMPACTAttackFires on its matching game event.—YesYes
EXP_GAINNeutralFires on its matching game event.—Yes—
USENeutralFires on its matching game event.Yes——
GUARDIAN_HURTNeutralFires on its matching game event.—Yes—
HURTDefenseFires on its matching game event.—Yes—
EQUIP_CHANGENeutralFires on its matching game event.—Yes—
PROJECTILE_LANDNeutralFires on its matching game event.—Yes—
PROXIMITY_EVENTNeutralFires on its matching game event.—YesYes
SUMMON_PAYLOADNeutralFires on its matching game event.—YesYes

See also​