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

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.

Commands

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