Installation

Requirements

• OptimalLibrary - required. It is a separate, free plugin that provides the shared runtime (text and MiniMessage, menus, messages, storage, scheduling). OptimalMiracleCubes will not enable without it.
• Paper or Folia (or a Paper fork). Spigot is not supported. Supported versions: 1.21.11, 26.1.1, 26.1.2, 26.2 and 26.3.
• Java 21 for 1.21.11, Java 25 for the 26.x versions. Check with java -version.

Optional soft dependencies (hooked only if installed):

• PlaceholderAPI - needed for the %optimalmiraclecubes_...% placeholders, and for resolving other plugins’ %...% inside messages, menu items and menu actions.
• PinnaPrison, EdDungeons, RivalHarvesterHoes - extra fragment sources. Each hook only registers when its plugin is enabled at startup, and each is off until you turn it on under Fragments.Events in config.yml.

Rewards and consolation prizes are console commands, so whatever plugin grants them (crates, titles, your economy) needs to be installed too. OptimalMiracleCubes does not hook it directly.

Steps

1. Confirm java -version matches your server version (21 for 1.21.11, 25 for 26.x).
2. Stop the server.
3. Drop OptimalLibrary.jar and OptimalMiracleCubes.jar into plugins/.
4. (Recommended) Add PlaceholderAPI.jar, plus any of the plugins above you want as fragment sources.
5. Start the server. The plugin generates its files and prints a startup banner with the number of rewards loaded.
6. Run /plugins - OptimalLibrary and OptimalMiracleCubes should both be green.

On the first start OptimalLibrary downloads its libraries (the SQLite and MySQL drivers, HikariCP and XSeries) through Paper’s library loader, so that launch needs internet access and may take a few extra seconds.

Each third-party hook that registers logs Hooked PinnaPrison. (or EdDungeons, RivalHarvesterHoes). If you enabled a source and don’t see its line, that plugin wasn’t loaded.

Generated files

plugins/OptimalMiracleCubes/
├─ config.yml                  # save interval, fragments, cube price & animation, lore addons, consolation prizes, sounds
├─ messages.yml                # every message
├─ guis/
│  ├─ select-menu.yml          # the reward selection menu
│  └─ board-menu.yml           # the cube board, incl. the encrypted/decrypted cube items
├─ rewards/                    # one file per board reward, id = file name
│  ├─ t1-orbs-pouch.yml
│  ├─ t1-gems-pouch.yml
│  ├─ 236-title.yml
│  ├─ goat-title.yml
│  ├─ rare-crate-key.yml
│  ├─ epic-crate-key.yml
│  └─ monthly-crate-key.yml
└─ data/
   └─ data.db                  # SQLite player data (do not edit by hand)

Seven example rewards ship so the select menu is populated on first run. They call pouches, titles and crates commands, and the consolation prizes call eco give and give. Retarget them at your own plugins before going live. See Creating Rewards.

The rewards/ folder is only extracted when it does not exist. A default reward you delete stays deleted; delete the whole folder to get every default back.

Storage

Player state (stage, fragments, the selected reward and every saved board) is stored in SQLite at data/data.db. There is no MySQL option for this plugin.

Two tables are used: player_boards holds one row per player (stage, fragments, selected reward), and player_reward_boards holds one row per saved board (the hidden cube and the cubes already opened).

• A profile is loaded while the player logs in. If it cannot be loaded, the login is refused with the PROFILE-LOAD-FAILED message, so nobody plays on an empty profile.
• Changes are kept in memory and saved every Settings.Save-Interval seconds (default 60), on quit and on shutdown.
• Every payout is saved immediately: a win (the new stage and the removed board) and a consolation prize (the spent fragments) are written before the prize’s commands run.
• Admin commands on an offline player write straight to the database.

Continue to Creating Rewards, or read the Information overview first.