Installation

Requirements

• Java 21+ - required. The plugin is compiled to Java 21 bytecode; on Java 17 or older it fails with UnsupportedClassVersionError. Check with java -version.
• Paper / Folia (or a Paper fork). Spigot is not supported. api-version is 1.20.
• Minecraft 1.20+, built against 1.21.11. The server must run Java 21.

Optional soft dependencies (hooked only if installed):

• PlaceholderAPI - required for the %optimalmiraclecubes_...% placeholders, and for resolving other plugins’ %...% inside messages and menu actions.
• PinnaPrison, EdDungeons, RivalHarvesterHoes - extra fragment sources. Each hook is pure reflection and registers only when its plugin is present, so none of them is a hard dependency.

Rewards and consolation prizes are console commands, so whatever plugin grants them needs to be installed - the plugin does not hook it directly.

Steps

1. Confirm java -version reports 21 or higher.
2. Stop the server.
3. Drop OptimalMiracleCubes.jar into plugins/.
4. (Recommended) Add PlaceholderAPI.jar, plus any of the mining plugins above you want as fragment sources.
5. Start the server. The plugin generates its files and prints a startup banner.
6. Run /plugins - OptimalMiracleCubes should be green.

XSeries downloads automatically on first startup via Paper’s library loader, so the first launch needs internet access and may take a few extra seconds. SQLite is not downloaded - the plugin uses the sqlite-jdbc driver Paper already bundles.

Each third-party hook that registers logs a line like Hooked PinnaPrison for miracle fragments. If you enabled a source and don’t see its line, that plugin wasn’t loaded.

Generated files

plugins/OptimalMiracleCubes/
├─ config.yml                  # fragments, cube price & animation, consolation rewards, icons, 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 - retarget them at your own plugins before going live. See Creating Rewards.

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.

Two tables are used: one profile row per player, and one row per saved board (the hidden slot plus the cubes already opened). Boards are rewritten as a delete-then-insert inside the save transaction.

Writes are buffered and flushed on Settings.Save-Interval (default 60 seconds), plus on quit and shutdown. A win is flushed immediately so a crash can never re-grant it.

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