> For the complete documentation index, see [llms.txt](https://docs.mongenscave.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mongenscave.com/premium-products/quests/features/level-system.md).

# Level System

The plugin has its own leveling system, completely separate from vanilla XP. Every player starts at level 1 and levels up by earning **quest XP**. The level is more than a number — it decides how many quests a player can hold, how big their daily board is, and which quests the board offers them.

### Earning XP <a href="#earning-xp" id="earning-xp"></a>

Quest XP comes from the `quest_xp` reward type. Add it to any quest and the player earns XP on completion:

```yaml
rewards:
  - type: quest_xp
    value: 250
```

Premium players earn more from the same quest — their XP multiplier (`premium.multipliers.xp`) is applied automatically. Admins can also grant XP directly with `/level addxp` (see below).

### The level curve <a href="#the-level-curve" id="the-level-curve"></a>

How much XP a level requires is controlled by two values in `config.yml`:

```yaml
leveling:
  base-xp: 100
  scale: 1.5
```

The formula for the XP needed to go from a level to the next one:

```
required XP = base-xp × level ^ scale
```

With the defaults, that looks like this:

| Level   | XP to next level |
| ------- | ---------------- |
| 1 → 2   | 100              |
| 2 → 3   | \~283            |
| 5 → 6   | \~1,118          |
| 10 → 11 | \~3,162          |
| 20 → 21 | \~8,944          |
| 50 → 51 | \~35,355         |

* **`base-xp`** shifts the whole curve up or down — double it and every level costs twice as much.
* **`scale`** controls how steep it gets. `1.0` is linear (level 10 costs 10× level 1), higher values make high levels progressively more expensive. Values between `1.2` and `1.8` are the practical range for most servers.

Leftover XP carries over: if a player needs 100 XP and earns 250, they level up and keep 150 toward the next level. A single large XP grant can trigger several level-ups at once — each level fires its own message, sound and rewards.

### Level-up rewards <a href="#level-up-rewards" id="level-up-rewards"></a>

When a player levels up, three things run, all configured under `leveling.level-up` in `config.yml`:

```yaml
leveling:
  level-up:
    commands:
      - "eco give {player} 50"

    rewards:
      default:
        commands:
          - "eco give {player} 100"

      levels:
        5:
          commands:
            - "give {player} diamond 1"
        10:
          commands:
            - "crate give {player} epic 1"
        20:
          commands:
            - "lp user {player} permission set quests.vip"
```

1. **The level-up message and sound** — configured in `messages.yml`.
2. **`commands`** — run on *every* level-up. Good for a small flat bonus.
3. **`rewards`** — either the milestone entry for the reached level (`levels.5`, `levels.10`, ...) or, if the level has no entry, the `default` one. A milestone **replaces** the default for that level, it doesn't stack on top of it.

All commands run from console and support two placeholders: `{player}` (player name) and `{level}` (the level just reached).

{% hint style="warning" %}
Leveling commands use `{player}`, not `%player%` — that syntax belongs to quest `command` rewards in `quests.yml`. Mixing them up leaves the placeholder unreplaced in the command.
{% endhint %}

### What the level affects <a href="#what-the-level-affects" id="what-the-level-affects"></a>

A player's level feeds back into almost everything:

| System                 | Effect                                                                                                                                 |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Daily board size       | `quests.daily-board.per-level` grants extra board slots as the level grows.                                                            |
| Daily board pool       | Only quests within `level-range` of the player's level can appear, and quests closer to their level are picked more often.             |
| Accepted/active limits | `quests.limits.max-accepted.per-level` and `max-active.per-level` raise the caps with level.                                           |
| Quest objectives       | The `level_up` and `gain_quest_xp` triggers let quests react to the leveling system itself ("reach a new level", "earn 500 quest XP"). |

See the [Daily Board](/premium-products/quests/features/daily-board.md) page for the exact math behind the per-level bonuses.

### Showing the level <a href="#showing-the-level" id="showing-the-level"></a>

* In the quest board GUI, the player head uses `{level}`, `{xp}`, `{xp-needed}` and `{progress}` (percentage toward the next level).
* Everywhere else, use the PlaceholderAPI placeholders — `%quests_level%`, `%quests_level_formatted%`, `%quests_xp%` — covered on the [Placeholders](file:///C:/Users/KomPhone/IdeaProjects/mc-Quests/docs/placeholders.md) page, including the level formatting rules (`MAX` labels, custom glyphs).

### Admin commands <a href="#admin-commands" id="admin-commands"></a>

All level commands require the `mcquests.admin.level` permission and work on offline players too:

| Command                                 | What it does                                                                                       |
| --------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `/level info [player]`                  | Shows level, XP and completed quest count.                                                         |
| `/level set <player> <level> <xp>`      | Sets level and XP in one go.                                                                       |
| `/level setlevel <player> <level>`      | Sets the level, keeps the XP.                                                                      |
| `/level addlevel <player> <amount>`     | Adds levels (can't go below 1).                                                                    |
| `/level removelevel <player> <amount>`  | Removes levels (can't go below 1).                                                                 |
| `/level setxp <player> <xp>`            | Sets the XP within the current level.                                                              |
| `/level addxp <player> <amount>`        | Adds XP — this goes through the normal XP pipeline, so it can trigger level-ups and their rewards. |
| `/level removexp <player> <amount>`     | Removes XP (can't go below 0).                                                                     |
| `/level setcompleted <player> <amount>` | Sets the completed-quest counter.                                                                  |
| `/level reset <player>`                 | Back to level 1 with 0 XP. The completed counter is kept.                                          |

{% hint style="info" %}
`/level addxp` is the only command that triggers level-ups, messages and rewards. The `set`/`setlevel`/`addlevel` commands change the values silently — use them for corrections, not for granting progress.
{% endhint %}