Skip to content

Migrating From AdvancedEnchantments

neoramm edited this page Nov 9, 2026 · 2 revisions

Migrating from AdvancedEnchantments

MetaEnchants can turn your AdvancedEnchantments enchantments into MetaEnchants enchantments, and later the items your players already have. It reads the files of AdvancedEnchantments, writes new files in a separate folder, checks each one with the engine, and gives you a report of everything it could not convert.

Your original files are never changed.

What you need

  • MetaCore and MetaEnchants installed and working.
  • The folder of AdvancedEnchantments still in plugins, with its enchantments.yml and groups.yml. AdvancedEnchantments itself does not have to be running; only its files are read.

Step by step

  1. Run this command in the console or in the game:

    /metacore migrate advancedenchantments
    

    It needs the permission metacore.migrate (operators have it). It works in the background. When it ends you get a summary like this:

    AdvancedEnchantments → MetaEnchants: 180/180 files, 292 warnings, 7 elements without equivalent, 0 rejected by the engine Report: plugins/MetaEnchants/migrated/report-advancedenchantments.md
    
  2. Open plugins/MetaEnchants/migrated/report-advancedenchantments.md. Each enchantment has its own section with what was approximated or skipped. It works like the report of the EcoHub migration, explained in The report.

  3. Decide the rarities (see Groups and rarities) and fix what the report asks for, directly in the files of plugins/MetaEnchants/migrated/enchants.

  4. Move the files to plugins/MetaEnchants/enchants and restart the server: new enchantments need a restart. If an enchantment with the same id already exists (for example Soulbound), keep only one of the two files.

  5. When the new enchantments work, turn on the conversion of items so the items of your players get them too.

Running the command again rewrites the files in migrated, so don't keep your fixes there for long.

What is converted

Each enchantment of enchantments.yml becomes one file, enchants/<name>.yml. Its id is the same as in AdvancedEnchantments: berserk becomes metaenchants:berserk.

In AdvancedEnchantments Becomes
display name, without colors: the color comes from the rarity.
description, and description inside a level description, per level when the levels have their own.
group rarity. See Groups and rarities.
levels max-level is the highest level, and each level becomes its own triggers.
applies supported-items and slots. ALL_SWORD becomes #minecraft:swords, ALL_BOOTS becomes #minecraft:enchantable/foot_armor and the boots slot, DIAMOND_ARMOR becomes the four diamond pieces...
applies-to applies-to, the text of books.
type The event of the triggers. See Triggers.
chance, cooldown, conditions of a level chance, cooldown and conditions of its trigger. A cooldown with <math> or variables stays a calculation.
effects of a level The actions of its trigger. See Effects.
settings.required-enchants requires, with the level when it has one (speed:3).
settings.removed-enchants replaces.
settings.not-applyable-with incompatible.
settings.removeable removable. It protects from the grindstone and from black scrolls.
souls of a level A souls condition and a remove-souls action: the level needs those souls on the item and spends them.
settings.disabled-worlds disabled-worlds.
settings.showActionBar An actionbar with the name of the enchantment at the start of each trigger.
enabled: false The enchantment is skipped.

Here is Berserk from the default AdvancedEnchantments file, after the migration:

name: Berserk
description:
  - <gray>Chance of strength
  - <gray>and mining fatigue.
rarity: uncommon
max-level: 5
supported-items:
  - '#minecraft:swords'
  - '#minecraft:axes'
slots:
  - mainhand
applies-to: Swords, Axes
triggers:
  attack-1:
    on: attack
    if:
      - '{level} == 1'
      - chance: 4%
    do:
      - effect:
          type: MINING_FATIGUE
          level: 1
          duration: 60t
          entity: '{player}'
      - effect:
          type: STRENGTH
          level: 1
          duration: 60t
          entity: '{player}'
    cooldown: 8s

Each level has its own trigger, like attack-1, attack-2... The last level uses {level} >= 5, so items with a level above the maximum still work.

Triggers

type in AdvancedEnchantments Event Notes
ATTACK, ATTACK_MOB attack With target-player or target-player: false. Both together: no condition.
DEFENSE, DEFENSE_MOB defend Melee hits only.
DEFENSE_PROJECTILE, DEFENSE_MOB_PROJECTILE defend Projectiles only.
SHOOT, SHOOT_MOB, ARROW_HIT bow-hit
BOW_FIRE shoot
MINING block-break
KILL, KILL_MOB, KILL_PLAYER kill
DEATH player-death
FALL_DAMAGE, FIRE, EXPLOSION, ELYTRA_FLY_DAMAGE damaged With the matching cause.
EFFECT_STATIC, HELD passive With actions that last: potions become permanent-effect, FLY becomes flight...
REPEATING passive With every and the time of the level.
RIGHT_CLICK alt-click
RIGHT_CLICK_ENTITY player-interact-entity
HOOK_ENTITY, CATCH_FISH, BITE_HOOK, ROD_CAST catch-entity, catch-fish, bite, cast-rod
ITEM_BREAK, SWING, JUMP, EAT, SHIELD_BLOCK, ELYTRA_FLY player-item-break, swing, jump, player-item-consume, shield-block, deploy-elytra
JOIN, QUIT, COMMAND player-join, player-quit, player-command-preprocess

Who gets the effect

In AdvancedEnchantments, @Victim and @Attacker depend on the event. The migration turns them into the player or the target of the MetaEnchants event:

Event @Attacker @Victim No target, @Self
ATTACK, SHOOT, KILL... (you hit) {player} (you) {target} {player}
DEFENSE, DEATH... (you are hit) {target} {player} (you) {player}
Other targets Become
@Aoe{radius=5,target=...} for-nearby with that radius. target=mobs skips players.
@NearestPlayer{radius=10} for-nearby with only one player.
@AllPlayers for-all-players.
@Block, @Trench, @Tunnel, @Veinmine The block of the event, mine-radius and mine-vein (with the whitelist of the level).

Effects

Most effects have a direct equivalent: POTION becomes effect, DO_HARM becomes damage, INCREASE_DAMAGE becomes set-damage: "{damage} * (1 + 20 / 100)", MESSAGE becomes message (also to the victim), CANCEL_EVENT becomes cancel, LIGHTNING, EXPLODE, BURN, FREEZE, DISARM, DROP_HEAD, REVIVE, BREAK_TREE, AUTO_REEL, TELEPORT_BEHIND, REMOVE_RANDOM_ARMOR, STEAL_HEALTH and many more.

Some need a closer look:

In AdvancedEnchantments Becomes
WAIT:20 A delay with the effects after it.
<chance>25</chance> on one effect A when block with chance: 25%.
<condition>...</condition> on one effect A when block with the condition.
<random number>1-5</random number> round(random(1, 5)). The first one of a level is kept in the value {random_value}, so %random% in a message shows the same number.
<math>, <round>, <int> A calculation, round() and floor().
DISABLE_ACTIVATION:angelic:5 disable-enchant: Angelic stops working for that player for 5 seconds.
GUARD:ZOMBIE:10:2 spawn-mobs: two zombies that attack the enemy for 10 seconds. They do not follow the player like guards.
BOOST velocity. Check the strength.
KEEP_ON_DEATH The soulbound option of the enchantment.
ADD_SOULS:2, REMOVE_SOULS:2 add-souls and remove-souls.
TP_DROPS, PLANT_SEEDS:0 telekinesis and replant-crops in an extra passive trigger: they work while the item is held, not only when the enchantment activates.
REVIVE in DEATH revive in an extra damaged trigger, which saves the player from the hit that would kill them.
STOP_KNOCKBACK The speed of the target is set to zero right after the hit.
Effects in EFFECT_STATIC that do not last (MESSAGE, ADD_HEALTH...) An extra trigger on activate, which runs once when the item is put on, as in AdvancedEnchantments.

Effects that used to be skipped have their own actions now: PLANT_SEEDS with a radius becomes plant-seeds, CACTUS becomes hurt-animation, PUMPKIN becomes pumpkin-view, RESET_COMBO, STEAL_EXP, STEAL_MONEY, STEAL_GUARD, IGNORE_ARMOR_PROTECTION, PERMISSION, SET_VARIABLE, INVERT_VARIABLE, FLY_SPEED and ADD_EXP_MCMMO become the actions of the same name in Actions, and TELEPORT and FIREWORK are converted too. An effect that needs something the event does not have (like TELEPORT_BEHIND without an enemy) is skipped and listed in the report, with how many times it appeared.

Conditions

AdvancedEnchantments conditions like %victim health% < 10 : %allow% become trigger conditions. They are read in order, as in AdvancedEnchantments:

Outcome Becomes
%allow% The trigger runs when the condition is true (with several %allow% lines, when any of them is true).
%stop% The trigger does not run when the condition is true.
%chance%+10 The chance of the level is 10 points higher while the condition is true.
%continue% Nothing.
%force% Like %allow%; the chance and the cooldown still apply.

The values are translated too: %victim health% becomes {target.health} or {player.health} depending on the event, %mob type% = ZOMBIE becomes entity: [ZOMBIE], %is sneaking% becomes sneaking, %player world% becomes the name of the world, %block type% contains COAL_ORE becomes text-contains, and so on. Old names are updated: PIG_ZOMBIE becomes ZOMBIFIED_PIGLIN, CROPS becomes WHEAT.

%souls on item% >= 10 becomes the souls condition.

%is headshot%, %combo%, %is bleeding% (needs mcMMO), %nearby mobs%, %players%, %item slot%, %offhand item%, %permissions% contains, %custom_<name>% (a variable) and matchesregex are converted too. Values with no equivalent are skipped and listed in the report. A skipped %allow% line lets the effect happen, so it never blocks the enchantment completely.

Groups and rarities

AdvancedEnchantments groups (SIMPLE, UNIQUE, ELITE...) become MetaEnchants rarities:

  • A group whose name is a rarity of your rarities.yml keeps it.
  • Otherwise, SIMPLE becomes common, UNIQUE uncommon, ELITE rare, ULTIMATE epic, and LEGENDARY, HEROIC and MASTERY legendary. Any other group gets the first rarity of rarities.yml.

The migration also writes plugins/MetaEnchants/migrated/rarities-from-advancedenchantments.yml, with every group as a rarity (name and color). If you prefer the names of AdvancedEnchantments, copy them into rarities.yml, change rarity in the migrated files, and restart.

Items players already have

Items enchanted with AdvancedEnchantments keep their enchantments in their own data. MetaEnchants can turn them into real enchantments:

advancedenchantments:
  convert-items: true
  remove-lore: true

With convert-items: true, every item in the inventory and the ender chest of a player is converted when they join, and the items of every inventory they open. Books become MetaEnchants books. With remove-lore: true, the lines AdvancedEnchantments wrote with the names of the enchantments (like Berserk III) are removed, because the tooltip now shows them.

Only enchantments that exist in MetaEnchants are converted. The console says which ones are missing, once each.

Commands, for administrators:

Command What it does
/metaenchants convert Converts the item in your hand. If there is nothing to convert, it lists the data keys of the item.
/metaenchants convert <players> Converts the inventories and ender chests of those players.

AdvancedEnchantments changed where it stores enchantments between versions. MetaEnchants looks for the usual places; if /metaenchants convert finds nothing on an item that has enchantments, look at the keys it lists and add a pattern in advancedenchantments.keys. The part (?<id>...) must capture the name of the enchantment:

advancedenchantments:
  keys:
    - "ae_enchantment;(?<id>[a-z0-9_-]+)"
    - "advancedenchantments:ae_enchantment[;_/]?(?<id>[a-z0-9_-]+)"

Keep convert-items on until your players have logged in at least once, then you can turn it off.

What is not migrated

The full list of what has no equivalent is in the report of each migration.

Clone this wiki locally