Using it

Rewards and odds

Rewards live under rewards: in the crate file. Each reward has a unique id and these options:

OptionWhat it does
kindITEM_ONLY, COMMAND_ONLY or ITEM_PLUS_COMMANDS.
chanceA 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.
rarityA tier id from the crate or from config.yml (common, rare, epic, legendary by default).
display-name, loreHow the reward looks in menus and animations (MiniMessage).
itemmaterial, amount, glow, custom-model-data, enchantments. Items added in the admin panel are stored as item.data and given exactly as they are.
commandsA list of command plus console: true|false. {player} is replaced with the winner's name.
limited.max-winnersLimited edition: the reward can only be won this many times. 0 means unlimited.
start, endISO-8601 timestamps (like 2025-12-01T00:00:00Z) for a seasonal reward.
enabled, retiredA disabled or retired reward is never rolled.
cosmetic-keyThe 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.policyBehavior
STACKDefault. Grant it again, silently.
REROLLRoll 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.
REFUNDGive back the key or the money spent on that open.
GRANTPay duplicate.grant-amount in the crate's economy.
COMMANDRun 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.