Skip to main content
Levels stores progress per server. Members can view a rank card or leaderboard; staff can enable the module, tune experience in the Dashboard, and assign roles at level milestones.
Levels is disabled initially. The starting XP values below apply to a new or normalized configuration; Headless may preserve custom values from existing profiles.

​
How XP is earned

​
Messages

In a new configuration, an eligible message grants a random 20–38 XP. Headless adds up to 8 XP for message length (one point per 120 characters) and applies a 45-second per-member, per-server cooldown. A message does not count if it is sent by a bot, appears in an excluded channel or role, starts with the server prefix, falls below the minimum non-whitespace character count, or repeats too much recent content. Attachments allow a short message to pass the character minimum. Smart anti-spam is enabled initially and rejects a new duplicate after two identical hashes were detected in the previous 180 seconds.

​
Voice

Voice XP is enabled initially too: the watcher grants random 18–32 XP per 180 eligible seconds, provided at least two eligible members are in the channel. Bots, the server AFK channel (when that option is enabled), excluded channels or roles, and muted/deafened members are skipped when the unmuted requirement is on. If the channel falls below the minimum member count, eligible voice sessions pause. You can change voice XP amounts and interval in the Dashboard’s Levels settings. If Headless cannot observe the channel, members, or voice states, the watcher may not award XP.

​
Check progress

Use .level [@member] or /level [user] to show a level, current XP, progress, total XP, and rank. .rank [@member] is a prefix alias; /rank [user] is also available. If you omit the member, you see your own rank. These commands only work in a server and have no explicit elevated permission check. .levels and /levels open the server leaderboard, sorted by level and then total XP. Longer views include pagination controls. Rank only reflects data Headless has stored for that server; it is not a Discord level and cannot recover activity from before installation or periods when the bot was unavailable.

​
.level — 1

Also works: .level @member · .rank @member

​
/level

​
.level — 2

​
.level [member]

​
.levels

​
/levels

​
/rank

​
Configure the module

​
Quick setup

1

Choose an announcement channel

Decide where level-up announcements should appear. Headless needs access to the channel and permission to send messages.
2

Enable Levels

Run .leveling setup #levels or enable the module in the Dashboard. The setup subcommand enables Levels and stores the channel as the announcement destination when one is provided.
3

Tune XP and filters

Use the Dashboard to set XP ranges, cooldown, message requirements, exclusions, anti-spam settings, and voice values for your community.
4

Test the query commands

Check a rank card with .level @member and the leaderboard with .levels. Confirm that the announcement appears in the chosen channel.

​
Dashboard settings

The Levels configuration page can edit module status and announcement channel; minimum/maximum message XP and cooldown; minimum message characters and smart anti-spam; ignored channels and roles; voice XP minimum/maximum, interval, minimum member count, exclusions, AFK-channel behavior, and the unmuted requirement; the level curve; reward stacking; and announcement title, content, color, and media. New guilds use an English level-up title and message by default. Headless migrates only the exact former built-in Spanish defaults; custom announcement text is preserved. The curve calculates XP required for the next level using a base XP value and a growth factor, with a minimum of 25 XP per level. The initial configuration uses a base of 60 and growth of 1.18. Configuration is bounded when normalized; the Dashboard shows the editable ranges.
Prefix administration commands do not expose a subcommand for every message or voice XP setting. Use the Dashboard for those controls; do not assume commands such as .leveling xp or .leveling voice exist.

​
.leveling

​
/leveling

​
.leveling setup

​
.leveling on

​
.leveling off

​
.leveling channel

​
.leveling message

​
.leveling color

If there is no valid or accessible announcement channel, Headless tries the text channel where the event originated. If that send also fails, saved XP and level progress are not rolled back; only the announcement fails. Check access, permissions, and role hierarchy before announcing rewards to the community.

​
Level rewards

A reward maps a level from 1 through 1,000 to a real server role. Rewards stack by default: when a member levels up, Headless applies all configured reward roles up to that level. If stacking is disabled in the Dashboard, Headless keeps the highest earned reward and attempts to remove the other configured reward roles. For the assignment to work, Headless needs native Manage Roles and its role must be above each reward role. A saved rule does not guarantee Discord will allow the assignment; deleted or inaccessible roles are skipped, and a rejection may be recorded as the latest error.

​
.leveling reward

​
.leveling rewards

​
.leveling reward-remove

​
Commands

.leveling shows status, channel, XP ranges, cooldown, anti-spam, and reward count. .leveling setup [#channel] enables the module; .leveling on enables it and .leveling off pauses it. .leveling channel [#channel] sets the announcement channel; without a channel, it uses the current channel.
.leveling reward <level> @role assigns a role to a milestone. .leveling rewards lists saved mappings, and .leveling reward-remove <level> removes one. The runtime clamps levels to 1–1,000. Managing the group requires Manage Server; editing a role mapping also requires Manage Roles.
.leveling message <text> accepts plain text or an embed script up to 8,000 characters. Available variables include {user}, {mention}, {username}, {server}, {level}, {xp}, {total_xp}, and {gained}. In the template, {mention} resolves to the display name; the separate mention option controls an actual user mention. .leveling color <#RRGGBB> changes the accent color.
Administration subcommands are prefix-only and require Manage Server; role edits also require Manage Roles. /level, /rank, and /levels are guild queries without an explicit elevated permission check. Headless still needs the Discord channel and role permissions appropriate to each action.
Running .leveling setup without a channel enables Levels but does not save the current channel as its destination. Use .leveling channel #channel to persist one.

​
.level