Skip to content

Triggers For Enchantments

neoramm edited this page Nov 5, 2026 · 2 revisions

Triggers for Enchantments

The triggers section of an enchantment says what it does. Each trigger is a small rule: when something happens, if some things are true, do some things.

The rule language is the one explained in the Trigger Engine Wiki. If you have never written a trigger, read its Getting Started first, then come back here.

A first example

triggers:
  strike:
    on: attack
    if:
      - chance: "{level} * 8%"
    do:
      - velocity:
          y: 0.6
      - set-damage: "{damage} + {level}"

When a player who holds an item with this enchantment hits something, there is a chance (8% per level) to push it up and add extra damage.

The special value here is {level}: the level of the enchantment the player has. This is how an enchantment gets stronger at higher levels.

When does an enchantment run?

A trigger of an enchantment runs only when the player has the enchantment on the right item. The plugin checks:

  1. The items the player is holding and wearing in the enchantment's slots. If the enchantment is on one of them, it counts.
  2. For bow-hit, the bow, crossbow or trident that was shot; for shoot, the bow or crossbow. It does not matter what the player holds a second later.
  3. If you set activation: event-item, the item that the event is about.

If several items have the same enchantment, the stack option decides: the highest level, or the sum.

{level} is always the level that was found. It can be higher than the maximum level of the enchantment: a level 50 enchantment really works as level 50. See Levels Above the Maximum.

Events

You can use any event listed in the Events page. Because the enchantment must be on something the player holds or wears, the events with a player are the useful ones: attack, kill, block-break, fish, player-item-consume, player-interact, player-toggle-sneak, and so on.

On top of those, MetaEnchants adds four events made for enchantments, and uses the passive event:

Event When it runs Values You can change
defend A player is hit by another entity. The player is you, the wearer. {player} (the wearer), {target} and {entity_type} (the attacker, when there is one), {world}, {cause}, {damage} set-damage, cancel
damaged A player takes any damage: falls, fire, lava, explosions and also hits. {player}, {world}, {cause}, {damage} set-damage, cancel
bow-hit An arrow or trident shot by the player hits something. The level comes from the bow that shot it. (Other projectiles, like snowballs, also run it, and then the items the player holds count.) {player} (the shooter), {target} and {entity_type} (what was hit), {world}, {cause}, {damage} set-damage, cancel
shoot A player shoots a bow or crossbow. {player}, {target} (the arrow), {world}, {item} and {item_type} (the bow), {amount} (how much the bow was drawn, from 0 to 1) cancel
passive Every moment, for every online player, while they wear the enchantment. {player}, {world}, {passive_count}

How often does passive run? Every passive-interval ticks. The default is 20 (one second). You can change it in config.yml (1 to 1200). It only affects enchantments: MetaJobs has its own passive-interval. Keep in mind that it runs for every player who wears the enchantment, all the time, so keep passive triggers light. The passive Event and Effects That Last explains it step by step.

For bonuses that should last exactly while the enchantment is worn, use the actions that last: permanent-effect, attribute, flight... They stay while passive keeps running them, and go away by themselves when the player takes the item off, with no flickering:

triggers:
  swiftness:
    on: passive
    do:
      - attribute: movement_speed "0.05 * {level}" multiply
      - permanent-effect: NIGHT_VISION

A few useful remarks:

  • attack runs when the player is the one hitting. defend runs when the player is the one being hit. For an enchantment on armor, you almost always want defend.
  • For armor with {cause} conditions (like only fall damage), use damaged.
  • defend and damaged only run when the damaged entity is a player.
  • A cooldown is per player, as always.

Extra values

Besides {level} and the usual values of the event, enchantments give you:

Write Meaning
{level} The level the player has.
{enchant} or {enchant.name} The name of the enchantment.
{enchant.id} Its id (the file name).
{enchant.rarity} The id of its rarity.
{enchant.max_level} Its maximum level.
{enchant.weight} Its weight.
{enchant.curse}, {enchant.treasure} Yes or no.

Do not call a variable level: that name is taken.

Extra conditions

Everything in Conditions works. MetaEnchants adds three:

Condition Meaning Example
enchant-level Compares the level of the enchantment of this file. enchant-level: ">= 3"
has-enchant True when the player wears or holds an item with an enchantment. See below.
in-slot True when the item with this enchantment is in one of these slots: mainhand, offhand, hand, head, chest, legs, feet, armor, body, saddle or any. Useful for enchantments that can go on several kinds of items. in-slot: head
souls Compares the souls of the item with this enchantment. False if it has no soul tracker. souls: ">= 5"

has-enchant has these options:

Option Meaning Default
enchant The enchantment: sharpness, minecraft:sharpness, vampirism, metaenchants:vampirism... (required)
level A comparison, like ">= 2". any level
slot Where to look: any, mainhand, offhand, hand, feet, legs, chest, head, armor, body, saddle. any
  if:
    - has-enchant: minecraft:mending
    - has-enchant:
        enchant: vampirism
        level: ">= 2"
        slot: mainhand

has-enchant is useful to make enchantments that work together, for example a bonus when you also wear a second enchantment.

Extra actions

Everything in Actions works. MetaEnchants adds eight. The first four affect the player's own items, in a specific slot.

Action What it does Options
add-enchant Adds or changes an enchantment on an item. enchant (required), level (default 1, 0 to 255), slot (default mainhand)
remove-enchant Removes an enchantment from an item. enchant (required), slot (default mainhand)
damage-item Wears down an item. amount (required), slot (default mainhand)
repair-item Repairs durability. amount (required), slot (default mainhand)

The slot of these actions must be one concrete place: mainhand, offhand, feet, legs, chest, head or body.

    - damage-item:
        amount: 2
        slot: mainhand
    - repair-item:
        amount: "{level}"
        slot: chest

damage-item breaks the item if it runs out of durability, like normal use does. add-enchant accepts any level up to 255, even above the maximum.

Two more actions change the souls of the item with this enchantment: add-souls: 1 and remove-souls: 5. The amount can be a calculation like "{level} * 2".

stop-other-enchants

Stops the other enchantments from running for this same event. Triggers of other enchantments that come later do not run; this enchantment keeps running. Jobs and other plugins are not affected.

triggers:
  guard:
    on: defend
    if:
      - chance: "{level} * 10%"
    do:
      - set-damage: 0
      - stop-other-enchants

When this Guard blocks a hit, armor enchantments like Frost do not react to it. It only lasts for that one event: the next hit starts again.

Enchantments run in the order of their files (alphabetical), so stop-other-enchants cannot stop the ones that already ran for that event.

disable-enchant

Turns off one enchantment for a player for a time: its triggers do not run for that player until the time is over. Write all to turn off every MetaEnchants enchantment of that player.

triggers:
  neutralize:
    on: attack
    if:
      - target-player
      - chance: 20%
    do:
      - disable-enchant:
          enchant: angelic
          duration: 5s
          entity: "{target}"
      - message:
          text: "<red>Your Angelic is disabled for 5 seconds!"
          entity: "{target}"
Option Meaning Default
enchant The id of the enchantment, like angelic or metaenchants:angelic, or all. (required)
duration How long it stays off. (required)
entity The player whose enchantment is turned off. The target, otherwise the player.

The enchantments can still be on the items: they simply do nothing for a while. The time is forgotten when the player leaves.

Worlds where an enchantment does nothing

disabled-worlds, in the enchantment file or in config.yml for all of them, turns enchantments off in some worlds: none of their triggers run there. See disabled-worlds.

Writing good enchantment triggers

  • Use {level} in your numbers. chance: "{level} * 8%", amount: "{level} * 2", the level of an effect. That is what makes level 3 feel better than level 1. Times can use it too, as a calculation in seconds: duration: "{level} * 3", or a cooldown that gets shorter at higher levels: cooldown: "12 - {level} * 2".
  • Keep numbers in check. Level 50 is possible. Use min() and clamp() to cap things that could get out of hand, for example min({damage} * 0.05 * {level}, 4).
  • Add a cooldown to strong effects.
  • For armor, use defend, damaged or passive. For weapons, use attack or kill. For bows, use shoot and bow-hit.
  • Remember entity: "{player}" when you want an action like heal or effect to affect the wearer instead of the target. See Actions.

Reloading

After editing a trigger, run /metaenchants reload. If there is a mistake, the console tells you where, and the previous triggers keep working.

Clone this wiki locally