> 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/edpets/progression/upgrades.md).

# Upgrades

`upgrades.yml` is a **generic player-upgrade engine** — the shipped upgrades (XP Finder, XP Booster, Candy Finder, Level Cap, Box Finder, Fusion Master, Rarity Hunter) are just presets of four effect building blocks. Invent your own by combining them.

## Anatomy of an upgrade

```yaml
upgrades:
  xp-booster:
    enabled: true
    max-level: 100
    price: 5000
    price-increase: 100        # price grows per owned level
    economy:                   # internal currency OR external bridge — see Currencies
      currency: boost-tickets
    effects:
      xp-boost:
        percent-per-level: 0.5
    display:                   # the item in guis/upgrades.yml (item format)
      material: ENDER_EYE
      name: '&2&lXP Booster &a&lUpgrade'
      lore: [...]
    refund-display:            # the item in guis/upgrade-refunds.yml
      ...
```

Display placeholders: `{level}`, `{max}`, `{cost}`, `{currency}`, `{balance}`, `{chance-percent}` (proc upgrades), `{boost}` (xp-boost), `{amount}` (level-cap). Refund displays additionally get `{refund}` (what refunding one level returns) and `{refund-percentage}`.

## Effects

| Effect         | Keys                | Does                                              |
| -------------- | ------------------- | ------------------------------------------------- |
| `xp-boost`     | `percent-per-level` | +% pet XP on every gain                           |
| `level-cap`    | `levels-per-level`  | + max levels on ALL pets                          |
| `fusion-boost` | `percent-per-level` | +% fusion success chance                          |
| `proc`         | see below           | chance-based reward table rolled per grind action |

### Proc tables

```yaml
effects:
  proc:
    chance-base: 0.01          # percent chance per grind action at level 1
    chance-per-level: 0.01
    rewards:                   # weighted — one reward per proc
      xp:
        type: pet-xp           # pet-xp, candy, box, scroll, rune, command
        id: ''                 # the candy/box/scroll/rune id (or the command line)
        amount: 100-500
        weight: 1
        message: '&2&lXP Finder &8┣ &aYou found &f{amount} &apet XP!'
        sound: 'ENTITY_PLAYER_LEVELUP:1:2'
```

Procs roll while the player grinds with active pets. Reward `type: command` runs `id` as console with `{player}`/`{amount}`.

## Buying, refunding, toggling

* In `guis/upgrades.yml`: left-click +1, right-click +10, shift-left +100, **Q = max affordable**.
* Refunds (`guis/upgrade-refunds.yml`) return `settings.refunds.percentage`% of what was paid; disable with `settings.refunds.enabled: false`.
* Per-upgrade **toggles** (enabled while grinding) and **proc-message mutes** are GUI items — see [GUIs](/p/edpets/customization/guis.md).