Skip to content
BattleStudio

Information

OptimalMiracleCubes features, fragments, boards, stages, commands, permissions, placeholders and tokens in one reference.

BattleStudio plugin

OptimalMiracleCubes

Players earn fragments by mining, pick a reward and decrypt cubes on a board to find where it is hidden. Wrong cubes pay consolation prizes, the right one pays the reward.

Requires
Paper / FoliaMC 1.21.11+Java 21+OptimalLibrary
Buy on BuiltByBitInstallation guideGet support

OptimalMiracleCubes is a hunt. Players earn fragments by mining, pick a reward on /miraclecube, then spend fragments decrypting cubes on a board to find where that reward is hidden. A wrong cube pays a weighted consolation prize. The right cube pays the real reward, advances the player’s stage and wipes that reward’s board.

Rewards unlock on stage multiples, so the pool of things worth hunting changes as a player climbs.

How a board works

Section titled “How a board works”
  1. Fragments drop from mining (or any other enabled source) on a configurable chance.
  2. /miraclecube opens the select menu when nothing is selected. Picking an unlocked reward starts (or resumes) that reward’s board and opens it.
  3. The board menu is a grid of encrypted cubes. One of them hides the selected reward, and the player does not know which.
  4. Clicking a cube costs Cube.Price fragments and plays a short spin animation.
    • Wrong cube - one weighted Random-Rewards prize pays out at the reveal, and that cube stays decrypted for good.
    • Right cube - the reward’s Commands run, the stage goes up by one, that board is wiped, the selection is cleared and the select menu reopens.

Every reward keeps its own board. Switching your selection keeps the old board’s hidden cube and opened cubes, and resumes the new reward’s board exactly where you left it (or starts a fresh one).

The fragments are taken the moment a cube is clicked, and the prize is paid at the reveal. Closing the menu, logging out or a server shutdown settles anything still animating, so a payout can never be lost. The winning cube is never written as opened, so an interrupted win leaves the board winnable.

Stages and unlocking

Section titled “Stages and unlocking”

A reward’s Stage is a multiple, not a minimum. A reward with Stage: 25 is selectable at stage 25, 50, 75 and so on. Stage: 1 is always selectable, because every stage is a multiple of one. Players start at stage 1.

Stage: 1    →  every stage
Stage: 5    →  stage 5, 10, 15, 20, ...
Stage: 25   →  stage 25, 50, 75, ...

Locked rewards still show in the select menu, with the Lore-Addons.Locked lines appended.

Features

Section titled “Features”
  • Fragment currency earned from block breaks (and optionally placements), with chance, amount, world and block filters
  • Player-placed blocks never drop fragments, so place-and-break farming does not work
  • Optional fragment sources from PinnaPrison, EdDungeons and RivalHarvesterHoes, no hard dependency
  • One independent board per reward, saved and resumed when the player switches
  • Weighted consolation prizes on every miss, with a spin animation you can time
  • Stage progression that gates which rewards can be hunted
  • One file per reward, dropped in and reloaded
  • [fragments] <amount> payouts that credit fragments directly
  • Temporary feedback icons on blocked clicks
  • PlaceholderAPI placeholders
  • SQLite storage with write-behind saving
  • Folia-ready

Commands

Section titled “Commands”

Player - /miraclecube (aliases /mcube, /miraclecubes):

  • /miraclecube - open the board of the selected reward, or the select menu when nothing is selected · optimalmiraclecubes.use

Admin - /miraclecubeadmin (alias /mcubeadmin) · all optimalmiraclecubes.admin:

  • /miraclecubeadmin - show the admin help panel.
  • /miraclecubeadmin fragments <give|take|set> <player> <amount> - change a fragment balance. <amount> must be a whole number of 0 or more. take never drops a balance below 0.
  • /miraclecubeadmin stage <player> <stage> - set a player’s stage. <stage> must be 1 or more. Saved boards are kept.
  • /miraclecubeadmin resetboard <player> - delete every saved board of the player and clear their selection. Their next /miraclecube opens the select menu.
  • /miraclecubeadmin reload - reload config.yml, messages.yml, both menu files and every reward file.

The admin commands work on online players and on offline players the server knows (anyone who has joined before). The confirmation message is sent once the change is saved. An unknown name sends INVALID-PLAYER.

Permissions

Section titled “Permissions”
  • optimalmiraclecubes.use - /miraclecube and both menus (default: everyone)
  • optimalmiraclecubes.admin - every /miraclecubeadmin command and its tab completion (default: op)

Rewards have no permission nodes. The stage is the only gate.

Placeholders

Section titled “Placeholders”

Requires PlaceholderAPI. Identifier optimalmiraclecubes.

Placeholder Value
%optimalmiraclecubes_fragments% Fragment balance, plain number.
%optimalmiraclecubes_fragments_formatted% Fragment balance, comma-grouped (1,234).
%optimalmiraclecubes_stage% Current stage.
%optimalmiraclecubes_reward% The selected reward’s name with all formatting stripped. Empty when nothing is selected.
%optimalmiraclecubes_price% Fragments charged per decrypt (Cube.Price).

They read the loaded profile, so they resolve for online players only. An offline player gets an empty string.

Tokens

Section titled “Tokens”

These are the plugin’s own {...} tokens. Each resolves only where it is listed.

Token Value Where
{fragments} The viewer’s fragment balance, comma-grouped. Board and select menu items, cube items, board temporary icons, FRAGMENTS-FOUND. In INSUFFICIENT-FRAGMENTS it is the plain number.
{price} Cube.Price. Board menu items, cube items, board temporary icons, INSUFFICIENT-FRAGMENTS.
{reward} The selected reward’s display name (with colors). Board menu items, cube items, board temporary icons, REWARD-SELECTED, REWARD-WON. In RANDOM-REWARD-WON it is the consolation prize’s name.
{stage} The player’s current stage. Select menu items, reward icons, Lore-Addons, the Locked icon, REWARD-LOCKED. In REWARD-WON it is the new stage.
{required} The reward’s Stage multiple. Reward icons, Lore-Addons, the Locked icon, REWARD-LOCKED.
{amount} Fragments found or changed. FRAGMENTS-FOUND, FRAGMENTS-GIVEN, FRAGMENTS-TAKEN, FRAGMENTS-SET.
{player} Player name. Admin messages, INVALID-PLAYER, reward and consolation Commands, menu action arguments.
{input} The rejected argument. INVALID-NUMBER.
{ms} Reload time in milliseconds. RELOAD.

Full per-message lists are on the messages.yml page and the per-menu lists on the menus page.

Formatting

Section titled “Formatting”

Every text field supports legacy & codes, &#RRGGBB hex, MiniMessage (<gradient:a,b,c>, <rainbow>, <bold>, <#RRGGBB>, <solid:HEX>, …) and, with PlaceholderAPI installed, %...% for the viewer in messages, menu items, cube items, temporary icons and action arguments. <gradient> accepts comma-separated hex stops. Messages also support [center] to centre a line.

Reference

Section titled “Reference”