> 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/customization/guis.md).

# GUIs

Every menu is a file in `guis/`, all sharing one format:

```yaml
title: '&8&nPets &7({page-number}/{total-pages})'
rows: 6
open-sound: 'ENTITY_BAT_TAKEOFF'
main-menu: ''            # gui id to return to on close ('' = none)
item-click-cooldown: 0   # seconds between clicks on the same slot
update-interval: 0       # ticks between live refreshes of dynamic items (0 = off)

items:
  filler:
    material: BLACK_STAINED_GLASS_PANE
    name: '&7'
    slot: '0-8'          # single slots, lists or ranges
  my-button:
    custom-item: { type: 'open-gui', gui: 'upgrades' }
    material: EXPERIENCE_BOTTLE
    slot: 45
    name: '&a&lUpgrades'
    lore: [...]
    requirement: '%edpets_equipped% >= 1'   # hide the item when false
    left-click-actions: ['sound ENTITY_PLAYER_LEVELUP']
```

Items use the standard [Item Format](/p/edpets/customization/item-format.md); every button supports `left/right/shift-left/shift-right/any-click-actions` lists run through the [action system](/p/edpets/customization/actions.md), plus a `requirement` condition.

## Pagination

```yaml
pagination:
  source: 'pets'         # a registered paged source
  mode: 'equip'          # source-specific option (pets: equip/bin/fusion/delete/select)
  filter: 'all'          # pets: all / stored / active
  slots: '9-35'
  previous-page: { slot: 48, material: ARROW, name: '&c&l<- Previous' }
  next-page: { slot: 50, material: ARROW, name: '&a&lNext ->' }
```

Paged sources: **`pets`** (the player's pets — the `mode` decides what clicking a pet does) and **`presets`**.

Dropping a **candy, scroll or rune** held on the cursor onto a pet entry applies it — pets menus allow vanilla cursor pickup in your own inventory for exactly this.

## Custom item types

Set `custom-item.type` to give a button behavior:

| Type               | Extra keys                                      | Behavior                                                                                                                                |
| ------------------ | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `open-gui`         | `gui`                                           | Opens another configured GUI                                                                                                            |
| `pets-action`      | `action`                                        | `fusion-confirm`, `fusion-quick`, `bin-confirm`, `bin-quick`, `delete-confirm`, `toggle-pets`, `sort-cycle`, `save-preset`              |
| `pets-sort`        | `modes`, `selected-format`, `unselected-format` | The sorting button — lists every mode in the `{modes}` lore placeholder, highlighting the selected one; clicking cycles in config order |
| `upgrade`          | `upgrade`, `refund`                             | An upgrade entry (buy or refund mode) — renders the upgrade's own display item                                                          |
| `upgrade-toggle`   | `upgrade`, `toggle: enabled\|messages`          | Toggle an upgrade / its proc messages (`{status}` placeholder)                                                                          |
| `pet-selector`     | `return-gui`                                    | The "selected pet" slot for boosts/enhancements/mastery                                                                                 |
| `boost-roll`       | `boost: all\|level\|buff\|experience`           | Rolls boosts on the selected pet                                                                                                        |
| `enhancement-roll` | —                                               | Rolls an enhancement on the selected pet                                                                                                |
| `mastery-prestige` | —                                               | Prestiges the selected pet (rich placeholders)                                                                                          |
| `display-mode`     | `mode`                                          | Selects a pet formation (`{selected}` placeholder)                                                                                      |
| `bulk-delete-tier` | `tier`                                          | Deletes all STORED pets of a tier (`{amount}` placeholder)                                                                              |
| `preset-icon`      | `icon` (optional)                               | An icon choice in the preset icon selector                                                                                              |

## Shipped menus

`main-menu`, `upgrades`, `upgrade-refunds`, `fusion`, `bin`, `bulk-delete`, `boosts`, `enhancements`, `enhancements-preview`, `mastery`, `presets`, `preset-icons`, `display-modes`, `pet-selection`, plus the backpack menus `backpack` / `backpack-upgrades` (rendered by the backpack module but configured in the same folder).