Set up the crate
Give players keys, set the odds of each rarity and let them win effects instead of buying a rank.
A crate lets players spend keys, watch reels fall and keep the effect they land on. What they win is saved on their own account, so it outlives any rank.
Before you start#
The crate is on by default (crate.enabled: true). Players open it with /hiteffect crate, the Crate button of the effect menu or a crate block, and everyone holds exyliahiteffect.crate by default. They start with 0 keys, so give some first.
Steps#
Give a key
Run /hiteffectsadmin keys give <player> 5. This is a number saved on the player's account, so it cannot be dropped, duplicated or lost to a full inventory. A shop, vote or reward plugin can run the same command as console.
Open the crate
As that player run /hiteffect crate, choose how many to open and click the open button. One key opens one crate.
Put a crate in the world (optional)
Look at a block and run /hiteffectsadmin crate block add. Right-clicking it opens the crate. A bound block cannot be broken, blown up or pushed away while it is on the list.
Check that it works#
Run /hiteffectsadmin keys check <player>: it shows the keys held. After opening, the key count drops, the reel stops on an effect, and a new effect shows as owned in /hiteffect. If the reel lands on an effect the player already owns, they get crate.duplicate-refund keys back (default 1).
Going further#
Give keys as an item#
An item key can be sold at a shop stall, put in a kit or given to a friend: /hiteffectsadmin item key <player> [1-64]. Right-clicking a bound crate block while holding one opens it on the spot, one key and one reel, and the key leaves the hand as the reel starts. A left click never spends one, and a key cannot be placed as a block. The item is set by key-item in config.yml, and its name and lore by key-item in messages.yml.
Other key commands: /hiteffectsadmin keys take <player> [amount] and /hiteffectsadmin keys set <player> <amount>. crate.start-keys is how many keys a player gets the first time the plugin sees them.
Change the odds of a rarity#
Every effect has a rarity, written as tier: in the catalogue (Edit the effect catalogue). The rarity decides its colour, how often a reel stops on it and what exyliahiteffect.tier.<id> grants. The shipped weights are common 60, rare 25, epic 12 and legendary 3 under tiers in config.yml.
chance is a weight, not a percentage: delete epic and its share is spread over the others rather than leaving a gap. You can rename a rarity, invent mythic or delete legendary. An effect naming a rarity that no longer exists falls back to the first one, and an effect with no tier: is common.
Let ranks open several at once#
crate.max-at-once is how many crates a player opens in one go (default 4, seven at most, which is what the screen fits). To give one rank more, grant exyliahiteffect.crate.multi.<n>; the highest one a player holds wins. See Permissions. Several reels fall side by side, each stopping crate.stagger-seconds (default 2.0) after the one before, and each pays out as it lands. Closing the window costs nothing: the keys are already spent and the prizes still arrive.
Opening in 3D#
Set crate.opening: SPATIAL to replace the falling reels with a crate in the world in front of the player: a reel slows onto the prize, the prize is revealed and the won effect is tried on a mannequin. Sneaking skips to the end and hands the prize over at once. Its look is spatial/crate.yml. A player on a client older than 1.21.4 gets the inventory reels, and a player without exyliahiteffect.preview sees the prize as an icon with no mannequin. The default is INVENTORY.
Choose what a win hands over#
Set crate.reward:
| Value | What the player gets |
|---|---|
UNLOCK | The effect is unlocked on their account and picked from /hiteffect. It cannot be traded or lost. The default. |
ITEM | Only the token, to bind to a weapon, sell or give away. Nothing is unlocked, so there are no duplicates and duplicate-refund never applies. |
BOTH | Unlocked on the account and a token as well. |
ITEM and BOTH need behaviour.mode set to weapon or both, see Modes and tokens.
Grant or remove a won effect by hand#
An unlocked effect is written to the player's account, not granted as a permission, so a rank running out takes its category node but nothing that was won. A player owns an effect if a permission grants it or their account says they unlocked it. Admins write the second half with /hiteffectsadmin unlocks grant <player> <effect> and /hiteffectsadmin unlocks revoke <player> <effect>.
Turn the crate off#
crate.enabled: false leaves the button in place and has it say the crate is closed.
Technical details
crate:
enabled: true
start-keys: 0
duplicate-refund: 1
reward: UNLOCK
blocks: []
max-at-once: 4
spin-frames: 34
stagger-seconds: 2.0
opening: INVENTORY
tiers:
common:
name: "Common"
material: GRAY_DYE
color: "{muted}"
chance: 60.0
priority: 1| Tier key | What it does |
|---|---|
name | What menus and placeholders call the rarity. |
material | The item the rarity is drawn with. |
color | The colour its effects are written in, see Colours. |
chance | How often a reel stops on it, relative to the others. |
priority | Where it sits in menus; lower comes first. |
spin-frames is how many faces the first reel runs through before stopping; higher is a longer fall, capped at 200 (about eleven seconds). crate.blocks holds server,world,x,y,z,yaw,pitch: bind blocks in game rather than by hand. A block in a world that loads later answers the moment that world loads. The key item is told apart by data it carries, not by its name or material.
The keys are spent and the prizes decided before the first frame, but each is handed over as its reel stops. Leaving the server mid-spin settles the reel on the way out: the effect is unlocked now and any token waits in the reward queue until the next join. What a reel came within one slot of stays on screen when it stops. Block commands: /hiteffectsadmin crate block add|remove|list|clear.
Something missing on this page? Tell us on Discord