> 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/pinnaprison/core/leveling.md).

# Leveling

A **leveling track** is a progression bar that costs a currency to level up and gives rewards at milestones. Each track is one file in `leveling/<id>.yml` — the filename is the track **id**. You can create unlimited tracks.

Leveling differs from [currencies](/p/pinnaprison/core/currencies.md): a currency is a spendable balance, while a leveling track is a single number that goes **up** by spending a currency, hands out rewards, and gates content (enchants, attributes, rebirth).

## Default tracks

| Id             | Name          | Levelled with                                                    |
| -------------- | ------------- | ---------------------------------------------------------------- |
| `pickaxelevel` | Pickaxe Level | `pickaxexp`                                                      |
| `rankup`       | Rankup        | `rankupxp`                                                       |
| `rebirth`      | Rebirth       | (driven by the [rebirth](/p/pinnaprison/core/rebirth.md) system) |

## Leveling file

`leveling/rankup.yml`:

```yaml
display-name: 'Rankup'
starting-level: 1
max-value: 1000
automatic-leveling: true

rewards:
  for-each:
    - "message &aYou have reached &frankup level %pinnaprison_notation_{level}%&a."
  specific:
    4:
      - "message level 4"
  interval:
    5:
      - "console crate givekey {player} common 1"

cost:
  currency: rankupxp
  starting-cost: 100
  increase-cost-by: 50
  remove-currency: true

bar:
  amount: 20
  completed: "&e┃"
  uncompleted: "&c┃"

commands:
  main: { permission: '', command: rankup, aliases: [] }
  balance: { permission: '', balance-other-permission: 'pinnaprison.balance.others' }
  give: { permission: 'pinnaprison.balance.give' }
  set: { permission: 'pinnaprison.balance.set' }
  remove: { permission: 'pinnaprison.balance.remove' }
```

| Key                                 | Description                                                                                                                                 |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `display-name`                      | The track's display name.                                                                                                                   |
| `starting-level`                    | The level new players start at.                                                                                                             |
| `max-value`                         | The maximum level.                                                                                                                          |
| `automatic-leveling`                | `true` = the player levels up automatically as soon as they can afford it. `false` = they must run the command / click the GUI to level up. |
| `cost.currency`                     | The currency spent to level up.                                                                                                             |
| `cost.starting-cost`                | The cost of the first level up.                                                                                                             |
| `cost.increase-cost-by`             | Added to the cost for each level.                                                                                                           |
| `cost.remove-currency`              | `true` = consume the currency on level up (a spend). `false` = the level just requires you to **have** that much.                           |
| `bar.amount`                        | Number of segments in the progress bar.                                                                                                     |
| `bar.completed` / `bar.uncompleted` | The filled / empty bar segments.                                                                                                            |

## Rewards

Three reward triggers, each a list of [action lines](/p/pinnaprison/customization/item-format.md#actions):

| Section                | When it runs                                      |
| ---------------------- | ------------------------------------------------- |
| `rewards.for-each`     | On **every** level up. `{level}` = the new level. |
| `rewards.specific.<n>` | When the player reaches level `<n>`.              |
| `rewards.interval.<n>` | Every `<n>` levels (5, 10, 15, …).                |

## Commands

Each track exposes a command named after `commands.main.command` (e.g. `/rankup`):

| Command                                        | Description                             |
| ---------------------------------------------- | --------------------------------------- |
| `/<track>`                                     | Open the level GUI or level up.         |
| `/<track> balance [player]`                    | Check your (or another player's) level. |
| `/<track> give\|set\|remove <player> <amount>` | Admin level management.                 |
| `/<track> help`                                | Command help.                           |

## Placeholders

```
%pinnaprison_leveling_balance_<id>%            -> current level
%pinnaprison_leveling_balance_<id>_formatted%  -> 1.5k
%pinnaprison_leveling_bar_<id>%                -> the progress bar
%pinnaprison_leveling_progress_<id>%           -> progress %
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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://edseries-plugins.gitbook.io/p/pinnaprison/core/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.