Creating Rewards

There are two kinds of reward in OptimalMiracleCubes, and they live in different places:

Kind	Where	Won by
Board reward	one file in rewards/	Finding the hidden cube. Advances the stage.
Consolation prize	Random-Rewards in config.yml	Decrypting any wrong cube.

Both are config, not commands. You need optimalmiraclecubes.admin to reload.

1. Add a board reward

Create a file in plugins/OptimalMiracleCubes/rewards/. The file name (without .yml) is the reward id.

rewards/legendary-crate-key.yml

Enabled: true
Order: 8
Stage: 100
Display:
  Material: TRIPWIRE_HOOK
  Name: "&f&lx1 &3| &b&lLegendary Crate Key"
  Lore:
    - "&7The rarest key on the server."
    - " "
  Glow: true
Commands:
  - "crates key give {player} legendary 1"
  - "[fragments] 25"

Field	Description
Enabled	false hides it from the select menu and removes any saved board for it.
Order	Sort key for the select menu, ascending. Ties are broken by id.
Stage	The stage multiple the reward unlocks on. See below. Minimum 1.
Display	The icon: Material, optional Base64, Name, Lore, Glow, Custom-Model-Data.
Commands	Run on a win. Console commands with {player}, or [fragments] <amount>.

Only files directly inside rewards/ are read; subfolders are ignored. Full field list: rewards reference.

2. Pick the stage gate

Stage is a multiple, not a minimum. A reward is selectable when the player’s stage divides evenly by it.

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

This makes big rewards recurring milestones instead of one-off unlocks. Each win raises the stage by exactly one, so a player at stage 24 who wins any hunt reaches stage 25 and can then pick a Stage: 25 reward. At stage 26 it is locked again until stage 50.

Keep at least one Stage: 1 reward enabled. Otherwise a player whose stage matches no reward has nothing to select and no way to advance.

A locked reward still shows in the menu with the Lore-Addons.Locked lines appended. Clicking it sends REWARD-LOCKED, plays the deny sound and flashes the Locked temporary icon.

3. Make room in the select menu

The select menu only has as many reward spots as Reward-Slots lists in guis/select-menu.yml. The default is a 3x3 grid, so nine rewards. Enabled rewards fill the slots in Order; rewards past the last slot are not shown at all.

The seven default rewards plus the one above make eight, so this fits. For a tenth reward, add slots:

Reward-Slots: [11-15, 20-24, 29-33]

Move the Barrier-Item glass in the same file to the same slots, so empty reward spots still show glass instead of the black background.

4. Reload

/miraclecubeadmin reload

The reward appears in the select menu immediately. Test the gate with /miraclecubeadmin stage <you> 100 and give yourself fragments with /miraclecubeadmin fragments give <you> 500.

Consolation prizes

Every wrong cube pays one weighted pick from Random-Rewards in config.yml. Their icons are also what the spin animation cycles through, so keep a few visually distinct ones.

Random-Rewards:
  Fragments-Small:
    Weight: 40
    Display:
      Material: PRISMARINE_SHARD
      Name: "&b&lx3 &3&lFragments"
    Commands:
      - "[fragments] 3"
  Money-Small:
    Weight: 25
    Display:
      Material: EMERALD
      Name: "&a&l$10,000"
    Commands:
      - "eco give {player} 10000"

The key (Fragments-Small) is just an id. Weight is relative, not a percentage: the roll is bounded by the sum of every weight. The Display.Name is what RANDOM-REWARD-WON shows as {reward}.

The section must contain at least one entry, or the plugin fails to load.

Paying out fragments

Both board rewards and consolation prizes accept [fragments] <amount> in Commands. It credits the player’s fragment balance directly instead of running a command:

Commands:
  - "[fragments] 5"
  - "eco give {player} 25000"

Refunding some fragments on a miss is the usual way to soften a long hunt. The amount must be a whole number; a typo such as [fragments] five only fails when that reward is paid out, so test new entries.

Notes

• Disable without deleting: Enabled: false removes the reward from the menu and deletes the saved boards for it the next time each player opens /miraclecube. If it was a player’s selection, the selection is cleared.
• Deleting a reward file has the same effect as disabling it.
• One board per reward. A player can chip away at several hunts and switch between them with the Selected Reward button on the board. Switching costs nothing.
• A missing Display section or an invalid material fails the load with the reward id printed to console.
• Commands run from console, so anything you can do from console you can hand out. Nothing is given directly by the plugin except [fragments].