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

# Levels

> Reward members with roles and XP for staying active.

## Getting started

XP tracking is off until you turn it on. Nothing else on this page has any effect until you do.

```javascript theme={null}
,level unlock
```

Run `,level lock` to pause tracking without losing anyone's progress.

> [!NOTE]
>
> Members earn 15–25 XP per message, at most once a minute. Very short messages and emoji-only messages don't count. Levels go up to **100**.

## Ignoring channels and roles

Do this before members start earning. Any channel or role on the ignore list earns nothing, and threads follow their parent channel.

```javascript Syntax theme={null}
,level ignore add (channel or role)
```

```javascript Example theme={null}
,level ignore add #spam
,level ignore add @Muted
```

| Command | What it does |
| - | - |
| `,level ignore remove (channel or role)` | Take something back off the list |
| `,level ignore list` | See everything currently ignored |
| `,level ignore reset` | Clear the list |

## Reward roles

Assign a role to a level and members receive it when they get there.

```javascript Syntax theme={null}
,level add (role) (level)
```

```javascript Example theme={null}
,level add @Level5 5
```

> [!NOTE]
>
> Levels run from **1** to **100**. `,level update` behaves identically to `add`. Roles with dangerous permissions can't be rewards.

Remove a reward by its level, not its role:

```javascript Syntax theme={null}
,level remove (level)
```

```javascript Example theme={null}
,level remove 5
```

`,level roles` lists every reward.

### Stacking

With stacking on, members keep every role they've earned along the way. With it off, they only hold the role for their current tier.

```javascript Syntax theme={null}
,level stackroles (yes or no)
```

```javascript Example theme={null}
,level stackroles no
```

### Backfilling existing members

If your server already had XP before you set up rewards, `,level sync` walks every member and applies the roles their current level entitles them to.

> [!TIP]
>
> Run this after adding a new reward role so existing members at that level pick it up immediately.

## Level-up messages

```javascript Syntax theme={null}
,level message (text or embed code)
```

```javascript Example theme={null}
,level message congrats {user.mention} on hitting level {level.new_rank}!
```

Full embed syntax works — start with `{embed}` for a rich embed. See [Scripting](/resources/scripting). Besides the usual variables, you can use `{level.new_rank}` and `{level.user_xp}`.

`,level message view` shows what's currently set.

### Where it posts

```javascript Syntax theme={null}
,level messagemode (mode)
```

```javascript Example theme={null}
,level messagemode #level-up
```

| Mode | Behavior |
| - | - |
| `#channel` | Posts to that specific channel |
| `context` | Posts wherever the member was chatting |
| `pm` | Sends a DM instead |
| `none` | Turns level-up messages off entirely |

> [!WARNING]
>
> If you use `pm`, include `{guild.name}` in your message. Otherwise members get a DM with no indication which server it came from.

## XP rate

```javascript Syntax theme={null}
,level setrate (multiplier)
```

```javascript Example theme={null}
,level setrate 2.5
```

> [!NOTE]
>
> Must be between **0.1** and **10**.

## Viewing progress

Running `,level` on its own shows your level, server rank, XP toward the next level, and a progress bar. Add a member to see theirs:

```javascript theme={null}
,level financely
```

`,level leaderboard` ranks your top earners. You can rename the leaderboard heading:

```javascript Syntax theme={null}
,level leaderboard rename (text)
```

```javascript Example theme={null}
,level leaderboard rename misery XP Leaderboard
```

## Admin tools

| Command | What it does |
| - | - |
| `,level configuration` | Whether tracking is on, your XP rate, message mode, stacking, rewards, and ignores |
| `,level list` | Every member who has earned XP, with their level and total |
| `,setxp (member) (amount)` / `,setlevel (member) (level)` | Set someone's progress directly |
| `,removexp (member) (amount)` | Take XP away |
| `,level reset` | Clear every member's XP and levels, after a confirmation |
| `,level cleanup` | Drop level data for anyone no longer in the server — server owner only |

> [!NOTE]
>
> When a member leaves, their XP is kept for **3 days** in case they come back. After that it's removed automatically.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.