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 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, prunes any saved board for it and clears it from anyone who had it selected.
Order	0	Select-menu sort key, ascending. Ties broken by id, case-insensitive.
Stage	1	The stage multiple this reward unlocks on. Clamped 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	[]	Console commands run on a win.

The stage gate

A reward is selectable when currentStage % Stage == 0. 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 block appended and {stage} / {required} filled in. Clicking one sends REWARD-LOCKED and flashes the Locked temporary icon.

Winning a hunt raises the stage by exactly one, so what is selectable changes as players climb.

Display fields

The same item shape is used by Random-Rewards, the temporary icons and the menu files.

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; resolved through XSeries, so legacy and modern names both work. An unknown name fails the load.
Base64	""	Head texture value, applied when the material is a player head.
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.

Italics are stripped from names and lore automatically.

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

Commands

Run from console 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"

One internal action is understood in place of a command:

Action	Does
[fragments] <amount>	Credits the player’s fragment balance directly. No command is dispatched.

Everything else is dispatched as a console command. On Folia they are dispatched on the global thread, which means they land one tick after the reveal.

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

What happens on a win

1. Stage goes up by one and is flushed to the database straight away.
2. That reward’s board is deleted and the selection cleared.
3. Commands run.
4. REWARD-WON is sent, with its screen title.
5. When Reveal-Ticks elapses, the select menu reopens.

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 in Order sequence. If you have more enabled rewards than slots, the extras are simply not rendered - widen Reward-Slots in guis/select-menu.yml when you add rewards.

Validation

Checked on load and on every reload; these fail loudly rather than being skipped:

• A reward file with no Display section
• An invalid Material in Display
• An unreadable rewards/ folder

Two files can’t share an id because the id is the file name. If two rewards share an Order, they fall back to alphabetical order by id.