Skip to content

Migration & Troubleshooting

Moving from the old one-reward default

The current distribution includes example-lotus.yml, a direct AdvancedCrates-style configuration based on the provided Monthly Crate reference. It selects size: 11 normal prizes and one best_prizes reward.

An untouched single-reward default from an older MonthlyCrates build is detected on startup. MonthlyCrates keeps it as:

plugins/MonthlyCrates/crates/example-lotus.single-reward-backup.yml

and writes the current multi-reward default as example-lotus.yml.

Edited, renamed, and custom crate files are not overwritten. To update one intentionally:

  1. Back up the existing file outside the active crates/ folder, or give it a non-.yml extension temporarily.
  2. Copy the desired direct AdvancedCrates YAML into plugins/MonthlyCrates/crates/.
  3. Choose its filename carefully; in compatibility mode it becomes the crate ID.
  4. Run /monthlycrates reload.
  5. Run /monthlycrates list, issue one test key, and confirm the normal and best reward counts.

If you leave both the old and new files enabled, they load as separate crates with separate IDs. This is useful for staged testing but can confuse staff issuing keys.

Moving a direct AdvancedCrates config

  1. Copy the crate YAML without converting its prizes hierarchy.
  2. Keep prizes, size, and, where required, final_prizes or best_prizes at the root.
  3. Verify every prize has either give_configured_item: true with material, or one or more commands.
  4. Reload and inspect the server console for the exact file error if the crate is skipped.
  5. Use numbered {ColoredReward:n} placeholders or the compact placeholders described in Messages & Placeholders.

The compatibility page lists intentionally unsupported legacy visual/UI fields. A config can contain them for use on an AdvancedCrates server, but MonthlyCrates will not implement their behavior.

Why am I receiving only one reward?

Check these in order:

  1. Run /monthlycrates list and make sure the issued key uses the crate ID you edited. An old key with a different embedded ID opens that other crate definition.
  2. In a direct AdvancedCrates config, set root-level size higher than 1. size: 11 means eleven regular selections.
  3. Add a non-empty final_prizes or best_prizes section if one extra final/best selection is expected. A final pool adds one reward; it is independent of size except for CosmicMonthlyAnimation, which always uses nine prizes rolls and one final-pool roll.
  4. For native YAML, set reward_selection.rewards_per_open higher than 1, preferably with mode: WEIGHTED for predictable multi-selection.
  5. With native PERCENTAGE mode, ensure chance totals reach 100 if every roll must produce a reward. Otherwise some rolls intentionally select nothing.
  6. Reload after saving and watch for configuration warnings. A skipped file cannot replace an already loaded crate.

Common configuration errors

Symptom or log message Cause Resolution
rewards must contain at least one reward Native file has no valid rewards: entries. Add at least one item or command reward.
prizes must contain at least one reward Compatibility file has no valid prizes: entries. Add a prize section.
item.amount must be 1 or crate.amount must be 1 The crate key itself was configured as a stack. Set the crate item amount to 1; use the give command's amount argument for key stacks.
chance ... non-negative A compatible prize has a negative or invalid chance. Use zero or a positive number. Zero works only for a guaranteed reward.
Native chance-total error Native reward chances total over 100. Reduce the total to 100 or below. This validation applies even when native mode is WEIGHTED.
commands cannot be empty A native command reward has no command. Add at least one non-empty command.
material is not supported The material is misspelled or unavailable on the server version. Use a supported uppercase XSeries/Bukkit material name.
Unknown crate animation Animation name is not one of the supported aliases. Use an entry in Animation Reference.
Crate file is skipped Bad YAML, duplicate crate ID, or a validation failure. Check the first MonthlyCrates warning in the console; fix that file and reload.

Safe test procedure

  1. Copy the production crate file to a test server.
  2. Use /monthlycrates reload and /monthlycrates list.
  3. Issue one key with /monthlycrates give <tester> <crate-id> 1.
  4. Record the expected normal count (size or rewards_per_open), best count, and any guaranteed/linked prizes.
  5. Open several keys, watching both the inventory and server console command output.
  6. Test the broadcast with one selection and multiple selections, especially if using {additional_rewards} or numbered placeholders.

Remember that weighted selection is random. Test multiple openings before judging relative chance behavior; use guaranteed_reward when a reward must arrive every time.