Enchantment Progression

Enchantment Progression (Forge 1.20.1)

Enchantment Progression overhauls Minecraft’s enchantment mechanics. Instead of instantly acquiring maximum-tier gear through basic trading or anvil combining, enchantments grow stronger dynamically as you use your equipment in the world.

Every swing, arrow, block broken, hit absorbed, and flight second feeds experience directly into your active gear. Enchantments level up organically through gameplay, turning your gear into evolving artifacts tailored to your journey.

Key Features

• Organic Leveling Mechanics: Enchantments level up while actively being used in battle, mining, exploration, and survival.
• Dedicated Dynamic Triggers: Built-in tracking for melee combat, ranged weapons, armor types, tridents, fishing rods, shields, and elytra flight.
• Anvil XP Recycling: Combining identical enchantments on an anvil transfers stored XP and level-based bonus XP instead of bypassing the progression curve with instant tier increases.
• Clean Visual Tooltips: Shift-hovering over items displays clear progress bars, current XP, and requirements for the next tier.
• Fully Data-Driven: Every enchantment's XP requirements, multipliers, maximum levels, and conditions can be adjusted via main config TOML file and JSON configs.
• KubeJS Integration: Native event hooks (EnchantmentProgressionEvents.xpGain) and script bindings (EnchProgression.addXp(...)) allow full modpack automation.

How It Works

Earning Experience

When an item has an enchantment that can still level up, relevant gameplay actions will award enchantment experience directly to that item.

When the stored XP reaches the required threshold for the current tier, the enchantment level automatically increments. The player receives a level-up notification in the action bar, accompanied by sound and particle effects.

Supported Progression Triggers

Anvil Merging & XP Transfer

In vanilla Minecraft, combining two items with identical enchantment levels instantly gives the next level. Enchantment Progression replaces this mechanic with an XP-transfer system:

• Target Item (Left Slot): Keeps its current level as the starting base.
• Sacrifice Item (Right Slot): Transfers a portion of its stored progression and grants bonus XP based on its level.

The Formula

XP Granted = (Stored XP on Sacrifice × combine_xp_percent) + (Sacrifice Level × combine_xp_per_level)

If the combined XP exceeds the requirement for the next tier, the target item levels up immediately on the anvil. Excess XP carries over to the new tier.

Configuration & Datapacks

Every single value in the mod is configurable without touching any Java code.

Global Config (config/enchantment_progression/_default.js)

Controls fallback default behavior when a specific enchantment file does not override a setting:

{
  "base_xp": 100.0,             // Base XP required for level 1 -> 2
  "level_multiplier": 2.0,      // Exponential scaling factor per level
  "max_level_override": 0,      // Override max enchantment tier (0 = use vanilla max)
  "enabled": true,              // Whether progression is active for this enchantment
  "combine_xp_per_level": 50.0, // Flat bonus XP per sacrifice level on an anvil
  "combine_xp_percent": 0.25,   // Percentage of stored sacrifice XP transferred on an anvil (0.25 = 25%)
  "trigger_xp": 1.0,            // Fallback XP amount if omitted in triggers
  "trigger_xp_multiplier": 1.0  // Fallback multiplier if omitted in triggers
}

Formulas

The amount of experience required for an item to move from the current level to the next: Threshold = base_xp × current_level^level_multiplier

The amount of experience awarded for a specific action (hit, mining, flying, etc.): XP Added = trigger.xp × (baseAmount × trigger.xp_multiplier)

Custom Enchantment JSON (data/enchantment_progression/enchantment_progression/<name>.js)

You can override or create custom files in datapacks or directly inside config/enchantment_progression/.

Example: sharpness.js

{
  "enchantment": "minecraft:sharpness",
  "base_xp": 120.0,
  "level_multiplier": 2.5,
  "max_level_override": 5,
  "enabled": true,
  "combine_xp_per_level": 60.0,
  "combine_xp_percent": 0.30,
  "triggers": [
    {
      "type": "deal_damage",
      "xp": 1.0,
      "xp_multiplier": 1.0
    },
    {
      "type": "kill_entity",
      "xp": 5.0,
      "xp_multiplier": 1.5
    }
  ]
}

Supported Trigger Filter Keys:

• "type": The identifier of the action (deal_damage, kill_entity, break_block, shield_block, elytra_flight, take_damage, etc.).
• "block_tag" / "specific_block": Matches specific block tags or registry IDs.
• "item_tag": Filter for caught fish/loot.
• "entity_type_tag": Filter for entities (minecraft:undead, minecraft:arthropods, etc.).
• "damage_type_tag": Filter for damage sources (minecraft:is_explosion, minecraft:is_fire, etc.).
• "min_distance": Minimum distance required for ranged hits or throws.
• "target_flying": Requires the target to be in flight.
• "target_on_fire": Requires the target to be burning.
• "in_water_or_rain": Requires the entity to be wet.

KubeJS Support (kubejs/server_scripts/<name>.js)

If KubeJS is installed, Enchantment Progression registers custom events and script bindings.

Listening & Modifying XP Gains

Example: xp_modifier.js

EnchantmentProgressionEvents.xpGain(event => {
    let player = event.player;
    let item = event.itemStack;
    let ench = event.enchantmentId; // e.g. "minecraft:sharpness"

    // Double Sharpness experience if the player is in the Nether
    if (ench === 'minecraft:sharpness' && player.level.dimension === 'minecraft:the_nether') {
        event.xp = event.xp * 2.0;
    }

    // Cancel XP gain completely under custom conditions:
    // event.cancel();
});

Manually Adding XP (Curios / Custom Inventory Integration)

You can award XP to any item from external scripts.

Example: manual_xp_addition.js

// Add 50 XP directly to the item's Unbreaking progression
EnchProgression.addXp(player, itemStack, 'minecraft:unbreaking', 50.0);

Commands for Testing

Quickly generate starter enchanted gear (lvl:1) to test the progression mechanics:

Weapon

/give @p netherite_sword{Enchantments:[{id:"minecraft:sharpness",lvl:1s},{id:"minecraft:looting",lvl:1s},{id:"minecraft:unbreaking",lvl:1s}]} 1

Bow & Crossbow

/give @p bow{Enchantments:[{id:"minecraft:power",lvl:1s},{id:"minecraft:unbreaking",lvl:1s}]} 1

/give @p crossbow{Enchantments:[{id:"minecraft:piercing",lvl:1s},{id:"minecraft:quick_charge",lvl:1s}]} 1

Trident

/give @p trident{Enchantments:[{id:"minecraft:loyalty",lvl:1s},{id:"minecraft:impaling",lvl:1s}]} 1

Armor & Shields

/give @p netherite_chestplate{Enchantments:[{id:"minecraft:protection",lvl:1s},{id:"minecraft:thorns",lvl:1s}]} 1

/give @p shield{Enchantments:[{id:"minecraft:unbreaking",lvl:1s}]} 1

/give @p elytra{Enchantments:[{id:"minecraft:unbreaking",lvl:1s}]} 1

Compatibility

• Minecraft Version: 1.20.1
• Mod Loader: Minecraft Forge (47.1.0+)
• Client / Server: Required on both Client and Server (syncs tooltips and progression logic).
• Modded Enchantments: Modded enchantments with defined categories automatically fall back to balanced default curves and can be fully customized with their own JSON definitions.

Known Issues

• Impaling & Loyality doesn't gain progress when used by trident throw.