Custom Crates Plugin
Make a complete custom crates plugin for Paper 1.21.11.
IMPORTANT — HOW CRATES ARE CREATED
When an OP runs:
/crate create <crateName>
the plugin MUST:
Check what item the OP is holding. The item must be a Shulker Box. Find the block/location the player is looking at. ACTUALLY PLACE/SPAWN a real Shulker Box block at that location. Register that exact shulker location as the crate. Give the shulker the crate's appearance/name if possible. Automatically create a hologram directly above the shulker. Save the crate permanently so it remains after a server restart. The placed shulker is the physical crate players interact with.
Do NOT only create a database entry.
Do NOT only create a hologram.
Do NOT require another command to spawn the shulker.
/crate create <name> MUST physically place the shulker in the world.
Example:
/crate create Legendary
Player is looking at a block.
The plugin places a shulker there and turns that shulker into the Legendary crate.
HOLOGRAM
Every crate automatically gets a hologram above the physical shulker.
Example:
LEGENDARY CRATE
Keys: 12
The key amount shown must be the amount of that crate's virtual keys that the PLAYER viewing the hologram owns.
The hologram must automatically load again after a restart.
Allow OPs to change the hologram title:
/crate title <crateName> <text>
Example:
/crate title Legendary &5&lLEGENDARY CRATE
Support Minecraft color codes / MiniMessage.
ADDING REWARDS
An OP holds an item in their hand and runs:
/crate add <crateName>
The plugin copies the EXACT item being held and adds it to that crate's reward pool.
It must preserve:
Item type Amount Name Lore Enchantments Custom model data Potion data Other item components/data
The player's held item should NOT be removed unless configured otherwise.
Example:
Hold 16 diamonds.
/crate add Legendary
Now 16 diamonds are one of the Legendary crate rewards.
VIRTUAL KEYS
Keys are completely virtual.
Players never need physical key items.
Commands:
/crate key give <player> <crateName> <amount>
/crate key take <player> <crateName> <amount>
/crate key set <player> <crateName> <amount>
/crate key giveall <crateName> <amount>
Example:
/crate key give Steve Legendary 10
Steve now has 10 Legendary keys.
The hologram above the Legendary crate should show Steve's key amount when Steve looks at it.
OPENING A CRATE
When a normal player right-clicks the physical shulker crate:
Check their virtual key count. If they have no key, do nothing except show a message such as: You don't have a Legendary Key! If they have a key, remove exactly 1 virtual key. Play a crate-opening animation. Show the possible rewards / opening GUI. Randomly select a reward using the configured chances. Give the reward to the player. If their inventory is full, safely handle the reward instead of deleting it.
The physical shulker must remain in the world.
Players must NOT be able to open the shulker as a normal storage container.
TEBEX
Make the plugin compatible with Tebex.
Tebex should be able to execute commands such as:
crate key give {username} Legendary 10
This gives the purchaser 10 virtual Legendary keys.
Do NOT create physical key items for Tebex.
The keys must be stored digitally.
FREE KEY SYSTEM
Have a special free-key crate/system.
Every 15 minutes, automatically give everyone online a configurable number of keys.
Default:
Every 15 minutes:
+1 free key
Make the amount configurable.
Example:
free-key-amount: 1
The system needs a countdown.
Example hologram:
FREE KEYS
Next Key: 08:42
You Have: 3
When the timer reaches zero:
Give the configured amount of free keys to everyone online. Reset the timer to 15 minutes. Play a server-wide animation. DRAGON BREATH GIVEAWAY ANIMATION
When the free-key giveaway happens, create a large dragon-breath-style particle animation around the free-key crate/location.
The animation should:
Use dragon-breath-style particles. Spread around the crate. Be visible to nearby players. Look like the crate is releasing magical energy. Play a sound if configured. Then give everyone online their free keys.
The amount given must be configurable.
OP-ONLY MANAGEMENT
All crate management commands must be OP ONLY.
Do NOT require a separate admin permission for OPs.
Check whether the player is actually OP.
OPs can use:
/crate create <name>
/crate delete <name>
/crate add <name>
/crate remove <name>
/crate title <name> <text>
/crate chance <name> <reward> <chance>
/crate key give <player> <crate> <amount>
/crate key take <player> <crate> <amount>
/crate key set <player> <crate> <amount>
/crate key giveall <crate> <amount>
/crate reload
/crate list
Normal players must NOT be able to use these management commands.
Normal players can still interact with crates and use their virtual keys.
CRATE DELETION
When an OP runs:
/crate delete <crateName>
remove the crate registration and its hologram.
Also safely remove the physical shulker that belongs to that crate.
Do NOT remove unrelated shulkers.
PERSISTENCE
Save everything to files/database so nothing is lost after restart.
Save:
Crate names Crate locations Crate type Hologram text Rewards Reward chances Player virtual key balances Free-key timer Configuration MULTIPLE CRATES
There can be unlimited crates.
Examples:
Common
Rare
Epic
Legendary
Mythic
Each crate must have its own:
Physical shulker Hologram Rewards Reward chances Virtual key balance per player PLACEHOLDERAPI
Add PlaceholderAPI support where possible.
Placeholders should include:
%crates_keys_<crate>%
Returns the player's virtual key count for that crate.
Example:
%crates_keys_legendary%
Also provide placeholders for:
Free-key countdown Crate names Player key counts VERY IMPORTANT IMPLEMENTATION REQUIREMENT
The most important part is that /crate create <crateName> MUST physically place a real shulker block.
Example:
Player holds a Shulker Box.
Player runs:
/crate create Legendary
Result:
A real Shulker Box appears in the world at the target location.
Above it:
LEGENDARY CRATE Keys: 0
That shulker is now the Legendary crate.
The plugin must detect interaction with THAT physical shulker and treat it as the crate.
Do not make /crate create only create an invisible crate, armor stand, hologram, or database entry.
The physical shulker is required.