Repository navigation
Dev Guides
This page is for plugin developers who want to create enchantments directly in code, instead of in a YAML file.
Everything else in this wiki is for server owners. This is the only page with code. All the examples are in Kotlin, the language of MetaEnchants and of the Trigger Engine's DSL. Imports are left out of the short snippets; the complete example at the end has them.
The built-in elements print their console messages in English, and so do the messages that report mistakes of code-defined enchantments.
An enchantment is made of two things:
- The enchantment itself: its name, levels, items, rarity, where it appears. The game reads this once, when the server starts.
-
What it does: its triggers. These are loaded when MetaEnchants enables and every time
/metaenchants reloadruns.
With the API, you describe both in one place, in your plugin's bootstrap class:
MetaEnchantsApi.enchantment("rage") {
name("Rage")
rarity("epic")
maxLevel(3)
supportedItems("#minecraft:enchantable/chest_armor")
slots(SlotGroup.CHEST)
triggers {
trigger("fury") {
on("defend")
actions { "message"("<red>Rage {level}!") }
}
}
}That enchantment is a real enchantment of the game, exactly like one defined in a file: it shows up in the enchanting table, in villagers and loot (as you choose), in /enchant, in the anvil and in the /metaenchants menu.
Your plugin needs MetaEnchants and MetaCore on its compile classpath. MetaCore is the shared plugin that provides the Trigger Engine classes; MetaEnchants compiles against them and does not bundle the engine.
Build both jars from this repository:
./gradlew :meta-core:shadowJar :enchants-plugin:jar
Copy MetaCore and MetaEnchants into libs/ and use them in your build:
plugins {
kotlin("jvm") version "2.4.20"
}
repositories {
mavenCentral()
maven("https://repo.papermc.io/repository/maven-public/")
}
dependencies {
compileOnly("io.papermc.paper:paper-api:26.2.build.+")
compileOnly(files("libs/MetaEnchants.jar"))
compileOnly(files("libs/MetaCore.jar"))
}
kotlin {
jvmToolchain(25)
}Use compileOnly: your jar does not carry MetaEnchants, MetaCore, Kotlin or the engine. The server provides them.
Declare MetaCore and MetaEnchants as dependencies in both places: the bootstrap (where you register the enchantments) and the server (where your plugin runs). Both must load before you, and their classes must be visible to you.
name: RageEnchant
version: '1.0'
main: rage.RagePlugin
bootstrapper: rage.RageBootstrap
api-version: '26.2'
dependencies:
bootstrap:
MetaCore:
load: BEFORE
required: true
join-classpath: true
MetaEnchants:
load: BEFORE
required: true
join-classpath: true
server:
MetaCore:
load: BEFORE
required: true
join-classpath: true
MetaEnchants:
load: BEFORE
required: true
join-classpath: trueAlso declare your bootstrap class with bootstrapper: as shown.
The game builds its list of enchantments before plugins are enabled. That is why the enchantments must be declared in the bootstrap, and why a few things happen in a strict order:
| Moment | What happens | What you do |
|---|---|---|
| Your plugin's bootstrap | The server is starting. The enchantment list is still open. | Call MetaEnchantsApi.enchantment(...) and MetaEnchantsApi.extend { ... }. |
| The game builds its enchantment list | MetaEnchants collects the enchantments from files and from code, checks them, and registers them in the game. | Nothing. Mistakes are printed in the console. |
| MetaEnchants enables | The engine is created. Your extend blocks run, then every trigger (files and code) is compiled. |
Register your own conditions and actions in extend. |
/metaenchants reload |
Descriptions, icons, files and triggers are loaded again. The triggers { } blocks of your enchantments run again. |
Nothing. Keep triggers { } free of side effects. |
Rules that follow from this:
-
MetaEnchantsApi.enchantmentonly works in the bootstrap. After the enchantment list is built it throws an error saying so. -
MetaEnchants must load before your plugin, so its bootstrap runs first. That is what
load: BEFOREdoes. -
Nothing you register can change the game's registry after the server has started. The registry data (levels, weight, items, slots, incompatibilities, rarity and the places of
obtain) is fixed until the next restart, exactly as for files. The reloadable rules (description, icon, activation, type, requires, price, book, chances inobtain...) and the triggers do reload: MetaEnchants keeps the values of the builder, and thetriggers { }block runs again on each reload. - Do not touch the game's world, players or registries in the bootstrap. They do not exist yet. The builder only stores your description.
- The enchantment id must be new. If a file with the same name exists in the
enchantsfolder, the console reports the clash and the code version is ignored.
Inside MetaEnchantsApi.enchantment("id") { ... } you describe the enchantment. Every function matches an option of the YAML files, with the same rules, the same defaults and the same checks.
| Function | YAML option | Notes |
|---|---|---|
name("Rage") |
name |
|
description("line 1", "line 2") |
description |
Lines with colors. |
rarity("epic") |
rarity |
The id of a rarity written in rarities.yml. |
maxLevel(3) |
max-level |
1 to 255. |
weight(2) |
weight |
1 to 1024. From the rarity if not set. |
anvilCost(4) |
anvil-cost |
|
minCost(10, 8) |
min-cost |
base, per-level. |
maxCost(40, 8) |
max-cost |
|
supportedItems("#minecraft:swords") |
supported-items |
Required. Item names and tags. |
primaryItems("minecraft:diamond_sword") |
primary-items |
|
slots(SlotGroup.MAINHAND, SlotGroup.OFFHAND) |
slots |
SlotGroup has ANY, MAINHAND, OFFHAND, HAND, FEET, LEGS, CHEST, HEAD, ARMOR, BODY and SADDLE. |
incompatible("minecraft:thorns", "vampirism") |
incompatible |
Names, ids of MetaEnchants enchantments and #tags. |
obtain(Channel.LOOT, Channel.VILLAGERS) |
obtain |
See the note below. |
obtain(Channel.VILLAGERS, 30) |
obtain |
Sets one place to 30% and keeps the other places already written. |
treasure() |
treasure |
Pass false to turn it off. |
curse() |
curse |
|
stack(StackMode.SUM) |
stack |
HIGHEST (default) or SUM. |
icon(Material.MACE) |
display-item |
|
activation(Activation.EVENT_ITEM) |
activation |
EQUIPMENT (default) or EVENT_ITEM. |
type("special") |
type |
The id of a type. |
requires("vampirism" to 2) |
requires |
Enchantment and lowest level. |
replaces("swiftness") |
replaces |
|
dragAndDrop(false) |
drag-and-drop |
|
price(money = 100.0, levels = 3, items = listOf("DIAMOND 2"), perLevel = true) |
price |
Every argument is optional. |
removable(false) |
removable |
|
disabledWorlds("world_nether") |
disabled-worlds |
|
soulbound(chance = 50.0, cost = SoulboundCost.LEVEL) |
soulbound |
SoulboundCost has NONE, LEVEL and ALL. |
minimumTableLevel(20) |
minimum-table-level |
|
book(item = mapOf("material" to "PAPER"), stackable = true, maxStack = 16, success = "60-100") |
book |
item is the same map as in YAML. |
appliesTo("Swords and axes") |
applies-to |
|
triggers { ... } |
triggers |
See section 5. |
Channel has ENCHANTING_TABLE, VILLAGERS, LOOT, FISHING, MOB_EQUIPMENT and TRADED_EQUIPMENT.
A difference with files: in a file, an obtain that mentions only some places keeps the rarity's value for the others. In code, obtain(...) turns on the places you list and turns off all the others, except fishing: it is omitted so the rarity's value applies, or the final loot value when the rarity does not set it, unless you pass Channel.FISHING. If you don't call obtain at all, everything comes from the rarity. Use obtain(channel, chance) when you only want to change one place and keep the rest.
All the checks of the files apply. If something is wrong (an unknown rarity, a level out of range, a bad tag name), the console prints the problem with the position code:<id>, and that enchantment is skipped. Everything else keeps loading.
Triggers are written with the Trigger Engine's Kotlin DSL inside triggers { }. It builds exactly what the YAML would. The whole language is described in the Trigger Engine Dev Guides; here is a summary:
triggers {
trigger("fury") {
on("defend")
vars { "bonus" eq "{level} * 2" }
conditions {
"chance"("{level} * 15%")
any {
"low-health"("12")
expression("{player.sneaking}")
}
}
actions {
"effect" {
"type" to "STRENGTH"
"duration" to "6s"
"level" to "{level}"
"entity" to "{player}"
}
"message"("<red>Rage {level}!")
}
otherwise { "actionbar"("<gray>Nothing") }
cooldown("10s")
priority(5)
}
}- All the values of enchantments are available:
{level},{enchant.name}, and so on. See Triggers for Enchantments. -
triggers { }runs when MetaEnchants loads, and again on every reload. Do not store state inside it, and do not assume it runs only once. - Mistakes inside it are reported just like YAML mistakes, with the file shown as
code:<id>.
For something quick that you do not want to register as a reusable element, write it inline:
conditions {
check { ctx -> ctx.getNumber(RageState.keys.level) >= 1 }
}
actions {
run { ctx ->
ctx.get(RageState.keys.paper.player())?.sendActionBar(Component.text("RAGE"))
}
}ctx is the context of the event. It gives you the values: ctx.get(key) for objects and ctx.getNumber(key) for numbers. The keys you need are in EnchantKeys, which you receive in extend (next section): keys.level is the level, keys.paper.player() the player, keys.paper.target() the target, and so on.
Keep inline code fast: it runs every time the event happens. The rules of the Trigger Engine Dev Guides apply.
Files and code can use any condition or action the engine has. To add your own, use MetaEnchantsApi.extend. It gives you the engine of MetaEnchants and its keys, before the first load of triggers, so everything you register is available to every enchantment, from files too.
MetaEnchantsApi.extend { paper, keys ->
RageState.keys = keys
val player = keys.paper.player()
paper.engine().condition("low-health") {
requires(player)
cost(Cost.TRIVIAL)
val below = param("below", Parsers.NUMBER)
factory {
val limit = this[below]
Condition { ctx ->
val target = ctx.get(player) ?: return@Condition false
target.health < limit.eval(ctx)
}
}
}
}After this, low-health: 12 works in any enchantment file and in "low-health"("12") in code.
Things to know:
-
extendblocks are stored in the bootstrap and run when MetaEnchants enables, before the first load. You can callextendas many times as you want. - You can register anything the engine supports: conditions, actions, properties, functions, parsers, even your own keys and event types. See the Trigger Engine Dev Guides to learn how each one is written and why registration order matters.
- Keep what you need later (like the
EnchantKeys) in a place your triggers can reach, such as theRageStateobject of the example. - If you register a new event type that carries a
player, enchantments can listen to it withon("your-event"). MetaEnchants finds the enchantment by looking at what the player holds and wears.
A plugin with one code-defined enchantment, Rage, and one custom condition, low-health. It was tested on a server together with MetaEnchants.
paper-plugin.yml
name: RageEnchant
version: '1.0'
main: rage.RagePlugin
bootstrapper: rage.RageBootstrap
api-version: '26.2'
dependencies:
bootstrap:
MetaCore:
load: BEFORE
required: true
join-classpath: true
MetaEnchants:
load: BEFORE
required: true
join-classpath: true
server:
MetaCore:
load: BEFORE
required: true
join-classpath: true
MetaEnchants:
load: BEFORE
required: true
join-classpath: trueRageState.kt
package rage
import io.github.neoramm.metaenchants.engine.EnchantKeys
object RageState {
lateinit var keys: EnchantKeys
}RageBootstrap.kt
package rage
import io.github.neoramm.metaenchants.api.MetaEnchantsApi
import io.github.neoramm.metaenchants.definition.Channel
import io.github.neoramm.metaenchants.definition.SlotGroup
import io.github.neoramm.triggerengine.core.api.Condition
import io.github.neoramm.triggerengine.core.api.Cost
import io.github.neoramm.triggerengine.core.config.Parsers
import io.github.neoramm.triggerengine.kotlin.condition
import io.papermc.paper.plugin.bootstrap.BootstrapContext
import io.papermc.paper.plugin.bootstrap.PluginBootstrap
import net.kyori.adventure.text.Component
import org.bukkit.Material
class RageBootstrap : PluginBootstrap {
override fun bootstrap(context: BootstrapContext) {
MetaEnchantsApi.extend { paper, keys ->
RageState.keys = keys
val player = keys.paper.player()
paper.engine().condition("low-health") {
requires(player)
cost(Cost.TRIVIAL)
val below = param("below", Parsers.NUMBER)
factory {
val limit = this[below]
Condition { ctx ->
val target = ctx.get(player) ?: return@Condition false
target.health < limit.eval(ctx)
}
}
}
}
MetaEnchantsApi.enchantment("rage") {
name("Rage")
description("<gray>When you are badly hurt,", "<gray>anger gives you strength.")
rarity("epic")
maxLevel(3)
supportedItems("#minecraft:enchantable/chest_armor")
slots(SlotGroup.CHEST)
incompatible("minecraft:thorns")
obtain(Channel.ENCHANTING_TABLE, Channel.LOOT)
icon(Material.NETHERITE_CHESTPLATE)
triggers {
trigger("fury") {
on("defend")
conditions {
"low-health"("12")
"chance"("{level} * 15%")
check { ctx -> ctx.getNumber(RageState.keys.level) >= 1 }
}
actions {
"effect" {
"type" to "STRENGTH"
"duration" to "6s"
"level" to "{level}"
"entity" to "{player}"
}
"message"("<red>Rage {level}! <gray>You feel stronger.")
run { ctx ->
ctx.get(RageState.keys.paper.player())?.sendActionBar(Component.text("RAGE"))
}
}
cooldown("10s")
}
}
}
}
}RagePlugin.kt
package rage
import org.bukkit.plugin.java.JavaPlugin
class RagePlugin : JavaPlugin()The plugin class is empty because everything happens in the bootstrap and in MetaEnchants.
When the server starts you will see something like this in the console:
[MetaEnchants] Registered 9 enchantments in the vanilla registry (1 from code)
That line means 9 enchantments were registered, one of them from code. Then /metaenchants info metaenchants:rage shows its details, and /enchant @s metaenchants:rage 2 works.
Every time an enchantment is about to run its triggers for a player, MetaEnchants calls io.github.neoramm.metaenchants.api.EnchantActivateEvent. Cancel it to stop that enchantment for that event:
@EventHandler
fun onActivate(event: EnchantActivateEvent) {
if (event.player.world.name == "spawn" && event.trigger == "attack") {
event.isCancelled = true
}
}| Getter | What it is |
|---|---|
player |
The player of the event. |
enchantment |
The Bukkit Enchantment. |
level |
The level it would run with. |
trigger |
The name of the event, like attack, defend or passive. |
It is only built when some plugin listens to it, so it costs nothing otherwise. It runs once per enchantment and event, before the conditions of the triggers, so it also runs when a condition later fails.
The external item ids of Enchanted Books work in your own ItemSpecs and in MetaCore's item registry: metaenchants:book/<id>/<level> and metaenchants:random-book/<rarity>.
The %metaenchants_...% placeholders are listed in PlaceholderAPI.
| Problem | Likely cause |
|---|---|
ClassNotFoundException or NoClassDefFoundError for MetaEnchants or engine classes |
The dependency is missing in paper-plugin.yml, it lacks join-classpath: true, or MetaCore (the shared engine) is missing from the compile or server classpath. |
The enchantment registry is already frozen |
MetaEnchantsApi.enchantment was called after the bootstrap. Call it from your PluginBootstrap. |
| The enchantment does not exist in the game | Check the console at startup for the error of code:<id>. The enchantment with errors is skipped. |
already exists as a file |
A file in enchants/ has the same id. Rename one of them. |
| The rarity does not exist |
rarity("...") must be an id from rarities.yml. |
| Your condition or action is "unknown" in a file | You registered it outside extend, or too late. Use MetaEnchantsApi.extend. |
| The trigger never runs | The item is not in the right slot, the event is wrong (attack vs defend) or the enchantment has no triggers. See Fixing Problems. |
| Changes in the numbers have no effect | They need a restart. Descriptions, icons, activation, the rules (type, requires, price, book...) and triggers reload. |
-
MetaCoreandMetaEnchantsare declared as dependencies in bothbootstrapandserver, withload: BEFOREandjoin-classpath: true. - Enchantments are declared in the
PluginBootstrap. - Every enchantment has
supportedItems(...). - The
rarityexists inrarities.yml. - Custom conditions and actions are registered in
extend. -
triggers { }has no side effects. - You restarted the server and checked the line "Registered ... (N from code)" and
/metaenchants info.