Skip to content
BattleStudio

Information

OptimalCrates features, the open flow, lootboxes, commands, permissions, placeholders, tokens and formatting in one reference.

BattleStudio plugin

OptimalCrates

Virtual key crates with five opening animations, placeable crate blocks with holograms, in-world lootboxes with jackpots, and a full in-game editor.

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

OptimalCrates is a virtual crates plugin. Keys are balances stored in a database, not items, so they can never be duped, dropped or lost to a full inventory. Players open crates from the /crates menu, with /crates open, or by right-clicking a crate block you placed in the world.

Every crate is its own file in crates/. A crate can roll a weighted reward (with an optional CSGO, Monthly, Roulette, Slots or Shuffle animation) or let the player pick the reward they want. Placed crate blocks get a cycling hologram and particle rings, and everything about a crate can be edited in game with /cratesadmin editor.

Lootboxes are a second kind of crate: a placeable item that plays an in-world show above the spot it was placed and hands out several rewards plus a jackpot. See Lootboxes.

How it works

Section titled “How it works”
  • Keys are a per-player balance for each crate. Admins hand them out with /cratesadmin give (works on offline players) or /cratesadmin giveall, usually from a vote, store or reward plugin.
  • Opening a ROLL crate takes the keys first, rolls the rewards, plays the animation (single opens only) and then hands everything out with a summary in chat.
  • Mass opens (more than one key at once) skip the animation and resolve instantly, no matter how many keys are opened.
  • Rewards give real items, run actions (console commands, messages, broadcasts, sounds), or both.
  • Paid rewards are never lost. Closing an animation early, pressing Q or disconnecting finishes the open at once and still grants the reward.
  • Spent keys are saved immediately, so a crash right after an open can never give the keys back.

Opening from the menu

Section titled “Opening from the menu”

/crates shows every crate at the slot its file sets.

  • Left click opens the redeem menu (Open One Key / Open All Keys). Pressing Escape there returns to the crate list.
  • Right click opens the reward preview.
  • With no keys, the click sends INSUFFICIENT-KEYS and flashes the crate’s No-Keys-Item.

A PICK crate skips the redeem menu: left click opens its preview as a picker, and clicking a reward spends one key and gives exactly that reward.

Crate blocks

Section titled “Crate blocks”
  • Right click a crate block to open one key.
  • Left click to preview its rewards.
  • Sneak + left click (with optimalcrates.admin) removes the crate block.

See Crate Blocks for placing, holograms and particles.

Features

Section titled “Features”
  • Unlimited crates, one file each, with virtual key balances
  • Two modes: ROLL (weighted random) and PICK (the player chooses the reward)
  • Five animation types: CSGO scroll, Monthly chest pick, Roulette wheel, Slots machine and Shuffle, all fully configurable
  • “Choose your slot” option on CSGO and Roulette: the key is only spent once the player picks a slot
  • Per-player animation toggle in the crates menu, saved across restarts
  • Instant mass opens of any size with one summary message
  • Reward preview menus with per-player reward filtering
  • Rewards that give real items, run actions, or both, scaled by the number of keys opened
  • Placeable crate blocks with cycling packet holograms and dust ring particles
  • Crate blocks are protected from breaking, explosions and pistons
  • Optional knockback for players who click a crate block without a key
  • In-game editor for crates, rewards, items, actions, holograms and particles
  • Lootboxes: placeable items with four in-world shows (Orbit, Helix, Wheel, Burst), several rewards without repeats and a jackpot
  • PlaceholderAPI placeholders for raw and formatted key balances
  • Configurable number format (12.5K or 12,500) for every balance and amount
  • SQLite or MySQL storage, write-behind flushed on a configurable interval
  • Older configs are migrated automatically when keys are renamed
  • Folia-ready

Commands

Section titled “Commands”

Player - /crates (aliases /crate, /optimalcrates):

  • /crates - open the crates menu
  • /crates preview <crate> - preview a crate’s rewards (does nothing if the crate has its preview disabled)
  • /crates open <crate> [amount] - open keys without the menu. [amount] defaults to 1.
  • /crates help - show the player help

The player commands have no permission check. Any other argument opens the menu.

Admin - /cratesadmin (aliases /crateadmin, /optimalcratesadmin) · all optimalcrates.admin:

  • /cratesadmin give <player> <crate> <amount> [-s] - give keys. Works on offline players who have joined before; a name that never joined answers UNKNOWN-PLAYER. -s skips the “you received” message.
  • /cratesadmin giveall <crate> <amount> [-s] - give keys to everyone online. One per IP address when GiveAll-One-Per-IP is on.
  • /cratesadmin remove <player> <crate> <amount> - take keys away. Balances never go below 0.
  • /cratesadmin check <player> - show a player’s key balance for every crate. Works offline.
  • /cratesadmin place <crate> - get the crate’s placeable block. Player only.
  • /cratesadmin lootbox <player> <lootbox> [amount] [-s] - give lootbox items to an online player. [amount] defaults to 1. See Lootboxes.
  • /cratesadmin editor [crate] - open the in-game editor, or jump straight to one crate. Player only.
  • /cratesadmin reload - reload every config file, crate, animation, preview, lootbox and lootbox animation.

Running /cratesadmin with no or unknown arguments shows the admin help. The admin command is hidden from tab completion for players without optimalcrates.admin.

Amounts accept suffixes and separators: 10, 1k, 2.5m, 1,000 and 1_000 all work.

Permissions

Section titled “Permissions”
  • optimalcrates.use - /crates (every subcommand), clicking crate blocks to open or preview them, and placing lootboxes (default: everyone). A player without it gets NO-PERMISSION.
  • optimalcrates.admin - every /cratesadmin command and removing crate blocks (default: op)

Crates themselves have no permission nodes: past optimalcrates.use, keys are the only gate. An admin’s sneak + left click removal needs only optimalcrates.admin.

Placeholders

Section titled “Placeholders”

With PlaceholderAPI installed, OptimalCrates registers two placeholders. <crate> is the crate’s file name without .yml.

Placeholder Value
%optimalcrates_keys_<crate>% The player’s key balance for that crate as a plain number, for example %optimalcrates_keys_vote% → 12500.
%optimalcrates_keys_formatted_<crate>% The same balance through the Number-Format, for example 12.5K.

Balances are only loaded while a player is online, so the placeholder returns 0 for offline players.

PlaceholderAPI placeholders from other plugins also work in messages, menu items, crate icons, hologram lines and reward actions.

Tokens

Section titled “Tokens”

These are the plugin’s own {...} tokens. Which ones work depends on where you use them.

Token Value Where
{crate} The crate’s name: its file name with the first letter capitalized (vote.yml → Vote). Everywhere a crate is involved
{keys} The viewer’s key balance for that crate, through the Number-Format. Called {crates} before; old files are migrated automatically. Crate icons, No-Keys-Item, redeem menu, preview menu, holograms
{rewards} How many rewards the crate has. Crate icons, menus, reward icons, holograms
{reward} A reward’s display name (its Display-Item name, or its key if it has none). Reward icons, holograms, PRINT-REWARD
{chance} A reward’s Chance value, rounded to two decimals. Reward icons, holograms
{item-display} Same as {reward}. Holograms
{player} The player’s name. Menus, animation titles, reward actions
{uuid} The player’s UUID. Reward actions and menu actions
{page}, {pages}, {max-page}, {results} Current page, page count, page count, number of entries. Paged menus (previews)

Messages have their own tokens, listed per key on the messages.yml page.

Formatting

Section titled “Formatting”

Every text field supports legacy & codes, &#RRGGBB hex, MiniMessage (<gradient:a,b>, <rainbow>, <bold>, <#RRGGBB>, …) and, with PlaceholderAPI installed, %...% placeholders. Messages also support [center] at the start of a line to center it in chat.

Reference

Section titled “Reference”