Skip to content

Leveling System

The leveling system awards XP for activity and tracks progression per server.

Command Surface

User Commands (/xp)

/xp level [user]
/xp rank [user]
/xp xpleaderboard [page]
/xp top [count]
/xp setcard [url] [image] [opacity]
/xp removecard

Admin Commands (/levels)

/levels setxp <user> <amount> [reason]
/levels addxp <user> <amount> [reason]

addxp can be positive or negative.

How XP Is Awarded

Message XP

When leveling is enabled for a server, XP is awarded for regular messages (not commands).

  • XP is random between configured min/max values.
  • The configured XP rate multiplier is applied.
  • Cooldown is enforced between XP gains.
  • Ignored channels and ignored roles do not gain XP.
  • Bonus role multipliers can increase XP.

Voice XP

Voice XP is processed on a timed loop and only applies when voice XP is enabled.

  • Awarded per minute based on configured voice XP rate.
  • Member must not be deafened.
  • Member must not be in the guild AFK channel.
  • Member must be in a voice channel with at least one other human member.
  • Ignored voice channels are skipped.

Level Formula

Level progression uses:

level = floor(0.1 * sqrt(total_xp))
xp_for_level = (level / 0.1)^2

Example: Level 10 starts at 10,000 XP.

Level-Up Messages and Rewards

On level-up, the system can:

  • Send a level-up message in a configured channel (or current channel)
  • Optionally DM the user
  • Grant configured reward roles for that level
  • Optionally remove earlier reward roles if reward progression is configured that way

Rank Card Customization

Users can set a custom background for /xp rank with /xp setcard.

  • Provide a public HTTPS image URL, or
  • Upload an image directly, and
  • Optionally set opacity from 0-100.

Advanced Configuration

There is no /levels config slash command in the current command surface.

Advanced leveling settings are managed in the Dashboard/API configuration routes, including:

  • XP min/max and cooldown
  • XP rate and voice XP settings
  • Ignore lists (channels/roles)
  • Bonus role multipliers
  • Level-up message/channel/DM settings
  • Level reward role mappings