Repository navigation
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.
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.
A trigger of an enchantment runs only when the player has the enchantment on the right item. The plugin checks:
- The items the player is holding and wearing in the enchantment's
slots. If the enchantment is on one of them, it counts. - For
bow-hit, the bow, crossbow or trident that was shot; forshoot, the bow or crossbow. It does not matter what the player holds a second later. - 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.
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_VISIONA few useful remarks:
-
attackruns when the player is the one hitting.defendruns when the player is the one being hit. For an enchantment on armor, you almost always wantdefend. - For armor with
{cause}conditions (like only fall damage), usedamaged. -
defendanddamagedonly run when the damaged entity is a player. - A
cooldownis per player, as always.
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.
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: mainhandhas-enchant is useful to make enchantments that work together, for example a bonus when you also wear a second enchantment.
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: chestdamage-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".
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-enchantsWhen 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.
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.
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.
-
Use
{level}in your numbers.chance: "{level} * 8%",amount: "{level} * 2", thelevelof 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 acooldownthat gets shorter at higher levels:cooldown: "12 - {level} * 2". -
Keep numbers in check. Level 50 is possible. Use
min()andclamp()to cap things that could get out of hand, for examplemin({damage} * 0.05 * {level}, 4). -
Add a
cooldownto strong effects. -
For armor, use
defend,damagedorpassive. For weapons, useattackorkill. For bows, useshootandbow-hit. -
Remember
entity: "{player}"when you want an action likehealoreffectto affect the wearer instead of the target. See Actions.
After editing a trigger, run /metaenchants reload. If there is a mistake, the console tells you where, and the previous triggers keep working.