Leveling

The leveling system rewards users with XP for chatting and voice activity. As they level up, they can unlock roles, earn coins, and show off with customizable rank cards.

Edit config/modules/leveling.yml. XP and role settings are under LevelingSystem.

Core Settings

✅ Enabled

Turns the leveling system on or off.

LevelingSystem:
  Enabled: true

---

ResetDataOnLeave

• true → User’s XP & levels reset when they leave.

• false → Progress is saved if they rejoin (recommended).

LevelingSystem:
  ResetDataOnLeave: false

---

MessageXP & 🎙 VoiceXP

• Format: min-max

• Defines how much XP users earn for activity.

Examples

• MessageXP: 5-10

• VoiceXP: 2-5

Recommendations

• Small servers → Higher XP (e.g., 10-20, 2-4)

• Large servers → Lower XP (e.g., 5-10, 1-2)

---

XPNeeded

• Base XP needed to level up.

• Scales with each level (Level 2 = 300 XP, Level 3 = 600 XP, etc).

Examples

• Fast leveling → 200-250

• Normal → 300-400

• Slow (competitive) → 500-750

LevelingSystem:
  XPNeeded: 300

---

Channel & Category Settings

Control where XP is earned:

LevelingSystem:
  ChannelSettings:
    LevelUpChannelID: []
    DisabledChannels:
      - CHANNEL_ID
    DisabledCategories:
      - CATEGORY_ID

---

XP Cooldown

Cooldowns prevent spam and balance XP gain.

LevelingSystem:
  CooldownSettings:
    EnableXPCooldown: true
    XPCooldown: 30s
    VoiceInterval: 60s

Recommendations

• Message cooldown → 30s–60s

• Voice interval → 60s–120s

---

Level-Up Messages

Customize the message shown when a user levels up.

Available placeholders

• {user} → Mention user

• {userName} → Username only

• {userId} → Discord ID

• {userIcon} → Profile picture

• {userBanner} → Banner image

• {guildName} → Server name

• {oldLevel} / {newLevel} → Levels

• {oldXP} / {newXP} → XP progress

• {randomLevelMessage} → Pulls from Messages.LevelMessages

Example (simple message):

LevelingSystem:
  LevelUpMessageSettings:
    Enabled: true
    ComponentsV2:
      Components:
        - Type: container
          AccentColor: '#1769FF'
          Components:
            - Type: text_display
              Content: '{user}, you are now level {newLevel}'

Example (formatted message):

LevelingSystem:
  LevelUpMessageSettings:
    Enabled: true
    ComponentsV2:
      Components:
        - Type: container
          AccentColor: '#eda3f0'
          Components:
            - Type: section
              Text:
                Content: |-
                  ## 🎉 Level Up!
                  {userName} just reached level {newLevel}!
                  {randomLevelMessage}
              Accessory:
                Type: thumbnail
                Media:
                  URL: '{userIcon}'

---

Role Rewards

Give roles when users hit certain levels.

StackRoles

• true → Users keep all unlocked level roles (Level 1, 5, 10).

• false → User only has the highest level role.

Example:

LevelingSystem:
  RoleSettings:
    StackRoles: true
    LevelRoles:
      - level: 1
        roleID:
          - ROLE_ID
      - level: 5
        roleID:
          - ROLE_ID

---

Coin Rewards (Economy Integration)

Reward coins at specific levels.

• +1 → Every level

• +5 → Every 5 levels

• 25 → Exactly level 25

Example:

LevelingSystem:
  RoleSettings:
    ScaleRewards:
      StackRewards: false
      Rewards:
        - level: '+1'
          coins: 10

---

Rank Card Customization

Your rank card can be styled with background, accent, and text colors.

RankCard:
  AccentColor: '#1769FF'
  SecondaryColor: '#4785FF'

---

Quick Setup Examples

Casual Server (fast leveling)

• MessageXP: 10-20

• VoiceXP: 2-4

• XPNeeded: 200

Competitive Server (slow leveling)

• MessageXP: 5-8

• VoiceXP: 1-2

• XPNeeded: 500

Community Server (balanced)

• MessageXP: 8-15

• VoiceXP: 1-3

• XPNeeded: 300

---

Commands

👥 User Commands

• /rank → View your rank card

• /rank user:@user → View someone else’s rank

• /leaderboard → Show server leaderboard

🔧 Admin Commands (requires Manage Server or configured Permission roles)

• /level give user:@user amount:5 type:xp → Add XP

• /level remove user:@user amount:3 type:xp → Remove XP

• /level set user:@user amount:10 type:level → Set a user’s level

• /level reset type:level → Reset levels for every member in the server