Leveling

Role Rewards

Automatically assign roles to members when they reach specific levels in your server.

Overview

Role rewards are a powerful way to incentivize leveling and create prestige tiers in your server. When a member reaches a configured level, they automatically receive designated roles.

You can assign multiple roles per level, customize role removals, and even set up announcement messages when members reach milestones.

Basic Commands

Use these commands to manage role rewards:

/leveling roles add <level> <role>Add a role reward for a specific level
/leveling roles remove <level> <role>Remove a role reward from a level
/leveling roles listView all configured role rewards
/leveling roles get <level>Show rewards for a specific level
/leveling roles clear <level>Remove all roles from a level
/leveling roles clear-allRemove all role reward configurations

Setting Up Role Rewards

Follow this process to set up role rewards in your server:

Step 1: Identify Key Levels

Decide which levels you want to reward. Common choices: 5, 10, 25, 50, 100, 250, 500, 1000+

Step 2: Create Tier Roles

In Discord, create roles for each tier (e.g., @Bronze, @Silver, @Gold). Organize them hierarchically.

Step 3: Configure Rewards

/leveling roles add 5 @Bronze

Use the command to associate roles with levels.

Step 4: Test and Verify

Use `/leveling roles list` to verify your setup is correct.

Example Tier Systems

Here are some popular tier system configurations:

Classic Metal Tiers

Level 5@Bronze
Level 15@Silver
Level 30@Gold
Level 50@Platinum
Level 100@Diamond

Gaming Ranks

Level 10@Copper
Level 25@Iron
Level 50@Steel
Level 100@Legendary

Prestige System

Level 50@Prestige I
Level 100@Prestige II
Level 250@Prestige III
Level 500@Prestige IV

Multiple Roles Per Level

Assign multiple roles to a single level for more flexibility:

Example: Level 10 Configuration

/leveling roles add 10 @Member
/leveling roles add 10 @Active
/leveling roles add 10 @Contributor

When a member reaches level 10, they receive all three roles simultaneously.

Announcement Settings

Configure announcements when members reach level milestones:

/leveling roles announce <level> <channel>Set announcement channel for a level
/leveling roles announce-message <level> <message>Set custom announcement message
/leveling roles announce-disable <level>Disable announcement for a level
/leveling roles announce-listView all announcement configurations

Announcement Variables

Use these variables in custom announcement messages:

{user}

Mentions the user who reached the level

Example: Congratulations {user}!

{level}

The level that was reached

Example: You have reached level {level}!

{role}

The role(s) they received

Example: You earned the {role} role!

{xp}

Total XP the user has

Example: {user} now has {xp} XP

{rank}

User rank in the leaderboard

Example: {user} is now rank {rank}!

{guild}

The server name

Example: Welcome to {guild}!

Announcement Examples

Here are some example announcement configurations:

Simple Announcement

/leveling roles announce-message 10 "Congrats {user} on reaching level 10! You earned the {role} role!"

Milestone Announcement

/leveling roles announce-message 50 "🎉 {user} has reached an incredible level 50! Rank {rank} in {guild}!"

Prestige Announcement

/leveling roles announce-message 100 "{user} has achieved legendary status at level 100! Earned: {role}"

Role Removal Settings

Control whether previous tier roles are removed when members rank up:

Stacking Mode (Default)

Members keep all earned roles as they level up. A level 50 player would have @Bronze, @Silver, @Gold, and @Platinum roles.

/leveling roles set-mode stacking

Replacement Mode

Members replace their role tier as they level up. A level 50 player would only have the @Platinum role.

/leveling roles set-mode replacement

Permanent Mode

Members keep roles even if their level decreases (only awarded once).

/leveling roles set-mode permanent

Advanced Configuration

Fine-tune role reward behavior:

Require Admin Role

/leveling roles require-admin-role <role>

Only members with a specific role can receive level-based role rewards.

Whitelist Channel

/leveling roles whitelist-channel <channel>

Only XP from specific channels count towards role rewards.

Tips & Best Practices

  • • Create a clear tier progression with spacing between levels (avoid levels too close together)
  • • Use visually distinct role colors to make tier progression feel rewarding
  • • Place tier roles below bot roles in the hierarchy for proper functionality
  • • Set announcements in a public channel to celebrate member achievements
  • • Consider using custom role names that fit your server's theme
  • • Use replacement mode for cleaner role lists; stacking for prestige systems
  • • Make lower tier rewards achievable within days, higher tiers require weeks/months
  • • Regularly review role reward progression and adjust based on member engagement

Troubleshooting

Roles not being assigned

Ensure the bot role is higher in the hierarchy than the reward roles. Check that levels are configured correctly with `/leveling roles list`.

Role assignment is delayed

Role assignments are processed immediately when a level is reached. If delayed, check server rate limits and bot permissions.

Announcements not posting

Verify the announcement channel is set and the bot has Send Messages permission. Check the channel isn't archived or restricted.

Members losing roles

In replacement mode, lower tier roles are removed when upgrading. Use stacking mode to keep all earned roles.

XP ConfigurationRank Cards