Skip to content
BattleStudio Wiki

Information

BattleStudio Plugin

OptimalMiracleCubes

Players mine fragments, pick a reward, and hunt it across a board of encrypted cubes - one board per reward, one stage at a time.

  • Paper / Folia
  • MC 1.20+
  • Java 21+
  • PlaceholderAPI
Buy on BuiltByBitDiscord

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

Rewards gate behind 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 enabled source) on a configurable chance.
  2. /miraclecube opens the select menu when nothing is selected. Picking a 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; the player does not know which.
  4. Clicking a cube costs Cube.Price fragments and plays a spin animation.
    • Wrong cube - a weighted Random-Rewards consolation prize pays out, and that cube stays decrypted for good.
    • Right cube - the reward’s Commands run, stage goes up by one, that board is wiped and the select menu reopens.

Every reward keeps its own board. Switching your selection saves the old board’s opened cubes and resumes the new one exactly where you left it. The winning cube is never marked as opened, so a crash mid-animation leaves the board intact.

Closing the menu (or logging out) settles anything still animating, so a payout can never be lost.

Stages and unlocking

Section titled “Stages and unlocking”

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

Stage: 1    →  always
Stage: 5    →  stage 5, 10, 15, 20, …
Stage: 25   →  stage 25, 50, 75, …

Features

Section titled “Features”
  • Fragment currency earned from block break/place, with chance, amount, world and block filters
  • Reflection-only hooks for PinnaPrison, EdDungeons and RivalHarvesterHoes - no hard dependency
  • One independent board per reward, saved and resumed on switch
  • Weighted consolation rewards 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
  • Temporary feedback icons on blocked clicks
  • Full PlaceholderAPI output
  • SQLite storage with write-behind flushing
  • Folia-ready (region schedulers throughout)

Commands

Section titled “Commands”

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

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

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

  • /miraclecubeadmin fragments <give|take|set> <player> <amount> - manage balances. Works offline.
  • /miraclecubeadmin stage <player> <stage> - set a player’s stage (minimum 1). Works offline.
  • /miraclecubeadmin resetboard <player> - wipe every saved board and clear the selection. Works offline.
  • /miraclecubeadmin reload - reload every config file.

Permissions

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

Rewards have no permission nodes. Stage is the only gate.

Placeholders

Section titled “Placeholders”

Requires PlaceholderAPI. Identifier optimalmiraclecubes.

  • %optimalmiraclecubes_fragments% - fragment balance
  • %optimalmiraclecubes_fragments_formatted% - same, comma-grouped (1,234)
  • %optimalmiraclecubes_stage% - current stage
  • %optimalmiraclecubes_reward% - selected reward’s name, stripped of formatting. Empty when nothing is selected.
  • %optimalmiraclecubes_price% - fragments per decrypt

All return empty for a player with no loaded profile.

Fragment sources

Section titled “Fragment sources”

Toggled under Fragments.Events in config.yml.

Source Event Notes
Block-Break Bukkit BlockBreakEvent On by default.
Block-Place Bukkit BlockPlaceEvent Off by default.
PinnaPrison BlockMineEvent Hooked by reflection when the plugin is present.
EdDungeons EdDungeonsSwingSwordEvent No material, so the Blocks whitelist does not apply.
RivalHarvesterHoe RivalBlockBreakEvent Hooked by reflection.

The three third-party hooks register only when their plugin is installed and log loudly if that plugin’s API changed. Toggles are read at fire time, so /miraclecubeadmin reload applies them without a restart.

Every source shares one path: chance roll first (the cheap early exit), then Ignore-Creative, the Worlds and Blocks whitelists, then the amount roll.

Formatting

Section titled “Formatting”

Every text field supports legacy & codes, &#RRGGBB hex, MiniMessage (<gradient:a,b,c>, <rainbow>, <bold>, <#RRGGBB>, <solid:HEX>, …) and PlaceholderAPI %...% in messages and action arguments. <gradient> accepts comma-separated hex stops.

Reference

Section titled “Reference”