CrateKeys

Each tier draws from a band of a curated catalogue scored 10 to 100 by desirability, so a common crate cannot roll netherite and a legendary one cannot roll copper. The bands overlap on purpose — four disconnected loot tables feel like four different plugins.

The pool is then filled against per-category quotas: valuables, blocks, gear, utility, consumables. Without that, blocks win on sheer count and every crate feels like a building-material delivery. The single best entry in the band is reserved as a chase item before quotas run, so a crate always has something to want.

Chance falls off steeply with desirability, which is what keeps the good pulls rare without a hand-tuned table. Generation is seeded, so the same seed and tier always produce the same pool — a regeneration is diffable rather than a surprise.

Hold the key and run /cratekeys key capture (crate). CrateKeys records the material, the display name, the custom model data and every readable persistent-data tag, and writes them into crates.yml under that crate’s key: block.

Two things are excluded on purpose. Values that look like a per-item unique id are skipped, because capturing one would produce a matcher that only ever accepts the single key you were holding. Lore is skipped too, since key lore often carries a player name or a date.

Check any item with /cratekeys key test, which names every crate it opens. If a captured item also opens another crate, CrateKeys tells you at capture time — one key opening several crates is a legitimate design, it just must not be a surprise.

A matcher that is too loose is the failure worth watching for: material alone turns every item of that type into a key. Add a name or a custom model data condition.

A block crate is any container registered with /cratekeys set. Right-click with a key to spin. Right-click without one and you get the preview plus a nudge, because being shown what you are missing is better feedback than an error and costs the player nothing. Sneak + right-click always previews, so somebody carrying a stack of keys can look without spending one, and left-click previews too.

The block is protected from breaking, explosions and lava. A sneaking admin can break it, which unregisters it in the same action.

An item crate is a shulker-box-style item that opens a small menu offering Preview rewards and Open. That is deliberately a choice rather than an immediate open, because the item is consumed when you open it and I only wanted to look must not cost somebody a crate. It cannot be placed as a block.

Any reward can carry a commands: list, run from the console on a win with %player% and %uuid% substituted. That is how a crate gives a rank, a permission, a currency payout or anything else another plugin owns.

A command-only reward still appears in the preview with its own display name and its real odds, so the pool a player sees is the pool that exists.

Rewards at or above a desirability score announce server-wide when won — 70 by default, which is roughly netherite and above. Set broadcast-at-score to 101 to switch that off entirely, or set broadcast: true on a crate to announce every win from it.

The console always hears a broadcast win. That doubles as the record for a disputed pull.

A player says the wheel showed one thing and gave another: it cannot. The reward is rolled before the first frame and the reel is built to land on it. Check the console, which logs every broadcast win.

A player logged off mid-spin: the console names them and the reward they were owed, at WARN. Their key was already spent, so compensate from that line.

You need a key while holding one: run /cratekeys key test. If it reports nothing, the matcher is stricter than the key — most often a custom model data or a name that differs between batches. Loosen the key: block in crates.yml.