# Levelling

InviteCount includes a complete levelling system with XP, levels, message ranks, customizable level cards, and level-up announcements.

***

## How It Works

1. Members earn **2–5 XP** per message (randomized)
2. XP accumulates until the member reaches the next level threshold
3. A **level-up announcement** is sent (if configured)
4. Members can earn **role rewards** at specific message counts

### XP Formula

Each level requires a specific amount of XP to advance:

$$
XP\_{required} = 10 \times (level \oplus 2) + 50 \times level + 100
$$

Where $\oplus$ is the bitwise XOR operation.

### XP Rate & Cooldown

| Setting            | Default | Description                                 |
| ------------------ | ------- | ------------------------------------------- |
| `xp_rate`          | 1       | Multiplier applied to XP earned per message |
| `message_cooldown` | 1s      | Minimum time between messages that award XP |

These settings can be configured via the [dashboard](https://invite-count.xyz/dashboard).

***

## Enable/Disable Levelling

| Command         | Description                  |
| --------------- | ---------------------------- |
| `/leveling on`  | Enable the levelling system  |
| `/leveling off` | Disable the levelling system |

***

## Viewing Stats

| Command               | Description                               |
| --------------------- | ----------------------------------------- |
| `/level [@member]`    | Display a member's level card (image)     |
| `/messages [@member]` | Display messages count and next rank info |

***

## Level-Up Announcements

Configure where and what message is sent when a member levels up.

| Command                        | Description                              |
| ------------------------------ | ---------------------------------------- |
| `/leveling text <text>`        | Set the level-up announcement message    |
| `/leveling channel [#channel]` | Set a specific channel for announcements |

### Announcement Modes

| Mode            | Description                                                |
| --------------- | ---------------------------------------------------------- |
| Current channel | Message is sent in the channel where the member leveled up |
| Custom channel  | Message is sent in a configured channel                    |
| Private (DM)    | Message is sent as a DM to the member                      |
| Disabled        | No level-up announcement                                   |

### Level-Up Variables

| Variable           | Description                     |
| ------------------ | ------------------------------- |
| `{member}`         | Member's name and discriminator |
| `{member_name}`    | Member's name                   |
| `{member_mention}` | Member's mention                |
| `{member_id}`      | Member's Discord ID             |
| `{member_avatar}`  | Member's profile picture URL    |
| `{level}`          | Current level                   |
| `{next_level}`     | Next level (current + 1)        |
| `{previous_level}` | Previous level (current - 1)    |

***

## Message Ranks (Role Rewards)

Automatically assign roles when members reach a specific number of messages.

| Command                             | Description                     |
| ----------------------------------- | ------------------------------- |
| `/rank add <@role> <messages_need>` | Add a role reward at X messages |
| `/rank remove <@role>`              | Remove a role reward            |
| `/rank list`                        | List all message rank rewards   |

**Limits:** 10 ranks (free) / 500 ranks (premium).

### Reward Announcements

When a member earns a rank role, an announcement can be posted in a configured channel. This feature can be enabled via the [dashboard](https://invite-count.xyz/dashboard).

***

## Level Card

The `/level` command generates a personalized level card image showing:

* Profile picture and username
* Current level and XP progress bar
* Total messages and XP
* Rank position on the server
* User badges

### Card Customization

Level card appearance can be customized via the [dashboard](https://invite-count.xyz/dashboard):

| Setting            | Default   | Description                 |
| ------------------ | --------- | --------------------------- |
| Accent color       | `#593695` | Card accent color           |
| Progress bar color | `#593695` | Progress bar fill color     |
| Overlay color      | `#000000` | Card overlay color          |
| Background opacity | `0.4`     | Overlay opacity             |
| Text color         | `#E8E8E8` | Text color                  |
| Custom background  | *(none)*  | Custom background image URL |

***

## XP/Messages Exclusions

Exclude specific roles or channels from earning XP or counting messages. Configure these via the [dashboard](https://invite-count.xyz/dashboard):

| Setting              | Description                            |
| -------------------- | -------------------------------------- |
| No XP roles          | Roles that don't earn XP               |
| No XP channels       | Channels where XP is not earned        |
| No messages roles    | Roles whose messages aren't counted    |
| No messages channels | Channels where messages aren't counted |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.invite-count.xyz/features/levelling.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.