MonthlyCrates Documentation

MonthlyCrates is a Bukkit-compatible crate plugin for giving players item-backed crate keys, running an opening animation, selecting one or many rewards, and delivering items and console commands. Crates are entirely file-driven: every YAML file in plugins/MonthlyCrates/crates/ is a crate.

The plugin supports two configuration formats:

• Native MonthlyCrates format for compact, purpose-built crate files.
• AdvancedCrates-compatible format for direct use of crate files that contain a top-level prizes: section, including size, final_prizes/best_prizes, rewards_dont_repeat, linked rewards, and AdvancedCrates-style messages.

The bundled example-lotus.yml is the direct AdvancedCrates-style Monthly Crate configuration. Its size: 11 and non-empty best_prizes mean an opening selects 11 regular rewards plus 1 best reward. It is deliberately not a one-reward example.

Quick start

1. Put the MonthlyCrates JAR in the server plugins/ directory and start the server once.
2. Review plugins/MonthlyCrates/crates/example-lotus.yml, or add your own YAML crate file.
3. Run /monthlycrates reload after editing crate files.
4. Give a test crate with /monthlycrates give <player> <crate-id> 1.
5. Hold the crate and right-click either air or a block to open it.

Use /monthlycrates list to see the crate IDs actually loaded. This is the safest way to catch a filename/ID mismatch.

How an opening works

1. A player right-clicks air or a block with a crate item that MonthlyCrates previously created.
2. The plugin reads the NBT API string monthly-crate-id, resolves that value to a loaded crate type, and prevents the same player from opening another crate until this opening finishes.
3. The visual animation plays around the player.
4. The configured normal pool is rolled the requested number of times. A best pool, if configured in AdvancedCrates format, contributes one more reward.
5. Guaranteed and linked rewards are added, then items and/or console commands are delivered.
6. Reward messages are sent. Crate-level summary messages run once for the entire opening, not once per selected reward.

If inventory space is unavailable, item rewards are dropped at the opener's feet. The key is consumed only once opening begins; if reward delivery fails, a replacement crate is returned.

Documentation map

• Installation & Setup: requirements, folders, test flow, reload behavior, and default-crate migration.
• Native Configuration: the concise MonthlyCrates schema and a complete example.
• AdvancedCrates Compatibility: multi-reward pools, size, best_prizes, linked/guaranteed rewards, and supported legacy keys.
• Animation Reference: available animation names and tuning values.
• Commands: player and administrator commands.
• Messages & Placeholders: per-reward, crate-summary, numbered, and compact broadcast placeholders.
• Permissions: the three available command permissions.
• Migration & Troubleshooting: moving from an older default, common configuration errors, and verification steps.

Requirements

• A Bukkit, Spigot, or Paper-compatible server using API version 1.13 or newer.
• Java compatible with the server runtime. The supplied build targets Java 8 bytecode.
• No required external plugin dependencies.

MonthlyCrates declares no PlaceholderAPI dependency. Its documented placeholders are replaced by MonthlyCrates itself.