Smart Crates

A modern, production-ready crate system for PaperMC 1.21 – 1.21.4 with a unique dual-mode design: a roulette-style Classic Roll and a player-driven Choose Reward mode — plus floating holograms, invisible virtual keys and a free reward preview menu on every crate.

✨ Features

• 🎰 Mode 1 — Classic Roll: a scrolling reward strip slows down and lands on a weighted-random reward, marked with glowing pointers
• 🖐️ Mode 2 — Choose Reward: the player opens a menu and picks a reward manually (optional confirmation screen, chances ignored)
• 🔍 Reward preview: right-click any crate to see all rewards without spending a key, then open straight from the preview — with animation, instantly, or via the choose menu depending on the mode
• 🏷️ Holograms: floating labels above every placed crate (vanilla TextDisplay, no dependencies), fully configurable per crate file
• 🎨 Custom crate textures: set block-custom-model-data in a crate file (with a resource pack) and a floating item with your texture appears above the crate
• 👻 Virtual keys: per-crate virtual-keys: true replaces physical items with invisible per-player balances (stored as currency), shown live above the crate as "You have X keys!"
• 🗂️ One file per crate: every crate lives in its own crates/<id>.yml — copy, rename, edit, /sc reload
• 🔑 Secure keys: material, name, lore, custom model data, glow + anti-fake PersistentDataContainer tag
• 🧱 Physical crates: turn any block into a crate with /sc set <id> (survives restarts in data/crates.yml)
• 🎁 Powerful rewards: items, custom names/lore, amounts, enchantments, custom model data and multiple console commands with %player%
• 🔊 Configurable sounds & particles for every event (or NONE to disable)
• 🛡️ Anti-exploit: fake-key rejection, click/shift-click/drag blocking, single-opening lock, key consumed exactly once, disconnect-safe rolls
• 🎨 Colors: legacy & codes and hex (&#RRGGBB, <#RRGGBB>)
• 💬 Everything configurable: all messages, GUI sizes, filler, buttons, animation speed

🎮 How players use it

1. Left-click a crate block with its key (or virtual balance) → opens the crate directly
2. Right-click a crate block → free preview of all rewards with open buttons (no key needed to look)
3. Mode 1: watch the roll and win — or use Quick Open to skip the animation
4. Mode 2: pick your reward and confirm

🛠️ Commands

Aliases: /scrates, /sc. Full tab-completion included.

Command	Description
/sc list	Show all crates and their modes
/sc create <id>	Create a new crate file in crates/<id>.yml
/sc delete <id>	Delete a crate and its file
/sc setname <id> <name>	Change the crate display name (& and hex colors allowed)
/sc setgui <id> <name>	Change the inventory window title
/sc setmode <id> <1|2>	1 = Classic roll, 2 = Choose Reward
/sc edit <crate>	Edit the crate in a Minecraft menu (green dye saves)
/sc set <id>	Turn the block you are looking at into this crate
/sc remove [crate]	Unbind the looked-at block, or all blocks of a crate
/sc givekey <player> <crate> [amount]	Give key(s) to one player
/sc givekeyall <crate> [amount]	Give key(s) to every online player
/sc reload	Reload config, messages and all crate files
/sc help	In-game command guide

🔐 Permissions

Permission	Description	Default
smartcrates.admin	Full access (parent of all below)	op
smartcrates.create	Create crates	op
smartcrates.delete	Delete crates	op
smartcrates.reload	Reload the plugin	op
smartcrates.givekey	Give keys to a player	op
smartcrates.givekeyall	Give keys to everyone	op

🚀 Quick setup

1. Drop the jar into plugins/ and restart — example crates (basic, epic, legendary, vote, summer) generate automatically
2. /sc create mycrate, edit plugins/SmartCrates/crates/mycrate.yml, /sc reload
3. Look at a block and run /sc set mycrate
4. /sc givekey Steve mycrate 3 — done!

📁 Files

plugins/SmartCrates/
├── config.yml        # global settings, GUI, sounds, animation, preview click
├── messages.yml      # all messages + help lines
├── crates/           # one file per crate (basic.yml, epic.yml, ...)
├── data/crates.yml   # placed crate blocks
└── data/virtualkeys.yml # virtual key balances

❓ FAQ

Which versions are supported? PaperMC 1.21 – 1.21.4 with Java 21.

Do I need a database? No. Everything is stored in local YAML files.

Can players preview without a key? Yes — the preview (right-click by default) is free. A key is consumed only when actually opening.

Can I change what right-click does? Yes — preview.click in config.yml: RIGHT_CLICK (default), LEFT_CLICK, SHIFT_LEFT_CLICK or SHIFT_RIGHT_CLICK. The other click always opens directly.

How do virtual keys work? Set virtual-keys: true in a crate file. /sc givekey then adds invisible balance instead of items, and opening consumes from it. The hologram above the crate shows each player's own balance. Works with both Mode 1 and Mode 2.

How do custom crate textures work? Vanilla blocks can't carry CustomModelData, so SmartCrates shows your texture as a floating glowing item above the crate (vanilla ItemDisplay). Set block-custom-model-data to your resource pack's number (plus block-display-material and block-display-height), run /sc reload — done. 0 disables it.

My old config.yml has a crates: section — will it break? No. Version 1.1.0+ migrates it automatically into the crates/ folder on first start.