minitreach

Build a REAL, COMPLETE, WORKING Minecraft plugin named CustomCrates for Paper 1.21.11 / Java 21. This is NOT a mockup, example, pseudocode or partial plugin. Everything below must be implemented, connected and functional.

PHYSICAL CRATES: "/crate create " is admin-only (OP OR "customcrates.admin"). The player MUST hold a Shulker Box. Ray-trace where they look and physically place a REAL Shulker Box there. That exact world+X+Y+Z becomes the crate. Normal Shulker Boxes are NOT crates. The physical Shulker is the actual crate; never use a fake/invisible replacement.

Each crate supports unlimited types/locations and has its own name, color/type, rewards, chances, hologram and player key balances.

HOLOGRAMS: Every crate has a persistent hologram above it. It must survive players leaving, nobody nearby, chunk unload/reload, world reload, server restart and plugin reload, and be restored automatically on startup. It must never only exist when a player is nearby. Protect against duplicate holograms.

The hologram displays:

Crate title Player-specific virtual key count Opening text

Example: "ʟᴇɢᴇɴᴅᴀʀʏ ᴄʀᴀᴛᴇ" "ᴋᴇʏs: 12" "ᴄʟɪᴄᴋ ᴛᴏ ᴏᴘᴇɴ"

Player A and Player B MUST see their own key counts, not a global count. Use an efficient Paper-compatible method.

Holograms MUST NOT depend on a player being nearby or on an expensive per-player/per-crate repeating task. Persist all hologram information using the crate's exact world+X+Y+Z location.

If the hologram implementation uses entities, safely handle chunk unload/reload and recreate the hologram when necessary. Before creating one, check for an existing hologram belonging to that exact crate so reloads never create duplicates.

Holograms must automatically recover after:

Server restart Plugin reload /crate reload World reload Chunk unload/reload Players leaving and returning Nobody being near the crate

The physical Shulker remains the REAL crate. Never replace it with an invisible block, fake crate or hologram-only system.

LEFT-CLICK PREVIEW: Left-clicking a registered physical crate MUST open a temporary reward-preview GUI.

The preview MUST:

Show all currently configured rewards. Show the exact saved reward ItemStacks. Show reward chances/weights where configured. Never consume a virtual key. Never give a reward. Never modify the real crate. Never modify rewards. Never modify the crate location. Never create a new crate. Never create a permanent hologram. Be temporary/visual only.

Right-clicking the registered physical crate remains the normal opening action.

TEXT: All CustomCrates displayed text should use Minecraft-style Unicode small caps where practical: "ᴄʀᴀᴛᴇ" "ᴋᴇʏs" "ᴄʟɪᴄᴋ ᴛᴏ ᴏᴘᴇɴ"

Commands stay normal.

Support color codes, MiniMessage and Unicode.

COMMANDS: "/crate create " = physically create/register crate. "/crate delete " = remove ONLY that crate, its registration and hologram, and safely remove its physical Shulker. "/crate add " = copy the exact item in the player's hand as a reward; do NOT remove the held item by default. "/crate remove " = remove reward. "/crate chance " = set reward weight/chance. "/crate title " = change persistent hologram title. "/crate preview " = temporary visual preview only; NEVER create/change the real crate. "/crate list" = list crates. "/crate reload" = safely reload config/data.

KEY COMMANDS: "/crate key give " "/crate key take " "/crate key set " "/crate key giveall "

Keys are 100% virtual and stored per-player/per-crate. Never use physical key items.

Key commands must work for offline players where possible.

Console MUST be able to run all key commands so Tebex can execute them.

Example: "crate key give {username} Legendary 10"

This gives the player 10 virtual Legendary keys.

REWARDS: "/crate add" must preserve the complete ItemStack, including:

Material Amount Display name Lore Enchantments Custom model data Potion data Attributes Item flags Modern Minecraft item-component data Any other serializable ItemStack metadata

Reward chances/weights MUST actually affect random reward selection.

Invalid reward IDs, crate names, amounts and chance values must be safely rejected with a useful message.

If the player's inventory is full, NEVER silently delete or lose the reward. Use configurable behavior such as:

Drop at player Pending reward/mail system

Pending rewards MUST persist through restarts.

OPENING: Right-clicking the registered physical Shulker checks that player's virtual key balance.

If the player has 0 keys: Show a configurable "no keys" message and do nothing.

If the player has at least 1 key:

Remove exactly 1 virtual key. Open a clean crate GUI/animation. Display possible rewards. Select the winner using the configured reward chances/weights. Give the exact saved ItemStack. Handle full inventory using the configured inventory-full behavior.

The physical Shulker remains in the world permanently and cannot be used as normal storage.

PROTECTION: Players cannot normally:

Break crate Shulkers. Open crate Shulkers as storage. Move crate Shulkers. Push crate Shulkers with pistons. Pull crate Shulkers with pistons. Destroy crate Shulkers with explosions.

Cancel all relevant interactions/events safely.

Only "/crate delete " may remove a registered crate and its physical Shulker.

TEBEX: This MUST work from console:

"crate key give {username} Legendary 10"

It must give 10 virtual Legendary keys.

No physical key item is required.

FREE KEYS: Provide a configurable free-key system.

Default:

1 key Every 15 minutes

Configure:

Amount Interval Target crate/location Whether it is enabled Sound Particle effect Announcement Message

Persist the timer across restarts/reloads.

Display: "ғʀᴇᴇ ᴋᴇʏs" "ɴᴇxᴛ ᴋᴇʏ: 08:42" "ʏᴏᴜ ʜᴀᴠᴇ: 3"

When the timer reaches zero:

Give configured keys to eligible online players. Play a configurable dragon-breath-style particle/sound animation around the configured location. Optionally announce it. Reset the timer.

Do NOT create an expensive per-player/per-crate task just to display the countdown.

LUCKPERMS: Management access is ALWAYS:

player.isOp() OR player.hasPermission("customcrates.admin")

Example: "/lp group admin permission set customcrates.admin true"

LuckPerms MUST NOT be required for the plugin to function.

If LuckPerms exists, support its prefixes/ranks automatically in chat where possible, for example:

"[ᴄᴀᴘᴛᴀɪɴ] Player: hello"

Avoid duplicate prefixes if another chat plugin already formats chat.

PLACEHOLDERAPI: PlaceholderAPI integration is OPTIONAL and must not be required.

Support at least:

%crates_keys_%

Also provide useful placeholders for:

Player key count Crate name Crate location Free-key countdown Free-key amount Current crate Other useful crate information

SCOREBOARD: Provide a configurable Java/Bedrock-compatible scoreboard system.

Support:

Configurable title Configurable lines Unicode small-cap styling PlaceholderAPI placeholders Update speed

Support placeholders/data for:

Player name Rank Ping Kills Deaths Money Current map Next map Free-key timer Crate keys

If Geyser/Floodgate exists, use a Bedrock-friendly scoreboard layout where needed.

If Geyser/Floodgate does not exist, the normal Paper scoreboard MUST still work.

PERSISTENCE: Persist everything required with no data loss:

Crates Exact world+X+Y+Z locations Shulker type Crate names Titles Colors/types Rewards Complete ItemStacks Reward chances/weights Player virtual keys Pending rewards Free-key timer Hologram information Any other required crate state

Everything MUST survive:

Server restart Plugin reload /crate reload World reload Chunk unload/reload

CONFIG: Provide a complete config.yml containing configurable settings for:

Hologram height Hologram text Hologram style Colors Unicode/small-cap text Sounds Opening animation Preview GUI Reward behavior Reward chances/weights Inventory-full behavior Pending rewards Free keys Free-key interval Free-key amount Free-key target Dragon-breath particle effect Free-key sound Announcements Scoreboard Java layout Scoreboard Bedrock layout Scoreboard update speed Messages Optional integrations PlaceholderAPI LuckPerms Vault Geyser/Floodgate

PERFORMANCE: Support many crates efficiently.

Do NOT use expensive per-tick-per-crate-per-player tasks.

Avoid memory leaks.

Do not create unnecessary entities.

Holograms must remain persistent and efficient.

Do not create duplicate holograms after reloads or restarts.

Use appropriate Paper APIs, scheduled tasks and event listeners.

FINAL RULE: Do not remove, simplify, fake, omit or skip any requirement above.

The finished result MUST be a real, compilable, complete Paper 1.21.11 / Java 21 plugin named CustomCrates.

It MUST include:

Complete source code plugin.yml Complete config.yml Commands Permissions Command handling Tab completion Event listeners Physical crate creation Physical crate protection Persistent holograms Player-specific hologram key counts Left-click reward preview Right-click crate opening Virtual keys Offline key storage Tebex-compatible console commands Complete ItemStack serialization Weighted reward selection Inventory-full handling Pending rewards Free-key system Free-key persistence Particle/sound effects LuckPerms integration PlaceholderAPI integration Scoreboard Geyser/Floodgate compatibility where available Persistence and safe reload handling

The plugin must compile and function on Paper 1.21.11 using Java 21. Do not provide pseudocode, mock implementations, TODO placeholders, incomplete classes or disconnected features.

Kodari AI
KodariSep 8 at 2:25 am 1
CustomCrates
A comprehensive Paper 1.21.11 crate plugin with physical Shulker Box crates, persistent player-specific holograms showing virtual key counts, left-click reward previews, right-click weighted reward opening, virtual key system with offline support and Tebex console compatibility, configurable free keys with particle effects, LuckPerms integration, PlaceholderAPI support, and Java/Bedrock scoreboards with Geyser/Floodgate detection. Features complete ItemStack serialization, pending rewards for full inventories, explosion/piston protection, and full persistence across restarts and reloads.

[Generation stopped]

Kodari can make mistakes. Review important code before using.
Files

No files in this session

Code