> 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/pinnapass/reference/menus.md).

# Menus (GUIs)

Every menu is a file in `plugins/PinnaPass/guis/`, written once and never overwritten: edit it freely and run `/pinnapass reload`. Delete a default file to get it back on the next start.

| File           | Opened by                      | Type                                 |
| -------------- | ------------------------------ | ------------------------------------ |
| `pass.yml`     | `/pass`                        | `pass`: the tier track               |
| `quests.yml`   | `/pass quests`                 | `quests`: the quest slots            |
| `infinite.yml` | `/pass infinite` (owners only) | `infinite`: the Infinite Pass levels |

Any other `guis/<id>.yml` is a menu too: open it with the `open-gui <id>` action, `/pinnapass open <player> <id>` or its own `commands:`.

## Menu format

```yaml
type: ''                     # pass | quests | infinite | '' (a plain menu)
title: '&8Season Pass &8» &5Tier {tier}'
rows: 6
update-interval: 0           # ticks between automatic redraws (0 = never)
main-menu: ''                # opened when this menu is closed
sounds:
  open: 'block.ender_chest.open 0.5 1.3'
  click: 'ui.button.click 0.4 1.4'
  claim: 'entity.player.levelup 0.7 1.6'   # a claim / purchase went through
  error: 'entity.villager.no 0.6 1.0'      # it was refused
commands:                    # optional commands that open this menu
  main: { command: 'rewards', aliases: [], permission: '' }
filler:                      # every empty slot (or `slots`)
  material: BLACK_STAINED_GLASS_PANE
  name: '&r'
  hide-tooltip: true
text-bar: { length: 20, filled: '&d▮', empty: '&8▮' }   # the {bar} of this menu
items:
  close:
    slot: 49                 # '4', '0-8,17' or a list
    material: BARRIER
    name: '&c&lCLOSE'
    lore: [ '&7Bye!' ]
    requirement: '{claimable} > 0'
    click-sound: 'ui.button.click 0.5 1.2'
    left-click-actions: [ 'close' ]
```

### Item keys

`slot` / `slots`, `material`, `amount`, `name`, `lore`, `glow`, `texture` (`self` = the viewer's head, or a base64 value), `custom-model-data`, `item-model`, `tooltip-style`, `hide-tooltip`, `color` (leather / potions), `requirement` (or `show-if`), `click-sound`, and the click lists `left-click-actions`, `right-click-actions`, `shift-left-click-actions`, `shift-right-click-actions`, `drop-click-actions`, `any-click-actions`.

`material` can be a material, `{icon}`, `head-<player>`, `texture-<base64>`, `itemsadder:ns:id`, `oraxen:id`, `nexo:id`.

### Texts and conditions

Texts take colours, `{tokens}` and `%placeholders%`. A lore line (or action) starting with `[if <condition>]` only shows (runs) while the condition holds; several `[if]` in a row must all hold. Conditions: `= != > >= < <=`, numbers compare as numbers. A token holding several lines (`{rewards}`, `{reward_lines}`) becomes several lore lines.

### Actions

| Action                                                                              |                                       |
| ----------------------------------------------------------------------------------- | ------------------------------------- |
| `close`                                                                             | closes the menu                       |
| `open-gui <id>` (also `menu`, `open`)                                               | opens another menu                    |
| `open-pass`, `open-quests`, `open-infinite`                                         | the configured pass menus             |
| `page <+1/-1/first/last/current/n>`                                                 | another page (`current` = your tier)  |
| `refresh`                                                                           | redraws the menu                      |
| `buy <gold/diamond/multiplier/infinite>`                                            | buys it with `economy.currency`       |
| `claim <all/free N/premium N/level N/infinite-all>`                                 | claims rewards                        |
| `reroll <category> <slot>`                                                          | swaps a quest (rules of its category) |
| `message`, `broadcast`, `actionbar`, `title <a>;<b>`, `sound <sound> [vol] [pitch]` | texts and sounds                      |
| `player <command>`, `console <command>`                                             | commands (`{player}`, `{uuid}`)       |

Actions may be written `[console] say hi` too.

## The pass menu (`type: pass`)

| Key                              |                                                                                           |
| -------------------------------- | ----------------------------------------------------------------------------------------- |
| `free-slots`, `premium-slots`    | one slot per tier of the page (`tiers.per-page`)                                          |
| `progress-bar`                   | `slots` + `filled` / `current` / `empty` pieces lit by progress through the tier          |
| `tier-markers`                   | `slots` + `locked` / `current` / `claimable` / `claimed` items (`amount-from-tier: true`) |
| `tier-items.<free/gold/diamond>` | base item, `lore-header`, `states.<locked/claimable/claimed/no-pass>`                     |

A reward item's lore is `lore-header` + the reward's `lore` from tiers.yml + the state's `lore`; a state overrides any key of its track (material, name, glow\...). Extra tokens: `{tier_number}`, `{tier_xp}`, `{icon}`, `{track}`, `{rewards}`. Clicking a claimable reward claims it. Items named `previous-page` / `next-page` only show when there is a page to go to; `infinite-locked` / `infinite-unlocked` show before / after the last tier.

## The quests menu (`type: quests`)

`quest-slots` (category → slots) and `quest-items.<in-progress/completed/expired/locked>`. Quest tokens: `{name}` `{description}` `{progress}` `{goal}` `{percent}` `{bar}` `{expires}` `{reward}` `{reward_lines}` `{category}` `{category_name}` `{icon}` `{index}` `{type}` `{reroll_cost}` `{can_reroll}` `{click_reroll}`.

## The Infinite menu (`type: infinite`)

`reward-slots`, `marker-slots`, `reward-line`, `progress-bar`, `reward-items.lore-header` + `reward-items.<locked/current/claimable/claimed>`, `level-markers.<state>`. Tokens `{level_number}`, `{next_level}`, `{level_first}`, `{level_last}`.

## Tokens of every menu

All the [placeholders](/p/pinnapass/reference/placeholders.md) without the `pinnapass_` part: `{tier}`, `{xp}`, `{needed}`, `{percent}`, `{bar}`, `{status}`, `{gold_status}`, `{claimable}`, `{total_multiplier}`, `{season}`, `{quests_daily_reset}`... plus `{page}` and `{pages}`.

## Resource-pack menus

Background pictures in the title, your own icons and tooltip frames, item models, the `counter` for numbers up to 9999 and an XP bar that fills pixel by pixel: see [Custom Textures & Resource-Pack Menus](/p/pinnapass/reference/custom-textures.md).