Set up the crate and the shop
Sell effects for keys or currency: the crate, its odds by rarity, crate blocks in the world and the menu shop.
An effect is normally sold as a permission node. The crate is the other way in: a rarity decides how
likely it is, a key buys one roll, and what comes out is written onto the player's own row rather
than granted as a node — so it outlives the rank that never granted it. Since 1.4.0 the crate itself
is ExyliaLib's; this plugin hands it the catalogue and reads its settings and lines from config.yml
and messages.yml, under the same keys as before.
By the end of this page players can open a crate with keys, win effects by rarity and buy locked ones with money. Set crate.enabled: true in config.yml; when it is off, the Crate button says so.
Before you start#
You need the preview stage set (see Your first effect) and, for the shop, ExyliaEconomy or Vault.
Steps#
Check the rarities
tiers below, and give effects a tier.Give keys
/arrowsadmin keys give <player> 1.Bind a crate block
/arrowsadmin crate block add.Open it
/arrows crate.Check that it works#
The crate screen shows the key count, a reel falls and the prize is written to the player. /arrowsadmin keys check <player> shows the keys left.
The rarities#
config.yml's tiers block declares them. Nothing about the four below is hard-coded: rename them,
delete one, invent mythic.
tiers:
common:
name: "Common"
material: GRAY_DYE
color: "{muted}"
chance: 60.0
priority: 1
rare:
name: "Rare"
material: LIGHT_BLUE_DYE
color: "{info}"
chance: 25.0
priority: 2
epic:
name: "Epic"
material: PINK_DYE
color: "{accent}"
chance: 12.0
priority: 3
legendary:
name: "Legendary"
material: ORANGE_DYE
color: "{highlight}"
chance: 3.0
priority: 4| Key | What it does |
|---|---|
name | What menus and placeholders call it. |
material | The item the rarity is drawn with in the crate. The old docs said nothing draws it; the shipped config comment says it does, so test it in your opening before relying on either. |
color | The colour its name and its effects are written in. |
chance | How often a crate lands on it, relative to the other rarities. |
priority | Where it sits in menus; lower comes first. |
An effect names its rarity with tier in effects.yml, and omitting it makes the effect common:
INFERNO:
category: ember
tier: epicThe shares are worked out from the weights every time they are needed, so deleting a rarity re-spreads its odds instead of leaving a gap, and weights that sum to seven are as honest as weights that sum to a hundred. A rarity nothing declares an effect for is left out of the roll entirely.
An effect naming a tier the file no longer declares falls back to the first rarity — the cheapest
one on a sane file. Renaming legendary to mythic demotes every legendary rather than deleting it.
Keys#
Two kinds, and the crate takes both. A number on the player's row is impossible to drop, dupe or lose to a full inventory; an item can be sold at a stall, put in a kit and given to a friend.
On the row#
| Command | What it does |
|---|---|
/arrowsadmin keys give <player> <amount> | Adds keys. Alias: keys add. |
/arrowsadmin keys take <player> <amount> | Takes them away. Never below zero. Alias: keys remove. |
/arrowsadmin keys set <player> <amount> | Sets the number outright. |
/arrowsadmin keys check <player> | Prints what they hold. |
Every one of them runs from console and for a player who is offline, which is how a shop, a vote listener, a crate key from another plugin or a rank reward hands keys out:
/arrowsadmin keys give %player% 1crate.start-keys is what a player is given the first time they are seen — once, never again on
later joins.
In the hand#
/arrowsadmin item key <player> [1-64]Right click a bound crate block holding one and it opens on the spot: one key, one reel, no question
screen. The key leaves the hand as the reel starts falling. A left click never spends one, and
neither does a right click anywhere else — a key cannot be placed as a block, so it cannot be lost to
a wall. Its material is key-item in config.yml, its name and lore key-item in messages.yml,
and it is told apart by what it carries in its data rather than by its name or material. Key items
handed out before 1.4.0 keep opening the crate. Keys that do not fit in the inventory wait and are
handed over on the player's next join, with rewards-claimed.
Opening it#
Open the crate screen
/arrows crate, the Crate button in the effects menu, or a crate block in the world.
All three need exyliarrows.crate, which everybody holds until a server denies it to a group.
Pick how many at once
One key opens one crate. crate.max-at-once decides how many choices are offered, capped at
seven by the width of the opening screen. A player holding exyliarrows.crate.multi.<n> gets
<n> instead, the highest one they hold.
Watch it fall
One reel per crate, each landing crate.stagger-seconds after the one before it. What a reel
came within one slot of stays on screen, because half of what a crate is worth is the legendary
that went past the line.
The roll itself is two rolls: a rarity by its weight, then an effect inside it with every effect equally likely. That is what makes the odds in the menu true — a legendary at three percent stays at three percent whether the file declares two legendaries or forty.
The keys are spent and the prizes written down before the first frame, but nothing is handed over
until a reel stops on the line. Four crates opened at once pay out one at a time, stagger-seconds
apart, each with its own sound and its own line in chat. Closing the window costs nothing — the reels
stop being drawn and the prizes still land on their own clock. Leaving the server ends the timer, so a reel
still in the air is settled on the way out: unlocked on the row now, and any token kept in the reward
queue until their next join.
The opening in 3D#
With crate.opening: SPATIAL in config.yml the reels no longer fall down menus/crate_open.yml: a
crate built from displays stands in front of the player, a reel slows onto the prize, the lid opens
and the prize is revealed with its name and rarity. Then the effect itself plays on a mannequin that
stays standing where the crate was, launch, trail and impact, so the player sees what they won rather
than reading it. Sneaking skips to the end and hands every prize over at once.
Only the presentation changes. The prize is drawn and the keys spent exactly as with the inventory
reels, and the question of how many to open is still menus/crate.yml. Its look is
spatial/crate.yml, written by ExyliaLib the first time. A player on a client older than 1.21.4
always gets the inventory reels, whatever opening says. The default is INVENTORY.
A player without exyliarrows.preview sees the prize as its icon, with no mannequin.
What a win is worth#
| Outcome | What happens |
|---|---|
| Something new | Whatever crate.reward says: UNLOCK writes the effect onto the player's row, owned for good; ITEM hands over only its token, to be bound to a bow, sold or given away; BOTH does both. |
| Something already owned | crate.duplicate-refund keys are handed back instead. Under ITEM nothing is unlocked, so no opening is ever a duplicate and every key pays out. |
| No keys | The crate says so and spends nothing. |
| Nothing to hand over | A crate with no rarities, or none with effects in them, refuses rather than charging for the disappointment. |
An effect is usable when either its permission node applies or the player won or bought it. That is the whole difference between the ways in: a node is a rank and stops when the rank does, an unlock is theirs.
| Command | What it does |
|---|---|
/arrowsadmin unlocks grant <player> <effect> | Marks an effect as won, without a crate. Alias: unlocks give. |
/arrowsadmin unlocks revoke <player> <effect> | Takes a won effect back, for a support ticket. Alias: unlocks take. |
Wiping what everybody won for a new season, or one player's unlocks and keys, is ExyliaLib's
/exylialib wipe and /exylialib resetplayer: the crate
table is @account data.
Buying with currency#
A locked effect does not have to be won: with shop.enabled on and ExyliaEconomy or Vault installed,
the menu draws its price and a left click asks the player to confirm, charges them and unlocks it —
the same unlock a crate writes. Prices are set per rarity in shop.tier-prices, or per effect with
price in effects.yml. See Configuration.
Crate blocks#
A block in the world that opens the crate when it is clicked: a barrel in the hub, an ender chest in every world, the statue somebody built.
| Command | What it does |
|---|---|
/arrowsadmin crate block add | Opens a wizard: click the block to bind. |
/arrowsadmin crate block remove | Unbinds it. |
/arrowsadmin crate block list | Prints every bound block. |
/arrowsadmin crate block clear | Unbinds all of them. |
Bind them in game rather than by hand: the command writes the block you are looking at into
crate.blocks, and a bound block cannot be broken, blown up or pushed away while it is on that
list. A crate drawn as a barrel does not open a barrel either.
The list lives in config.yml, not in the world, so the blocks survive a world edit, a schematic
paste and a rollback — and a server that moves its hub only edits the list.
The two screens#
| File | What it draws |
|---|---|
lang/<code>/menus/crate.yml | The crate: how many keys the player holds, how much of the catalogue they have unboxed, and the one question of how many to open at once. A choice the player cannot afford is drawn by empty_template with how many keys it is missing. |
lang/<code>/menus/crate_open.yml | The crates opening: one reel per crate, falling down its own column, with the prize landing on the third row. |
Both are ordinary Exylia menu files — slots, templates, sounds and actions. crate.spin-frames
decides how long the first reel falls (capped at 200, about eleven seconds), and crate.on-spin,
crate.on-win and crate.on-duplicate are full effect blocks: sound, title, action bar, boss bar,
particle and firework. They play as each reel lands rather than once at the end, so four crates
opened together read as four prizes, each with its own sound and its own line in chat.
Coming from 1.3.0#
Up to 1.3.0 keys and unlocks lived on this plugin's own arrows_players row. They now live in
ExyliaLib's exylia_crate_players, in the same database. The first time a player is seen after
updating, their old keys and unlocks are carried across once, so nobody loses a key or an effect; the
old columns are left in place so a rollback still finds them.
Something missing on this page? Tell us on Discord