> From the BotGhost docs: https://botghost.com/docs/fun-modules/leveling
> Every page: https://botghost.com/docs/llms.txt

# Leveling

XP for chatting and voice, role rewards, leaderboards and rank cards. Free for every bot.

Leveling gives members XP for chatting, talking in voice and more, turns that XP into levels, and rewards each level with roles, perks and coins. Members check their place with `/rank` and `/level top`, and weekly, monthly and season boards start again on their own with a winners post. Leveling is free for every bot: every feature, with no Premium split.

The [Discord leveling bot](https://botghost.com/discord-leveling-bot) page gives a shorter tour of what Leveling can do.

![A level-up card: Fabian reached level 25 and unlocked the Regular role, with the next reward at level 30](https://botghost.com/docs/content/assets/workspace/leveling-levelup-card-example.png)

*A level-up card, one of the designs you can pick*

> **Note:** Using the old Leveling module? The new page offers to move everyone's XP and your settings across, so every member keeps their level. See [Moving from the old Leveling](https://botghost.com/docs/fun-modules/leveling#moving-from-the-old-leveling).

## Before you start

You need:

- Your bot in your Discord server. See [Invite Your Bot](https://botghost.com/docs/getting-started/invite-your-bot) if it isn't yet.
- For role rewards: your bot's own role **above** every reward role, with **Manage Roles** turned on.
- For level-up messages in a channel: **View Channel**, **Send Messages** and **Attach Files** (for cards) in that channel.

## Setup

### Step 1: Turn on Leveling

Open **Leveling** in your bot's dashboard and press **Enable** at the top right.

![The top of the Leveling page with Enabled, the server menu, Reset to Default and Docs marked](https://botghost.com/docs/content/assets/workspace/leveling-enable.png)

- **A** **Enable** turns Leveling on. It adds the `/rank`, `/level`, `/xp` and `/prestige` commands, the events Leveling runs on and the custom variables it keeps XP and settings in.
- **B** The server you're setting up. Every Leveling setting belongs to one server, so pick the server first. The page shows the server's icon and name on the settings you're changing.
- **C** **Reset to Default** puts every setting in that server back to how a new Leveling starts. The lists of rewards and perks stay.
- **D** **Docs** opens this page.

### Step 2: Follow the setup strip

![The setup strip saying You're set, with the three steps ticked](https://botghost.com/docs/content/assets/workspace/leveling-setup-strip.png)

- **A** What to do next. Once everything is done, it says **You're set**.
- **B** The steps: pick where level-up messages go, add a role reward, and put your bot's role above the rewards. Press one to go to it.

### Step 3: Save

A bar pops up at the bottom of the page. Press **Save Changes**. Your bot restarts to pick up the changes, which takes about 20 seconds.

![The Unsaved changes bar with Save Changes marked](https://botghost.com/docs/content/assets/workspace/welcomer-save.png)

To try it out, send a few messages in your server and run `/rank`.

## How Leveling works

Members earn XP. Their total XP decides their level through your curve: the XP from one level to the next grows as levels go up, so early levels come fast and later ones take longer. Changing the curve later never changes anyone's XP, only the level it reaches.

Every XP source runs through the same steps: the multipliers, the message bonuses, the daily cap and the streak, then every board, then the level check. When a member reaches a new level, they get that level's perks and roles, and the level-up message goes where you picked.

The settings are on six tabs:

![The Leveling tabs: XP, Levels and rewards, Level-ups, Leaderboards, Members and BotPanel](https://botghost.com/docs/content/assets/workspace/leveling-tabs.png)

Leveling is built from ordinary builder blocks. At the bottom of the page, **The Leveling commands** and **The Leveling events** list everything it adds. Open one in the builder to see how it works or to add your own blocks. The settings on the page are read by those blocks, so changing a setting never needs the events made again.

![The Leveling events list: Message Sent, Give XP, Settle Level and Level Up, each with Open in builder and a switch](https://botghost.com/docs/content/assets/workspace/leveling-events.png)

## XP

### XP from messages

A random amount between **From** and **To** for chatting, at most once per cooldown. New servers start at 15 to 25 XP once a minute.

![The XP from messages card: 15 to 25 XP once every minute, with the message bonus switches](https://botghost.com/docs/content/assets/workspace/leveling-xp-messages.png)

- **XP in threads and forum posts**: off means messages in threads and forum posts earn nothing.
- **Longer messages earn more**: a bonus for messages over a length. Spaces, emoji, mentions and links don't count.
- **Pictures and files earn extra**: a message with a picture, video or file.
- **Replies earn extra**: replying to someone else's message.
- **First message of the day bonus**: their first message that earns XP each day, in the server's time zone.

The bonuses come after the multipliers and count toward the daily cap.

### What earns nothing

Checked before anything is saved, so spam costs nothing.

![The What earns nothing card: messages shorter than 3 characters, the same message again, only a picture or a link, command prefixes and the daily cap](https://botghost.com/docs/content/assets/workspace/leveling-what-earns-nothing.png)

- **Messages shorter than** a number of characters. Emoji, mentions and links don't count. 0 lets any message earn.
- **The same message again**: sending the same words twice in a row earns XP once.
- **Only a picture or a link**: a message needs some words of its own.
- **Commands**: messages starting with any of the characters you list. Leave it empty to let commands earn XP.
- **Daily cap**: the most XP a member can earn from messages in a day.

### XP from voice

XP for each minute in a voice channel with at least the number of other people you pick (bots don't count). The AFK channel and deafened members never count.

![The XP from voice card: 10 XP a minute with at least 1 other person, muted members, stage audience, streaming bonus and daily voice cap](https://botghost.com/docs/content/assets/workspace/leveling-xp-voice.png)

- **XP a minute**: 10 to start.
- **Muted members earn voice XP**: they may still be listening.
- **Stage audience earns XP**: people listening in a stage channel earn too.
- **Streaming bonus**: ×2 doubles their XP while they share their screen. ×1 means no bonus.
- **Daily voice cap**: the most minutes a member can earn XP for in a day.

Voice XP is counted every 10 minutes while members talk, and settled when they leave, so long sessions level up as they go.

### More ways to earn

Each has its own amount.

![The More ways to earn card with reactions, new forum posts, boosting the server and live server events switched on](https://botghost.com/docs/content/assets/workspace/leveling-more-ways.png)

- **Reactions on their messages**: XP for the message's author, once per person per message. Reacting to your own message earns nothing.
- **New forum posts**: XP for a new post in a forum channel, at most once every 10 minutes.
- **Boosting the server**: XP once per boost, every time they boost.
- **Live server events**: voice XP is multiplied in an event's channel while the event is live.
- **Remove XP when members leave**: off keeps their XP, so they keep their level if they come back.

### Where XP is off

![The Where XP is off card: which channels, channels and roles that earn nothing, and the Bots earn XP switch](https://botghost.com/docs/content/assets/workspace/leveling-where-xp-is-off.png)

- **Which channels**: every channel except the ones you list, or only the ones you list. Threads and forum posts follow their channel.
- **Roles that earn nothing**: members with any of these never earn XP.
- **Bots earn XP**: other bots earn XP from messages, voice, reactions and posts like members do. Off, they never earn it, though staff can still give them XP with `/xp`. Off to start.

### Role multipliers

Members with the role earn this many times the XP.

![Role multipliers with Supporter at ×1.5, Channel multipliers, and Server boosters at ×1](https://botghost.com/docs/content/assets/workspace/leveling-multipliers.png)

### Channel multipliers

XP earned in the channel is multiplied. A thread uses its own row, then its channel's, then the category's.

### Server boosters

Members boosting the server earn this many times the XP. ×1 means no bonus.

### Time windows

Extra XP during set hours or days, like double XP at weekends, in the server's time zone. A window may pass midnight, like 22:00 to 02:00.

![A time window giving ×2 on Saturday and Sunday, and the Double XP event card with 2 XP for 3 hours and Start](https://botghost.com/docs/content/assets/workspace/leveling-time-windows.png)

### Double XP event

Pick how many times the XP and for how long, then press **Start**. It starts once you save. It shows on rank cards and level-ups while it runs.

Staff can also run `/xp boost` in Discord, with a multiplier like `2` and a duration like `3h` or `2d` (an hour if left out). `/xp boost 1` ends it. `/xp boost` posts the started message; starting it from the page doesn't.

### How multipliers add up

When several multipliers apply at once:

- **Use the highest**: only the biggest counts. A Supporter (×1.5) chatting on a ×2 weekend earns ×2.
- **Multiply them**: ×1.5 and ×2 make ×3.
- **Add them up**: ×1.5 and ×2 make ×2.5.

**Never more than** caps the total, ×5 to start.

![How multipliers add up set to Use the highest, never more than ×5, and Daily streaks on with 2% a day up to 30% and milestone days 7, 30 and 100](https://botghost.com/docs/content/assets/workspace/leveling-multipliers-add-up.png)

### Daily streaks

A bonus for each day in a row a member chats. Missing a day starts the streak again. **Bonus a day** is the extra XP each day in a row adds, in percent (2% to start), **Up to** is the most it can reach (30%), and **Milestone days** (7, 30 and 100 to start) get the streak message.

## Levels and rewards

### How fast levels come

Pick a curve. The table under it shows the total XP for some levels and about how long steady chatting takes to get there.

![The curve picker with Classic chosen, and a table of levels 1 to 100 with their total XP and how long each takes](https://botghost.com/docs/content/assets/workspace/leveling-curve.png)

| Curve | Good for |
| --- | --- |
| Classic | Most servers. The default |
| Gentle | Small servers |
| Steep | Very busy servers |
| Same every level | Game style: every level takes the same XP |
| Leveling (old) | The old Leveling module's curve |
| Your own numbers | Pick the three numbers yourself |
| Your own table | The XP for each level, as a list. Levels past the list keep the last step |

Changing it later never changes anyone's XP, only the level it reaches.

![The Highest level, Levels never go down, Hide far rewards and Recalculate everyone cards](https://botghost.com/docs/content/assets/workspace/leveling-level-options.png)

### Highest level

0 means no limit. Past the highest level, XP keeps counting for the boards.

### Levels never go down

On, taking XP and decay lower a member's XP but never their level or its rewards.

### Hide far rewards

Rewards more than five levels past your highest member show as ??? in `/level rewards`. Members still get them when they get there.

### Recalculate everyone

After you change the curve, some members' levels will move. Save first, then press **Recalculate everyone** to put every member on the level their XP reaches now.

### Level perks

**What each level gives** has one card per level, as many as you like.

![A level 5 card giving the Supporter role and two written perks: Post pictures in #media and Custom colour role](https://botghost.com/docs/content/assets/workspace/leveling-level-perks.png)

- **Level** and **Pick an icon**: the level, and an icon for it in the perks list.
- **Roles**: given when they reach the level. Your bot can only give roles below its own role.
- **Give to a variable**: items or money added to any member variable, like coins, each with an amount and a name. Added once, when they reach the level, and never given twice.
- **Written perks**: what the level brings that the bot doesn't give itself, like "Post pictures in #media". Press Enter for the next one, or paste a list.

**Post or update the perks list** posts every level's perks in a channel, or edits the post when it's already there.

![The Every level from a level on, How rewards stack, When levels drop or members return and Coins on level up cards](https://botghost.com/docs/content/assets/workspace/leveling-rewards-options.png)

### Every level from

For servers that go past their last perk card: from a level on, every level gives amounts worked out from the level, such as `1000 * ({level} - 100)` money from level 101. 0 is off.

### How rewards stack

- **Keep all earlier rewards**: members keep every reward role they earned.
- **Only the latest reward**: members keep only their newest reward role, and the one before comes off.

### When levels drop or members return

- **Take rewards back**: when staff take XP, decay or a new curve drops a member below a level, that level's reward roles come off. Items and money stay.
- **Give rewards back when they rejoin**: members who leave and come back get their roles again.

### Coins on level up

Money added each time a member levels up, kept in the variable you pick. **Coins every level** gives the same amount each time; set it to 0 to use **Coins by level**, where only the levels you list give coins.

### Sync rewards

After you change the rewards, **Sync rewards for everyone** adds missing roles and takes extra ones.

## Level-ups

![Where level-up messages go set to Where they chatted, and When to announce set to Every level with Delete after](https://botghost.com/docs/content/assets/workspace/leveling-levelup-where.png)

### Where level-up messages go

- **Where they chatted**: in the channel of the message that levelled them up. Voice and boost level-ups go to the level-up channel, so pick one if you want those announced.
- **A channel**: one level-up channel.
- **Their DMs**
- **Nowhere**: rewards are still given.

### When to announce

- **Every level**
- **Reward levels only**
- **Every few levels**: every 5 levels, or the number you pick.

**Delete after** removes the message after a while; 0 keeps it. Members can stop their own pings with `/level quiet`.

### When someone levels up

The level-up message, with a live preview beside it.

![The When someone levels up message card with its three texts, Edit message, the variables it fills in, and the preview of Fabian reaching level 30](https://botghost.com/docs/content/assets/workspace/leveling-levelup-message.png)

- **A** The message's texts. `{member}`, `{level}` and the others fill in when it's sent.
- **B** **Edit message** for pictures, separators and the layout. Your bot adds the buttons.
- **C** What fills in. Click one to copy it.
- **D** The preview, with sample details.

### Milestone messages

Up to five levels with their own message, like a big one at level 50.

### Random level-up messages

On, one of up to five messages is picked each time. An empty one is skipped.

### Level-up card

A picture card with the new level under the level-up message. Off to start: a card on every level-up is the heaviest thing Leveling does. **Pick a design** chooses a template, and **Edit in Card Studio** changes it.

![The Level-up card switched on, with the Level 13 card, Pick a design and Edit in Card Studio](https://botghost.com/docs/content/assets/workspace/leveling-levelup-card.png)

## Leaderboards

### Leaderboards

**All time** always counts. These boards start again on their own and never touch it:

![The Leaderboards card: This week starting again on Monday, This month, Seasons, Staff XP counts on these boards, the reset hour and the time zone](https://botghost.com/docs/content/assets/workspace/leveling-boards.png)

- **This week**: starts again once a week, on the day you pick.
- **This month**: starts again on the 1st.
- **Seasons**: a board with a name, a start and an end date. **Repeat** starts a new season of the same length when one ends.
- **Staff XP counts on these boards**: on, XP from `/xp give`, `take` and `set` changes This week, This month and the season too. Off changes All time only.

**Boards start again at** an hour, in the **Time zone** you pick (UTC until you pick one). Time windows and the first message of the day use it too.

### Leaderboard card

The leaderboard members open with `/level top`, with buttons for each board and the pages. **Use a card for /level top** shows the top members on a picture card. `/level climbers` shows who gained the most XP this week.

![The /level top card switched on, with the podium leaderboard card](https://botghost.com/docs/content/assets/workspace/leveling-top-card.png)

### Weekly winners

Posted before a board starts again.

![Weekly winners on, posted in #weekly-winners, the Regular role for the winner, Top 1, and Show the winners as a card](https://botghost.com/docs/content/assets/workspace/leveling-weekly-winners.png)

- **Post in**: the winners channel.
- **Role for the winner**: given until next time. Leave it empty to give no role.
- **Who gets the role**: the top 1 or the top 3.
- **Show the winners as a card**: monthly and season winners get it too.

![A winners card with Tom first, Fabian second and Jayce third](https://botghost.com/docs/content/assets/workspace/leveling-winners-card-example.png)

*A winners card*

### Rank card

Drawn for `/rank`, with their level, XP, rank and streak. Turn it off to reply with text. **Pick a design** chooses a template, and **Edit in Card Studio** changes it.

![The Rank card switched on, with the XP ring design, Pick a design and Edit in Card Studio](https://botghost.com/docs/content/assets/workspace/leveling-rank-card.png)

![A rank card for Fabian: level 25, rank 3, a 14 day streak, top 2% and an XP boost](https://botghost.com/docs/content/assets/workspace/leveling-rank-card-example.png)

*Another rank card design*

### Members' own style

Members pick a colour and a background from yours with `/level style`, from the level you set (5 to start). They can never use a picture of their own.

![Members' own style on from level 5, with five colours and three backgrounds members can pick](https://botghost.com/docs/content/assets/workspace/leveling-own-style.png)

- **Colours they can pick**: click a colour to take it out, or **Add** another.
- **Backgrounds they can pick**: picture links that start with `https://`, up to 12.

### Prestige

At the level you pick (100 to start), members can use `/prestige` to start again from level 0. They get a prestige badge and earn more XP for each prestige (5% more to start). Their lifetime XP is kept. **Prestige roles** give a role for a number of prestiges.

![Prestige on at level 100 with 5% more XP each prestige, and Prestige roles](https://botghost.com/docs/content/assets/workspace/leveling-prestige.png)

### XP decay

Members quiet for a number of days (30 to start) lose a part of their XP each week (5% to start), so the board shows who is active now. **How far it goes**: never below their level, or down to nothing. Decay is checked once a week, on the day and hour the boards start again, and never touches the time boards.

![XP decay on: members quiet for 30 days lose 5% a week, never below their level](https://botghost.com/docs/content/assets/workspace/leveling-decay.png)

## Members

### Members

Search for anyone and see their XP on All time, This week and This month. **Edit** sets a member's XP, and their level follows your curve. **Reset** clears one member. **Export CSV** downloads the server's members and their XP.

![The Members card with Tom and Fabian, their level and XP, Edit and Reset, and Export CSV](https://botghost.com/docs/content/assets/workspace/leveling-members.png)

### Old Levels data

Only for a server that still has XP from BotGhost's old built-in Levels: **Bring over the old Levels data** shows a preview first, then moves everyone across so each member keeps their level. A backup is kept for 30 days, with one click to undo.

### Backups

Every move and reset keeps what was there before for 30 days. **Undo** puts it back.

![Backups from the last 30 days with a move from Leveling (old) and Undo the move, and the Reset this server card](https://botghost.com/docs/content/assets/workspace/leveling-backups-reset.png)

### Reset this server

Clears everyone's XP, boards and levels in one server. Type the server's name to confirm. A backup is kept for 30 days.

### When staff change someone's XP

Staff use these in Discord:

| Command | What it does |
| --- | --- |
| `/xp give` | Adds XP to a member, or to everyone with a role |
| `/xp take` | Takes XP away, never below nothing |
| `/xp set` | Sets a member's XP |
| `/xp reset` | Asks first, then clears a member's XP, level and boards and takes their rewards off |
| `/xp boost` | Starts or ends a double XP event |
| `/level sync` | Puts the role rewards right for a member, or for everyone |

The answer to `/xp give`, `take`, `set` and `reset` is private: only the staff member sees it.

## Commands

![The Leveling commands: /rank, /level with 6 subcommands, /xp with 5 subcommands and /prestige, each with Settings and a switch](https://botghost.com/docs/content/assets/workspace/leveling-commands.png)

| Command | Who | What it does |
| --- | --- | --- |
| `/rank` | Everyone | Your level and rank, or a member's |
| `/level top` | Everyone | The leaderboard, with a button for each board |
| `/level climbers` | Everyone | Who gained the most XP this week |
| `/level rewards` | Everyone | Every level's rewards, ticked where you reached them |
| `/level quiet` | Everyone | Turns your level-up pings off or on |
| `/level style` | Everyone | Picks the colour and background of your rank card |
| `/prestige` | Everyone | Starts again from level 0 for a prestige and an XP bonus |
| `/xp give`, `/xp take`, `/xp set`, `/xp reset`, `/xp boost`, `/level sync` | Staff | See [When staff change someone's XP](https://botghost.com/docs/fun-modules/leveling#when-staff-change-someones-xp) |

Each subcommand is its own command. Open one under **The Leveling commands** to edit it in the builder, change who can use it, or switch it off.

## The messages

Every message Leveling sends is on the page with **Edit message** for pictures, separators and the layout, and a list of what fills in. Your bot adds the buttons. Besides the level-up messages, there are messages for `/rank`, `/level rewards`, the perks list, a board resetting, someone prestiging, someone keeping a streak, staff changing XP, an XP boost starting and ending, and `/level quiet`.

## BotPanel

With a [BotPanel](https://botghost.com/docs/botpanel) website, members see the leaderboards, their rank and the rewards on the web, and server admins change Leveling for their server there. These pages come with **BotPanel Plus**.

![The BotPanel tab: Your BotPanel website is live with Open the website and Open BotPanel, and the server's own website switches](https://botghost.com/docs/content/assets/workspace/leveling-botpanel-site.png)

### BotPanel pages

Turn each page on or off in BotPanel, under **Website**, **Pages**, **Leaderboards**.

![Pages for Leveling: Leaderboards, My rank, Climbers, Hall of fame, Server activity, Rewards and Member profiles, all on](https://botghost.com/docs/content/assets/workspace/leveling-botpanel-pages.png)

- **Leaderboards**: each server's top members, for XP and any number your bot keeps for members, like coins or wins. As many boards as you like. While Leveling is on, its XP boards are added by themselves.
- **My rank**: members sign in and see their place on every board, with their rank card.
- **Climbers**: who gained the most this week, on each board.
- **Hall of fame**: each board's top three when its week or month ends.
- **Server activity**: each board's total per day for 30 days, and the busiest channels.
- **Rewards**: every level's roles and perks, ticked for what a signed in member has.
- **Member profiles**: click a name to see that member on every board. Members can hide themselves from every board.

![A server's XP leaderboard on a BotPanel website, with Boards, Hall of fame, Activity and Rewards](https://botghost.com/docs/content/assets/workspace/leveling-website-board.png)

*A server's leaderboard on the website*

![My rank on the website for a signed in member: level 3, prestige 2, 10 messages and 2 minutes in voice, and their place on every board](https://botghost.com/docs/content/assets/workspace/leveling-website-my-rank.png)

*My rank on the website*

![The Server activity page with a chart for Counting, XP, XP this week and XP this month](https://botghost.com/docs/content/assets/workspace/leveling-website-activity.png)

*Server activity on the website*

### Leaderboard on your website

Each server picks for itself, on the Leveling page's **BotPanel** tab:

- **Show this server on the website's Leaderboards**: members can still hide themselves from it.
- **Count XP per channel for Server activity**: the Server activity page shows this week's busiest channels. It starts again at each weekly reset.

### BotPanel server dashboard

Server admins sign in with Discord on the website's server dashboard and change Leveling for their own server. Card designs, members' XP, resetting a server and starting a double XP event stay on your dashboard.

![What server admins can change on the website, and what stays only on the dashboard](https://botghost.com/docs/content/assets/workspace/leveling-botpanel-admins.png)

## Moving from the old Leveling

While the old Leveling module is on, the new page shows **Bring over everyone's XP from Leveling (old)**.

![The strip saying Bring over everyone's XP from Leveling (old), with Move my settings and XP](https://botghost.com/docs/content/assets/workspace/leveling-move-strip.png)

Press **Move my settings and XP**:

1. **A dry run first**: nothing changes yet. It shows each server, how many members have XP, the top five with their old and new level, the settings that change and what can't move.
2. **Move**: every member's XP is copied across, and every count is checked. Everyone keeps exactly the same level and progress: your old step per level comes across as your own numbers on the curve.
3. **Save**: the old module is switched off and the new one on, with the settings in each server. Until you save, the old one keeps running.

![The move window's dry run: one member in Ghost Lounge, level 2 stays 2, the settings that change, what can't move, and Move 1 member and the settings](https://botghost.com/docs/content/assets/workspace/leveling-move-window.png)

Only the members being moved get their XP replaced; everyone else keeps theirs. **Undo the move** puts every value back and turns the old module on again. The old values are kept for 30 days. Changes you made to the old module's own commands and events don't move: add your own blocks under the note in the new Level Up event if you need them.

## Free for everyone

Leveling is free for every bot. Its variables, stored values and usage never count toward your free limits.
