AdvancedCrates Compatibility & Multi-Reward Openings

MonthlyCrates recognizes an AdvancedCrates-style crate automatically when the YAML has a top-level prizes: section. This lets a direct crate configuration retain the important reward behavior instead of reducing every opening to one reward.

The bundled example-lotus.yml is in this format. It has size: 11, rewards_dont_repeat: true, regular prizes, and best_prizes; one opening therefore delivers eleven normal rewards and one best reward, subject to linked and guaranteed additions.

Minimal compatible crate

animation: RoundAnimation
material: ENDER_CHEST
amount: 1
name: '&b&lMonthly Crate'
lores:
  - '&7Right-click to open.'

# Select 3 normal prizes on every opening.
size: 3
rewards_dont_repeat: true

final_message:
  - '&d&lLotus &7» &b{player_name} &7opened a Monthly Crate!'
  - '&7Rewards: &f{ColoredReward:1}&7, &f{ColoredReward:2}&7, &f{ColoredReward:3}'
  - '&7Best: &f{ColoredReward:best}'

prizes:
  money:
    material: SUNFLOWER
    amount: 1
    name: '&e$50,000'
    lores: []
    give_configured_item: false
    commands:
      - 'eco give {player_name} 50000'
    chance: 50

  diamonds:
    material: DIAMOND
    amount: 16
    name: '&b16 Diamonds'
    lores: []
    give_configured_item: true
    chance: 35

  key:
    material: TRIPWIRE_HOOK
    amount: 1
    name: '&6Legendary Key'
    lores: []
    give_configured_item: false
    commands:
      - 'crate key give {player_name} legendary 1'
    chance: 15

best_prizes:
  rank:
    material: NETHER_STAR
    amount: 1
    name: '&d30 Day Rank'
    lores: []
    give_configured_item: false
    commands:
      - 'lp user {player_name} parent addtemp vip 30d'
    chance: 1

The file's crate ID is its filename without .yml; an id: value is not used in this compatibility format. For example, save it as monthly.yml and give it with /monthlycrates give <player> monthly 1.

Pool selection

`prizes` and `size`

prizes is the regular reward pool. size is the number of regular selections per opening and defaults to 1. Set it to 11 to mimic an eleven-reward monthly crate.

Each compatible chance is a relative weight, not a strict percent. A reward with chance: 10 is twice as likely as one with chance: 5; the values do not need to total 100 and may exceed 100. A zero chance is never randomly selected.

`rewards_dont_repeat`

Set rewards_dont_repeat: true to prevent the same randomly selected entry from being selected twice in the same pool while distinct candidates remain. If there are fewer distinct entries than size, MonthlyCrates continues rolling the available pool, so repeats can occur after all candidates have been used.

This flag applies separately to the regular and best pools. It does not stop a reward from being added by guaranteed_reward or linked_rewards.

`best_prizes` and `final_prizes`

If best_prizes exists and is non-empty, MonthlyCrates selects one additional best reward after the normal size selections. final_prizes is also accepted and is preferred for Cosmic monthly crates. The pool uses the same relative-weight and rewards_dont_repeat rules, but its results are kept separate for {ColoredReward:best}.

There is currently one automatic best-pool selection per compatible crate opening; do not expect size to change that number.

CosmicMonthlyAnimation is the exception to the size rule: it always rolls nine rewards from prizes and one reward from final_prizes/best_prizes.

Supported root-level options

Key	Supported behavior
`animation`	Uses the named MonthlyCrates visual animation. See Animation Reference.
`material`, `amount`, `name`, `lores`	Define the crate key. Root `amount` must be `1`.
`size`	Number of normal-pool selections. Must be zero or greater.
`rewards_dont_repeat`	Enables no-repeat selection within each pool.
`prizes`	Required regular reward pool.
`final_prizes`, `best_prizes`	Optional pool contributing one final/best reward. `final_prizes` is preferred for Cosmic monthly crates.
`messages_to_player`, `final_message_to_opener`	Private, crate-level summary messages.
`broadcast_messages_to_players`, `final_message`	Broadcast, crate-level summary messages.

final_message is emitted once per opening after all rewards are known. It is not repeated for every prize, so a 12-reward monthly opening produces one complete announcement.

Supported prize options

Key	Supported behavior
`material`, `amount`, `name`, `lores`	The item definition and visual preview. `amount` must be valid for the material's stack size.
`chance`	Non-negative relative selection weight.
`give_configured_item`	When `true`, gives the configured item directly. The old mixed-case AdvancedCrates alias is still accepted for unconverted files.
`commands`	List of console commands to run for this reward. A leading `/` is optional.
`guaranteed_reward`	Adds this reward to every opening in addition to random selections.
`linked_rewards`	List of other prize IDs to add when this reward is selected. Links can resolve across both pools.
`messages_to_player`	Private messages for this selected reward.
`broadcast_messages_to_players`	Broadcast messages for this selected reward.
`final_message`	Broadcast messages for this selected reward; normally prefer a root-level `final_message` for one full-opening summary.

Every compatible prize must either set give_configured_item: true (and provide material) or contain at least one commands entry. Both can be used together: the player receives the item and all commands run.

Guaranteed and linked rewards

prizes:
  monthly-bonus:
    material: EMERALD
    amount: 4
    name: '&aMonthly Bonus'
    lores: []
    give_configured_item: true
    guaranteed_reward: true
    chance: 0

  gkit:
    material: NETHER_STAR
    amount: 1
    name: '&dGKit Voucher'
    lores: []
    give_configured_item: false
    commands:
      - 'gkit give {player_name} archer'
    linked_rewards:
      - monthly-bonus
    chance: 5

monthly-bonus is delivered every time even though it has zero random chance. When gkit wins, its linked monthly-bonus is also added. MonthlyCrates follows links recursively, ignores unknown link IDs, and stops cycles safely. A reward is only linked once during an opening, even if multiple selected rewards refer to it.

Deliberately unsupported or visual-only legacy fields

MonthlyCrates accepts the structure needed for crate key, selections, delivery, and messaging. It is not a complete reimplementation of every AdvancedCrates presentation feature. The following fields are not applied by MonthlyCrates and should not be relied on:

Field or family	Current result
`only_placable`, `command_on_crate_place`, `key_crate`	No placed-crate/key-crate behavior; use the tagged key by right-clicking air or a block.
`middle_animation_item`, `reward_hologram`	No custom legacy middle item or hologram text. The plugin displays its own item previews.
`rewards_preview_gui_title`, `prize_size`	No reward-preview GUI.
`enchanted`, `glow`, `damage`, `nbt_tags`, `item_flags`	These legacy item decorations are not applied.
`enchantments` in a compatible prize	Not parsed in compatibility mode. Use supported item material/name/lore or a command from an item plugin.

Keep such fields in a shared file if another server still uses AdvancedCrates; MonthlyCrates ignores them. Test every changed crate using /monthlycrates reload and a real key before publishing it.