Native MonthlyCrates Configuration

Use the native format when creating a new crate from scratch. A file is native format when it has a top-level item: and rewards: section and does not have a top-level prizes: section. If prizes: exists, MonthlyCrates loads the file in AdvancedCrates-compatible mode instead.

Complete example

Save this as plugins/MonthlyCrates/crates/weekly.yml, then run /monthlycrates reload.

# `id` is optional. Without it, the filename (`weekly`) is the ID.
id: weekly

item:
  material: ENDER_CHEST
  amount: 1
  name: '&b&lWeekly Crate'
  lore:
    - '&7Right-click to open.'
    - '&7Contains three rewards.'
  enchantments:
    DURABILITY: 1

animation:
  type: RoundAnimation
  duration_ticks: 60
  preview_interval_ticks: 3
  radius: 1.25

messages:
  player:
    - '&aYou opened the &b{crate}&a crate!'
  broadcast:
    - '&d&lLotus &7» &b{player} &7opened a &f{crate} &7crate.'
    - '&7They received: &f{reward}'

reward_selection:
  rewards_per_open: 3
  rewards_dont_repeat: true
  mode: WEIGHTED

rewards:
  money:
    type: COMMAND
    chance: 50
    preview:
      material: SUNFLOWER
      amount: 1
      name: '&e$50,000'
      lore: []
    commands:
      - 'eco give {player} 50000'
    messages:
      player:
        - '&aYou received &e$50,000&a.'

  diamonds:
    type: ITEM
    chance: 35
    item:
      material: DIAMOND
      amount: 16
      name: '&b16 Diamonds'
      lore:
        - '&7A weekly crate reward.'
    messages:
      broadcast:
        - '&b{player} &7won &f{reward}&7 from a weekly crate!'

  key:
    type: COMMAND
    chance: 15
    preview:
      material: TRIPWIRE_HOOK
      amount: 1
      name: '&6Legendary Key'
      lore: []
    commands:
      - 'crate key give {player} legendary 1'

The chance values in this example are relative weights because mode is WEIGHTED: money is selected roughly 50% of the time, diamonds 35%, and key 15% for each roll. With rewards_per_open: 3 and rewards_dont_repeat: true, the player receives all three different rewards when three positive-weight rewards are available.

Top-level sections

Section	Required	Purpose
`id`	No	Native crate ID. Defaults to the filename without `.yml`. It must use lowercase letters, digits, `_`, or `-`.
`item`	Yes	The physical key item that `/monthlycrates give` creates.
`animation`	No	Visual opening animation and timing. Defaults to `NoAnimation`.
`messages`	No	Messages sent once for the whole opening.
`reward_selection`	No	Number of normal-pool rolls, repeat behavior, and chance interpretation. Defaults to one percentage roll.
`rewards`	Yes	One or more named reward entries.
`final_rewards`	Only for `CosmicMonthlyAnimation`	Final reward pool used by Cosmic monthly openings.

`item` section

Key	Required	Rules
`material`	Yes	A supported XSeries/Bukkit material name, such as `ENDER_CHEST`, `TRIPWIRE_HOOK`, or `CHEST`.
`amount`	No	Must be exactly `1` for a crate key. The give command controls how many keys a player receives.
`name`	No	Display name. Supports `&` color codes.
`lore`	No	List of lore lines. Supports `&` color codes.
`enchantments`	No	Map of enchantment name to a level of at least `1`. This can be used to create a normal enchantment or visual glint where supported.

Item amounts for reward items must be between 1 and that material's Minecraft stack limit. For example, DIAMOND may be 1–64; a non-stackable item must be 1.

`animation` section

animation:
  type: RevealAnimation
  duration_ticks: 45
  preview_interval_ticks: 3
  radius: 1.25

Key	Default	Valid range / meaning
`type`	`NoAnimation`	One of the names in Animation Reference.
`duration_ticks`	Animation's default	`0`–`2400`. Twenty ticks are roughly one second.
`preview_interval_ticks`	`3`	`1`–`100`. Frequency at which preview visuals update.
`radius`	`1.25`	`0.25`–`8.0`, measured from the player.

The animation is visual only; it does not place or break a real crate block.

`reward_selection` section

reward_selection:
  rewards_per_open: 3
  rewards_dont_repeat: true
  mode: WEIGHTED

Key	Default	Meaning
`rewards_per_open`	`1`	Number of normal-pool rolls. May be `0` or greater.
`rewards_dont_repeat`	`false`	Prevents a selected reward from being selected again in the same normal-pool opening while another candidate exists.
`mode`	`PERCENTAGE`	`PERCENTAGE` or `WEIGHTED`; see below.
`best_rewards_per_open`	`0`	Final-pool rolls for native crates with `final_rewards`; `CosmicMonthlyAnimation` overrides this to `1`.

`PERCENTAGE` versus `WEIGHTED`

PERCENTAGE treats every chance as a segment of a 0–100 roll. Native chance values must be greater than zero and the total across all rewards cannot exceed 100. If the total is less than 100, the uncovered part of the roll grants no normal reward. This is useful for a genuine chance of receiving nothing, but it can yield fewer rewards than rewards_per_open during a multi-roll opening.

WEIGHTED treats chance as a relative weight. Values do not need to total 100; 50, 35, and 15 behave exactly like a 50/35/15 distribution. Use this mode for the predictable “give N rewards” behavior. With enough distinct positive-weight rewards and rewards_dont_repeat: true, a three-roll selection returns three distinct rewards.

CosmicMonthlyAnimation always uses weighted selection and overrides the opening to nine rewards rolls plus one final_rewards roll.

Native reward entries

Every entry beneath rewards: or final_rewards: needs a unique ID, type, and positive chance.

Item reward

rewards:
  diamonds:
    type: ITEM
    chance: 25
    item:
      material: DIAMOND
      amount: 16
      name: '&b16 Diamonds'
      lore: []
    # Optional alternate item used only in messages/animation previews.
    preview:
      material: DIAMOND_BLOCK
      amount: 1
      name: '&b16 Diamonds'
      lore: []
    messages:
      player:
        - '&aYou received &f{reward}&a.'

The item is delivered to the player. If preview is omitted, the item itself is used as the preview and the {reward} display name.

Command reward

rewards:
  balance:
    type: COMMAND
    chance: 75
    preview:
      material: SUNFLOWER
      amount: 1
      name: '&e$50,000'
      lore: []
    commands:
      - 'eco give {player} 50000'
      - 'tell {player} &aYour balance reward was delivered.'

At least one non-empty command is required. Commands execute as the server console, and a leading / is accepted but unnecessary. A command reward may omit preview; in that case its ID is used as its displayed reward name.

Reward-level messages.player and messages.broadcast are optional. Unlike crate-level messages, they run once for each selected reward.

Validation checklist

Use spaces, not tabs, in YAML.
Give every native reward a positive chance and a valid type of ITEM or COMMAND.
Keep native chance totals at or below 100, even in WEIGHTED mode.
Set item.amount: 1 for the crate item.
For CosmicMonthlyAnimation, add at least one positive-chance final_rewards entry.
Run /monthlycrates reload, inspect the log, and confirm the ID using /monthlycrates list.
Use Messages & Placeholders rather than PlaceholderAPI syntax for announcement fields.