rewards

Every board reward is one file in rewards/. The file name (without .yml) is the reward id. After adding or editing one, run /miraclecubeadmin reload.

These are the rewards a player hunts on the board. The consolation prizes paid out for a miss are a different thing and live in config.yml → Random-Rewards. A walkthrough is in Creating Rewards.

Only .yml files directly in rewards/ are read. The folder is extracted from the jar only when it does not exist, so deleted default rewards stay deleted.

A reward file

rewards/epic-crate-key.yml

Enabled: true
Order: 6
Stage: 10
Display:
  Material: TRIPWIRE_HOOK
  Name: "&f&lx1 &3| &b&lEpic Crate Key"
  Glow: true
Commands:
  - "crates key give {player} epic 1"

Key	Default	Description
Enabled	true	false removes it from the select menu, deletes any saved board for it and clears it from anyone who had it selected.
Order	0	Select menu sort key, ascending. Ties are broken by id, ignoring case.
Stage	1	The stage multiple this reward unlocks on. Raised to at least 1. See the stage gate.
Display	required	The icon shown in the select menu and revealed on a win. A missing section fails the load.
Commands	[]	Run when the player finds the hidden cube. See commands.

Default rewards

File	Order	Stage	Pays
t1-orbs-pouch.yml	1	1	pouches give {player} orbs_t1 1
t1-gems-pouch.yml	2	1	pouches give {player} gems_t1 1
236-title.yml	3	25	titles give {player} 236
goat-title.yml	4	40	titles give {player} goat
rare-crate-key.yml	5	5	crates key give {player} rare 1
epic-crate-key.yml	6	10	crates key give {player} epic 1
monthly-crate-key.yml	7	50	crates key give {player} monthly 1

Retarget the commands at your own plugins before going live.

The stage gate

A reward is selectable when the player’s stage is a multiple of its Stage. It is a recurring multiple, not a one-time threshold.

Stage: 1    →  every stage (players start at stage 1)
Stage: 5    →  stages 5, 10, 15, 20, ...
Stage: 25   →  stages 25, 50, 75, ...

Locked rewards still appear in the menu, with the Lore-Addons.Locked lines appended and {stage} / {required} filled in. Clicking one sends REWARD-LOCKED and flashes the Locked temporary icon.

The gate is checked when a reward is selected. A board the player already started is kept while the reward is locked, and resumes when it becomes selectable again.

Display fields

Display:
  Material: PLAYER_HEAD
  Base64: "e3RleHR1cmVzOntTS0lOOnt1cmw6..."
  Name: "&b&lMystery Reward"
  Lore:
    - "&7A very rare drop."
  Glow: true
  Custom-Model-Data: 0

Field	Default	Description
Material	required	Any material name. An unknown name fails the load.
Base64	""	Head texture value. Only use it with PLAYER_HEAD; a texture on any other material is an error when the icon is shown.
Name	the id	Display name. Also what {reward} shows in messages and on the board’s Selected-Reward-Item.
Lore	[]	Lore lines. The select menu appends the matching Lore-Addons block after these.
Glow	false	Adds an enchant glint.
Custom-Model-Data	0	0 leaves it unset.

Reward icons take only these six fields. The {stage} and {required} tokens work in Name and Lore in the select menu; PlaceholderAPI placeholders are not resolved here.

The %optimalmiraclecubes_reward% placeholder returns the Name with all formatting stripped, so it is safe to drop into a scoreboard.

Commands

Run when the player finds the hidden cube. {player} is replaced with their name.

Commands:
  - "crates key give {player} monthly 1"
  - "broadcast &e{player} &7completed a miracle board!"
  - "[fragments] 25"

Line	Does
[fragments] <amount>	Credits the player’s fragment balance directly. No command is run. The amount must be a whole number.
anything else	Run as a console command.

The payout runs at the animation reveal. If the player closes the menu (or logs out) mid-animation, it is paid out on the spot instead, so a win can never be dropped.

What happens on a win

1. The spin lands on the reward’s icon and the REWARD-WON sound plays.
2. The stage goes up by one, that reward’s board is deleted and the selection is cleared. This is saved to the database straight away.
3. Commands run.
4. REWARD-WON is sent, with its screen title.
5. Further cube clicks are refused until Reveal-Ticks ends, then the select menu opens.

The winning cube is never written as opened, so an interrupted animation leaves the board fully winnable.

Ordering and the slot limit

The select menu fills its Reward-Slots list with enabled rewards in Order sequence. If you have more enabled rewards than slots, the extras are simply not shown - widen Reward-Slots in guis/select-menu.yml when you add rewards.

Validation

Checked on load and on every reload; these fail loudly with the reward id in the console:

• A reward file with no Display section
• An invalid Material in Display

Two files can’t share an id because the id is the file name. Rewards that share an Order fall back to alphabetical order by id.