# 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


---

# 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.drakodevelopment.net/economy-and-engagement/leveling.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.