🎁 FrozenCrates

📦 Plugin Info

A DonutSMP-inspired crate plugin. Bind crates to physical blocks in the world, give players physical or virtual keys, and let them right-click to open an animated reward GUI. Includes a visual reward editor, floating holograms above bound crates, MySQL/YAML storage, and Folia support.

Name - FrozenCrates

👤 Author Info

• Author: DrFrozenXD

✅ Versions / Compatibility / Software Support

• API Version: 1.21
• Built against: Paper API 1.21.8-R0.1-SNAPSHOT (Java, Maven + Shade plugin) ☕
• Server software: Paper / Spigot forks
• Folia support: ✅ Supported (folia-supported: true) — region-scheduler-safe (e.g. /crate verify, holograms)
• Soft dependency: PlaceholderAPI 2.11.6 (optional — enables %frozencrates_*% placeholders)
• Storage backends: YAML (default, zero setup) or MySQL (via HikariCP connection pooling + MySQL Connector/J)

🔐 Permissions

Permission	Default	Purpose
frozencrates.use	true	Use/open crates
frozencrates.admin	op	Access to admin commands (bind, unbind, edit, reload, verify)
frozencrates.key.give	op	Give/take keys to/from players

⌨️ Commands

Command	Permission	Description
/crate bind <crate>	frozencrates.admin	Binds the block you're looking at to a crate type
/crate unbind	frozencrates.admin	Removes the crate binding from the block you're looking at
/crate verify	frozencrates.admin	Checks all bound blocks still match the block type recorded when bound (Folia-safe region-by-region check)
/crate edit <crate>	frozencrates.admin	Opens the visual reward editor GUI for a crate (auto-saves on close)
/crate key give <player> <crate> <amount>	frozencrates.key.give	Gives keys to a player
/crate key giveall <crate> <amount>	frozencrates.key.give	Gives keys to all online players
/crate key take <player> <crate> <amount>	frozencrates.key.give	Takes keys from a player
/crate key takeall <crate> <amount>	frozencrates.key.give	Takes keys from all online players
/crate reload	frozencrates.admin	Reloads config, messages, and all crate definitions
/crate help	—	Shows the command list

Full tab completion is provided for subcommands, crate IDs, key actions, and amount presets.

🎯 Uses

• 🔑 DonutSMP-style crates: bind a crate to any block, players right-click with a matching key to open it.
• 🎰 Animated GUI crate-opening sequence via CrateGuiService, with a separate confirm menu before claiming.
• 🗝️ Physical or virtual keys — virtual-keys toggle in config lets keys be tracked as data instead of requiring inventory items.
• 🎨 In-game visual reward editor (/crate edit) instead of hand-editing YAML reward tables.
• 🏷️ Floating holograms above bound crates, chunk-aware so they load/unload correctly (HologramChunkListener).
• 🛡️ Block protection listener prevents bound crate blocks from being broken/griefed.
• 🧩 PlaceholderAPI hook for displaying crate/key stats elsewhere (scoreboards, GUIs, chat).
• 💾 Choice of lightweight YAML storage or MySQL for larger networks.
• 🔍 /crate verify audits bindings against live blocks to catch griefing or world edits that silently broke a crate.
• 🕯️ Five preset key/crate tiers out of the box: Common, Prime, Amethyst, Crimson, Gold — each with its own candle-item key, glow effect, and hologram config.

⚙️ Key Config Areas

• config.yml — sounds (open/claim/deny/editor-save), bind reach distance, confirm menu title, all user-facing messages, storage backend selection (yaml/mysql) + MySQL credentials, virtual-keys toggle.
• keys.yml — per-key material, display name, lore, and glow (enchant glint) settings.
• crates/*.yml — one file per crate (prime, crimson, common, amethyst, gold) defining rewards.
• hologram/*.yml — one file per crate controlling the floating hologram text/appearance shown above bound blocks.