> 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/pinnagiveaways/features/menus.md).

# Menus (GUIs)

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

| File                           | Opened by                                                               |
| ------------------------------ | ----------------------------------------------------------------------- |
| `giveaways.yml`                | `/giveaway` (set `gui.enabled: false` to open the sponsor menu instead) |
| `giveaway-sponsor.yml`         | `/giveaway sponsor`, the Sponsor button                                 |
| `giveaway-sponsor-confirm.yml` | a preset, a typed amount, `/giveaway sponsor <amount>`                  |

The format is **PinnaPrison's menu format**, so a menu file can be copied between PinnaPrison and PinnaGiveaways. Any other `guis/<id>.yml` is a menu too: open it with the `open-gui <id>` action or its own `commands:`.

## Menu format

```yaml
title: '&8ɢɪᴠᴇᴀᴡᴀʏꜱ'
rows: 5
open-sound: 'BLOCK_ENDER_CHEST_OPEN'   # '' = none
main-menu: ''                          # opened when this menu is closed
item-click-cooldown: 0                 # seconds before the same slot can be clicked again
update-interval: 20                    # ticks between redraws (0 = never)
commands:                              # optional commands that open this menu
  main: { command: 'gw', aliases: [], permission: '' }
pagination:                            # an optional paged list
  source: 'pinnagiveaways-list'
  slots: '19-25'
  always-show-arrows: false
  previous-page: { slot: '36', material: ARROW, name: '&cPrevious' }
  next-page: { slot: '44', material: ARROW, name: '&aNext' }
  entry: { material: CHEST, name: '{name}', lore: [...] }
items:
  close:
    slot: '40'                         # '4', '0-8,17' or a list
    material: BARRIER
    name: '&c&lClose'
    requirement: '{participants} > 0'
    click-sound: 'UI_BUTTON_CLICK'
    left-click-actions: ['close']
    custom-item: { type: 'open-gui', gui: 'giveaways' }   # optional special behaviour
```

Items are drawn in file order (a later one wins a shared slot); an item whose `requirement` fails leaves its slot to what is under it. `gui.click-cooldown-ms` in config.yml ignores clicks of a player closer together than that, in every menu.

### Item keys

`material` (a material, `texture-<base64>` heads, `head-<player>` / `head-{player}`, `itemsadder:ns:id`, `oraxen:id`, `nexo:id`), `texture` (`self` or a base64 value, for `PLAYER_HEAD`), `amount`, `name`, `lore`, `glow`, `unbreakable`, `custom-model-data`, `item-model`, `tooltip-style`, `hide-tooltip`, `color` (leather / potions), `requirement`, `click-sound`, `update-interval`, and the click lists `left-click-actions`, `right-click-actions`, `shift-left-click-actions`, `shift-right-click-actions`, `drop-click-actions`, `any-click-actions`.

Texts take colours, `{tokens}` and `%placeholders%`. A lore line (or action) starting with `[if <condition>]` only shows (runs) while it holds: `= != > >= < <=`, numbers compare as numbers.

### Actions

The [reward actions](/p/pinnagiveaways/features/giveaways.md#rewards) (`message`, `console`, `give-eco`, `sound`...) plus `close`, `open-gui <id>` (also `open`, `menu`), `page <+1|-1|first|last|n>`, `refresh`, `giveaway-menu`, `giveaway-sponsor-menu`, `giveaway-sponsor <amount> [currency]`, `giveaway-sponsor-custom [currency]`, `giveaway-toggle`.

## Item types

| `custom-item.type`               |                                                                                                                             |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `open-gui` (`gui: <id>`)         | opens another menu                                                                                                          |
| `pinnagiveaways-info`            | `{next}` `{next-time}` `{participants}` `{eligible}` `{hidden}` `{sponsor-queue}`                                           |
| `pinnagiveaways-toggle`          | shows its `shown:` or `hidden:` sub-item and flips the animation on click                                                   |
| `pinnagiveaways-sponsor-open`    | the button to the sponsor menu (hidden when sponsoring is off or without permission)                                        |
| `pinnagiveaways-sponsor-info`    | `{balance}` `{currency-name}` `{min}` `{max}` `{tax}` `{min-players}` `{players}` `{queue}` `{queue-limit}` `{start-delay}` |
| `pinnagiveaways-sponsor-preset`  | `amount:`, optional `currency:` and `too-expensive:` sub-item; a click opens the confirm menu                               |
| `pinnagiveaways-sponsor-custom`  | optional `currency:`; closes the menu and asks for the amount in chat                                                       |
| `pinnagiveaways-sponsor-confirm` | pays and queues the amount waiting for confirmation                                                                         |

Preset and confirm tokens: `{amount}` `{amount-short}` `{formatted}` `{currency-name}` `{balance}` `{after}` `{prize}` (what the winner gets) `{prize-amount}` `{tax}` `{affordable}` `{sponsor}`.

The `pinnagiveaways-list` source lists every giveaway with the pagination's `entry` item (the giveaway's `icon` replaces its material). Tokens: `{id}` `{name}` `{prize}` `{time}` `{interval}` `{winners}` `{min-players}` `{last-winner}`.

Every menu also has `{player}`, `{uuid}`, `{page}` (0-based), `{page-number}` and `{total-pages}`. The giveaways and sponsor menus are redrawn every second while open.