Auto Level

Auto Level awards XP for activity, turns it into levels along a configurable curve, and hands out role rewards. Members get image rank cards; the server can publish a public web leaderboard.

plugins:
  autolevel:
    enabled: true
    seconds_per_point: 60
    levels:
      1000: 669626417461289002   # 1,000 POINTS, not level 10
      5000: 674638268135047186
    public_leaderboard: true

Setup checklist

1. Open Levels and enable Auto Level. Begin with one main track and the default curve.
2. Choose message and voice sources. Exclude staff, bot channels, and other places where activity should not earn XP.
3. Leave display delay and cooldown jitter at their defaults for normal use. Set them to zero only for a short private test if instant numbers are needed.
4. Add one low test reward below the bot's highest role. Decide whether earlier earned rewards stay with keep_previous.
5. Choose an announcement destination or leave announcements off for the first test.
6. Send qualifying messages as a regular member, respecting the message cooldown. Inspect the dashboard XP overview for live values.
7. Cross the reward threshold and confirm the role plus announcement. Use an XP admin command to move back below it and confirm explicit adjustments reconcile rewards as intended.
8. Enable the public leaderboard or rank-card customization only after checking the corresponding feature grants and privacy expectations.

How XP works

• Message and voice activity earn points (weight tunes the mix, seconds_per_point is the per-member cooldown between message awards).
• Include/exclude lists scope earning by role, channel, and category (include_roles, exclude_channels, include_voice, and friends).
• multiplier and multiplier_roles boost earning globally or per role.
• Multiple tracks (tracks, category) let separate areas of your server level independently, each with its own default_curve or fully custom curve.

Keeping XP hard to game

Two built-in defenses stop members from reverse-engineering your XP rates and farming to them:

• Randomized awards and cooldowns. Each message earns a random amount in your configured range, and the cooldown between awards is randomized too (cooldown_jitter_seconds on a track's message source, default 15 - so the default window lands anywhere between 45 and 75 seconds). Neither the award nor the window can be timed.
• Delayed readouts. Rank cards, !rank text, !leaderboard pages, and the public web leaderboard refresh on a randomized delay (display_delay_seconds, default 180) instead of live - so sending a message and re-checking a card never reveals the exact award. Level-ups always show immediately; only progress within a level lags. Set it to 0 if you prefer live numbers.

Because of the delay, an xp give/xp take/xp set you issue can take a few minutes to appear on the member's card - the dashboard's XP overview always shows live values.

Rewards and announcements

levels maps a points threshold to a role, so 1000: <role id> grants that role at 1,000 points rather than at level 10. (If you would rather work in levels, the newer tracks.<id>.rewards form is keyed by level and the dashboard's Levels page converts for you.) keep_previous controls whether earlier reward roles stay on promotion. Reward roles also come OFF when the XP that earned them goes away - xp take, xp set, or a reset below a threshold removes the roles that threshold granted. Rewards you add after members already have XP are settled automatically: anyone owed a role receives it the next time they earn XP, so setting up rewards late (or importing levels first) just works - no recheck command needed. Announcements go to the channel where it happened, a fixed channel (announce_chan), or DM (announce_dm), with a templated announce_msg. When announcing in the channel where it happened, turn on the track's announce.reply option (also a toggle on the Levels page) and the bot replies directly to the message that earned the level-up instead of posting a loose line - if that message is gone by then, it posts normally.

Rank cards and the leaderboard

!rank renders an image card (server accent via card_theme, a default background via background_url). Members can personalise their own card with the rankcard commands - rankcard background takes a direct image upload as well as a URL (static images: png, jpg, or webp); card_background_min_level can gate custom backgrounds behind a level. card_full_numbers: true (also on the dashboard Levels page) shows exact XP numbers on cards instead of the 12.3k shorthand. Card customizations are per server: the background, accent color, bio, title, and level-up message a member sets in your server show only in your server, and the rankcard commands change the server they are run in. Bio, title, and custom level-up message text must pass your censor filter - a rank card is not a way around the word list. The filter is enforced when a member sets the text and again every time a card or level-up message renders, so text that predates a filter addition is simply hidden. Mods can inspect any member's card customizations (background included) with rankcard view, and wipe them with rankcard modreset. public_leaderboard: true publishes a shareable web leaderboard for your server at /leaderboard/<server id>. If your games economy publishes its richest-members board too, the two pages link to each other.

Custom backgrounds (the server default and per-member ones) require the LEVELS_PRO feature; image cards at all require RANK_CARDS - without it, rank commands answer in text.

A member's own background beats the server default, so background_url is the fallback rather than an override. Rank cards show up to six badge icons.

If a member holds any HepBoat badges (supporter tiers, staff and community badges - the same ones !info lists), their icons render on the rank card automatically, under the avatar. Badges are platform-wide, so the same icons show on every server's cards.

The dashboard's Levels page includes a full structured editor for tracks, curves, XP sources and rewards, with live previews of the curve maths.

Troubleshooting

• Messages never award XP: check the track source, include and exclude lists, member role, channel, category, and randomized cooldown.
• The dashboard changed but rank looks old: member-facing readouts may be delayed by display_delay_seconds; the dashboard overview is live.
• A reward role does not grant: check role hierarchy and threshold units. The legacy levels map uses points, not displayed levels.
• Rank is text instead of an image: the server needs RANK_CARDS.
• Custom backgrounds are refused: they need LEVELS_PRO and may be gated by card_background_min_level.
• The public page is unavailable: turn on public_leaderboard and use the server's leaderboard URL.

Commands

Arguments in {curly braces} are required. Arguments in [square brackets] are optional.

Command	What it does
/rank [user] [track]	Show your level and rank card.
/profile [user] [track]	Show a leveling profile card.
/leaderboard [window] [track] [page]	XP leaderboard - all-time, weekly, or monthly.
/top [window] [track] [page]	XP leaderboard (alias of leaderboard).
/rewards [track]	List the level-up role rewards for a track.
/rankcard background [url] [image]	Set your rank-card background image (premium).
/rankcard color [hex]	Set your rank-card accent color.
/rankcard bio [text]	Set your rank-card bio.
/rankcard title [text]	Set your rank-card title.
/rankcard message [text]	Set your custom level-up message.
/rankcard reset	Reset your rank-card customizations.
/rankcard modreset {user} [scope]	Reset a member's rank-card background or all customizations (mod).
/rankcard view {user}	Inspect a member's rank-card customizations, background shown as an image (mod).
/xp give {user} {points} [track]	Grant XP to a user (admin).
/xp take {user} {points} [track]	Remove XP from a user (admin).
/xp set {user} {points} [track]	Set a user's XP to an exact value (admin).
/xp reset [user] [track]	Reset XP for a user or the whole guild (admin).
/xp sync-roles {user} [track]	Re-apply a user's earned reward roles (admin).
/xp show [user]	Show a user's XP across all tracks (mod).
/xp level {level} [track]	Show the XP required to reach a level (mod).