Leveling

Leveling

Voxy includes a complete leveling system that awards players experience (XP), levels them up, displays configurable progress bars, and executes rewards upon reaching specific levels.

Overview

The leveling model manages each player's level and their current XP towards the next level. A player's progression is calculated dynamically based on an experience formula. Server administrators can also configure how the progress is displayed using Bar Styles and Level Formats.

Experience Formula

The formula is a cumulative expression: evaluated at a given <level> it returns the total XP that level represents. By default, the formula is:

1250 * (<level> ^ 2) + (6250 * <level>) - 7500

(Where <level> is the level being evaluated).

The XP needed to advance from one level to the next is the difference between the formula at consecutive levels - that is, f(level + 1) - f(level) - not the raw formula value at a single level.

You can modify this formula via the settings, along with defining the server's max level (default 1000).

Bar Styles

Progress bars visually represent a player's XP progress. You can define multiple bar styles and choose which one to display. A bar style consists of:

• Size: Total length of the progress bar (e.g., 20 characters).
• Bar Character: The symbol used to draw the bar (e.g., ❘ or ■).
• Done Prefix: The formatting (color/style) applied to the completed portion.
• Progress Prefix: The formatting applied to the single character representing current progress.
• Remaining Prefix: The formatting applied to the unfilled portion of the bar.

Default Styles

Voxy provides two default styles out of the box:

• bar: Uses the ❘ character (Size: 20).
• box: Uses the ■ character (Size: 10).

Level Formats

You can customize how a level is displayed in text or chat by setting Level Formats. A format allows you to define a displayFormat and a chatDisplayFormat (e.g., &7[☆ {level}]).

Formats are tied to specific levels. When displaying a player's level, Voxy finds the format assigned to their current level or the nearest format below it.

These formats are used by the level_chat and level_display placeholders — see Placeholders for usage.

Level Rewards

Rewards can be configured to trigger automatically when a player reaches a specific level. A single LevelReward consists of multiple actions, which can include giving items, executing commands, sending messages, or granting currency.

Level-Up and Reminders

• When a player levels up, Voxy sends them a chat message (configured as LEVELS_LEVELUP_CHAT in messages.yml).
• When a player has claimable level rewards waiting, an unclaimed-reward reminder (LEVELS_REWARD_UNCLAIMED) is sent on join, pointing them to /rewards to claim.

Commands

Staff can manage a player's levels and XP, as well as configure the entire system through an in-game GUI.

The command is registered as both /level and /levels.

(Requires the voxy.admin permission).