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 reward	`Random-Rewards` in `config.yml`	Decrypting any wrong cube.

You need optimalmiraclecubes.admin to reload.

1. Add a board reward

Create a file in plugins/OptimalMiracleCubes/rewards/. The file name is the reward id.

Enabled: true
Order: 8
Stage: 100
Display:
  Material: TRIPWIRE_HOOK
  Name: "&f&lx1 &3| &b&lLegendary Crate Key"
  Glow: true
Commands:
  - "crates key give {player} legendary 1"

Field	Description
`Enabled`	`false` hides it from the select menu and prunes any saved board for it.
`Order`	Sort key for the select menu, ascending. Ties 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`	Console commands run on a win. `{player}` is replaced. `[fragments] <n>` grants fragments instead of running a command.

Full field list: rewards reference.

2. Pick the stage gate

Stage is a multiple, not a minimum. A reward is selectable whenever currentStage % Stage == 0.

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 is deliberate: it makes big rewards recurring milestones instead of one-off unlocks. A reward the player can’t take yet still shows in the menu, with the Lore-Addons.Locked block appended and {stage} / {required} filled in.

The select menu only has as many reward slots as Reward-Slots lists in guis/select-menu.yml. Rewards past that count are not shown - add slots if you add rewards.

3. Reload

/miraclecubeadmin reload

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

Consolation rewards

Every miss 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"

Weight is relative, not a percentage - the roll is bounded by the sum. The section must contain at least one entry or the plugin fails to load.

Paying back fragments

Both board rewards and consolation rewards accept the internal action [fragments] <amount> in their Commands. It credits the player’s fragment balance directly rather than dispatching a command:

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

Refunding some fragments on a miss is the usual way to soften the cost of a long hunt. Tune it against Cube.Price and the board size.

Tuning the hunt

Three numbers set the pace:

Cube.Price - fragments per decrypt.
Board size - the length of Cube-Slots in guis/board-menu.yml. The default is 28 cubes, so an average hunt is about 14 decrypts.
Fragments.Chance / Min-Amount / Max-Amount - how fast fragments come in.

Roughly: average hunt cost = Cube.Price × (board size + 1) ÷ 2, minus whatever [fragments] you pay back on misses.

Notes

Disable without deleting: Enabled: false removes the reward from the menu and prunes saved boards for it. If it was a player’s active selection, the selection is cleared.
One board per reward. Switching selection saves the old board and resumes the new one. Players can chip away at several hunts in parallel.
The winning cube is never marked opened. If the animation is interrupted the board is still winnable.
A missing Display section or an invalid material fails the load with the reward id printed to console.