VaultCrates

A feature-rich, fully animated crate plugin for Paper 1.21.x

No NMS · No legacy libraries · No external hologram plugin required

---

✨ Features

• 12 unique animations — particles, sounds and visual effects for every style
• Physical & Virtual Keys — NBT-tagged items with anti-dupe UUID tracking
• Pity system — guaranteed drop after N opens per rarity
• Reward limits — global and per-player caps per reward
• Key shop — players buy keys with in-game money via /vc shop
• Pouches — right-clickable reward bags with random number ranges
• Holograms — floating Text Display entities, no external plugin needed
• Placement ID system — each placed crate gets a unique ID (/vc remove <id>)
• In-game GUI editor — edit crates without touching YAML files
• Reward preview — paginated GUI with normalised drop percentages
• Best Prizes — guaranteed bonus reward from a separate pool
• Bundled items — give multiple items alongside the main reward
• Selectable rewards — players pick their prize from N options
• Milestones — bonus rewards after X total crate opens
• Reward footer — auto-appended lore showing reward type and rarity
• NPC support — Citizens, ZNPCs, ZNPCsPlus, FancyNpcs, or any entity
• Multi-language — English, German, French, Spanish built-in + custom locale support
• Multi-database — JSON (default), SQLite or MySQL
• Developer API — events, programmatic crate opening, key management

---

📋 Requirements

• Paper (or forks) 1.21 – 1.21.4+
• Java 21+

Optional soft-dependencies

All are fully optional and loaded via reflection:

• Vault + economy plugin — key shop & economy commands
• PlaceholderAPI — placeholders in messages & holograms
• ItemsAdder / Oraxen / Nexo — custom block & item models
• ExecutableItems / MMOItems — custom items as rewards
• Citizens / ZNPCs / ZNPCsPlus / FancyNpcs — NPC-to-crate linking

---

🚀 Quick Start

1. Drop the JAR into plugins/
2. Restart the server
3. /vc getcrate ExampleRound — get a crate block
4. Place it in the world
5. /vc key give <name> ExampleRound 1 — give yourself a key
6. Right-click the crate!

---

🎬 Animations

Name	Style
ROUND	Slot machine — cycles and locks on the winner
ROUND2	Mystery boxes — BARRIER boxes orbit with lightning reveal
QUICK	Slot machine — fast version (~3 s)
COSMIC	Double counter-rotating orbital rings
DISPLAY	Single item cycles and lands on the winner
PYRAMID	Three-tiered rotating pyramid
CONTRABAND	Items float up and vanish one-by-one
INSTANT	Particle burst, reward given instantly
AIR_STRIKE	Items fall from height with lightning
BREAKOUT	Items burst outward and arc back
METEOR_SHOWER	Items rain down with flame trails
YIN_YANG	Two rings converge in a yin-yang pattern

---

🌐 Languages

Code	Language
en	English (default)
de	German / Deutsch
fr	French / Français
es	Spanish / Español

Drop a messages_<code>.yml in the plugin folder and set Language: <code> to add any language. Regional locale codes (en_us, pt_br, etc.) are supported with automatic fallback.

---

🗄️ Storage

Type	Notes
JSON	Default, zero setup
SQLITE	File-based SQL, bundled driver
MYSQL	Full MySQL/MariaDB, auto table creation

---

⚙️ Crate config example

Animation: ROUND
Block: ENDER_CHEST
Size: 1

HologramLines:
  - "&6&lMy Crate"
  - "&7Right-click to open"

KeyCrate:
  Require: true
  Material: TRIPWIRE_HOOK
  Name: "&6&lMy Key"
  MatchNBT: true

Prizes:
  diamond:
    Name: "&b&lDiamond"
    Rarity: epic        # common | rare | epic | legendary | jackpot | mega_jackpot
    Chance: 10.0
    Material: DIAMOND
    GiveItem: true

---

📊 PlaceholderAPI

Placeholder	Returns
%vaultcrates_keys_<CrateName>%	Virtual key count
%vaultcrates_opens_<CrateName>%	Total opens by player
%vaultcrates_pity_<CrateName>_<rarityId>%	Pity counter
%vaultcrates_is_animating%	true / false

Custom events: CrateOpenEvent (cancellable), CrateOpenedEvent, CrateKeyUseEvent