Rewards and rarities
The weighted reward editor, how a prize is drawn, rarities as bands of the real odds in tiers.yml, rewards per key, the guarantee, and the contents screen with its real odds.
Rewards
Rewards → Rewards on a crate's overview opens ExyliaLib's weighted reward editor. A reward is one of:
| Type | Gives |
|---|---|
| Item | An item, taken from your hand, with its own name, enchantments and lore. |
| Command | A console command run for the winner. |
| Economy | An amount of money, in a currency of your choice (the default one when none is picked). Paid with the reason crates:prize, so economy statistics show what crates hand out; prefer it over an eco give command. |
| Experience | Experience. |
| Potion | A potion effect, such as SPEED|2|15. |
| Message | A line sent to the winner. |
Each reward also has a display name and icon (what the screens and the animations show), an optional amount range, a weight, a chance, and an optional permission and condition.
In the editor, shift + left-click raises a reward's weight and shift + right-click lowers it, in steps that grow with the weight (tenths below 1, then ones, fives and tens), never below 0.1. Every row shows its real share of the crate and its rarity, redrawn as you click. Sort by weight orders the list most common first; press it again for the rarest first. Nothing is saved until you save; cancelling leaves the crate as it was.
How a prize is drawn
The prize is decided the moment the key is spent, before the animation starts. The animation only shows it.
Who can win what
Rewards whose permission or condition the player does not meet are taken out of the draw for them. If nothing is left the player is told "This crate has no rewards yet." and nothing is charged.
The weighted draw
One reward is picked in proportion to its weight. Weights are relative: a reward weighted 10 next to one weighted 5 comes out twice as often, and the numbers do not have to add up to anything.
Its own chance
The picked reward then rolls its own chance. If it misses, the draw starts again — a key always opens something. In effect each reward comes out in proportion to weight × chance.
Its amount
An amount range is rolled now, so the stack the animation shows is the stack the player gets.
A draw is tried up to 16 times. A crate whose rewards all have a low chance can miss all 16, and that draw pays nothing. If every draw of an opening misses, the player is told "This crate has no rewards yet." and the keys are still spent. Leave chance at 100 and use the weight to make a reward rare.
Rewards per key
Rewards → Rewards per key: a minimum and a maximum, 1 to 9 each. Every key pays a random number of rewards in that range, each drawn on its own; the same reward can come out twice. Raising the minimum above the maximum raises the maximum with it, and the other way round.
Rarities
A rarity is not a label you set on a reward. It follows the real odds: a rarity is a band of a reward's
share of the crate, with a name, a colour, whether winning it is announced, and what plays when it comes out.
They live in tiers.yml.
A reward's share is its weight × chance over the sum of weight × chance of every reward in the crate, in percent: the same number the reward editor shows on each row. Weights only mean something against each other, so a crate whose rewards all weigh 1 is a fair draw, not a crate of legendaries.
tiers:
legendary:
display: "{highlight}&lLEGENDARY"
color: "{highlight}"
max-chance: 1.0
broadcast: true
celebrate:
- "[SOUND] ENTITY_PLAYER_LEVELUP;0.7;1.2"
- "[TITLE] %tier%;{letters}%reward%;0.1;2.5;0.6"
- "[BEAM] END_ROD;height:7;points:34;y:0.2"
- "[RING_PULSE] END_ROD;radius:0.6;rings:3;points:16;y:0.4"
epic:
display: "{accent}&lEPIC"
color: "{accent}"
max-chance: 5.0
broadcast: true
celebrate: [ ... ]
rare:
display: "{info}&lRARE"
color: "{info}"
max-chance: 20.0
broadcast: false
celebrate: [ ... ]
common:
display: "{letters_black}&lCOMMON"
color: "{letters_black}"
max-chance: 100.0
broadcast: false
celebrate:
- "[SOUND] ENTITY_ITEM_PICKUP;0.8;1.2"| Key | Meaning |
|---|---|
display | What menus, announcements and the reveal call it. |
color | The palette token the reward's name is written in on the screens. |
max-chance | The highest share, in % of the crate's drops, that still counts as this rarity. |
broadcast | Announce to the whole server when somebody wins one. See Openings. |
celebrate | Effect lines played once where the prize comes out, whatever the animation. |
A reward belongs to the first rarity, ordered by max-chance, whose max-chance it does not exceed. A
share above every band still belongs to the widest one, so keep the last rarity at 100. You can rename,
remove or add rarities; their ids are what the guarantee and the Tier Slots gems refer to.
With the default file a reward that is 1% of the crate or less is legendary, up to 5% epic, up to 20% rare, and anything more common. Because the share is read against the other rewards, adding, removing or re-weighting one reward can move the others to another rarity; the editor redraws every row's rarity as you click.
tiers.yml used to band rarities by raw weight (max-weight). On the first start of 1.1.0 each tier's
max-weight is replaced by the max-chance of the shipped band its old weight sat in (1, 5, 20 or 100), so
renamed and custom tiers keep their place. The shipped celebration lines are quietened in the same pass:
fireworks and screen shake are dropped, the toast sound becomes a level-up and the sounds play softer. A line
you wrote yourself is left as it is.
Celebrations
celebrate lines are ExyliaLib sequences. %reward%, %tier%, %tier_color%, %player%, %crate% and
%amount% are filled in, and {item:reward} draws the prize's icon. who:nearby on a [TITLE] or
[MESSAGE] line reaches everybody watching instead of the opener only; a [CAMERA] line with who:source
gives the opener a camera shot of their own. See Sequences.
The celebration is the only place the reveal's sound lives: when it plays a [SOUND], the chat line telling
the opener what they won drops its own leading sound tag.
In a bulk opening the celebration is that of the rarest prize.
The guarantee
A crate can promise a rarity after a number of openings: "a legendary at least every 50 keys".
Rewards → Guarantee: left-click sets the number of openings (0 to 500, 0 is off), right-click picks
the rarity from tiers.yml, shift + left-click turns it off (keeping the rarity for later).
- Each player has a counter per crate. Every opening adds one.
- When the counter reaches the number, the first reward of that opening is drawn only among rewards of the guaranteed rarity.
- Winning a reward of that rarity — guaranteed or by luck — sets the counter back to 0.
- A bulk opening moves the counter once per key: ten keys at once are ten openings closer.
The counter is per player and crate, stored in the database, and shared across a network.
A number set without a rarity guarantees nothing: the contents screen says "No guarantee", though
%exyliacrates_crate_pity_<crate>% still counts down. And a rarity the crate holds no reward of cannot be
paid: the opening falls back to an ordinary draw, the counter never resets, and the contents screen keeps
saying the next one is guaranteed.
The contents screen
Left-clicking a crate block, /crates preview <crate> or Player view on the overview opens the crate's
contents: every reward, rarest first, each with its rarity and its chance.
The chance shown is the real one for the player looking: weight × chance of each reward, over every reward they can win. A reward they cannot win — missing permission or condition — shows Locked.
The crate's own item at the bottom shows how many keys they hold for it (items and balance of the first key
it takes) and how far they are from the guarantee: "4 more to LEGENDARY", or "The next one is LEGENDARY!".
Clicking it opens the crate; shift-clicking opens as many as they can pay for. That opening plays in front
of the player, wherever they stand, not on the block — the same as /crates open.
Your openings opens the player's own history, with a way back to the contents.
Something missing on this page? Tell us on Discord