Keys and costs

A key is a record of its own: an id, a name and the item it is drawn as. Which crates it opens is up to the crates — each one lists the keys it takes — so one key can open several crates and outlives a crate that is deleted.

Items and balances

A player can hold a key in two ways, and both open the same crates:

When a crate is opened, the key items the player carries are spent first and the balance pays the rest. A player with two items and five in their balance can open seven.

A key item opens whatever its key opens now: renaming the key or changing which crates take it changes what every existing item does. Key items are inert as their material — a key drawn as a sweet berry is not eaten, one drawn as a block is not placed.

/crates opens Crates: every enabled crate with how many of its key the player holds, items and balance together, and their total at the bottom. A click opens that crate's contents.

The keys screen

/cratesadmin keys (or /cratesadmin key list in game), or Keys on the crate list, lists every key with the crates that take it. /cratesadmin key create <id> run in game opens the new key's screen.

A key's screen edits its name (the item's name; colours work), its icon (a material, a head, or an item from another plugin; settings.default-key-material until one is chosen, TRIPWIRE_HOOK by default), and has Get keys, which hands you that many key items to test with, and Delete key.

A new key is named after default-key-name in messages.yml: KEY » <id>. Only new keys take it; an existing key is renamed from its screen.

Deleting a key

Deleting a key removes it from the costs of every crate that took it, and the confirmation says how many those are. Players' balances of it are kept, unread: a key created again with the same id finds them there. Key items of a deleted key stop opening anything.

What a crate costs

A crate charges an ordered list of costs per opening. Opening cost on a crate's overview lists them.

On a cost: left-click changes its amount, right-click removes it after a confirmation. Adding a key the crate already takes sets its amount rather than adding a second line. A crate with no costs is free and says so on its overview.

A crate can take several keys — one vote key and one event key — and money with them. A player has to pay every one of them: when one is missing they are told which ("You need 1x Event Key to open Rare.") and nothing is charged.

How a charge works

Money is charged first, then each key cost in order. The charge is all or nothing: when a later cost cannot be paid — another server spent the balance a moment earlier — everything already charged is given back, money and keys alike.

Money

Money goes through ExyliaLib's economy: ExyliaEconomy or any Vault economy. A money cost without a currency is in the server's default one, and its amount is written the way that currency writes it. Without an economy plugin a money cost cannot be paid, and the crate cannot be opened. Every charge carries the reason crates:open and every give-back crates:refund, so an economy's ledger and statistics can tell them apart.

Opening several at once

Sneaking while opening pays for as many openings as every cost allows, up to the player's multi-open limit: settings.max-multi-open (10), or their highest exyliacrates.multiopen.<n>. It needs exyliacrates.multiopen, which everybody holds by default; see Permissions. A crate costing 2 keys and 100 coins, opened by a player with 7 keys and 250 coins, opens twice.

A free crate opened while sneaking opens that limit's number of times every time.

Giving and taking keys

Every key command takes a key's id. An id that names no key but a crate is read as that crate's key — the first key its cost lists — so a store command can name the crate.

take and set work on the balance only; they never touch key items in an inventory.

Key items are handed over through ExyliaLib's delivery path: a full inventory, a death screen or a disconnect keeps them for the player's next join instead of dropping them on the floor.

The player is told when keys reach them — "You received 3 Vote keys." — with the keys.received effect from config.yml (a title, a sound and a burst of particles by default). Keys added to the balance of a player who is not online are announced on their next join, on whichever server: "3 Vote keys arrived while you were away." A take or a set tells an online player the new state.

take and set can answer "The keys of player changed on another server meanwhile. Try again." when another server kept changing the same balance through five attempts.

Every give, take and set, and creating and deleting keys and crates, is written to ExyliaLib's staff log, read with /exylialib logs.

From a web store

A store runs commands from the console while the buyer may be offline. Use key virtual:

cratesadmin key virtual {username} vote 5

The keys are added in the database itself, so a purchase landing while the player spends a key on another server counts both.