This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Leveling — XP, Ranks & Leaderboard

GrumpyLeveling awards XP for messages and voice activity, displays rank cards, and can automatically assign roles on level-up.

---

Activation

In configs/config.yml:

addons:
  leveling: true

channels:
  levelup: ""        # "" = same channel, "dm" = DM, or a Channel ID

On first start, configs/modules/leveling.yml is created.

---

leveling.yml

enabled: true

messageXp:
  enabled: true
  min: 15                    # Min XP per message
  max: 25                    # Max XP per message
  cooldownSeconds: 60        # Cooldown between XP awards per user
  ignoredChannels: []        # Channel IDs where no XP is earned

voiceXp:
  enabled: true
  xpPerMinute: 2             # XP per minute in a voice channel
  excludedChannels: []       # Excluded voice channels (e.g. AFK)

levelUp:
  channel: ""                # "" = message channel | "dm" | Channel ID
                             # Fallback: channels.levelup in config.yml
  message: "🎉 {user} has reached **Level {level}**!"
  # Placeholders: {user}, {level}, {xp}

roleRewards: []
# Role rewards at specific levels, e.g.:
#   - level: 5
#     roleId: "123456789"
#   - level: 10
#     roleId: "987654321"

stackRoles: true             # true = keep all level roles
                             # false = only keep the highest current level role

accentColor: "#5865F2"       # Accent color for rank cards and level-up cards

---

XP Formula

GrumpyLeveling uses the MEE6-compatible formula:

XP for Level n → n+1 = 5 × n² + 50 × n + 100

Level	XP for this level	Total XP
0 → 1	100 XP	100 XP
1 → 2	155 XP	255 XP
5 → 6	475 XP	1,700 XP
10 → 11	1,100 XP	5,500 XP
20 → 21	3,100 XP	27,200 XP

Only totalXp is stored — level and progress are always calculated from it.

---

Voice XP

Every 60 seconds the bot scans all voice channels and awards xpPerMinute XP to eligible members.

Eligible: User is in a voice channel + at least 1 other non-bot user present + not server-muted + not deafened.

---

Level-Up Card

On level-up the bot automatically posts a canvas card (900×300 px):

╔══════════════════════════════════════════════════════╗
║ ⬆ LEVEL UP!                                         ║
║ [Avatar]  Username                                   ║
║           Level 12                                   ║
║           ████████░░  2450 / 3050 XP                ║
╚══════════════════════════════════════════════════════╝

• Same style as the rank card (/rank)
• Accent color from accentColor in leveling.yml
• Falls back to text-only if avatar fetch fails

Channel priority: levelUp.channel in leveling.yml → channels.levelup in config.yml → same channel as the trigger message

---

Commands

/rank [@user]

Displays the canvas rank card (900×280 px) with:

• Round avatar with accent glow ring
• Username, level, server rank (#N)
• XP progress bar

/rank
/rank @Jonas

---

/leaderboard [page]

The server's XP leaderboard — 10 users per page with ◀▶ navigation. Shows level and total XP.

---

/xp give|take|set|reset @user [amount]

Admin management of XP. Triggers the level-up card when appropriate.

Subcommand	Description
give @user 500	Add 500 XP
take @user 200	Deduct 200 XP (minimum 0)
set @user 5000	Set total XP to 5000
reset @user	Reset everything to 0

Permission: Manage Guild

---

Role Rewards

In leveling.yml, roles can be automatically assigned at specific levels:

roleRewards:
  - level: 5
    roleId: "1234567890"    # Role "Active"
  - level: 10
    roleId: "9876543210"    # Role "Veteran"
  - level: 25
    roleId: "1122334455"    # Role "Legend"

stackRoles: true   # User keeps all roles (recommended)
                   # false = at level 10, the level 5 role is removed

The bot requires Manage Roles and its role must be above the reward roles in the hierarchy.