Leveling

Any relic can level up as it's used, getting stronger over time instead of having fixed values. This page covers turning a relic into a levelling item, how it earns xp, how its effects scale, and how progress is shown to players.

Quick start

1. Add a leveling: section to a relic (copy the one from _example.yml).

2. Set xp-formula (or requirements) so the plugin knows how much xp each level needs.

3. Add at least one xp-sources entry so the relic gains xp while equipped.

4. Use %level% inside effects: to scale a stat with level.

5. Add "%leveling%" as its own line in item.lore to show the level and progress.

6. Run /oftrelics reload, equip the relic, and trigger an xp source to watch it level up.

The leveling section

leveling:
  xp-formula: "(2 ^ %level%) * 25" # Xp needed to go from %level% to the next level
  max-level: 5 # (Optional) Omit for no cap
  # requirements: [50, 100, 200, 400] # Alternative to xp-formula: one entry per level

  xp-sources: # Ways to earn xp while equipped (libreforge counters)
    - trigger: melee_attack
      value: "5"

  level-up-message: "&fYour &6Magmatic Ring&f reached level &a%level%&f!" # (Optional)
  level-up-sound: entity_player_levelup # (Optional) A Bukkit Sound name

  name-prefix: "&7[Lvl. %level%] &r" # (Optional) This is the default; "" turns it off

  placeholders: # (Optional) Named expressions usable as %name% in item.lore
    dmg: "2 + (%level% - 1) * 0.5"

  format: # (Optional) The lines "%leveling%" expands to in item.lore; this is the default
    - ""
    - "&f&lLEVEL &6%level%"
    - "%bar% &7%progress%%"

Every relic starts at level 1 with 0 xp.

Xp requirements

Pick one of these to define how much xp each level needs:

leveling:
  xp-formula: "(2 ^ %level%) * 25" # %level% is the CURRENT level
  max-level: 10 # Optional; omit for infinite levels

With this formula, level 1 needs 50 xp to reach level 2, level 2 needs 100 to reach level 3, and so on. Xp left over after a level-up carries over to the next level.

leveling:
  requirements: [ 50, 100, 200, 400 ] # Entry 1 is level 1 -> 2, entry 2 is level 2 -> 3, ...

With requirements, the max level defaults to the length of the list (set max-level to cap it lower). If both are set, requirements is used and xp-formula is ignored.

xp-formula is plain arithmetic: numbers, %level%, + - * / ^ and parentheses. It isn't the full libreforge expression engine, just enough for level curves.

Granting xp

Xp comes from libreforge counters, the same system EcoSkills uses for skill xp, so any libreforge trigger, with the full conditions and filters system, can feed a relic's level:

leveling:
  xp-sources:
    - trigger: melee_attack
      value: "5" # Flat 5 xp per hit, ignoring the trigger's own value
    - trigger: melee_attack
      multiplier: "0.5" # 0.5 xp per point of damage dealt
    - trigger: kill
      value: "20"
      conditions: [ ] # Counters support conditions and filters too

Each entry needs a trigger, plus at most one of:

Only equipped relics gain xp; a relic in an inventory or a chest earns nothing. If a player wears several copies of the same relic (with max-active above 1), each copy gets the xp.

Scaling effects with %level%

On a relic with a leveling: section, every effect in its effects: list can use %level%, resolved from the equipped item's current level, the same way EcoEnchants injects %level% into enchantment effects:

effects:
  - id: attack_damage
    args:
      damage: "2 + (%level% - 1) * 0.5" # +2 at level 1, +4 at level 5

This works for permanent effects (like attack_damage above) and triggered effects alike. When the relic levels up, its effects are re-applied at once with the new level.

Holding an effect back until a level

For an all-or-nothing unlock instead of continuous scaling, put the relic_level_above condition on an effect:

effects:
  - id: bleed
    args:
      chance: 20
      amount: 3
      damage: 1
      interval: 15
    triggers:
      - melee_attack
    conditions:
      - id: relic_level_above
        args:
          level: 3 # Only works from level 4

The level is strictly above the given value. Unlike libreforge's item_level_above, this condition takes no id argument: it always checks the relic it's on.

Level-up feedback

leveling:
  level-up-message: "&fYour &6Magmatic Ring&f reached level &a%level%&f!"
  level-up-sound: entity_player_levelup

Both are optional. %level% in the message is the level just reached. The message and sound play for every level gained, so a big xp grant that crosses two levels plays them twice. /oftrelics setlevel plays them once, for the new level, and only when it raises the level.

With the HUD on, a level-up also plays a level-up animation in the xp popup, with its own sound (hud.popup.level-up-sound).

Showing level and progress

Name prefix

leveling:
  name-prefix: "&7[Lvl. %level%] &r" # This is the default; "" turns it off

Added in front of the relic's name, so a level 5 Voidwoven Circlet shows as [Lvl. 5] Voidwoven Circlet.

Lore placeholders

leveling:
  placeholders:
    dmg: "2 + (%level% - 1) * 0.5" # Becomes %dmg% in item.lore

item:
  lore:
    - "&c⚔ &f+%dmg% Attack Damage"

This mirrors EcoEnchants' placeholders: for dynamic descriptions. Use the same expression as the matching effect, so the number in lore always matches the effect's real value for that copy. Whole numbers are shown without decimals, and other values with one decimal place.

The %leveling% block

item:
  lore:
    - "%leveling%"

"%leveling%" as its own line in item.lore expands to every line of leveling.format, filled in for that copy:

Admin commands

Both work on the relic the player has equipped (the first copy, if they wear several), because that's where its level lives; they fail with a message if it isn't equipped. Tab completion only lists relics that have levelling. See Commands and Permissions.

Where to go next

• Build the relic this applies to: the How to Make a Relic guide.

• See progress on screen: the HUD on the Menus and HUD page.

• Effects reference: Configuring an Effect for everything %level% can scale.