Creating Crates

Every crate is one file in crates/. The file name is the crate’s id: crates/legendary.yml is the crate legendary, used in commands (/cratesadmin give Steve legendary 1) and shown as Legendary in messages. You need optimalcrates.admin to reload.

You can build a crate entirely in game with the In-Game Editor. This page covers writing the file by hand, which is faster for large reward lists.

1. Create the file

Create plugins/OptimalCrates/crates/legendary.yml. A crate needs a Settings section, a Display-Item with a Slot, a Place-Item and at least one reward.

Settings:
  Mode: "ROLL"
  Spin-Animation: "roulette"
  Preview-Enabled: true
  Preview-Menu: "default"
  Mass-Open-Enabled: true
  Display-Amount: -1

Display-Item:
  Material: ORANGE_SHULKER_BOX
  Slot: 13
  Name: "&6&lLegendary Crate"
  Lore:
    - "&7The rarest crate on the server."
    - ""
    - "&6Information:"
    - "&e - &7Keys: &f{keys}"
    - "&e - &7Rewards: &f{rewards}"
    - ""
    - "&e➥ Left click to open!"
    - "&e➥ Right click to preview!"

No-Keys-Item:
  Material: BARRIER
  Name: "&c&lError!"
  Lore:
    - "&7You don't have any &f{crate} &7keys to open!"

Place-Item:
  Material: ORANGE_SHULKER_BOX
  Name: "&6&lLegendary Crate"
  Lore:
    - "&7Place this block to register it"
    - "&7as a crate block."

Rewards:
  diamonds:
    Display-Item:
      Material: DIAMOND
      Name: "&b&l16x Diamonds"
      Lore:
        - "&7Chance: &f{chance}%"
    Actions:
      - "[console] give {player} diamond $16"
    Chance: 70.0
  money:
    Display-Item:
      Material: GOLD_INGOT
      Name: "&e&l$50,000"
      Lore:
        - "&7Chance: &f{chance}%"
    Actions:
      - "[console] eco give {player} $50000"
      - "[message] &aYou won &e$50,000&a!"
    Chance: 30.0

Full field list: crates reference.

2. Pick a free slot

Display-Item.Slot is the slot of the crate’s icon in the /crates menu, counting from 0. It must be inside the menu Size set in guis/crates-menu.yml (36 by default), or the crate simply does not show up in the menu. Give every crate its own slot.

3. Reload and give yourself keys

/cratesadmin reload
/cratesadmin give <you> legendary 5

Open /crates, left click the new crate and open a key. If the crate does not appear, check the console: a crate that fails to load logs its file name and the reason, and every other crate keeps working.

Rewards

Every key under Rewards is one reward. The key is the reward’s id and is only used internally and as a fallback name. Each reward needs a Chance above 0 and must give something: Items, Actions, or both.

• Actions are [type] argument lines, such as [console] eco give {player} 1000. See reward actions for every type.
• Items are real items, stored in full (enchantments, custom names, NBT). They are easiest to add with the editor: hold the item and add it in the reward’s Items menu. The items are copied, nothing is taken from your inventory.

Chances are weights

Chances are weights, not percentages. The roll is bounded by the sum of every chance, so these two crates behave the same:

Rewards:
  common: { ..., Chance: 75.0 }   # 75%
  rare:   { ..., Chance: 25.0 }   # 25%

Rewards:
  common: { ..., Chance: 3.0 }    # still 75%
  rare:   { ..., Chance: 1.0 }    # still 25%

Making them add up to 100 keeps {chance}% in your lore readable.

Scaling with $n

When a player opens many keys at once, a reward can be won many times. An action containing $n runs once, with n multiplied by the number of wins. An action without $n runs once per win.

Actions:
  - "[console] give {player} diamond $16"   # 3 wins → one command giving 48
  - "[message] &aYou won diamonds!"         # 3 wins → the message is sent 3 times

Items are scaled the same way and handed over in full stacks. Anything that does not fit in the inventory is dropped at the player’s feet.

Modes

Mode	What happens
ROLL (default)	Spending a key rolls a weighted random reward. A single open plays the crate’s Spin-Animation.
PICK	The player chooses the reward. The preview menu becomes a picker: clicking a reward spends one key and gives exactly that reward. The menu stays open so they can keep picking.

A PICK crate ignores Spin-Animation and Mass-Open-Enabled, and it must have Preview-Enabled: true and a Preview-Menu, since the picker is that menu. Chances do nothing in a PICK crate. Because every key is worth any reward, keep PICK crates for things like “choose your kit” rewards.

Animations

Settings.Spin-Animation names a file in animations/ without .yml (csgo, monthly, roulette, slots, shuffle, or one of your own), or "none" for no animation.

• Only single opens animate. Opening more than one key at once is always instant.
• A player who turns animations off with the toggle in /crates gets instant opens everywhere.
• Pressing Q during an animation skips to the result. Closing the menu also finishes it, and the reward is still given.
• A monthly animation reveals several rewards (Picks, 3 by default) for one key.

If the named animation does not exist or failed to load, the crate refuses to load rather than open without it. Animation settings are on the animations page.

Previews and filtering

Settings.Preview-Menu names a design in previews/ (default ships). Several crates can share one design. The preview shows each reward’s Display-Item.

In a ROLL crate’s preview, players can click a reward to filter it out. The lore lines from Filter-Formats in config.yml show its state.

Filtering does not change the odds

A filtered reward is still rolled at its normal chance, it is just not given. Filtering never makes the other rewards more likely, so a filtered roll is a wasted key. Filters are kept in memory only and reset when the player leaves.

Notes

• Disable without deleting: move the file out of crates/ (or rename it to something other than .yml) and reload. Players keep their key balances for when it comes back.
• Renaming a file changes the crate’s id. Existing key balances and placed blocks point at the old id and will not follow the rename.
• One broken crate never breaks the rest. Each file loads on its own; check the console after a reload.
• The preview, redeem menu and crates menu read {keys} (the player’s key balance) live each time they open.