> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bloombot.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Leveling

> Reward your members for being active with XP, levels, level up messages, and level rewards.

Bloom rewards active members with XP as they chat, and can announce level ups and grant roles at milestones. This page covers how XP is earned and how to set up rewards, announcements, multipliers, and more.

## How leveling works

Leveling is **on by default**. Members earn XP for taking part in chat, and Bloom tracks each member's XP per server. What is off by default is the announcement: Bloom stays silent about level ups until you enable level up messages.

Bloom is designed to reward genuine conversation, not activity for its own sake:

* **Substantive messages earn more.** A real message is worth more than a one word reply. Attachments and stickers earn a little on their own.
* **Low effort messages earn little or nothing.** Symbol only messages, one character repeated, and messages that just repeat what the member recently said are not rewarded.
* **Bursts are fine, spamming is not.** A natural flurry of messages is rewarded, but flooding the channel quickly stops paying out, so there is nothing to gain from it.

A server or per channel [multiplier](#server-and-channel-multipliers) can scale how much XP members earn. Bots never earn XP.

<Info>
  Because Bloom rewards real participation and limits how fast XP can be earned, members cannot climb the leaderboard by spamming, and you do not need to set a message cooldown yourself.
</Info>

### Level progression

Each level requires a little more XP than the one before, so ranks stay meaningful while remaining reachable for active members. A member's rank card shows a progress bar toward their next level.

## Defaults

| Setting                | Default         | Meaning                                             |
| ---------------------- | --------------- | --------------------------------------------------- |
| Leveling               | Enabled         | Members earn XP right away.                         |
| Level up messages      | Disabled        | No announcement is sent until you enable it.        |
| Announcement channel   | Current channel | Where the announcement is sent once enabled.        |
| Server XP multiplier   | `1`             | XP is granted normally, with no boost or reduction. |
| Role stacking          | On              | Members keep every level role they earn.            |
| Role restore on rejoin | On              | Level roles are reapplied when a member rejoins.    |

## Quick start

<Steps>
  <Step title="See your own rank">
    Run `!level`. Bloom shows your level, XP, rank, and a progress bar. Run `!level @member` to view someone else.
  </Step>

  <Step title="Turn on level up messages">
    Run `!level on` to make sure leveling is enabled, then `!level message enable` to announce level ups. By default the announcement is sent in the channel where the member leveled up.
  </Step>

  <Step title="Reward a role at a level">
    Run `!level role add 5 @Regular`. Members who reach level 5 receive the Regular role.
  </Step>

  <Step title="Check the configuration">
    Run `!level config` to review the current settings at any time.
  </Step>
</Steps>

## Viewing rank and the leaderboard

<ParamField path="level" type="prefix command">
  Shows a member's level card, and is also the entry point for every subcommand below. Alias: `lvl`.

  * `!level` shows your own card.
  * `!level <user>` shows another member's card, by mention, ID, or name.
  * `!level leaderboard` shows the server's top ranked members. Aliases: `top`, `lb`.
  * **You need:** nothing to view cards or the leaderboard.
</ParamField>

## Configuring leveling

All setup subcommands are permission gated. The permission is checked through Bloom's permission system, so a member you granted the matching Bloom permission through fake permissions can run them without the raw Discord permission.

### Enable or disable

<ParamField path="level on | level off" type="Manage Server">
  Turns XP earning on or off for the whole server. Accepts `on`, `enable`, `yes`, `unlock`, and the opposites `off`, `disable`, `no`, `lock`.

  ```text theme={null}
  !level off
  ```

  Disabling stops new XP from being earned. It does not delete existing XP.
</ParamField>

### Server and channel multipliers

<ParamField path="level multiplier <value>" type="Manage Server">
  Sets the server wide XP multiplier. Alias for the subcommand: `mult`.

  * **Accepted values:** `0` to `100`
  * `0` stops XP entirely for the whole server, the same effect as disabling.

  ```text theme={null}
  !level multiplier 2
  ```

  Members now earn twice the XP everywhere except channels that have their own multiplier.
</ParamField>

<ParamField path="level channel multiplier <#channel> <value|reset>" type="Manage Server">
  Sets a multiplier for one channel, which overrides the server multiplier in that channel.

  * **Accepted values:** `0` to `100`, or `reset` to remove the channel's override
  * `!level channel multiplier list` shows all channel overrides.

  ```text theme={null}
  !level channel multiplier #grinding 3
  ```

  Messages in `#grinding` now earn three times the XP, regardless of the server multiplier.
</ParamField>

### Ignored channels

<ParamField path="level ignore" type="Manage Server">
  Excludes channels from earning XP. Messages sent in an ignored channel do not earn anything toward leveling.

  Use `!level ignore` to manage the ignored channel list.
</ParamField>

### Level rewards

<ParamField path="level role add <level> <@role>" type="Manage Server">
  Grants a role when a member reaches a level. The subcommand accepts `role`, `roles`, or `r`.

  * **level:** a whole number, 1 or higher
  * Running `!level role` with no arguments lists the configured rewards and marks which you have earned.

  ```text theme={null}
  !level role add 10 @Trusted
  ```

  Members reaching level 10 receive the Trusted role.
</ParamField>

<ParamField path="level role remove <level>" type="Manage Server">
  Removes the reward configured at a level.

  ```text theme={null}
  !level role remove 10
  ```
</ParamField>

<ParamField path="level roles stack <yes|no>" type="Manage Server">
  Controls whether members keep every reward role they earn.

  * `yes` (default): a member keeps all level roles at or below their level.
  * `no`: a member keeps only the highest level role they qualify for, and lower reward roles are removed.

  In both modes, Bloom removes reward roles above a member's current level.
</ParamField>

<ParamField path="level role sync" type="Administrator">
  Recalculates and reapplies every member's level roles to match their current level. The subcommand accepts `sync`, `fullcheck`, or `check`, and has a cooldown between runs. Use it after adding or changing rewards so existing members receive the roles they already qualify for.
</ParamField>

<ParamField path="level role restore <@user>" type="Manage Server">
  Reapplies a single member's level roles based on their stored level, without touching anyone else.

  ```text theme={null}
  !level role restore @Ada
  ```
</ParamField>

### Role restoration on rejoin

<ParamField path="level restore on | off" type="Manage Server">
  Controls whether a member's level roles are reapplied when they rejoin the server. On by default.

  ```text theme={null}
  !level restore on
  ```
</ParamField>

### Administering XP

<ParamField path="level xp add | remove <@user> <amount>" type="Manage Messages">
  Adds or removes XP for a member.

  ```text theme={null}
  !level xp add @Ada 500
  ```

  Ada gains 500 XP, and if that crosses a level threshold she levels up and receives any reward roles.
</ParamField>

<Danger>
  `!level reset` deletes **all** leveling data for the server: every member's XP and level, every reward role mapping, ignored channels, channel multipliers, and the leveling settings. It requires the **Administrator** permission and a confirmation. Bloom asks you to type `confirm` within 15 seconds, and the action cannot be undone.
</Danger>

## Level up messages

Level up messages are off until you enable them. Once enabled, Bloom sends a message when a member levels up.

<ParamField path="level message enable | disable" type="Manage Server">
  Turns level up announcements on or off. Every `level message` subcommand requires Manage Server.
</ParamField>

Choose where the announcement is sent:

| Command                   | Destination                                                   |
| ------------------------- | ------------------------------------------------------------- |
| `!level message context`  | The channel where the member leveled up. This is the default. |
| `!level message #channel` | A specific channel.                                           |
| `!level message dm`       | The member's direct messages.                                 |

Customize the text:

<ParamField path="level message set <text>" type="Manage Server">
  Sets the announcement template. The template can be plain text with variables, or an embed written in the `$e{...}` format described in the [Embed syntax reference](/reference/embeds).

  ```text Plain text with variables theme={null}
  !level message set Nice work {user.mention}, you reached level {level}!
  ```

  ```text Embed template theme={null}
  !level message set $e{title: Level up!}$e{description: {user.mention} reached level {level}}$e{color: #6E8CAB}
  ```
</ParamField>

* `!level message view` shows the current template, channel, and whether messages are enabled.
* `!level message variables` lists the available variables.
* `!level message test` sends a preview using the current template.

If you enable messages but never set a template, Bloom sends a simple default such as *Ada leveled up to level 5!*, and appends the earned role when one is granted.

### Level up variables

These variables are replaced when the announcement is sent. They apply only to level up messages; other Bloom features use their own variables.

| Variable            | Replaced with                    |
| ------------------- | -------------------------------- |
| `{level}`           | The new level                    |
| `{prev.level}`      | The previous level               |
| `{next.level}`      | The level after this one         |
| `{xp.total}`        | XP for the current level         |
| `{user}`            | The member's username            |
| `{user.mention}`    | A mention of the member          |
| `{user.id}`         | The member's user ID             |
| `{user.avatar}`     | The member's avatar URL          |
| `{user.servername}` | The member's server display name |
| `{user.nickname}`   | The member's nickname            |
| `{guild.name}`      | The server name                  |
| `{guild.id}`        | The server ID                    |
| `{guild.icon}`      | The server icon URL              |
| `{date}`            | The current date                 |
| `{time}`            | The current time                 |

To show text only when a role was earned, wrap it in `&&`:

```text theme={null}
!level message set {user.mention} reached level {level}! && You earned the {role.name} role! &&
```

The section between the `&&` markers appears only when the level up granted a role. Inside it, `{role.name}` and `{role.mention}` refer to the earned role.

## How rewards are applied

When a member levels up, Bloom updates their roles as follows:

* Reward roles above the member's new level are always removed.
* With stacking on, every reward role at or below the new level is added.
* With stacking off, only the highest qualifying reward role is kept and lower ones are removed.

<Warning>
  Bloom can only assign a role that sits **below its own highest role** in the server's role list, and Bloom needs the Manage Roles permission. If a reward role is above Bloom's role, Bloom cannot grant it. Place Bloom's role above every reward role.
</Warning>

## Interactions with other features

* **Ignored channels and multipliers** control where and how much XP is earned. A message in an ignored channel earns nothing, and a message in a channel with a `0` multiplier also earns nothing.
* **Embed templates** for level up messages use the same `$e{...}` syntax as saved embeds. See the [Embed syntax reference](/reference/embeds).
* **Role hierarchy** determines whether reward roles can be granted, the same as any other role Bloom assigns.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Members are earning XP but no level up message appears">
    Level up messages are off by default. Run `!level message enable`. Confirm the destination with `!level message view`, and if you set a specific channel, make sure Bloom can send there.
  </Accordion>

  <Accordion title="A member reached the level but did not get the reward role">
    Check that Bloom's own role is above the reward role and that Bloom has Manage Roles. For members who reached the level before you added the reward, run `!level role sync` to grant roles they already qualify for.
  </Accordion>

  <Accordion title="XP seems to stop after a lot of messages at once">
    This is expected. Bloom rewards a natural burst of chatting, then limits how fast XP is earned so that spamming cannot farm it. Earning recovers after a short pause.
  </Accordion>

  <Accordion title="Repeated or symbol only messages earn nothing">
    Also expected. Messages that just repeat what the member recently said, and messages that are only symbols or one repeated character, do not earn XP.
  </Accordion>
</AccordionGroup>

## Related pages

<CardGroup cols={2}>
  <Card title="Embed syntax" icon="code" href="/reference/embeds">
    Write embed level up messages with the `$e{...}` format.
  </Card>

  <Card title="Using prefix commands" icon="keyboard" href="/getting-started/commands">
    How to run the `level` command and read its syntax.
  </Card>
</CardGroup>