# Leveling

### Core Settings

#### ✅ Enabled

Turns the leveling system on or off.

```yaml
Enabled: true
```

***

#### ResetDataOnLeave

* `true` → User’s XP & levels reset when they leave.
* `false` → Progress is saved if they rejoin (recommended).

```yaml
ResetDataOnLeave: false
```

***

#### MessageXP & 🎙 VoiceXP

* Format: `min-max`
* Defines how much XP users earn for activity.

**Examples**

* MessageXP: `5-10`
* VoiceXP: `2-5`

**Recommendations**

* Small servers → Higher XP (e.g., `10-20`, `2-4`)
* Large servers → Lower XP (e.g., `5-10`, `1-2`)

***

#### XPNeeded

* Base XP needed to level up.
* Scales with each level (Level 2 = 300 XP, Level 3 = 600 XP, etc).

**Examples**

* Fast leveling → `200-250`
* Normal → `300-400`
* Slow (competitive) → `500-750`

```yaml
XPNeeded: 300
```

***

### Channel & Category Settings

Control where XP is earned:

```yaml
ChannelSettings:
  LevelUpChannelID: ""           # Leave empty to use current channel
  DisabledChannels: ["12345"]    # No XP in these channels
  DisabledCategories: ["67890"]  # No XP in these categories
```

***

### XP Cooldown

Cooldowns prevent spam and balance XP gain.

```yaml
CooldownSettings:
  EnableXPCooldown: true
  XPCooldown: "30s"   # Message XP cooldown
  VoiceInterval: "60s" # How often voice XP is given
```

**Recommendations**

* Message cooldown → `30s–60s`
* Voice interval → `60s–120s`

***

### Level-Up Messages

Customize the message or embed shown when a user levels up.

**Available placeholders**

* `{user}` → Mention user
* `{userName}` → Username only
* `{userId}` → Discord ID
* `{userIcon}` → Profile picture
* `{userBanner}` → Banner image
* `{guildName}` → Server name
* `{oldLevel}` / `{newLevel}` → Levels
* `{oldXP}` / `{newXP}` → XP progress
* `{randomLevelMessage}` → Pulls from `lang.yml`

**Example (simple message):**

```yaml
LevelUpMessage: "{user}, you are now level {newLevel}"
UseEmbed: false
```

**Example (embed):**

```yaml
UseEmbed: true
Embed:
  Title: "🎉 Level Up!"
  Description:
    - "{userName} just reached level {newLevel}!"
    - "{randomLevelMessage}"
  Thumbnail: "{userIcon}"
  Color: "#eda3f0"
```

***

### Role Rewards

Give roles when users hit certain levels.

#### StackRoles

* `true` → Users keep all unlocked level roles (Level 1, 5, 10).
* `false` → User only has the highest level role.

**Example:**

```yaml
RoleSettings:
  StackRoles: true
  LevelRoles:
    - level: 1
      roleID: "ROLE_ID"
    - level: 5
      roleID: "ROLE_ID"
```

***

### Coin Rewards (Economy Integration)

Reward coins at specific levels.

* `+1` → Every level
* `+5` → Every 5 levels
* `25` → Exactly level 25

**Example:**

```yaml
ScaleRewards:
  StackRewards: false
  Rewards:
    - level: +1
      coins: 10
```

***

### Rank Card Customization

Your rank card can be styled with colors, progress bars, and emojis.

```yaml
RankCard:
  AccentColor: "#1769FF"
  SecondaryColor: "#4785FF"
  ProgressBar:
    StartColor: "#1769FF"
    EndColor: "#4785FF"
  Emojis:
    Level: "✧"
    TopRank: "♚"
    NormalRank: "★"
```

***

### Quick Setup Examples

* **Casual Server (fast leveling)**
  * MessageXP: `10-20`
  * VoiceXP: `2-4`
  * XPNeeded: `200`
* **Competitive Server (slow leveling)**
  * MessageXP: `5-8`
  * VoiceXP: `1-2`
  * XPNeeded: `500`
* **Community Server (balanced)**
  * MessageXP: `8-15`
  * VoiceXP: `1-3`
  * XPNeeded: `300`

***

### Commands

#### 👥 User Commands

* `/rank` → View your rank card
* `/rank @user` → View someone else’s rank
* `/leaderboard` → Show server leaderboard

#### 🔧 Admin Commands *(requires Permission roles)*

* `/level give @user 5` → Add XP
* `/level take @user 3` → Remove XP
* `/level set @user 10` → Set user’s level
* `/level reset @user` → Reset progress