Configuring

Rarities and the crate

The rarities effects are sorted into, the keys that open a crate, and what a player keeps after it lands.

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.

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.
`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:

effects.yml

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

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, 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 — written once, when the row is created, 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. How it is drawn is key-item in config.yml, and it is told apart by what it carries in its data rather than by its name or material.

Opening it

Open the crate screen

/arrows crate, the EFFECT CRATE button in the effects menu, or a crate block in the world.

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.

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.

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 it. That is the whole difference between the two ways in: a node is a rank and stops when the rank does, a win 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`.
`/arrowsadmin unlocks clear <player>`	Wipes what they won, for a new season.

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`	Binds the block you are looking at.
`/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
`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.
`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.

Something missing on this page? Tell us on Discord