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

# Leveling System

> Configure XP rewards, rank cards, and role progression for your server.

# Leveling System

Veronica's leveling system rewards active members with XP, custom rank cards, and automatic role assignments. This guide covers setup, configuration, and customization options.

## Overview

The leveling system includes:

* **Automatic XP Gain**: Earn XP by sending messages
* **Custom Rank Cards**: Personalized level-up displays
* **Role Rewards**: Auto-assign roles at specific levels
* **Leaderboards**: Track top contributors

<Info>
  The leveling system is **enabled by default** and tracks activity across all text channels.
</Info>

## Basic Commands

<CodeGroup>
  ```bash View Rank theme={null}
  # Check your current level and XP
  /rank
  ,rank

  # Check another user's rank
  /rank user:@Member
  ,rank @Member
  ```

  ```bash Leaderboard theme={null}
  # View server leaderboard
  /leaderboard
  ,leaderboard
  ```

  ```bash Set Level theme={null}
  # Moderators: Set a user's level
  /setlevel user:@Member level:10
  ,setlevel @Member 10
  ```
</CodeGroup>

## XP Configuration

### Earning Rates

Configure how users gain experience:

| Activity                | XP Gain  | Cooldown   |
| :---------------------- | :------- | :--------- |
| Text Message            | 15-25 XP | 60 seconds |
| Voice Chat (per minute) | 5-10 XP  | None       |
| Reactions               | 1-3 XP   | 30 seconds |

<Note>
  XP values are randomized within the range to prevent gaming the system.
</Note>

### XP Multipliers

Boost XP gain for specific roles or channels:

<CodeGroup>
  ```bash Role Multiplier theme={null}
  # Give boosters 2x XP
  /xpmultiplier role:@Booster multiplier:2.0
  ```

  ```bash Channel Multiplier theme={null}
  # Increase XP in specific channels
  /xpmultiplier channel:#active-chat multiplier:1.5
  ```
</CodeGroup>

## Role Rewards

Automatically assign roles when members reach specific levels:

<Steps title="Reward Configuration Workflow">
  <Step title="Establish Thresholds">
    Set up roles for different level milestones (e.g., Level 5, Level 10, Level 25).
    <Check>Roles created in Server Settings.</Check>
  </Step>

  <Step title="Map Level Roles">
    Link roles to level thresholds using the command suite.

    ```bash theme={null}
    /levelrole add level:5 role:@Active Member
    /levelrole add level:10 role:@Regular
    /levelrole add level:25 role:@Veteran
    ```

    <Check>Role mapping successfully stored.</Check>
  </Step>

  <Step title="Validate Hierarchy">
    Ensure Veronica can manage these roles.
    <Check>Veronica's role is positioned above reward roles.</Check>
  </Step>

  <Step title="Verification Test">
    Use `/setlevel` to test role assignments at different levels.
    <Check>Auto-assignment confirmed via audit logs.</Check>
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Card Customization" icon="palette" href="/configuration/leveling#rank-card-customization">
    Design unique rank cards for your community.
  </Card>

  <Card title="Economy Integration" icon="coins" href="/configuration/economy">
    Combine leveling with virtual rewards.
  </Card>
</CardGroup>

<Warning>
  Ensure Veronica's role is **above** the reward roles in your server's role hierarchy, or it won't be able to assign them.
</Warning>

## Rank Card Customization

Personalize your rank card appearance:

<CodeGroup>
  ```bash Set Background theme={null}
  # Upload custom background image
  /rankcard background [image_url]
  ```

  ```bash Set Color theme={null}
  # Change accent color
  /rankcard color #FF5733
  ```

  ```bash Reset Card theme={null}
  # Return to default design
  /rankcard reset
  ```
</CodeGroup>

## Leaderboard Features

<CardGroup cols={2}>
  <Card title="Server Leaderboard" icon="trophy">
    View top 10 members by XP in your server.

    ```bash theme={null}
    /leaderboard
    ```
  </Card>

  <Card title="Global Leaderboard" icon="globe">
    See top contributors across all servers.

    ```bash theme={null}
    /globalleaderboard
    ```
  </Card>
</CardGroup>

## Advanced Configuration

<AccordionGroup>
  <Accordion title="Disable Leveling in Channels">
    Prevent XP gain in specific channels (e.g., spam channels):

    ```bash theme={null}
    /leveling ignore channel:#spam
    ```
  </Accordion>

  <Accordion title="Level-Up Announcements">
    Configure where level-up messages are sent:

    ```bash theme={null}
    /leveling announce channel:#level-ups
    /leveling announce disable
    ```
  </Accordion>

  <Accordion title="XP Decay">
    Enable XP loss for inactive members:

    ```bash theme={null}
    /leveling decay enable days:30 percent:10
    ```
  </Accordion>

  <Accordion title="Import/Export Data">
    Migrate leveling data from other bots:

    ```bash theme={null}
    /leveling import [file]
    /leveling export
    ```
  </Accordion>
</AccordionGroup>

## Level Calculation

XP required for each level increases exponentially:

```
Level 1: 100 XP
Level 2: 255 XP
Level 3: 475 XP
Level 5: 1,225 XP
Level 10: 5,525 XP
Level 25: 33,525 XP
Level 50: 133,525 XP
```

**Formula**: `XP = 5 * (level^2) + (50 * level) + 100`

## Best Practices

<CardGroup cols={2}>
  <Card title="Balanced Progression" icon="chart-line">
    Set role rewards at achievable intervals (every 5-10 levels) to maintain engagement.
  </Card>

  <Card title="Exclusive Perks" icon="star">
    Give high-level roles access to exclusive channels or features.
  </Card>

  <Card title="Regular Recognition" icon="megaphone">
    Announce level milestones in a dedicated channel to celebrate achievements.
  </Card>

  <Card title="Fair Multipliers" icon="equals">
    Keep XP multipliers reasonable (1.5x-2x max) to avoid imbalance.
  </Card>
</CardGroup>

<Tip>
  Combine the leveling system with economy rewards: give Vero Bucks to users who reach certain levels!
</Tip>