Leveling System - Celestia

Overview

The Leveling System rewards members for being active in your server. Members earn XP by chatting or participating in voice channels, level up automatically, unlock reward roles, and compete on the server leaderboard. Everything is managed through a centralized interactive control panel where administrators can configure XP sources, progression formulas, cooldowns, rewards, restrictions, and announcement settings.

Features

Message XP

Reward members for sending messages

Voice XP

Reward members for participating in voice channels

Reward Roles

Automatically grant roles when members reach specific levels

Leaderboard

Rank every member based on total XP

Blacklist & Whitelist

Control exactly where and who can earn XP

Custom Formula

Customize how much XP is required for every level

Commands

level

Opens the interactive leveling configuration panel.

,level

,level
,level config

Aliases: lvl
Permissions: Manage Server

level rank

View your own level, XP, and server ranking.

,level rank [@user]

,level rank
,level rank @Zenith

Permissions: Everyone

level leaderboard

Displays the server’s leveling leaderboard.

,level leaderboard [page]

,level leaderboard
,level leaderboard 2

Permissions: Everyone

level statistics

Shows an overview of your server’s leveling configuration and statistics.

,level statistics

,level statistics

Permissions: Manage Server

level debug

Displays the most recent XP checks performed for a member, including why XP was or wasn’t awarded.

,level debug <@user>

,level debug @Zenith

Permissions: Manage Server

level rewards

Manage automatic reward roles granted at specific levels.

,level rewards add <level> <@role>
,level rewards remove <level>
,level rewards list

,level rewards add 10 @Trusted
,level rewards remove 10
,level rewards list

Permissions: Manage Server

level blacklist

Prevent specific channels, roles, or users from earning XP.

,level blacklist add <target>
,level blacklist remove <target>
,level blacklist list
,level blacklist clear

,level blacklist add #bot-spam
,level blacklist remove @Muted
,level blacklist list
,level blacklist clear

Permissions: Manage Server

level whitelist

Restrict XP earning so only selected channels, roles, or users can gain XP.

,level whitelist add <target>
,level whitelist remove <target>
,level whitelist list
,level whitelist clear

,level whitelist add #general
,level whitelist remove #general
,level whitelist list
,level whitelist clear

Permissions: Manage Server

level admin

Manually manage member XP and levels.

,level admin addxp <@user> <amount>
,level admin removexp <@user> <amount>
,level admin setlevel <@user> <level>
,level admin reset <@user>
,level admin reset-all

,level admin addxp @Zenith 500
,level admin removexp @Zenith 100
,level admin setlevel @Zenith 25
,level admin reset @Zenith
,level admin reset-all

Permissions: Manage Server

XP Sources

The leveling system currently supports the following XP sources:

Messages

Earn XP by sending messages that pass spam detection and cooldown checks.

Voice Activity

Earn XP while actively participating in voice channels.

Administrators can enable or disable each XP source independently.

Reward Roles

Reward roles allow members to automatically receive roles after reaching specific levels. Features include:

Unlimited reward levels
One reward role per level
Automatic role assignment
Dangerous permission detection
Permission warnings for sensitive roles

Reward roles that contain Administrator, Manage Server, Manage Roles, Ban Members, or Kick Members cannot be added.

Blacklist & Whitelist

The leveling system provides two independent filtering systems.

Blacklist

Prevent specific:

Channels
Roles
Users

from earning XP.

Whitelist

Restrict XP so that only selected:

Channels
Roles
Users

are eligible to earn XP.

If no whitelist rules exist, everyone is eligible to earn XP unless blacklisted.

Level Formula

Level progression uses a customizable XP formula consisting of:

Base XP
Linear Growth
Quadratic Growth

This allows server owners to make leveling easier or significantly more challenging depending on their community.

Statistics

The statistics command provides an overview including:

Total members with XP
Highest level reached
Total XP earned
Active XP sources
Reward role count
Blacklist rules
Whitelist rules
Current leveling formula

Debugging

The debug command displays the five most recent XP evaluations for a member. Each entry includes:

Whether XP was awarded
Which checks passed
Which checks failed
Time of evaluation
XP source

This makes it easy to diagnose why someone isn’t gaining XP.

Control Panel

The level command opens a fully interactive Components V2 control panel. Administrators can configure:

Enable or disable leveling
XP sources
XP cooldowns
XP rewards
Voice settings
Level formula
Maximum level
Announcement settings
Reward roles
Blacklist
Whitelist

Changes are applied instantly without requiring a bot restart.

Only the user who opened the control panel can interact with it. Once the session expires, the interface becomes inactive.

Best Practices

Use reward roles for milestones rather than staff permissions.
Exclude spam or bot channels using the blacklist.
Use the whitelist if only specific channels should award XP.
Keep your leveling formula balanced so progression remains rewarding.
Regularly review your leaderboard and statistics.

Logging

Administrative actions performed through the leveling system are automatically logged if your logging system is configured. This includes actions such as:

Reward role changes
XP adjustments
Level resets
Configuration updates
Enable or disable actions