Lootboxes

A lootbox is a separate kind of crate. There are no keys, no menu and no crate block: a lootbox is an item. The player places it on the ground, an in-world show plays above it, and they get Rewards-Amount different rewards from the normal pool plus one jackpot from the jackpot pool.

Lootboxes live in their own folders:

• lootboxes/ - one file per lootbox (its item, reward pools and how many rewards it gives). See lootboxes.
• lootbox-animations/ - one file per show (orbit, helix, wheel, burst). See lootbox animations.

Four example lootboxes ship, one per animation: example (orbit), example-helix, example-wheel and example-burst.

Giving lootboxes

/cratesadmin lootbox <player> <lootbox> [amount] [-s]

• <lootbox> is the file name without .yml, for example example-wheel.
• [amount] defaults to 1. Amounts accept suffixes like /cratesadmin give (10, 1k).
• The player must be online. The items go into their inventory, and whatever does not fit is dropped at their feet.
• One command gives at most a full inventory (36 stacks). A larger amount answers AMOUNT-TOO-LARGE.
• -s skips the LOOTBOX-RECEIVED message.

Lootbox items are tagged, so they can be traded, stored in chests or sold in a shop like any other item. Whoever places one opens it.

Opening

1. The player places the lootbox like a block. No block is ever placed: the placement is cancelled and one item is taken from the stack.
2. The box rises out of the ground, grows and starts spinning.
3. The reward icons deploy around it and shuffle through the pool, then lock onto the rolled rewards one by one, each with its name above it.
4. The jackpot rises out of the box (or falls from the sky, for burst), cycles through the jackpot pool and lands on the rolled jackpot.
5. After a short hold, every icon flies back into the box, the rewards are handed out and LOOTBOX-OPENED lists them in chat.

The show is sent as packets, so nothing is left behind in the world and nothing can be broken or picked up. Everyone within the animation’s View-Distance sees it.

Rules

• The player needs optimalcrates.use.
• A player can run one lootbox at a time (LOOTBOX-BUSY).
• A lootbox cannot be opened within 4 blocks of another one that is still running (LOOTBOX-TOO-CLOSE).
• Protection plugins are respected. If a region plugin would block the placement, nothing happens and the item is kept.
• A lootbox item whose file was deleted answers LOOTBOX-UNAVAILABLE and is kept.

Rewards are never lost

Everything is rolled the moment the show starts. If the player disconnects mid-show, they get their rewards at once and the show stops. A server shutdown or plugin disable does the same for every running show.

Rewards and the jackpot

• Rewards is the normal pool. Rewards-Amount rewards are drawn from it without repeats, so a lootbox with Rewards-Amount: 4 always gives four different rewards.
• Jackpot-Rewards is the jackpot pool. Exactly one jackpot is drawn every time.
• Both pools use the crate reward format: Display-Item, Items, Actions and Chance. Chances are weights, just like in crates.

The item lore can list both pools automatically with {exclusive-items} and {jackpot-items}, one line per reward. See lootboxes.

Creating a lootbox

1. Copy one of the shipped files in lootboxes/, for example example.yml to legendary.yml.
2. Change Settings.Display-Name, the Item and both reward pools.
3. Pick a show with Settings.Animation (orbit, helix, wheel, burst or one of your own files in lootbox-animations/).
4. Run /cratesadmin reload and /cratesadmin lootbox <you> legendary.

A lootbox whose file is broken, or whose Animation names a show that did not load, fails to load with its file name and the reason in the console. Every other lootbox keeps working.

Upgrading from an older version

lootboxes/ and lootbox-animations/ are created on the first start that has them. Like the other folders, they are only filled with the defaults when the folder does not exist yet.