XP & Leveling
Message and voice XP, rank cards, role rewards, leaderboard snapshots, and rank card customization.
Zagreus tracks XP from messages and voice activity, assigning levels and role rewards as members participate. Rank cards are fully customizable with layouts, colors, and background images.
How XP Works
Earn XP
Members earn XP by sending messages (with a cooldown to prevent spam) and by spending time in voice channels. The amount per message is randomized within an admin-configurable range.
Level Up
XP required per level follows the formula: 5 * level^2 + 50 * level + 100. When you level up, a notification is posted in the configured channel.
Earn Role Rewards
Admins configure role rewards at specific level thresholds. When you reach a level with a reward, the role is automatically assigned.
Climb the Leaderboard
The server XP leaderboard ranks all members. Historical snapshots are taken daily, weekly, and monthly.
Commands
| Command | Description | Permission |
|---|---|---|
/level rank [user] | View your or another user's rank card (level, XP, progress, rank position) | Everyone |
/level leaderboard | View the server XP leaderboard (top 15) | Everyone |
/level rewards | View all configured role rewards and their level thresholds | Everyone |
/level customize | Customize your rank card (layout, colors, background) | Everyone |
/level reset-card | Reset your rank card to the default Hades theme | Everyone |
/leaderboard-history <type> <period> | View a historical leaderboard snapshot | Everyone |
Rank Card Customization
Use /level customize to personalize your rank card:
| Option | Description | Example |
|---|---|---|
layout | Card layout style | classic, minimal, compact |
accent-color | Accent color (hex) | #DC2626 |
bg-color | Background color (hex) | #1a1a2e |
bar-start | Progress bar gradient start (hex) | #DC2626 |
bar-end | Progress bar gradient end (hex) | #F59E0B |
bg-image | Background image URL (PNG/JPG/GIF/WebP) | Direct image link |
Use /level reset-card to revert to the default Hades-themed card.
Leaderboard Snapshots
Historical snapshots let you see who was on top at any point in time.
| Type | Period | Captured At |
|---|---|---|
| XP | Daily | Every day at 00:05 UTC |
| XP | Weekly | Every Sunday at 00:05 UTC |
| XP | Monthly | First of every month at 00:05 UTC |
| Playtime | Daily | Same schedule as XP |
| Playtime | Weekly | Same schedule as XP |
| Playtime | Monthly | Same schedule as XP |
Use /leaderboard-history <xp|playtime> <daily|weekly|monthly> to view the latest snapshot for that period.
Role Rewards
Admins configure role rewards through the dashboard or XP admin commands. When a member reaches the required level, the role is automatically assigned.
If "stack role rewards" is enabled, members keep all previously earned level roles. If disabled, only the highest earned role is kept and lower ones are removed.
Admin Configuration
XP settings are managed per-server through the dashboard Settings page:
- XP per message — min/max range (randomized)
- Cooldown — seconds between XP-earning messages
- Blacklisted channels — channels where messages don't earn XP
- Blacklisted roles — roles that don't earn XP
- Level-up channel — where level-up notifications are posted
- Level-up message — customizable template with
{user},{level}placeholders - Role rewards — level thresholds and role assignments
- XP multipliers — per-channel or per-role multipliers