> For the complete documentation index, see [llms.txt](https://edseries-plugins.gitbook.io/p/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://edseries-plugins.gitbook.io/p/codexmomentum/momentum/levels.md).

# Levels

The `levels:` section of `config.yml` defines the momentum ladder. Define as many levels as you want — numbered `1, 2, 3, ...` with no gaps. Every field except `blocks` is optional.

## Level fields

**`blocks`**

* **Required.** How many blocks of progress are needed to **reach** this level from the previous one.

**`boosters`**

* Any number of live boosters held **while at this level** (PinnaPrison only — see [Boosters](/p/codexmomentum/momentum/boosters.md)).

**`multiplier-display`**

* The text shown by `{multiplier}` and `%codexmomentum_multiplier%` while at this level. If unset, `placeholders.no-multiplier` is shown instead.

**`bossbar`**

* `name` and/or `color` override for this level — see [Boss Bar](/p/codexmomentum/momentum/bossbar.md).

**`effects`**

* Fired once when the level is **reached**: `title`, `subtitle`, `sound`, `particles`, and a `commands` list of console commands (`{player}` is replaced with the player's name). Anything not set falls back to the `visuals.level-up` defaults. See [Visual Effects](/p/codexmomentum/momentum/visuals.md).

**`aura`**

* A continuous particle aura worn while **holding** the level. See [Visual Effects](/p/codexmomentum/momentum/visuals.md).

**`decay-blocks-per-second`**

* Drain-speed override while at this level (defaults to `decay.blocks-per-second`).

## Example

```yaml
levels:
  5:
    blocks: 340                 # 340 weighted blocks to go from level 4 to 5
    boosters:
      - type: currency
        currency: tokens
        multiplier: 0.25        # +25% Tokens income
      - type: all-enchants
        multiplier: 0.05        # +5% proc chance on every enchant
    multiplier-display: '&#FFDE59+25% Tokens &8│ &#D9A6FF+5% Enchants'
    bossbar:
      name: '&#C77DFF&l⛏ MOMENTUM &8[&#E3BDFF&lV&8] &f{progress}&7/&f{required} &8│ {multiplier}'
      color: PURPLE
    effects:
      title: '&#C77DFF&l⚡ MOMENTUM V'
      subtitle: '&7Halfway to the apex &8│ {multiplier}'
      sound: UI_TOAST_CHALLENGE_COMPLETE;1;1
      particles:
        type: ELECTRIC_SPARK
        count: 60
        offset: 1.0
        speed: 0.4
      commands:
        - 'say {player} reached Momentum V!'
```

## Default ladder

The shipped config defines 10 levels with a color heat ramp (green → gold → purple → pink → red, amber APEX at the top):

| Level | Blocks | Boosters                                     |
| ----- | ------ | -------------------------------------------- |
| I     | 40     | +5% Tokens                                   |
| II    | 80     | +10% Tokens                                  |
| III   | 140    | +15% Tokens, +5% Gems                        |
| IV    | 220    | +20% Tokens, +10% Gems                       |
| V     | 340    | +25% Tokens, +15% Gems, +5% Enchants         |
| VI    | 500    | +30% Tokens, +20% Gems, +8% Enchants         |
| VII   | 720    | +35% Tokens, +25% Gems, +10% Enchants        |
| VIII  | 1,000  | +40% Tokens, +30% Gems, +12% Enchants        |
| IX    | 1,350  | +50% Tokens, +35% Gems, +15% Enchants        |
| X     | 1,800  | +60% Tokens, +45% Gems, +20% Enchants (APEX) |

Level V and X ship with special level-up effects, and level X wears a continuous `SOUL_FIRE_FLAME` aura.

{% hint style="warning" %}
The default booster currencies (`tokens`, `gems`) are PinnaPrison currency ids — make sure they match the currencies configured on your server, or replace them with your own.
{% endhint %}