VaultCrates

# 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 ```yaml 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`