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

# Menus (GUIs)

Both menus are regular PinnaPrison GUI files, written once to `plugins/PinnaPrison/guis/pinnablockselector/` (`config.yml` → `gui`) and then yours to edit. Run `/pinnaprison reload` after editing them. Every item takes PinnaPrison's usual options (`material`, `head-<name>` / `texture-<base64>` heads, `name`, `lore`, `glow`, `amount`, `color`, `requirement`, `update-interval`, `click-sound`, click actions...) and lore lines may start with `[if <condition>]` to show only when the condition holds, e.g. `'[if {selected} = 0] &7Nothing chosen'`.

To get a fresh default menu, delete (or rename) the file and restart the server.

## blockselector.yml (the selector)

Window tokens (usable in the title and every item): `{category}` (open category id), `{category-name}`, `{page-number}`, `{total-pages}`, `{player}`.

### Block entries

`pagination.source: 'pinnablockselector-blocks'` lists the blocks of the open category in the `pagination.slots`. Each block uses the section of its state:

| Section          | When                                                                                                    |
| ---------------- | ------------------------------------------------------------------------------------------------------- |
| `selected-entry` | the block is in the choice being edited                                                                 |
| `locked-entry`   | a category [permission](/p/pinnablockselector/features/categories.md#rank-only-blocks) the player lacks |
| `full-entry`     | the choice is full                                                                                      |
| `entry`          | otherwise                                                                                               |

Tokens: `{material}` (material id, use it as `material: '{material}'`), `{name}` (e.g. "Oak Planks"), `{position}` (its place in the choice), `{selected}`, `{max}`, `{status}` (selected blocks: `status-applied` or `status-pending` of the pagination section) and `{requirement}` (locked blocks: the category's `locked-text`). Leave `name` out of these sections so every player sees the block's name in their own game language.

### Item types

Use them as `custom-item: { type: '<type>', ... }`:

| Type                                                | What it does                                                                  | Options                                                                                                                           | Tokens                                                                                    |
| --------------------------------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `pinnablockselector-selected`                       | one choice slot; click removes the block. Hidden for slots above `max-blocks` | `index` (1, 2...), `empty` (item shown while free), `status-applied`, `status-pending`, `vanilla-name` (default true)             | `{material}` `{name}` `{position}` `{status}` `{selected}` `{max}`                        |
| `pinnablockselector-info`                           | summary of the player's mine                                                  | `mode-custom`, `mode-tier`, `changes-yes`, `changes-no`, `cooldown-ready`, `block-line`, `no-blocks-line`                         | `{selected}` `{max}` `{applied}` `{blocks}` `{mode}` `{changes}` `{changed}` `{cooldown}` |
| `pinnablockselector-apply`                          | applies the choice                                                            | `changed` (item while there are changes), `cooldown` (changes but cooling down), `cooldown-ready`, `block-line`, `no-blocks-line` | `{selected}` `{max}` `{blocks}` `{cooldown}`                                              |
| `pinnablockselector-clear`                          | empties the edited choice                                                     | `empty` (item while nothing is chosen)                                                                                            | `{selected}` `{max}`                                                                      |
| `pinnablockselector-category`                       | filter button: left click next category, right click previous                 | `line`, `line-selected`, `line-locked`                                                                                            | `{category}` `{icon}` `{count}` `{categories}`                                            |
| `pinnablockselector-category` with `category: <id>` | a tab for one category                                                        | `selected` (item while it is open)                                                                                                | `{name}` `{icon}` `{count}` `{locked}`                                                    |

`{blocks}` becomes one lore line per block (`block-line` with `{position}` and `{name}`, or `no-blocks-line`). Give the info and apply items `update-interval: 20` so the cooldown counts down while the menu is open (the defaults do).

With `max-blocks` above 4, add more `pinnablockselector-selected` items with `index: 5`, `6`... in free slots.

### Category tabs instead of the filter button

```yaml
  tab-ores:
    custom-item:
      type: 'pinnablockselector-category'
      category: 'ores'
      selected:
        material: '{icon}'
        glow: true
        name: '&b&l{name} &8({count})'
        lore: ['&a&l✔ &aShowing']
    slot: '46'
    material: '{icon}'
    name: '&7{name} &8({count})'
    lore: ['&3[ᴄʟɪᴄᴋ ᴛᴏ sʜᴏᴡ]']
```

## blockselector-buy.yml (the purchase menu)

Opened while the Block Selector is locked. Tokens: `{price}`, `{currency}`, `{balance}` (the player's balance of that currency), `{can-afford}` (`true` / `false`, for `[if {can-afford} = true]` lines) and `{max}`.

| Type                     | What it does                                                                                          | Options                                             |
| ------------------------ | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| `pinnablockselector-buy` | buys the unlock, then opens the selector. A failed purchase keeps the menu open and the chat says why | `cannot-afford` (item while the balance is too low) |

## The /mine button

`pinnablockselector-button` works in any PinnaPrison menu: it opens the selector when unlocked, else the purchase menu. Add it to `plugins/PinnaPrison/guis/mine.yml` (slot 15 is free in PinnaPrison's default mine menu):

```yaml
  block-selector:
    custom-item:
      type: 'pinnablockselector-button'
      block-line: '&3 | &f#{position} &b{name}'
      no-blocks-line: '&3 | &7Your mine tier''s blocks'
      locked:
        material: GRASS_BLOCK
        name: '&b&lBlock Selector'
        lore:
          - '&7Choose the blocks your mine'
          - '&7is made of.'
          - ' '
          - '&3 | &bStatus: &cLocked'
          - '&3 | &bPrice: &f{price} {currency}'
          - ' '
          - '&3[ᴄʟɪᴄᴋ ᴛᴏ ᴜɴʟᴏᴄᴋ]'
    slot: 15
    material: GRASS_BLOCK
    glow: true
    name: '&b&lBlock Selector'
    lore:
      - '&7Choose the blocks your mine'
      - '&7is made of.'
      - ' '
      - '&3 | &bBlocks in use: &f{applied}&8/&7{max}'
      - '{blocks}'
      - ' '
      - '&3[ᴄʟɪᴄᴋ ᴛᴏ ᴏᴘᴇɴ]'
```

Tokens: `{price}` `{currency}` `{balance}` `{can-afford}` `{max}`, `{applied}` (blocks on the mine now) and `{blocks}`. The `locked` section is drawn while the player hasn't unlocked it.

Both default menus go back to `mine` (`main-menu: 'mine'` and the Back / Cancel buttons): change those if your mine menu has another id.

## Resource-pack menus

Background pictures in the title, your own button icons, tooltip frames and values drawn with your pack: see [Custom Textures & Resource-Pack Menus](/p/pinnablockselector/reference/custom-textures.md).