menus

Both menus are files in guis/. You can retheme them freely: titles, sizes, backgrounds, buttons and the cube items themselves. After editing, run /miraclecubeadmin reload.

File	Menu
select-menu.yml	The reward selection menu. Opens from /miraclecube when nothing is selected, and after a win.
board-menu.yml	The cube board. Opens once a reward is selected.

Like config.yml, these files are read exactly as written. An item you delete stays deleted.

How a menu file works

The root holds Title, Size (a multiple of 9), an Items section, a slot list naming where the dynamic content goes (Reward-Slots or Cube-Slots) and an optional Temporary-Icons section.

Every entry in Items is a menu item with a position:

• Slot: - a single slot number, from 0.
• Slots: - a list where each entry is a number or an a-b inclusive range.

An entry with neither is never painted. A slot outside Size fails the load with the menu title and slot in the console.

Items without Actions are plain decoration. Items with an Actions list run them on click. The entry keys (Filler-Item, Selected-Reward-Item) are only names, so you can rename and move items freely.

Paint order: the item with the most slots is painted first, and when two items share a slot the one with fewer slots wins. A full-size filler therefore never covers a button. Reward icons and cubes are painted last, on top of everything, and their slots take clicks before any item.

select-menu.yml

Title: "Select Miracle Reward"
Size: 45
Reward-Slots: [12-14, 21-23, 30-32]

Items:
  Filler-Item:
    Material: BLACK_STAINED_GLASS_PANE
    Slots: [0-44]
    Name: "&r"
  Barrier-Item:
    Material: GLASS_PANE
    Slots: [12-14, 21-23, 30-32]
    Name: "&r"

Temporary-Icons:
  Locked:
    Material: BARRIER
    Name: "&c&lError!"
    Lore:
      - "&7This reward unlocks every &f{required} &7stages!"

Reward-Slots is filled with the enabled rewards in Order sequence. The list length is the cap - rewards past it are not shown, so widen it when you add rewards. The default 3x3 grid holds nine.

The glass Barrier-Item sits under exactly the reward slots, so an unused reward spot shows glass instead of the black background. Move it when you move Reward-Slots.

Each reward icon is the reward’s Display with the matching Lore-Addons block appended. Clicking an unlocked reward selects it, plays REWARD-SELECTED and opens its board. Clicking a locked one sends REWARD-LOCKED, plays DENY and flashes the Locked icon.

Where	Tokens
Items entries	{stage}, {fragments}
Reward icons and Lore-Addons	{stage}, {required}
Temporary-Icons.Locked	{stage}, {required} (of the clicked reward)

board-menu.yml

Title: "Miracle Cubes"
Size: 54
Cube-Slots: [10-16, 19-25, 28-34, 37-43]

Encrypted-Cube:
  Material: PLAYER_HEAD
  Base64: "e3RleHR1cmVzOntTS0lOOnt1cmw6..."
  Name: "&b&lEncrypted Cube"
  Lore:
    - "&7Decrypt this miracle cube"
    - "&7to reveal a hidden reward."
    - " "
    - "&3 - &bPrice: &f{price} Fragments"
    - " "
    - "&e➥ Click to decrypt!"

Decrypted-Cube:
  Material: NETHER_STAR
  Name: "&e&lDecrypted Cube!"
  Glow: true
  Lore:
    - "&7You already claimed this cube."

Items:
  Filler-Item:
    Material: BLACK_STAINED_GLASS_PANE
    Slots: [0-3, 5-9, 17, 18, 26, 27, 35, 36, 44-53]
    Name: "&r"

  Selected-Reward-Item:
    Material: ENDER_CHEST
    Slot: 4
    Name: "&b&lSelected Reward"
    Lore:
      - "&7Your selected reward is hidden"
      - "&7somewhere on the miracle board."
      - " "
      - "&bInformation:"
      - "&3 - &7Reward: &f{reward}"
      - "&3 - &7Balance: &b{fragments} &3Fragments"
      - " "
      - "&e➥ Click to reselect!"
    Actions:
      - "[reselect]"

Temporary-Icons:
  Insufficient-Fragments:
    Material: BARRIER
    Name: "&c&lError!"
    Lore:
      - "&7You need &f{price} Fragments &7for this!"
  Decryption-Pending:
    Material: BARRIER
    Name: "&c&lError!"
    Lore:
      - "&7Please wait for the current decryption to finish!"

Key	Description
Cube-Slots	The board. Its length is the number of cubes (28 by default), and the hidden reward is stored as a position in this list.
Encrypted-Cube	Required. The item shown for a cube not yet decrypted. Root level, not under Items.
Decrypted-Cube	Required. The item shown for an opened cube. Root level, not under Items.
Items	Background and buttons. Selected-Reward-Item with [reselect] lets the player switch hunts.
Temporary-Icons	The icons flashed on a refused cube click. See below.

Tokens on Items entries, both cube items and the temporary icons: {reward} (the selected reward’s name), {fragments} (the balance, comma-grouped) and {price}. Items are repainted when a decrypt starts and after a consolation prize is paid, so the balance stays current.

Resizing Cube-Slots

Because the hidden cube is a position in the list, shrinking the list can leave a saved board pointing past the end. Such a board is rolled again from scratch (opened cubes cleared) the next time the player opens it. Boards that still fit keep their opened cubes. Growing the list is safe, but a saved board’s opened cubes stay at the same positions in the list, so reordering the slots moves them.

Clicking cubes

Outcome	Behaviour
Not enough fragments	INSUFFICIENT-FRAGMENTS, the DENY sound and the Insufficient-Fragments flash. Nothing is charged.
Already decrypted	Nothing happens.
Cube already spinning	Nothing happens.
Wrong cube	Price charged, cube marked opened, CUBE-DECRYPT sound, spin, consolation prize revealed and paid, then the Decrypted-Cube item after Reveal-Ticks.
Right cube	Price charged, spin, reward revealed and paid, stage up, board deleted, then the select menu opens after Reveal-Ticks.
Any cube while a win is revealing	DECRYPTION-PENDING, the DENY sound and the Decryption-Pending flash.

Several wrong-cube spins can run at once. Closing the menu stops the visuals and pays every pending prize immediately.

Temporary-Icons

Icons that flash for two seconds in the clicked slot when a click is refused, then restore the real item. While a slot is flashing, clicks on it are ignored, so the deny sound can’t be spammed. Each one is optional: remove it and that refusal just plays the sound and sends its message.

Key	File	Flashed when
Locked	select-menu.yml	A reward the player’s stage does not unlock is clicked.
Insufficient-Fragments	board-menu.yml	A cube is clicked without enough fragments.
Decryption-Pending	board-menu.yml	A cube is clicked while a winning reveal is still playing.

Item fields

Menu items, the two cube items, temporary icons and the Display of consolation prizes all use the same item format. The common fields:

Field	Default	Description
Material	required	Any material name. An unknown name fails the load.
Amount	1	Stack size.
Name	""	Display name. "&r" gives a blank name for fillers.
Lore	[]	Lore lines.
Base64	""	Head texture, for PLAYER_HEAD only. "{player}" shows the viewer’s own head.
Custom-Model-Data	0	0 leaves it unset.
Item-Model	none	An item model key, for resource packs.
Glow	false	Adds an enchant glint.
Item-Flags	[]	Bukkit item flags such as HIDE_ATTRIBUTES.

Names and lore resolve the menu’s tokens and, with PlaceholderAPI, %...% for the viewer. The menu Title is plain text and takes no tokens.

Actions

Items in Items can carry an Actions list. They run in order on click.

Action	Does
[reselect] / [select] / [open-select]	Open the reward select menu.
[board] / [open-board]	Open the board of the selected reward (or the select menu when nothing is selected).
[command] <cmd>	Run <cmd> as console.
[console] <cmd>	Run <cmd> as console.
[player] <cmd>	Run <cmd> as the player.
[message] <text>	Send the player a chat message.
[broadcast] <text>	Send a message to everyone.
[actionbar] <text>	Show text on the player’s action bar.
[title] title;subtitle;in;stay;out	Show a screen title.
[sound] <sound>	Play a sound to the player.
[close]	Close the menu.

The argument is the text after ]. {player}, {uuid}, the menu’s own tokens and (with PlaceholderAPI) %...% are resolved in it.

The command action runs as console here

In these two menu files [command] is the same as [console]. A line without a [type] and an unknown type are ignored when clicked rather than failing the load.

The sounds both menus play live in config.yml, not in these files.