A Best Crates

ABestCrates 1.2.2

Version 1.2.2 adds admin maintenance tools, crate templates, config versioning, statistics GUI improvements, and release polish for the Paper 1.20.x branch.

Added

- Admin commands and GUI tools for resetting player cooldowns, player open stats, player reward limit counters, and global reward limit counters. - Admin Tools statistics GUI for viewing a player's crate history, players who opened a selected crate, player totals, and the most-opened crates. - Crate duplication with /abc duplicate <crate> <newName>. - Crate template export/import with /abc export <crate> [file] and /abc import <file> [newName]. - Template files stored under plugins/ABestCrates/templates. - config-version: 2 markers for generated configuration files. - bStats integration wiring, controlled by metrics.enabled and metrics.plugin-id in config.yml. - Insert Nickname lookup for player statistics and Give Keys GUI workflows. - Additional unit coverage for crate IDs, safe value clamping, reward settings, and zero-chance reward rolls.

Changed

- Chat prompts, command help, protected-crate, admin, and template messages now live in messages.yml. - Player open data now stores last-known player names for easier offline stat lookup.

Fixed

- Modern Paper serialized ItemStack fields in crate files are normalized before loading to avoid Material cannot be null startup errors. - Existing bundled config files are no longer recopied on startup, removing noisy already-exists warnings.

Requirements

- Paper 1.20.1-1.20.6. - Java 17 for Paper 1.20.1-1.20.4. - Java 21 for Paper 1.20.5-1.20.6 and 1.21.x. - Vault and PlaceholderAPI remain optional.

ABestCrates 1.2.1

Version 1.2.1 is a stability release focused on routine bug fixes and safer edge-case handling.

Fixed

- Rewards with 0.0 real or effective chance can no longer be selected when the random roll lands exactly on the lower boundary. - Virtual key displays now refresh after crate renames migrate stored virtual key balances. - Empty virtual-key entries are removed after the last key is consumed or removed. - Vault economy reconnects now clear stale hooks before checking for an available provider. - PlaceholderAPI expansion requests safely ignore empty or null placeholder parameters. - Virtual key display refreshes now guard against teleport events without a destination. - Reward lookup and removal now handle null IDs safely, and blank reward IDs are normalized to a safe fallback.

Requirements

- Paper 1.20.1-1.20.6. - Java 17 for Paper 1.20.1-1.20.4. - Java 21 for Paper 1.20.5-1.20.6. - Vault and PlaceholderAPI remain optional.

ABestCrates 1.2.1

Version 1.2.1 is a stability release for the Paper 1.21.x branch.

Fixed

- Rewards with 0.0 real or effective chance can no longer be selected when the random roll lands exactly on the lower boundary. - Virtual key displays now refresh after crate renames migrate stored virtual key balances. - Empty virtual-key entries are removed after the last key is consumed, removed, or loaded from disk. - Virtual-key rename/removal now avoids unnecessary disk saves when no balances changed. - Vault economy reconnects now clear stale hooks when Vault is unavailable, disabled, or incompatible. - PlaceholderAPI expansion requests safely ignore empty placeholder parameters. - Virtual key display refreshes now guard against teleport events without a destination. - Reward lookup and removal now handle null IDs safely, and blank reward IDs are normalized to a safe fallback.

Requirements

- Java 21. - Paper 1.21.x. - Vault and PlaceholderAPI remain optional.

ABestCrates 1.2.0

Version 1.2.0 expands crate openings with new animations, multi-reward rolls, improved previews, paginated menus, and cleaner configuration files.

New opening animations

- Added Roll/CSGO with fast initial movement and progressive slowdown before stopping on the rewards. - Added Casino, Cosmic, Roulette, Wheel, and Wonder opening layouts. - Opening cycle, slowdown, and finish sounds can now be configured in config.yml.

Multiple rewards

- Crates can now roll from 1 to 9 different rewards per opening. - Every selected reward is displayed in the animation and awarded when it finishes. - CHOOSE crates support selecting multiple rewards when multiple rolls are configured. - Multiple rewards still consume the configured key requirements only once per opening.

Preview and GUI improvements

- Reward previews are now centered inside the inventory. - Added Open this crate and Open with all keys buttons to the preview GUI. - Added pagination for crate, reward, preview, and key-distribution menus. - Added light gray stained-glass fillers to empty GUI slots. - Reward item bundles now support regular drag and drop as well as Shift-clicking items directly from the player inventory.

Keys and commands

- Multiple key requirements for one crate remain fully supported. - Added /abc giveall <crate> <amount> [physical|virtual] to give keys to every online player.

Configuration

- Added dedicated configuration files: - config.yml — global settings, rarities, particles, mass opening, and sounds. - crates.yml — crate and reward definitions. - keys.yml — physical key definitions and custom key items. - messages.yml — plugin messages. - Existing key definitions stored in the old crates.yml format are loaded and migrated on save. - Existing installations remain compatible with legacy messages stored in config.yml.

Requirements

- Paper 1.21.x or 1.20.x. - Java 21 - Vault and PlaceholderAPI remain optional.

ABestCrates 1.2.0

Version 1.2.0 expands crate openings with new animations, multi-reward rolls, improved previews, paginated menus, and cleaner configuration files.

New opening animations

- Added Roll/CSGO with fast initial movement and progressive slowdown before stopping on the rewards. - Added Casino, Cosmic, Roulette, Wheel, and Wonder opening layouts. - Opening cycle, slowdown, and finish sounds can now be configured in config.yml.

Multiple rewards

- Crates can now roll from 1 to 9 different rewards per opening. - Every selected reward is displayed in the animation and awarded when it finishes. - CHOOSE crates support selecting multiple rewards when multiple rolls are configured. - Multiple rewards still consume the configured key requirements only once per opening.

Preview and GUI improvements

- Reward previews are now centered inside the inventory. - Added Open this crate and Open with all keys buttons to the preview GUI. - Added pagination for crate, reward, preview, and key-distribution menus. - Added light gray stained-glass fillers to empty GUI slots. - Reward item bundles now support regular drag and drop as well as Shift-clicking items directly from the player inventory.

Keys and commands

- Multiple key requirements for one crate remain fully supported. - Added /abc giveall <crate> <amount> [physical|virtual] to give keys to every online player.

Configuration

- Added dedicated configuration files: - config.yml — global settings, rarities, particles, mass opening, and sounds. - crates.yml — crate and reward definitions. - keys.yml — physical key definitions and custom key items. - messages.yml — plugin messages. - Existing key definitions stored in the old crates.yml format are loaded and migrated on save. - Existing installations remain compatible with legacy messages stored in config.yml.

Requirements

- Paper 1.21.x or 1.20.x. - Java 21 - Vault and PlaceholderAPI remain optional.

Changelog

All notable changes to the ABestCrates project are documented in this file.

[1.1.0] - 2026-06-20

Added

- Two crate modes: - GAMBLE — rolls a reward using weights and rarity multipliers. - CHOOSE — allows the player to select a reward without gambling. - Crate particle effects: RING, SPIRAL, HELIX, and DYSON_SPHERE. - A personalized virtual key counter displayed below each crate hologram. - Global and per-crate options for enabling the virtual key display. - Placeable crate items that are automatically linked to their crate definition. - The /abc givecrate <player> <crate> <amount> command. - The abestcrates.crateitem permission. - A command-free key distribution workflow in the GUI: - select a physical or virtual key, - select a crate, - select a player, - enter the amount in chat. - Multiple key requirements for a single crate. - Vault economy costs for opening crates. - Per-player and per-crate opening cooldowns. - Permission requirements for individual crates. - Optional pushback for players who do not meet crate requirements. - Milestones that grant bonus rewards for consecutive openings of the same crate. - Global and per-player reward limits. - Required and blocked permissions for individual rewards. - An automatically scalable reward weight system. - Configurable rarity-based weight multipliers in config.yml. - Item rewards containing up to 27 items with a dedicated GUI editor. - Unlimited commands assigned to a reward. - Dedicated reward roll logging in reward-rolls.log. - Opening counts, cooldowns, limits, and player streaks stored in player-data.yml. - Custom preview and opening GUI titles for every crate. - A PlaceholderAPI expansion with the following placeholders: - %abestcrates_virtual_<crate>% - %abestcrates_physical_<crate>% - %abestcrates_total_<crate>% - %abestcrates_opened_<crate>%

Expanded

- The crate GUI editor with crate modes, effects, key counters, costs, cooldowns, permissions, pushback, key requirements, milestones, and GUI titles. - The reward GUI editor with rarity, weight, commands, item bundles, permissions, broadcasts, fireworks, and limits. - The reward system with functional item, command, and mixed reward types. - Mass Open with multiple key requirements, reward limits, economy costs, and rarity weights. - The key system with safe splitting of large physical key amounts into multiple stacks. - Crate ID renaming to also update key requirements, crate items, and keys held by online players. - Custom item support by preserving complete Bukkit ItemStack metadata, including data from Nexo, ItemsAdder, Oraxen, ExecutableItems, and MMOItems. - Holograms with owner-only virtual key information. - Crate block protection and automatic visual refreshing after configuration changes.

Integrations

- Added optional Vault integration for crate opening costs. - Added optional PlaceholderAPI integration with version 2.11.6 as a provided dependency. - Added soft dependencies for Vault, PlaceholderAPI, Nexo, ItemsAdder, Oraxen, ExecutableItems, and MMOItems.

Configuration

- Added the virtual-key-display section. - Added the particles section. - Added the mass-open.max-at-once safety limit. - Added configurable rarity multipliers. - Added messages for costs, cooldowns, milestones, CHOOSE crates, permissions, and crate items. - Preserved compatibility with the previous crates.yml format; existing single-item rewards are automatically loaded by the new reward system.

Changelog

All notable changes to the ABestCrates project are documented in this file.

[1.1.0] - 2026-06-20

Added

- Two crate modes: - GAMBLE — rolls a reward using weights and rarity multipliers. - CHOOSE — allows the player to select a reward without gambling. - Crate particle effects: RING, SPIRAL, HELIX, and DYSON_SPHERE. - A personalized virtual key counter displayed below each crate hologram. - Global and per-crate options for enabling the virtual key display. - Placeable crate items that are automatically linked to their crate definition. - The /abc givecrate <player> <crate> <amount> command. - The abestcrates.crateitem permission. - A command-free key distribution workflow in the GUI: - select a physical or virtual key, - select a crate, - select a player, - enter the amount in chat. - Multiple key requirements for a single crate. - Vault economy costs for opening crates. - Per-player and per-crate opening cooldowns. - Permission requirements for individual crates. - Optional pushback for players who do not meet crate requirements. - Milestones that grant bonus rewards for consecutive openings of the same crate. - Global and per-player reward limits. - Required and blocked permissions for individual rewards. - An automatically scalable reward weight system. - Configurable rarity-based weight multipliers in config.yml. - Item rewards containing up to 27 items with a dedicated GUI editor. - Unlimited commands assigned to a reward. - Dedicated reward roll logging in reward-rolls.log. - Opening counts, cooldowns, limits, and player streaks stored in player-data.yml. - Custom preview and opening GUI titles for every crate. - A PlaceholderAPI expansion with the following placeholders: - %abestcrates_virtual_<crate>% - %abestcrates_physical_<crate>% - %abestcrates_total_<crate>% - %abestcrates_opened_<crate>%

Expanded

- The crate GUI editor with crate modes, effects, key counters, costs, cooldowns, permissions, pushback, key requirements, milestones, and GUI titles. - The reward GUI editor with rarity, weight, commands, item bundles, permissions, broadcasts, fireworks, and limits. - The reward system with functional item, command, and mixed reward types. - Mass Open with multiple key requirements, reward limits, economy costs, and rarity weights. - The key system with safe splitting of large physical key amounts into multiple stacks. - Crate ID renaming to also update key requirements, crate items, and keys held by online players. - Custom item support by preserving complete Bukkit ItemStack metadata, including data from Nexo, ItemsAdder, Oraxen, ExecutableItems, and MMOItems. - Holograms with owner-only virtual key information. - Crate block protection and automatic visual refreshing after configuration changes.

Integrations

- Added optional Vault integration for crate opening costs. - Added optional PlaceholderAPI integration with version 2.11.6 as a provided dependency. - Added soft dependencies for Vault, PlaceholderAPI, Nexo, ItemsAdder, Oraxen, ExecutableItems, and MMOItems.

Configuration

- Added the virtual-key-display section. - Added the particles section. - Added the mass-open.max-at-once safety limit. - Added configurable rarity multipliers. - Added messages for costs, cooldowns, milestones, CHOOSE crates, permissions, and crate items. - Preserved compatibility with the previous crates.yml format; existing single-item rewards are automatically loaded by the new reward system.

ABestCrates

ABestCrates is a modern, GUI-first crates plugin for Paper servers. It lets server owners create and manage crates, keys, rewards, chances, animations, holograms, and messages directly in-game without manually editing configuration files.

Features

- Fully configurable crates managed from an in-game GUI - Physical keys with custom item support - Virtual keys stored per player - Item rewards, command rewards, or mixed rewards - Real chance and display chance support - Reward preview GUI - Classic, fast, and instant opening animations - Display-name holograms above placed crates - Custom crate block material - Crate color presets - Bulk opening with shift-left click - Right-click preview and left-click opening - Protected placed crates against breaking and explosions - Rare reward broadcasts - Firework effects - Custom messages - Tab completion for commands, players, crates, and key amounts

Crate Editing

Administrators can configure crates from the GUI: - Display name - Technical crate name - Crate color - Block type - Hologram lines - Rewards - Key item - No-key message - Opening animation - Reward preview Items can be assigned by holding them in hand, clicking the target slot, or dragging an item into the GUI. Custom key items copy the original item attributes while replacing only the key name.

Rewards

Each reward can have: - Custom display item - Dropped item - Commands - Real chance - Display chance - Rarity text - Broadcast toggle - Firework toggle This allows public-facing odds to be shown separately from the real internal roll chance.

Commands

Main command:

/abestcrates

Aliases:

/abc
/acrates

Admin commands:

/abc gui
/abc reload
/abc create <name>
/abc delete <name>
/abc deletecrate
/abc spawncrate <name>
/abc edit <name>
/abc givekey <player> <crate> <amount>
/abc addkeys <player> <crate> <amount>
/abc removekeys <player> <crate> <amount>
/abc forceopen <player> <crate>

Permissions

abestcrates.admin
abestcrates.use
abestcrates.open
abestcrates.create
abestcrates.givekey
abestcrates.reload

Players need abestcrates.use to open crates.

Player Interaction

- Right-click a placed crate to preview rewards - Left-click a placed crate to open it - Shift-left-click a placed crate to open all matching keys Bulk opening checks inventory space before consuming keys.

Compatibility

ABestCrates is designed for modern Paper servers and uses the current Paper API.

License

All Rights Reserved.

ABestCrates

ABestCrates is a modern, GUI-first crates plugin for Paper servers. It lets server owners create and manage crates, keys, rewards, chances, animations, holograms, and messages directly in-game without manually editing configuration files.

Features

- Fully configurable crates managed from an in-game GUI - Physical keys with custom item support - Virtual keys stored per player - Item rewards, command rewards, or mixed rewards - Real chance and display chance support - Reward preview GUI - Classic, fast, and instant opening animations - Display-name holograms above placed crates - Custom crate block material - Crate color presets - Bulk opening with shift-left click - Right-click preview and left-click opening - Protected placed crates against breaking and explosions - Rare reward broadcasts - Firework effects - Custom messages - Tab completion for commands, players, crates, and key amounts

Crate Editing

Administrators can configure crates from the GUI: - Display name - Technical crate name - Crate color - Block type - Hologram lines - Rewards - Key item - No-key message - Opening animation - Reward preview Items can be assigned by holding them in hand, clicking the target slot, or dragging an item into the GUI. Custom key items copy the original item attributes while replacing only the key name.

Rewards

Each reward can have: - Custom display item - Dropped item - Commands - Real chance - Display chance - Rarity text - Broadcast toggle - Firework toggle This allows public-facing odds to be shown separately from the real internal roll chance.

Commands

Main command:

/abestcrates

Aliases:

/abc
/acrates

Admin commands:

/abc gui
/abc reload
/abc create <name>
/abc delete <name>
/abc deletecrate
/abc spawncrate <name>
/abc edit <name>
/abc givekey <player> <crate> <amount>
/abc addkeys <player> <crate> <amount>
/abc removekeys <player> <crate> <amount>
/abc forceopen <player> <crate>

Permissions

abestcrates.admin
abestcrates.use
abestcrates.open
abestcrates.create
abestcrates.givekey
abestcrates.reload

Players need abestcrates.use to open crates.

Player Interaction

- Right-click a placed crate to preview rewards - Left-click a placed crate to open it - Shift-left-click a placed crate to open all matching keys Bulk opening checks inventory space before consuming keys.

Compatibility

ABestCrates is designed for modern Paper servers and uses the current Paper API.

License

All Rights Reserved.