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

# Menus (GUIs)

Every chest menu is a file in `plugins/EdCosmetics/guis/`. They are written once and never overwritten, so edit them freely; `/edcosmetics reload` applies the changes. Delete a file to get the default back on the next start.

| File                     | Opened by                                                                                                     |
| ------------------------ | ------------------------------------------------------------------------------------------------------------- |
| `cosmetics.yml`          | `/cosmetics`: one entry per category                                                                          |
| `cosmetics-category.yml` | `/cosmetics <category>` and clicking a category; shared by every category (a category can set its own `gui:`) |
| `emotes.yml`             | `/emotes` with `menus.emotes: gui`                                                                            |

You can add your own menus too: any `guis/<id>.yml` opens with the `open-gui <id>` action, or with its own command.

## Menu format

```yaml
title: '&8Cosmetics'
rows: 5                      # 1-6
open-sound: 'BLOCK_NOTE_BLOCK_PLING 0.6 1.6'   # '' = none
main-menu: ''                # menu opened when this one is closed, '' = none
item-click-cooldown: 0       # seconds between clicks on one slot
update-interval: 0           # ticks between refreshes of the whole menu, 0 = never
commands:                    # optional commands that open this menu
  main: { command: 'mymenu', aliases: [], permission: '' }

pagination:                  # lists (categories, cosmetics, emotes)
  source: 'edcosmetics-categories'
  slots: '10-16,19-25'
  always-show-arrows: false
  previous-page: { slot: '39', material: ARROW, name: '&b&lPrevious Page' }
  next-page:     { slot: '41', material: ARROW, name: '&b&lNext Page' }
  entry:                     # how one entry looks (some lists have more, see below)
    material: '{material}'
    name: '{name}'
    lore: ['{description}']

items:
  filler:
    material: BLACK_STAINED_GLASS_PANE
    slot: '0-9,17,18,26-44'
    name: '&r'
    hide-tooltip: true
  shop:
    slot: '40'
    material: GOLD_INGOT
    name: '&6&lShop'
    requirement: '%player_level% >= 5'
    click-sound: 'UI_BUTTON_CLICK 0.5 1.2'
    left-click-actions:
      - 'close'
      - 'player shop'
```

### Item keys

`slot` (`'4'`, `'0-8,17'`), `material`, `amount`, `name`, `lore`, `glow`, `custom-model-data`, `item-model` (`namespace:key`), `tooltip-style`, `hide-tooltip`, `color` (leather / potion colour), `requirement`, `click-sound`, `update-interval`, and the click lists `left-click-actions`, `right-click-actions`, `shift-left-click-actions`, `shift-right-click-actions`, `any-click-actions` (`click-actions` works as `any-click-actions`).

`material` can be a material, `head-<player>`, `texture-<base64>`, `itemsadder:namespace:id`, `oraxen:id` or `nexo:id`.

### Texts and conditions

Texts take `&` / `&#RRGGBB` / `<#RRGGBB>` / `<gradient:...>` / `<rainbow>`, `{tokens}` and `%placeholders%`.

* `requirement: '<condition>'` shows the item only while the condition holds.
* A lore line `'[if <condition>] text'` only shows while the condition holds.
* Conditions: `= != < > <= >=`, compared as numbers when both sides are numbers, as text otherwise (case-insensitive), e.g. `{state} = locked`, `%player_level% >= 5`. A condition with no operator holds unless it is empty, `false` or `0`.

### Actions

| Action                           |                                      |
| -------------------------------- | ------------------------------------ |
| `message <text>`                 | chat message to the player           |
| `broadcast <text>`               | chat message to everyone             |
| `actionbar <text>`               | action bar message                   |
| `title <title>;<subtitle>`       | title                                |
| `player <command>`               | the player runs a command            |
| `console <command>`              | the console runs a command           |
| `sound <SOUND> [volume] [pitch]` | plays a sound                        |
| `close`                          | closes the menu                      |
| `open-gui <menu>`                | opens `guis/<menu>.yml`              |
| `equip <category> <cosmetic>`    | equips a cosmetic the player has     |
| `unequip [category]`             | takes off a category (or everything) |
| `open-category <category>`       | opens a category's menu              |
| `emote <emote>`                  | plays an emote                       |

`{player}` and every token of the menu work inside actions.

## Lists and tokens

**cosmetics.yml**: source `edcosmetics-categories`. Tokens: `{category}` (id) `{name}` `{description}` `{material}` `{type}` `{unlocked}` `{total}` `{equipped}` (equipped cosmetic's name) `{has-equipped}` (true / false). Item type `edcosmetics-unequip` takes everything off.

**cosmetics-category.yml**: source `edcosmetics-cosmetics`, entries `equipped-entry`, `unlocked-entry`, `locked-entry` (missing ones fall back to `entry`). Clicking an unlocked cosmetic equips it, clicking the equipped one takes it off, shift-click withdraws a voucher.

* Menu tokens (anywhere in the file): `{category}` `{category-name}` `{description}` `{unlocked}` `{total}` `{equipped}`.
* Entry tokens: `{id}` `{name}` `{description}` `{material}` `{item-model}` (hats and wings: their model, for the icon) `{preview}` (what it looks like: the viewer's name in the colour, the tag, the glow colours, the size, the message) `{state}` (equipped / unlocked / locked) `{permission}` `{withdrawable}` `{limited}` `{limited-lore}` `{limited-max}` `{limited-count}` `{limited-left}`.
* Item type `edcosmetics-unequip` takes off the category. Item type `edcosmetics-view` switches between the unlocked cosmetics and all of them (unless the category has `show-locked: false`); its `custom-item.showing-all` section is how it looks while everything is shown.

**emotes.yml**: source `edcosmetics-emotes` (favourites first), entries `favourite-entry`, `unlocked-entry`, `locked-entry`. Left click plays, right click toggles a favourite. Tokens: `{id}` `{name}` `{state}` `{favourite}` `{favourites}` (favourites on) `{loop}` `{length}`. Item type `edcosmetics-stop-emote` stops the emote being played (hidden while none plays).

Custom item types go in a `custom-item:` section:

```yaml
  view:
    custom-item:
      type: 'edcosmetics-view'
      showing-all: { material: ENDER_EYE, name: '&b&lShowing Everything' }
    slot: '50'
    material: ENDER_PEARL
    name: '&b&lShow Locked Cosmetics'
```