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

# Level rewards

> ## Documentation Index
>
> Fetch the complete documentation index at: [https://docs.bleh.bot/llms.txt](https://docs.bleh.bot/llms.txt)
> Use this file to discover all available pages before exploring further.

# Level Rewards

> Reward your members for being active in your server.

## Getting started

Before you run any commands, it's important to use the `levels unlock` command otherwise
XP will not be tracked for users. You can also use the `levels lock` command to temporarily stop tracking XP.

## Ignoring channels and roles

You should immediately ignore channels and roles that you don't want gaining XP. You can do this by using the `levels ignore` command.

<Info>
  If you no longer want to ignore a channel or role, you can re-run the command.
  You can also use `levels list` to view all ignored channels and roles.
</Info>

<CodeGroup>
  ```javascript Syntax theme={null} theme={null}
  ,levels ignore (channel or role)
  ```

  ```javascript Example theme={null} theme={null}
  ,levels ignore #spam
  ,levels ignore @jailed
  ```
</CodeGroup>

<br />

<Frame />

## Setting up roles to reward

You can reward your members with roles when they reach a certain level. You can use the `levels add` command to add a level reward.

<Info>
  If you no longer want to reward a role for a level, you can use the `level
          remove` command.
</Info>

<Tip>If your server already has XP, you can use the `levels sync` command to ensure that all users have the correct roles based on their XP.</Tip>

<CodeGroup>
  ```javascript Syntax theme={null} theme={null}
  ,levels add (role) (level)
  ,levels remove (level)
  ```

  ```javascript Example theme={null} theme={null}
  ,levels add @Levelone 5
  ,levels remove 5
  ```
</CodeGroup>

<br />

<Frame />

### Stacking reward roles

Stacking roles means that users will keep all the roles they've earned when they reach a new level, instead of only having the role for their current level. By default, this feature is enabled.

<CodeGroup>
  ```javascript Syntax theme={null} theme={null}
  ,levels stackroles (on or off)
  ```

  ```javascript Example theme={null} theme={null}
  ,levels stackroles off
  ```
</CodeGroup>

## Customizing level-up messages

You can customize the level-up message that will be sent when a user achieves a new level.

<Danger>
  Level up messages start sending at level four. This is intended behavior.
</Danger>

<Info>
  The `message` parameter can be raw text or an [embed](/resources/scripting)
  with dynamic [variables](/resources/scripting/variables).
</Info>

<Warning>You must include the `{guild.name}` variable in your message if `messagemode` is set to `pm`.</Warning>

<CodeGroup>
  ```javascript Syntax theme={null} theme={null}
  ,levels message (text or embed code)
  ```

  ```javascript Example theme={null} theme={null}
  ,levels message Congrats {user} on reaching level {level.new_rank} in {guild.name}!
  ,levels message {embed}$v{message: {user.mention}}$v{description: you have reached level {level.new_rank} in {guild.name}}
  ```
</CodeGroup>

### Setting where the message is sent

You can set the channel where the level-up message will be sent. By default, the message is sent in the same channel where the user achieved the level.

The `option` parameter can be one of the following:

* `pm` - Sends the message in the user's direct messages.
* `context` - Sends the message in the same channel where the user gained XP.
* `#channel` - Sends the message in the specified channel.
* `none` - Entirely disables the level-up message.

<CodeGroup>
  ```javascript Syntax theme={null} theme={null}
  ,levels messagemode (option)
  ```

  ```javascript Example theme={null} theme={null}
  ,levels messagemode #level-up
  ,levels messagemode pm
  ```
</CodeGroup>

<br />

<Frame />

## Changing a member's level

You can change a member's level to a specific level or set their XP to a specific amount.

<CodeGroup>
  ```javascript Syntax theme={null} theme={null}
  ,setlevel (member) (level)
  ,setxp (member) (xp)
  ```

  ```javascript Example theme={null} theme={null}
  ,setlevel @user 5
  ,setxp @user 10000
  ```
</CodeGroup>

## Changing the XP multiplier

You can change the XP multiplier to increase or decrease the amount of XP members receive.

<CodeGroup>
  ```javascript Syntax theme={null} theme={null}
  ,levels setrate (multiplier)
  ```

  ```javascript Example theme={null} theme={null}
  ,levels setrate 2.4
  ```
</CodeGroup>

## Related commands

<AccordionGroup>
  <Accordion title="Viewing a user's level and XP">
    Use the `rank` command to view a user's level and XP.
  </Accordion>

  <Accordion title="Viewing the XP leaderboard">
    Use the `levels leaderboard` subcommand to highest XP earners in the server.
  </Accordion>

  <Accordion title="Viewing the level rewards">
    Use the `levels roles` subcommand to view all level rewards and the
    remaining XP needed to receive them.
  </Accordion>
</AccordionGroup>