VaultCrates

A feature-rich, fully animated crate plugin for Paper 26.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; virtual keys stored per player in the database
• Pity system — configurable guaranteed drop after N opens per rarity
• Reward limits — global and per-player caps per reward
• Virtual key shop — players buy keys with in-game money via /vc shop (requires Vault or VaultUnlocked)
• Pouches — right-clickable reward bags with configurable random number ranges
• Holograms — floating Text Display entities, no external plugin needed; persist across restarts
• Placement ID system — every placed crate gets a unique ID; remove it with /vc remove <id>
• Furniture crates — use ItemsAdder furniture as a crate, including multi-entity furniture (display + hitbox)
• In-game GUI editor — edit crates and keys without touching a YAML file
• Reward preview — paginated GUI with normalised drop percentages; toggleable per crate
• Best Prizes — guaranteed bonus reward rolled from a separate pool
• Bundled items — give multiple bonus items alongside the main reward
• Selectable rewards — players pick their prize from N random options
• Milestones — bonus rewards after X total crate opens
• Reward footer — auto-appended lore lines showing reward type and rarity
• NPC support — Citizens, FancyNpcs, ZNPCsPlus, ZNPCs, or any entity via /vc linknpc
• Multi-language — English, German, French, Spanish built in; add any language with a messages_<code>.yml file
• Multi-database — JSON (default), SQLite or MySQL with automatic table creation
• Developer API — custom events, programmatic crate opening, key management

📋 Requirements

Which jar do I need?

Each jar refuses to load on a Minecraft version older than the one it was built for. For Minecraft 1.21.x, use VaultCrates 1.0.1.

Optional soft-dependencies

All soft-dependencies are loaded via reflection — VaultCrates runs without any of them installed.

🚀 Installation

1. Pick the jar for your Minecraft version (see table above) and drop it into plugins/
2. Start or restart the server — example configs are generated automatically
3. Get a placeable crate: /vc getcrate ExampleRound
4. Place it anywhere — the hologram appears and the placement is saved automatically
5. Give yourself a key: /vc key give <name> ExampleRound 1
6. Right-click the crate to open it

💬 Commands

All commands use /vc (aliases: /vaultcrates, /crate).

Crate management

Placement management

Tip: The placement ID is shown in chat when you place a crate. Block crates: Shift + left-click breaks and removes the block (requires vaultcrates.admin). Furniture crates: Shift + left-click only shows the ID — remove them with /vc remove <id>, so nobody deletes a crate by accident.

Physical keys (items)

Virtual keys

Pouches

NPC linking

FancyNpcs and ZNPCsPlus NPCs are packet-based and have no real entity, so they are linked by name/id. Opening a crate through an NPC requires a key, just like the crate itself.

🔑 Permissions

⚙️ Configuration

config.yml — key settings

# Language: en (default) | de | fr | es | or any custom locale code
Language: en

Storage:
  Type: JSON          # JSON (default) | SQLITE | MYSQL
  KeyUuidExpiryDays: 365

Settings:
  Cant_Open_Creative: false
  Must_Hold_Key_In_Hand: false
  Cant_Drop_Key: false
  Crate_Radius: 3     # Min. distance between two crates, 0 = off

Keys:
  Virtual_Keys_Enabled: true
  Physical_Keys_Enabled: true

Shop:
  Enabled: true
  VirtualKeys: true   # true = virtual keys; false = physical key items

Win_Message: "&8[&6VaultCrates&8] &7You won {reward_name} &8[{rarity}&8] &7from &e{crate_name}&7!"

RewardFooter:         # Extra lore lines appended to every reward item
  Enabled: false
  Fallback: "Reward"
  Lines:
    - ""
    - "&8Reward Type » &7{reward_type}"
    - "&8Rarity » &7{rarity_name}"

Crate config (crates/MyCrate.yml)

Animation: ROUND          # See animations list
Material: ENDER_CHEST
IAModel: "namespace:my_crate"   # Optional — ItemsAdder block or furniture
Size: 1                   # Rewards given per open
PreviewEnabled: true
ShowChanceInPreview: true
ShiftInstantlyOpen: false

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

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

FinalMessage: []          # Broadcast to all players on open (leave empty to disable)

Prizes:
  diamond:
    Name: "&b&lDiamond"
    Rarity: epic           # common | rare | epic | legendary | jackpot | mega_jackpot | custom
    Chance: 10.0           # Relative weight — does not need to sum to 100
    Material: DIAMOND
    Amount: 1
    Glow: true             # Visual glint only — the item can still be enchanted normally
    GiveItem: true
    Type: "Item"           # Optional — shown in RewardFooter as {reward_type}
    Enchantments:
      sharpness: 5
      "myplugin:soulbound": 1   # Enchantments from enchant plugins via namespaced id
    Commands: []
    EnchantCommands: []    # Run after the item is given (for enchant plugins without registry enchants)
    MessagesToPlayer: []
    BroadcastMessages: []
    GlobalLimit: 0         # 0 = unlimited
    PlayerLimit: 0

BestPrizes:
  legendary_item:
    Name: "&6&lLegendary Sword"
    Chance: 100.0
    Material: NETHERITE_SWORD
    GiveItem: true

Available rarities

Custom rarities can be added in config.yml under Rarities: with optional pity thresholds, glow colours and broadcast messages.

Pouch config (pouches/MyPouch.yml)

Name: "MoneyPouch"
DisplayName: "&6&lMoney Pouch"
Material: SUNFLOWER
Glow: true
Commands:
  - "eco give {player_name} {random_number}"
MinNumber: 500
MaxNumber: 5000

🌐 Multi-language

Four languages are bundled out of the box:

Using a custom or regional language:

1. Create messages_pt_br.yml (or any messages_<code>.yml) in the plugin folder
2. Set Language: pt_br in config.yml
3. Run /vc reload

Fallback chain: messages_en_us.yml → messages_en.yml → messages.yml

🗄️ Storage backends

Data stored: virtual keys, pity counters, reward limits, milestone progress, used key UUIDs.

🎬 Animations

🎨 Custom item support

# In a reward:
Material:     "namespace:item_id"   # ItemsAdder item
OraxenModel:  "item_id"
NexoModel:    "item_id"
EIModel:      "my_item_id"          # ExecutableItems
MMOItem:      "TYPE:item_id"        # e.g. SWORD:my_sword

# On a crate or key:
IAModel:      "namespace:item_id"
OraxenModel:  "item_id"
NexoModel:    "item_id"

ItemsAdder font images (:icon_name:) work in every text field: names, lore, holograms and messages.

📊 PlaceholderAPI

🔧 Developer API

VaultCratesAPI api = VaultCratesAPI.get();

// Virtual keys
int keys = api.getVirtualKeys(player.getUniqueId(), "MyCrate");
api.addVirtualKeys(player.getUniqueId(), "MyCrate", 5);
api.removeVirtualKeys(player.getUniqueId(), "MyCrate", 1);

// Physical keys
api.givePhysicalKey(player, crate, 3);

// Open programmatically
api.openCrate(player, api.getCrate("MyCrate"), crateLocation);

// Events
@EventHandler
public void onCrateOpened(CrateOpenedEvent e) {
    List<Reward> rewards = e.getRewards();
    Reward best = e.getBestReward();
}

📄 License

VaultCrates is free software licensed under the GNU General Public License v3.0. You may use, modify and redistribute it under the terms of the GPL-3.0 — modified versions must stay open source under the same license. See LICENSE for the full text.

Made with ❤️ by itslarss