Configuring

The crate

Rarities, both kinds of key, the reels that fall, and the blocks that open them.

The crate is how effects are won rather than given. A key is spent, a reel falls, and what it lands on is written to the player's own row — owned for good, whatever happens to their rank afterwards.

Rarities

Every effect declares a tier in effects.yml, and config.yml declares what the tiers are:

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.

Nothing here is hard-coded. Delete legendary, invent mythic, rename all four: the key is the id effects.yml writes as tier, and an effect naming a rarity that no longer exists falls back to the first one — it loses its colour, never its existence.

chance is a weight, not a percentage

The shares shown in the menu are worked out from the weights, so four rarities weighted 60/25/12/3 and four weighted 6/2.5/1.2/0.3 behave identically. Deleting a rarity re-spreads its odds across the rest instead of leaving a three-percent hole.

Keys

Two kinds, and the crate takes both.

On the row

A number on the player's own row. Nothing can be dropped, duped, or lost to a full inventory:

/killeffectsadmin keys give <player> <amount>
/killeffectsadmin keys take <player> <amount>
/killeffectsadmin keys set <player> <amount>
/killeffectsadmin keys check <player>

Safe to run from console — a shop, a vote listener, a reward plugin or a crate on another plugin all hand keys over the same way.

[console] killeffectsadmin keys give %player% 1

In the hand

An item, so it can be sold at a shop stall, put in a kit, dropped, and given to a friend:

/killeffectsadmin 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 the moment the reel starts falling. Left clicking never spends one — that is how a player asks what a block is — and neither does right clicking 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. It is told apart by what it carries in its data rather than by its name or material, so renaming one changes nothing and a lookalike opens nothing.

Which kind to sell

An item is worth having when keys are traded between players or sold in a physical shop. A number on the row is worth having when they are not: it cannot be scammed, lost on death, or duplicated by a duping bug in another plugin. Servers that want both simply run both commands.

Opening

/killeffect crate, the button in the corner of the effects menu, or a bound block clicked empty-handed. The first screen asks only one thing: how many at once. Picking four spends four keys and drops four reels side by side on the next screen.

How many

menus/crate.yml. Choices are drawn up to crate.max-at-once, capped at seven by the width of the screen, and spread the way the reels will be — where you click is where that reel falls.

The reels fall

menus/crate_open.yml. One reel per crate, each running the full height of the chest, each with its own faces and its own finishing line crate.stagger-seconds after the one before it. Every face keeps its name and its lore the whole way down, so a reel can be read while it falls.

What went past stays

Nothing is cleared when a reel stops. What it came within one slot of stays on screen, because half of what a crate is worth is the legendary that went past the line.

Paid out as each reel lands

Keys are spent and prizes decided before the first frame, but nothing is handed over until a reel actually 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 mid-fall 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.

Duplicates

Landing on something already owned hands keys back — as many as crate.duplicate-refund says. At the default of 1 a duplicate is a free re-roll rather than a loss, which is what keeps a nearly complete collection worth opening.

Under crate.reward: ITEM nothing is unlocked at all, so no opening is ever a duplicate and the refund never comes into it: every key pays out a token.

Settings

crate:
  enabled: true
  start-keys: 0
  duplicate-refund: 1
  reward: UNLOCK
  blocks: []
  max-at-once: 4
  spin-frames: 34
  stagger-seconds: 2.0

Key	Default	What it does
`enabled`	`true`	Off, the button says so instead of opening.
`start-keys`	`0`	Keys a player is given the first time they are seen.
`duplicate-refund`	`1`	Keys handed back for something already owned.
`reward`	`UNLOCK`	What a crate hands over. `UNLOCK` keeps the effect on the account, `ITEM` hands over only its token, `BOTH` does both. `ITEM` and `BOTH` want `behaviour.mode` on `weapon` or `both`.
`blocks`	`[]`	The blocks that open the crate. Bind them in game, not by hand.
`max-at-once`	`4`	How many crates one player may open in one go. The screen fits seven.
`spin-frames`	`34`	How many faces the first reel runs through before it stops. Capped at 200, about eleven seconds.
`stagger-seconds`	`2.0`	How long after one reel stops the next one does. `0` stops them together.

on-spin, on-win and on-duplicate are full ExyliaLib effect blocks — title, action bar, boss bar, sound, particle and firework — played on every falling tick, and then once per reel the moment it lands: the win, or the duplicate instead when that reel stopped on something already owned.

Crate blocks

A physical block, anywhere in the world, that opens the crate when it is clicked:

/killeffectsadmin crate block add      # the block you are looking at
/killeffectsadmin crate block remove
/killeffectsadmin crate block list
/killeffectsadmin crate block clear

They are written to config.yml, not into the world, so a bound block survives a schematic paste, a world edit and a rollback. While it is bound it cannot be broken, blown up or pushed away, and clicking it no longer does what its material does — a crate drawn on a barrel must not open a barrel.

A block in a world that loads after the plugin — a hub a world manager brings up later — starts answering the moment that world loads.

What a crate hands over

Whatever comes out is written to the player's row rather than granted as a permission, so it outlives a rank running out. /killeffectsadmin unlocks grant|revoke|clear is the same door for a reward plugin that wants to hand an effect over without a crate.

Permissions and unlocks are two separate ways in

A player may use an effect they own from a crate or one their rank grants. Selling a rarity as a rank is one line — exyliakilleffect.tier.legendary — and it is independent of anything they unboxed.

Something missing on this page? Tell us on Discord