Installation

Requirements

• OptimalLibrary - required. OptimalCrates depends on it and will not enable without it. It is a separate free plugin that provides the shared runtime (text and MiniMessage, menus, storage, holograms, particles and more). Install the latest version alongside OptimalCrates.
• Paper / Folia (or a Paper fork). Spigot is not supported.
• Minecraft 1.21.11, 26.1.1, 26.1.2, 26.2 or 26.3.
• Java 21 for 1.21.11, Java 25 for the 26.x versions. Check with java -version.

If OptimalLibrary cannot hook into your server version, OptimalCrates logs an error and disables itself instead of running half-broken.

Optional soft dependency:

• PlaceholderAPI - registers the %optimalcrates_keys_<crate>% placeholders and resolves %...% placeholders from other plugins in messages, menus, crate icons, hologram lines and reward actions.

Crate rewards can run console commands, so whatever plugin those commands belong to (vouchers, economy, ranks) needs to be installed as well. OptimalCrates does not hook it directly.

Steps

1. Confirm java -version reports the right version for your server.
2. Stop the server.
3. Drop OptimalLibrary.jar and OptimalCrates.jar into plugins/.
4. (Optional) Add PlaceholderAPI.jar.
5. Start the server. OptimalCrates generates its files and prints a startup banner with the number of crates, animations and crate blocks it loaded.
6. Run /plugins - OptimalLibrary and OptimalCrates should both be green.

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

Generated files

plugins/OptimalCrates/
├─ config.yml               # storage, number format, settings, filter lore, editor words, sounds
├─ messages.yml             # every message
├─ crates/
│  └─ vote.yml              # one file per crate (one example ships)
├─ animations/
│  ├─ csgo.yml              # CSGO scroll animation
│  ├─ monthly.yml           # Monthly chest pick animation
│  ├─ roulette.yml          # Roulette wheel animation
│  ├─ slots.yml             # Slots machine animation
│  └─ shuffle.yml           # Shuffle animation
├─ lootboxes/
│  ├─ example.yml           # one file per lootbox (four examples ship)
│  ├─ example-helix.yml
│  ├─ example-wheel.yml
│  └─ example-burst.yml
├─ lootbox-animations/
│  ├─ orbit.yml             # the four in-world lootbox shows
│  ├─ helix.yml
│  ├─ wheel.yml
│  └─ burst.yml
├─ previews/
│  └─ default.yml           # reward preview menu design
├─ guis/
│  ├─ crates-menu.yml       # the /crates menu
│  ├─ open-menu.yml         # the redeem menu (open one / open all)
│  └─ editor/               # the nine in-game editor menus
│     ├─ crates.yml
│     ├─ crate.yml
│     ├─ rewards.yml
│     ├─ reward.yml
│     ├─ items.yml
│     ├─ lines.yml
│     ├─ particles.yml
│     ├─ holograms.yml
│     └─ confirm.yml
└─ data/
   └─ data.db               # SQLite key balances, crate blocks, settings (not used with MySQL)

The example vote crate uses a vouchers give command as its reward. Retarget it at your own plugins, or replace it with real items in the editor, before going live.

Deleted defaults stay deleted

crates/, animations/, previews/, lootboxes/ and lootbox-animations/ are only filled with the defaults when the folder does not exist yet. Delete the example crate and it stays gone across reloads and restarts. To get the defaults back, delete the whole folder and restart. guis/ is different: any missing menu file there is restored on the next server start, because every menu file is required.

Storage

The backend is set in config.yml under Settings.Storage:

• SQLite (default) - a local file at data/data.db. Nothing to set up.
• MySQL - set Type: MYSQL and fill in Host, Port, Database, Username and Password. Use this if several servers should share key balances.

Changing the backend needs a full restart. The database holds three tables:

Table	Holds
crate_keys	Every player’s key balance per crate.
crate_blocks	Every placed crate block (world, x, y, z and crate).
crate_settings	Each player’s animation toggle.

Key balances are loaded when a player logs in and kept in memory while they are online. Changes are flushed every Settings.Save-Interval seconds (default 60), on quit and on shutdown. Spending keys is the exception: an open saves the new balance immediately, so a crash can never return spent keys.

If a player’s keys cannot be loaded from the database, the login is refused with the PROFILE-LOAD-FAILED message rather than letting them play with an empty balance.

Upgrading

Drop in the new jar and restart. On every start and reload, OptimalCrates checks your files for renamed keys and rewrites them in place, logging each change to the console:

• config.yml gets the new Settings.Storage and Settings.Number-Format blocks, and the NOT-ENOUGH-KEYS sound becomes DENIED.
• messages.yml keys move to their new names (KEYS-LOAD-FAILED → PROFILE-LOAD-FAILED, INSUFFICIENT-CRATES → INSUFFICIENT-KEYS, and so on, see messages.yml) with your text kept.
• The key balance token {crates} becomes {keys} in messages.yml, guis/crates-menu.yml, guis/open-menu.yml, previews/ and crates/.

New default files (the slots and shuffle animations, lootboxes and lootbox animations) only appear in folders that do not exist yet. Copy them from the jar into an existing animations/ folder to use them.

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