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

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

---

📋 Requirements

- Java 21+ (or forks) 1.21 – 1.21.4+ - Java 21+

Optional soft-dependencies

All are fully optional and loaded via reflection:

- Citizens / ZNPCs / ZNPCsPlus / FancyNpcs + economy plugin — key shop & economy commands - Citizens / ZNPCs / ZNPCsPlus / FancyNpcs — placeholders in messages & holograms - Citizens / ZNPCs / ZNPCsPlus / FancyNpcs — custom block & item models - Citizens / ZNPCs / ZNPCsPlus / FancyNpcs — 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`