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

# leveling

`leveling.yml` controls trainer progression. StellarSkills levels are separate from Minecraft levels and Pokemon levels.

## Main settings

| Field                         | Meaning                                                                    |
| ----------------------------- | -------------------------------------------------------------------------- |
| `enabled`                     | Enables the leveling system                                                |
| `title`                       | Player-facing progression title                                            |
| `currency`                    | Currency awarded by level rewards; must exist                              |
| `starting-level`              | Starting trainer level, normally 1                                         |
| `maximum-level`               | Trainer level ceiling; supported safety ceiling 100000                     |
| `starting-experience`         | Initial stored XP; choose consistently with the starting level             |
| `announce-level-up`           | Player level-up feedback                                                   |
| `broadcast-milestones`        | Public milestone broadcasts                                                |
| `legacy-direct-point-sources` | Enables legacy direct currency earning; leave false for level-based points |

## Curve calculation

Let `n = current level - starting level`. These formulas describe **XP needed to advance one level**, not cumulative XP:

| `curve.type`  | Formula before global multiplier/clamps                             |
| ------------- | ------------------------------------------------------------------- |
| `linear`      | `base-requirement + linear-growth × n`                              |
| `power`       | `(base-requirement + linear-growth × n) × (n + 1)^(power - 1)`      |
| `exponential` | `base-requirement × exponential-growth^n + linear-growth × n`       |
| `table`       | Corresponding table entry; last entry repeats if the table runs out |

`curve.overrides` is keyed by the **level being left**: `9: 900` means level 9 to level 10 costs 900 XP. An explicit table entry also takes precedence over the formula. Overrides and table entries receive requirement clamps but do not receive `global-multiplier`; formula values do. The first table entry applies at `starting-level`.

`minimum-requirement` and a positive `maximum-requirement` clamp the advance cost. Formula results are rounded to whole XP. The total XP floor for a level is the sum of prior advance costs.

## Point rewards

```yaml
skill-point-rewards:
  points-per-level: 1
  bonus-every-levels: 5
  bonus-points: 1
  milestones:
    10: 2
    25: 4
    50: 8
```

These rewards **add**. Reaching level 10 in this example grants 1 base point + 1 periodic bonus + 2 milestone points = 4 points. The starting level itself does not grant a level reward. Currency caps can limit what is credited.

The persisted highest-level ledger prevents repeat point rewards after XP is lowered or curves change. Lowering a level does not automatically remove already-earned/spent points. On reload, a changed curve recalculates levels; only newly reached historical highs can produce new level rewards.

## Automatic XP tasks

The `sources` map is separate from quests. Packaged IDs include `capture`, `hatch`, `evolve`, `wild_win`, `apricorn`, `berry`, `pokemon_xp`, `mob_kill`, `block_break`, `dynamax_raid_win`, `tera_raid_win`, `anomaly_capture`, `anomaly_cure`, `trade`, `fish`, `fossil`, `heal_team`, `move_learn`, and `ride`. Anomalies require the matching external producer. Arbitrary new source IDs require server integration code to call the API; naming one does not create an event handler.

| Source field                                                                         | How to configure it                                                                 |
| ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| `enabled`                                                                            | Allow this source to award XP                                                       |
| `base-xp`                                                                            | Base award per event unit                                                           |
| `multiplier`                                                                         | Multiplies base units plus flat bonus                                               |
| `flat-bonus`                                                                         | Flat addition before multiplier                                                     |
| `pokemon-level-bonus`                                                                | Additional XP per Pokemon level, after the base multiplier                          |
| `shiny-multiplier`, `legendary-multiplier`, `mythical-multiplier`, `boss-multiplier` | Multiply when the server event supplies that flag; multiple matching flags compound |
| `minimum-award`, `maximum-award`                                                     | Positive values floor/cap the rounded award; zero omits that bound                  |
| `cooldown-ticks`                                                                     | Per-player/source delay; 20 ticks is roughly one second at full TPS                 |
| `daily-xp-cap`                                                                       | Persistent source cap resetting by UTC date; zero is uncapped                       |
| `require-unique`                                                                     | Requires the producer's uniqueness key; still test your event's repeat behavior     |
| `minimum-player-level`, `maximum-player-level`                                       | Eligible trainer-level range                                                        |

The base formula is `(base-xp × event units + flat-bonus) × multiplier`, then Pokemon-level bonus, matching rarity multipliers, rounding, and award bounds. Award modifiers from installed integrations can also affect the result. Quest rewards do not use these source formulas or source daily caps.

Cooldown/recent-key guards live in server memory; persistent transaction and daily ledgers provide additional protection. Do not describe every source's uniqueness flag as a permanent blacklist of all targets. Farming rewards still need cooldowns, caps, filters, and real-world testing.

## Quest-only progression

Disable automatic sources that you do not want. Leave quests enabled and give them `reward.xp`. Remove unwanted Journey direct currency rewards, class starting grants, and currency-paying node effects. Leave `legacy-direct-point-sources: false`. Administrative grants remain available for recovery.

Quest XP stops at the configured maximum-level floor. Administrative/direct XP pathways are distinct; lifetime/current XP can differ. Inspect `/skills level` when balancing.

## In-game authoring

Run `/skills admin progression-editor`, or use Progression in a tree editor.

{% stepper %}
{% step %}

### Levels & Rewards

Edit the curve and points.
{% endstep %}

{% step %}

### XP Tasks

Edit sources.
{% endstep %}

{% step %}

### Quests & Stories

Edit quests.
{% endstep %}

{% step %}

### Preview & Issues

View calculated requirements and validation.
{% endstep %}
{% endstepper %}

Every typed field has help. Save Draft is not Publish.

See the [full leveling defaults](file:///4985688/reference/leveling.md) and [migration guide](file:///4985688/operations/storage-and-migration.md).