Level Configuration

Each level progression is its own file inside levels/. The filename (without .yml) is the progression ID used everywhere else.

The default file is levels/sword-level.yml (ID: sword-level).

---

Full Reference

# levels/sword-level.yml

progression-name: 'Sword Level'
progression-name-plural: 'Sword Levels'

starting-level: 1
max-level: 0          # 0 = unlimited
automatic-leveling: true

linked-inventory: ''  # menu ID to open on the root command, or blank

cost:
  currency-id: 'sword-xp'
  starting-cost: 300
  increase-cost-by: 250
  consume-currency: true
  scaling:
    method: 'LINEAR'   # LINEAR | EXPONENTIAL | CUSTOM
    exponential-multiplier: 1.15
    custom-costs:
      2: 300
      3: 600
      4: 1200

display:
  progress-bar:
    length: 30
    completed-character: '&a|'
    uncompleted-character: '&c|'
  level-format: 'Sword Level %level%'

  progress-display:
    type: 'NONE'        # NONE | BOSS_BAR | ACTION_BAR |
    format: '&eSword Level &6%level% &8| &7%progress_bar%'
    update-interval: 3  # seconds
    # Boss bar only:
    color: 'YELLOW'     # PINK | BLUE | RED | GREEN | YELLOW | PURPLE | WHITE
    overlay: 'NOTCHED_12' # PROGRESS | NOTCHED_6 | NOTCHED_10 | NOTCHED_12 | NOTCHED_20

rewards:
  on-each-level:
    - "[message] &aYou leveled up to %level%!"

  on-specific-level:
    10:
      - "[console] give {player} diamond 1"

  on-interval:
    5:
      - "[console] crate givekey {player} common 1"

---

Top-Level Keys

Key	Type	Description
progression-name	string	Human-readable name (singular). Used in messages.
progression-name-plural	string	Plural form. Used in messages.
starting-level	integer	Level assigned to a new player. Usually 1.
max-level	integer	Cap on the level. Set to 0 for no cap.
automatic-leveling	boolean	If true, the plugin automatically levels the player up when they have enough currency. No manual command needed.
linked-inventory	string	Menu ID (from menus/) to open when the player runs the root command. Leave blank to send the BALANCE message instead.

---

cost

Controls what currency is consumed and how much each level costs.

Key	Type	Description
currency-id	string	Economy ID from economies/ (e.g. sword-xp, souls).
starting-cost	number	Cost for the very first level-up (level 1 → 2).
increase-cost-by	number	Flat amount added to the cost per subsequent level.
consume-currency	boolean	If true, the currency is removed when a level-up happens. Set to false for milestone-style progressions.
scaling.method	string	Optional. LINEAR, EXPONENTIAL, or CUSTOM. Defaults to LINEAR.
scaling.exponential-multiplier	number	Optional. Used only when scaling.method is EXPONENTIAL.
scaling.custom-costs	map<number, number>	Optional. Used when scaling.method is CUSTOM; keys are target levels and values are the cost to reach that level.

LINEAR

Linear scaling

This is the default and matches the plugin's old behaviour.

Formula:

cost(level) = starting-cost + (level - 2) × increase-cost-by

For starting-cost: 300 and increase-cost-by: 250:

Level	Cost
1→2	300
2→3	550
5→6	1,300
10→11	2,550

EXPONENTIAL

CUSTOM

---

display

progress-bar

Key	Type	Description
length	integer	Number of segments in the bar.
completed-character	string	Character (with colour) for filled segments.
uncompleted-character	string	Character (with colour) for empty segments.

The result is accessible via %phantomdungeons_leveling_{id}_progressbar%.

level-format

String used when displaying the level in certain messages. Supports %level%.

progress-display

Continuously displays the player's progress while they are online.

Key	Type	Options	Description
type	string	NONE, BOSS_BAR, ACTION_BAR, XP_BAR	Where to display the progress. NONE disables it entirely.
format	string	—	The text shown. Supports all PAPI placeholders and the tokens listed below.
update-interval	integer	—	Refresh rate in seconds.
color	string	PINK BLUE RED GREEN YELLOW PURPLE WHITE	Boss bar colour. Only used when type: BOSS_BAR.
overlay	string	PROGRESS NOTCHED_6 NOTCHED_10 NOTCHED_12 NOTCHED_20	Boss bar notch style. Only used when type: BOSS_BAR.

Format tokens (work inside format only):

Token	Description
%level%	Player's current level.
%progress_bar%	Rendered progress bar string.
%current_xp%	Player's current currency balance for this progression.
%required_xp%	Currency required to reach the next level.

Changing type from BOSS_BAR to NONE and reloading will automatically remove the active boss bar from all online players.

---

on-each-level

Runs every single time a player levels up.

on-each-level:
  - "[message] &aYou reached level %phantomdungeons_leveling_sword-level_level%!"
  - "[sound] ENTITY_PLAYER_LEVELUP 1.0 1.0"

on-specific-level

Runs only when the player reaches an exact level. Keys are level numbers.

on-specific-level:
  10:
    - "[console] lp user {player} permission set phantom.vip true"
  50:
    - "[console] give {player} netherite_ingot 5"
  100:
    - "[message] &6&lYou have reached the century mark!"

on-interval

Runs every N levels. The key is the interval.

on-interval:
  5:
    - "[console] crate givekey {player} common 1"
  25:
    - "[console] crate givekey {player} rare 1"

A player at level 50 with interval: 5 would have triggered this 10 times total.

---

commands

Controls the player-facing command for this progression.

commands:
  root:
    enabled: true
    command-name: 'swordlevel'
    aliases:
      - 'slevel'
      - 'sword-level'

  nodes:
    balance:
      enabled: true
      permission: 'phantom.swordlevel.balance'
      check-others-permission: 'phantom.swordlevel.balance.others'

    give:
      enabled: true
      permission: 'phantom.swordlevel.give'
      require-online-player: false

    set:
      enabled: true
      permission: 'phantom.swordlevel.set'
      require-online-player: false

    remove:
      enabled: true
      permission: 'phantom.swordlevel.remove'
      require-online-player: false

Key	Description
root.enabled	Whether the root command is registered at all.
root.command-name	The base command (e.g. /swordlevel).
root.aliases	Additional aliases for the same command.
nodes.balance.check-others-permission	Separate permission to check another player's level.
nodes.*.require-online-player	If false, admin commands work on offline players too (data is saved to DB).

---

messages

All messages in the level file support Sound and Message blocks.

BALANCE:
  Sound:
    Enable: false
    Value: ''          # Format: SOUND_NAME;volume;pitch
  Message:
    Enable: true
    Value: '&7You are at &e%level_formatted%'

Available message keys:

Key	When sent
BALANCE	Player checks their own level.
BALANCE_OTHER	Admin checks another player's level.
LEVEL_UP	Player levels up (if on-each-level is not used instead).
GIVE_SUCCESS	Admin gives levels.
SET_SUCCESS	Admin sets a level.
REMOVE_SUCCESS	Admin removes levels.
MAX_LEVEL	Player tries to level past max-level.
INVALID_PLAYER	Target player not found.
INVALID_AMOUNT	Non-numeric or zero amount provided.
PLAYER_HELP	/swordlevel help.
ADMIN_HELP	/swordlevel help for admins.