Content generated with AI — it may contain mistakes.

ExyliaArrows/GuidesUpdated in v1.7.1

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.

Page 8 of 2210 min read

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

Edit tiers below, and give effects a tier.

Give keys

Run /arrowsadmin keys give <player> 1.

Bind a crate block

Look at a block and run /arrowsadmin crate block add.

Open it

Right click the block, or run /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.

yaml
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
KeyWhat it does
nameWhat menus and placeholders call it.
materialThe 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.
colorThe colour its name and its effects are written in.
chanceHow often a crate lands on it, relative to the other rarities.
priorityWhere it sits in menus; lower comes first.

An effect names its rarity with tier in effects.yml, and omitting it makes the effect common:

effects.yml
yaml
INFERNO:
  category: ember
  tier: epic
chance is a weight, not a percentage

The 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.

A rarity that is gone costs its effects their colour, never their existence

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#

CommandWhat 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% 1

crate.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.

Paid out as each reel lands

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#

OutcomeWhat happens
Something newWhatever 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 ownedcrate.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 keysThe crate says so and spends nothing.
Nothing to hand overA 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.

CommandWhat 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.

CommandWhat it does
/arrowsadmin crate block addOpens a wizard: click the block to bind.
/arrowsadmin crate block removeUnbinds it.
/arrowsadmin crate block listPrints every bound block.
/arrowsadmin crate block clearUnbinds 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#

FileWhat it draws
lang/<code>/menus/crate.ymlThe 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.ymlThe 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