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

# Levels

> XP for chatting, role rewards at milestones, and a fully configurable progression curve.

Members earn XP for messages. Enough XP levels them up, which can announce in a channel and grant a role.

```javascript theme={null}
!level toggle on
```

That's the minimum. Everything below is tuning.

## Checking progress

<CodeGroup>
  ```javascript Your own theme={null}
  !level
  ```

  ```javascript Someone else's theme={null}
  !level @someone
  ```

  ```javascript The leaderboard theme={null}
  !leaderboard
  ```
</CodeGroup>

Aliases: `levels`, `lvls`, `lvl`, `rank`. The leaderboard is also at `!level leaderboard` (`lb`, `top`).

## Role rewards

<CodeGroup>
  ```javascript Add a reward theme={null}
  !level role add 10 @Regular
  ```

  ```javascript More rungs theme={null}
  !level role add 25 @Veteran
  !level role add 50 @Elder
  ```

  ```javascript Remove one theme={null}
  !level role remove 25
  ```

  ```javascript List them theme={null}
  !level role list
  ```
</CodeGroup>

`!level add 10 @Regular` is a shortcut for the same thing. Requires **Manage Roles** and **Manage Server**.

### Stacking

```javascript theme={null}
!level role stack
```

Toggles whether members keep lower rewards. **Stacking on** means a level 50 member holds Regular, Veteran and Elder; **off** means they only hold Elder, and the earlier roles are removed as they progress.

### Backfilling

```javascript theme={null}
!level sync
```

Grants everyone the rewards their current level entitles them to. Run it after adding a new reward tier — otherwise existing members only get it if they level up again.

## Level-up messages

<CodeGroup>
  ```javascript Where they go theme={null}
  !level channel #level-ups
  ```

  ```javascript In the channel they were talking in theme={null}
  !level channel
  ```

  ```javascript Customise the message theme={null}
  !level message {content: gg {user.mention}} {description: you're level **{user.level}**} {color: dominant}
  ```

  ```javascript Preview theme={null}
  !level message view
  ```

  ```javascript Back to default theme={null}
  !level message remove
  ```
</CodeGroup>

### Available variables

| Variable             | Value                        |
| -------------------- | ---------------------------- |
| `{user.level}`       | The level just reached       |
| `{user.next_level}`  | The one after                |
| `{user.xp}`          | XP toward the current level  |
| `{user.total_xp}`    | Lifetime XP                  |
| `{user.required_xp}` | XP needed for the next level |

Plus all the standard [variables](/scripting/variables).

### Only announce role rewards

```javascript theme={null}
!level message roles
```

Only send a message when a level actually grants a role. Cuts the noise dramatically on a busy server. Aliases: `reward`, `roleonly`, `ro`.

### Cooldown

```javascript theme={null}
!level cooldown 60
```

Minimum seconds between level-up messages for the same member.

## The XP curve

```javascript theme={null}
!level spec
```

Three knobs, all requiring **Manage Server**.

<CodeGroup>
  ```javascript XP per message theme={null}
  !level spec gain 10 18
  ```

  ```javascript Base XP for level 1 theme={null}
  !level spec base 100
  ```

  ```javascript How steeply it scales theme={null}
  !level spec factor 1.2
  ```

  ```javascript Back to defaults theme={null}
  !level spec reset
  ```
</CodeGroup>

The formula is:

```
xp needed for level N  =  base × N^factor
```

rounded up to the nearest 10. With the defaults — base `100`, factor `1.2`, gain `10–18` XP per message — the curve looks like:

| Level | XP for that level | Messages (approx) |
| ----- | ----------------- | ----------------- |
| 1     | 100               | \~7               |
| 5     | 690               | \~50              |
| 10    | 1,590             | \~114             |
| 25    | 4,760             | \~340             |
| 50    | 10,940            | \~782             |
| 100   | 25,120            | \~1,794           |

<AccordionGroup>
  <Accordion title="Making it faster" icon="gauge-high">
    Raise the gain, or lower base and factor:

    ```javascript theme={null}
    !level spec gain 20 35
    !level spec base 75
    ```
  </Accordion>

  <Accordion title="Making it a real grind" icon="mountain">
    Raise the factor. Small changes matter a lot — `1.5` is dramatically steeper than `1.2` by level 50:

    ```javascript theme={null}
    !level spec factor 1.5
    !level spec base 150
    ```
  </Accordion>

  <Accordion title="Capping progression" icon="flag-checkered">
    ```javascript theme={null}
    !level max 100
    ```

    Members stop gaining XP at that level. Aliases: `maxlevel`, `maximum`.
  </Accordion>
</AccordionGroup>

## Multipliers

Give a role bonus XP:

<CodeGroup>
  ```javascript Double XP for boosters theme={null}
  !level multiplier 2 @Booster
  ```

  ```javascript 3.6× for VIPs theme={null}
  !level multiplier 3.6 @VIP
  ```

  ```javascript List them theme={null}
  !level multiplier list
  ```

  ```javascript Remove theme={null}
  !level multiplier remove @Booster
  ```
</CodeGroup>

Aliases: `multipliers`, `multi`, `mp`, `x`.

### Effort boost

```javascript theme={null}
!level effort 25
!level effort cooldown 300
```

Grants extra XP for longer messages — `25` means +25%. The cooldown prevents someone farming it by posting essays back to back. Alias: `boost`. Remove it with `!level effort remove`.

## Blacklisting

<CodeGroup>
  ```javascript A channel theme={null}
  !level blacklist #spam
  ```

  ```javascript A member theme={null}
  !level blacklist @someone
  ```

  ```javascript A role theme={null}
  !level blacklist @Muted
  ```

  ```javascript View theme={null}
  !level blacklist view
  ```

  ```javascript Clear theme={null}
  !level blacklist clear
  ```
</CodeGroup>

Toggles, so running it twice undoes it. Aliases: `ignore`, `block`, `bl`.

<Tip>
  Blacklist your bot-command channels, spam channels and counting channels. Otherwise the leaderboard measures who spams commands the most, which isn't what you're trying to reward.
</Tip>

## Manual adjustments

```javascript theme={null}
!level set @someone 25
!level set xp @someone 5000
```

Requires **Manage Server**. Setting the level recalculates their XP to match.

## Reviewing everything

```javascript theme={null}
!level settings
```

Shows whether levelling is on, the channel, the cooldown, the curve, the multipliers, the reward roles and the blacklist.

## Command reference

| Command                              | Permission            | Description              |
| ------------------------------------ | --------------------- | ------------------------ |
| `level [member]`                     | —                     | View level and XP        |
| `leaderboard`                        | —                     | Top members              |
| `level toggle (on/off)`              | Manage Server         | Enable or disable        |
| `level role add <level> <role>`      | Manage Server + Roles | Add a reward             |
| `level role remove <level>`          | Manage Server + Roles | Remove a reward          |
| `level role list`                    | —                     | View rewards             |
| `level role stack`                   | Manage Server + Roles | Keep lower rewards       |
| `level sync`                         | Manage Server         | Backfill missing rewards |
| `level channel [channel]`            | Manage Channels       | Where messages go        |
| `level message <script>`             | Manage Server         | Customise the message    |
| `level message view`                 | Manage Server         | Preview it               |
| `level message roles`                | Manage Server         | Only announce rewards    |
| `level message remove`               | Manage Server         | Reset to default         |
| `level cooldown <seconds>`           | Manage Server         | Between messages         |
| `level spec base <base>`             | Manage Server         | Base XP value            |
| `level spec factor <factor>`         | Manage Server         | Curve steepness          |
| `level spec gain <min> <max>`        | Manage Server         | XP per message           |
| `level spec reset`                   | Manage Server         | Restore defaults         |
| `level max <level>`                  | Manage Server         | Cap progression          |
| `level multiplier <mp> <role>`       | Manage Server         | Role XP multiplier       |
| `level multiplier list`              | —                     | View multipliers         |
| `level multiplier remove <role>`     | Manage Server         | Remove one               |
| `level effort <percentage> [length]` | Manage Server         | Bonus for long messages  |
| `level effort cooldown <seconds>`    | Manage Server         | Effort boost cooldown    |
| `level blacklist [target]`           | Manage Server         | Toggle a blacklist entry |
| `level blacklist view`               | Manage Messages       | View the blacklist       |
| `level blacklist clear`              | Manage Messages       | Clear it                 |
| `level set <member> <level>`         | Manage Server         | Set a level manually     |
| `level set xp <member> <xp>`         | Manage Server         | Set XP manually          |
| `level settings`                     | Manage Server         | Full overview            |