Item Levels

Item levels let an item gain XP and level up as it is used, instead of having a value set directly. Each item level is a config file that defines how much XP each level needs and what happens on level-up, and you grant XP with the level_item effect, or set the level directly with set_item_level. This page covers creating one, naming it, its structure, and the placeholders it exposes.

Quick start

1. Open the /plugins/libreforge/levels/ folder.

2. Copy _example.yml and rename it, e.g. pickaxe.yml. The file name (without .yml) is the level's ID.

3. Set your XP requirements with either xp-formula or a requirements list.

4. Add the effects you want under level-up-effects.

5. On an item, add the level_item effect with your level's ID so it gains XP (see Granting XP).

6. Run /libreforge reload, then use the item and watch it gain XP and level up.

Naming and IDs

The file name without .yml is the item level's ID. A file named pickaxe.yml has the ID pickaxe, which you reference as id: pickaxe in the level_item effect and in placeholders like %libreforge_item_level_pickaxe%.

The structure of an item level

# === XP requirements: how much XP each level needs ===
# Option 1: a formula for infinite levels
xp-formula: (2 ^ %level%) * 25 # XP needed for the next level; %level% is the current level
max-level: 10 # Optional; the maximum level

# Option 2: a fixed list instead of xp-formula, one entry per level
# requirements:
#   - 50
#   - 100
#   - 200
#   - 400

# === Level-up effects: what runs when the item levels up ===
level-up-effects: # %level% is the level the item reached
  - id: send_message
    args:
      message: "&fYou leveled up to &a%level%&f!"
  - id: play_sound
    args:
      sound: entity_player_levelup
      volume: 1.0
      pitch: 1.5

XP requirements

There are two ways to set how much XP each level needs: a formula for infinite levels, or a fixed list. Use one or the other.

xp-formula: (2 ^ %level%) * 25 # XP needed for the next level; %level% is the current level
max-level: 10 # Optional; the maximum level

requirements: # XP for each level, in order; the list length sets the max level
  - 50
  - 100
  - 200
  - 400

Level-up effects

These effects run each time the item levels up. The %level% placeholder is the level the item just reached.

level-up-effects:
  - id: send_message
    args:
      message: "&fYou leveled up to &a%level%&f!"

Granting XP

The level config only defines requirements and rewards; an item earns XP with the level_item effect. Add it to the item that should level up, passing your level's ID and the XP to grant. Here is an example EcoItems item using the example level:

item:
  item: diamond_pickaxe hide_attributes unbreakable efficiency:5 blast_mining:3
  display-name: "&eLevellable Pickaxe &8- &6%libreforge_item_level_example_numeral%"
  lore:
    - "&fCurrently on level &a%libreforge_item_level_example%"
    - "&fXP: &a%libreforge_item_xp_example%&8/&a%libreforge_item_xp_required_example% &f(&a%libreforge_item_progress_example%%&f)"
  craftable: false
  recipe: [ ]

slot: mainhand

effects:
  - id: level_item # Grants XP to the item level
    args:
      id: example # The item level ID (the level file name without .yml)
      xp: "%v%" # XP granted per trigger; %v% is the trigger value
    triggers:
      - mine_block

conditions: [ ]

To set an item straight to a level instead of granting XP towards it, use set_item_level. XP progress on the item resets to 0, and level-up effects fire if the new level is higher than the current one (nothing fires if it's the same or lower):

effects:
  - id: set_item_level
    args:
      id: example # The item level ID (the level file name without .yml)
      level: 5 # The level to set the item to. Supports expressions.
    triggers:
      - some_trigger

Internal placeholders

Swap <id> for your item level's ID. Add _numeral to the end of any placeholder to get the value as a roman numeral.

Where to go next

• Effects: Configuring an Effect to build the level_item effect and your level-up effects.

• Points: The Points System for the related per-item data system.

• Placeholders: Custom Placeholders to reuse level expressions across configs.