# 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 |