Rewards and odds
Rewards live under rewards: in the crate file. Each reward has a unique id and these options:
| Option | What it does |
|---|---|
kind | ITEM_ONLY, COMMAND_ONLY or ITEM_PLUS_COMMANDS. |
chance | A relative weight, not a hard percent. The percentages players see are the weight divided by the sum of all active weights. If you leave it out, the rarity tier's default-chance is used. |
rarity | A tier id from the crate or from config.yml (common, rare, epic, legendary by default). |
display-name, lore | How the reward looks in menus and animations (MiniMessage). |
item | material, amount, glow, custom-model-data, enchantments. Items added in the admin panel are stored as item.data and given exactly as they are. |
commands | A list of command plus console: true|false. {player} is replaced with the winner's name. |
limited.max-winners | Limited edition: the reward can only be won this many times. 0 means unlimited. |
start, end | ISO-8601 timestamps (like 2025-12-01T00:00:00Z) for a seasonal reward. |
enabled, retired | A disabled or retired reward is never rolled. |
cosmetic-key | The id used for duplicate detection. Defaults to the reward id. |
A reward is rolled only if it is enabled, not retired, inside its season and (for limited rewards) has copies left.
A real reward from the example crate:
dragon_egg:
kind: ITEM_PLUS_COMMANDS
chance: 1.0
rarity: legendary
display-name: "<gold>Dragon's Egg"
lore:
- "<dark_purple>Only 5 of these will ever be won."
- "<gray>First to claim it, keeps it."
item:
material: DRAGON_EGG
glow: true
custom-model-data: 2001
commands:
- command: "announce {player} claimed the Dragon's Egg!"
console: true
limited:
max-winners: 5
winners: []
Limited rewards#
Wins of limited rewards are tracked and the winners are listed in the reward tooltip (unwon rewards show ???). When one is won, mcVaults announces it to the whole server with a clickable link to your store, plays a sound and shows a particle burst around the winner. Configure this under broadcast: in config.yml.
Duplicates#
By default a duplicate is simply granted again. Add a duplicate: section to a crate to change that. A reward counts as owned once the player has won a reward with the same cosmetic-key.
| duplicate.policy | Behavior |
|---|---|
STACK | Default. Grant it again, silently. |
REROLL | Roll again (up to 5 tries), then pick from the rewards the player does not own yet. Rewards rolled earlier in the same x5 or x10 open count as owned. |
REFUND | Give back the key or the money spent on that open. |
GRANT | Pay duplicate.grant-amount in the crate's economy. |
COMMAND | Run duplicate.fallback-command from the console. {player} is replaced. |
Test your odds#
/mv simulate <crate> [opens] runs the odds simulator (default 10000 opens, at most 1,000,000) and prints how often each reward was won. It changes no player data.