Engagement Module

Leveling

Members earn XP for chatting and climb levels. Announce level-ups, hand out role rewards at chosen levels, and give each member a custom rank card with /rank.

Where to find it: run /config Category dropdown Engagement Leveling. Toggle the module on first, no XP is counted until it's enabled.

How XP works

Every qualifying message gives a member a bit of XP. Enough XP levels them up. You control how much XP a message is worth, which messages count, and what happens on a level-up.

Good to know

Start with the defaults and only tune XP Amount if leveling feels too fast or too slow. Everything else is optional polish.

Recommended first setup

Level Up: choose where level-up messages go: a reply to the member's message, the current channel, or a custom channel (e.g. #level-ups). Write the message and decide whether to ping the member.
(Optional) Level Up Embed: dress the level-up message up as a custom embed. See Level-up message & embed below.
Roles Add Role: pick a level (say 5) and a role to award at that level. Repeat for as many tiers as you like.
(Optional) Decide Stack Roles: keep every reward role as they climb, or replace the old one with the new one each tier.
Start chatting, XP is now flowing. Check progress with /rank and the server leaderboard.

Level-up message & embed

Setting	What it does
Level Up	Where the message goes (Reply, Current Channel, Custom Channel, or Disable), the message text, and two options: Mention the member and a Rewards Button for more leveling info.
Level Up Embed	Paste embed code from the embed builder to send the level-up as a custom embed. Message content inside the embed code replaces the Level Up message. Leave the code empty to remove the embed.

Both the message and the embed (every text field) can use these variables:

Variable	Becomes
`{user}`	The member mention.
`{user_name}`	Their username.
`{user_nickname}`	Their display name.
`{new_level}`	The level they just reached.
`{old_level}`	The level they came from.
`{next_level}`	The level after this one.
`{new_xp}`	Their XP now.
`{old_xp}`	Their XP before this message.
`{xp_needed}`	XP still needed to reach the next level.
`{next_level_xp}`	Total XP required for the next level.
`{rank}`	Their position on the server leaderboard.
`{server_name}`	The server name.

Turn on Level Up before setting a Level Up Embed. If the level-up goes to a custom channel, the bot also needs Embed Links there.

Tuning XP

Setting	What it does
Amount	Base XP given per message.
Multiply	Roles that earn bonus XP (e.g. boosters get 1.5×).
Text Only	Only give XP for text messages (ignore stickers/attachments-only messages).
More Long Messages	Award extra XP for longer, higher-effort messages.
More Replies	Award extra XP for replies (rewards conversation).
No Spam	Reduce XP for repeated/spam-like messages.
No Text	Reduce XP for non-text messages.

Role rewards

Setting	What it does
Stack Roles	Keep all earned reward roles (on) or only the latest tier (off).
Remove Roles	Keep members’ reward roles in check, corrects roles if they’re manually changed.
Add / Edit / Remove Role	Create, change, or delete a level-to-role reward.

The bot's role must sit above any reward roles in the role list, or it can't assign them.

The rank card (/rank)

/rank shows a member's level, XP, and rank on an image card. Customise it under Custom Card:

Setting	What it does
Background Image	Upload a custom background for the card.
Accent Color	The highlight/progress colour on the card.
Font Type	The font used for the card text.
Level Text Size	How large the level number appears.

Blacklists & management

Setting	What it does
Blacklist Messages	Channels where level-up announcements are suppressed.
Blacklist XP	Channels/roles where no XP is earned at all (e.g. bot-spam, off-topic).
Command Permissions	Who can manage the `/xp` command (give/remove XP).
Sync Members	Recheck every member and fix their reward roles to match their level.
Transfer Levels	Import levels from another leveling bot.
Reset Levels	Wipe all XP and levels on the server (irreversible).

Troubleshooting

Problem	Fix
No XP is being earned	Enable the module, and check the channel isn’t under Blacklist XP.
Level-up messages don’t show	Set a Level Up message, and check the channel isn’t under Blacklist Messages.
“Enable the level up messages first”	Level Up Embed needs Level Up set to anything other than Disable.
Level Up message text is ignored	Your Level Up Embed has its own message content, which overrides it. Edit or remove the content in the embed code.
Reward role isn’t given	Move the bot’s role above the reward role, then run Sync Members.
Old bot’s levels are gone	Use Transfer Levels to import them.