minitreach

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.

Kodari AI
KodariSep 6 at 5:52 pm 3
CustomCrates
A comprehensive virtual key crate system for Paper 1.21.11. OPs create physical shulker crates by holding a shulker box and targeting a block, which spawns a real shulker with an automatic hologram showing crate name and player key counts. Features virtual keys managed via commands, configurable rewards with chances, Tebex compatibility for digital key distribution, and an automatic free-key system with a 15-minute countdown and dragon-breath particle animation. Includes PlaceholderAPI support, persistent storage, unlimited crate types, and OP-only management commands.
  1. Create the Gradle/Paper project metadata and default configuration.

  2. Implement persistent crates, rewards, virtual keys, holograms, and free-key timing.

  3. Add crate interaction/opening animation, OP-only commands, Tebex-compatible key commands, and PlaceholderAPI support.

  4. Register all services and listeners in the plugin lifecycle.

  1. Created a complete Paper 1.21.11 custom crates plugin with:

    • Physical shulker crate placement via /crate create

    • Persistent crate locations, titles, rewards, and chances

    • Exact item reward serialization

    • Virtual keys with give/take/set/giveall commands

    • OP-only management commands

    • Crate holograms with per-player key counts

    • Legacy color codes and MiniMessage support

    • Opening animation GUI with weighted rewards

    • Safe overflow reward drops

    • Physical crate protection and storage prevention

    • Persistent free-key countdown and Dragon Breath animation

    • PlaceholderAPI expansion, including %crates_keys_<crate>%

    • Tebex-compatible console key commands

    • Restart persistence through crates.yml, keys.yml, and config.yml

  2. Added Gradle configuration, plugin.yml, default configuration, managers, listeners, commands, persistence, holograms, and plugin bootstrap classes.

Kodari can make mistakes. Review important code before using.
Files
src
build.gradle
settings.gradle
Code
16 1,064
src/main/java/com/kodari/crates/CratesPlugin.java
package com.kodari.crates;

import net.kyori.adventure.text.Component;
import net.kyori.adventure.text.serializer.legacy.LegacyComponentSerializer;
import net.kyori.adventure.text.minimessage.MiniMessage;
import org.bukkit.ChatColor;
import org.bukkit.NamespacedKey;
import org.bukkit.plugin.java.JavaPlugin;

public class CratesPlugin extends JavaPlugin {
    private CrateManager crateManager;
    private KeyManager keyManager;
    private HologramManager hologramManager;
    private FreeKeyManager freeKeyManager;
    private CrateOpeningService openingService;
    private NamespacedKey crateKey;

    @Override
    public void onEnable() {
        saveDefaultConfig();
        crateKey = new NamespacedKey(this, "crate-name");
        crateManager = new CrateManager(this);
        keyManager = new KeyManager(this);
        freeKeyManager = new FreeKeyManager(this);
        hologramManager = new HologramManager(this);
        openingService = new CrateOpeningService(this);

        CrateCommand command = new CrateCommand(this);
        getCommand("crate").setExecutor(command);
        getCommand("crate").setTabCompleter(command);
        getServer().getPluginManager().registerEvents(new CrateListener(this), this);
        getServer().getPluginManager().registerEvents(openingService, this);
        getServer().getPluginManager().registerEvents(hologramManager, this);
        freeKeyManager.start();
        hologramManager.start();

        if (getServer().getPluginManager().isPluginEnabled("PlaceholderAPI")) {
            new CratesPlaceholderExpansion(this).register();
            getLogger().info("PlaceholderAPI support enabled.");
        }
    }

    @Override
    public void onDisable() {
        if (openingService != null) openingService.shutdown();
        if (hologramManager != null) hologramManager.removeAll();
        if (keyManager != null) keyManager.save();
        if (crateManager != null) crateManager.save();
    }

    public String color(String text) {
        return ChatColor.translateAlternateColorCodes('&', text == null ? "" : text);
    }

    public Component component(String text) {
        if (text != null && text.contains("<") && text.contains(">")) return MiniMessage.miniMessage().deserialize(text);
        return LegacyComponentSerializer.legacyAmpersand().deserialize(text == null ? "" : text);
    }

    public CrateManager getCrateManager() { return crateManager; }
    public KeyManager getKeyManager() { return keyManager; }
    public HologramManager getHologramManager() { return hologramManager; }
    public FreeKeyManager getFreeKeyManager() { return freeKeyManager; }
    public CrateOpeningService getOpeningService() { return openingService; }
    public NamespacedKey getCrateKey() { return crateKey; }
}