Authored enchantments

EliteMobs and FreeMinecraftModels supply custom enchantments through a shared MagmaCore system. Each plugin owns its definitions and Lua effects under its own enchantments/ folder. Native Minecraft enchantments remain in the minecraft: namespace.

Item references

Custom effects use a lowercase namespaced ID and a positive integer level. This example is an FMM item definition:

enchantments:
  - "minecraft:unbreaking,3"
  - "elitemobs:critical_strikes,2"

For example, critical_strikes.yml in EliteMobs' enchantment catalog defines elitemobs:critical_strikes. An FMM definition uses freeminecraftmodels:. Subfolders do not become part of the ID; give content files unique filenames.

EliteMobs custom-item YAML retains Bukkit names such as UNBREAKING,3 for native enchantments, while requiring namespaced IDs for custom effects. Do not copy FMM's native-item syntax into another plugin without checking that plugin's item format.

The installed provider must recognize the ID. Compatibility, item type, slot, conflicts, and required capabilities come from its definition. Removing a provider does not turn its custom effect into a native enchantment.

Definition format

This is the shipped FMM Ignition definition, paired with ignition.lua in the same enchantment catalog:

isEnabled: true
name: Ignition
description: Sets surviving targets on fire after a staff fireball hits.
maxLevel: 3
curse: false
validSlots: [MAINHAND]
itemTypes: [STAFF]
attackKinds: [STAFF_FIREBALL]
requires: []
conflicts: []
stacking: source_item
script: ignition.lua
parameters:
  base_ticks: 20
  ticks_per_level: 20

return {
    api_version = 1,
    on_ignition_ticks = function(context)
        return math.max(0, math.min(200, context.parameters.base_ticks
            + context.parameters.ticks_per_level * context.enchantment.level))
    end
}

This query returns an ignition duration to FMM. It does not run as a prop script or an equipped-item script.

Field	Meaning
isEnabled	Defaults to true; disabled definitions do not enter the catalog
name	Required plain display name
description	Optional description, empty by default
maxLevel	Positive enchanting level cap; explicitly authored items may exceed it
curse	Whether the enchantment is a curse; defaults to false
validSlots	Equipment slots: HEAD, CHEST, LEGS, FEET, MAINHAND, OFFHAND
itemTypes	Accepted item categories, including WAND and STAFF
attackKinds	Optional magic attack filter: WAND_MISSILE, STAFF_MELEE, STAFF_FIREBALL
requires	Provider capability requirements
conflicts	Other lowercase namespaced enchantment IDs
stacking	source_item by default, or sum_equipped_levels
script	Required lowercase .lua filename without a directory
parameters	Named scalar values or per-level scalar lists

A per-level list must have exactly maxLevel entries. Above that level, the last list value is retained while the script still receives the actual enchantment level. Parameters belong to the particular effect; putting an arbitrary key here does not create a new mechanic.

Unknown top-level fields, duplicate IDs, missing scripts, and unsupported hooks reject the candidate catalog. Fix the file named in the error before reloading. A failed candidate is not published over the active catalog.

Effect ownership

Start from an effect shipped by the plugin that will own your new definition. Its supported hooks and domain operations determine what it can do. Query hooks return values such as missile count, critical chance, or threat bonus. Action hooks handle accepted item inputs and can own timed effects.

The old FMM context.item API and its equip/unequip lifecycle do not apply here. Enchantment scripts use their own context.enchantment, context.parameters, captured source information, and action operations. Do not rename an old item script and assume its context is compatible.

Upgrading existing content

FMM skips custom items with nonempty scripts: or retired unnamespaced enchantment entries. Replace those item definitions with namespaced enchantments; prop scripts remain supported.

EliteMobs custom effects now use maxLevel and effect-specific parameters in provider YAML. Native and elite-level enchantment configuration is a separate format. Follow the EliteMobs enchantment reference rather than copying an old maxLevelV2 file into a provider definition.