Addict-O-Crate

Ultra-complete, highly configurable crate plugin with CSGO roulette animations!


⭐ What is Addict-O-Crate?
Addict-O-Crate is a premium-grade crate/loot box system designed for servers that demand the best. Featuring a stunning CSGO-style roulette animation, fully configurable crate types, physical & virtual key management, native holograms, and a built-in pity system — all without a single external dependency beyond Vault.

Create unlimited crate types, each in their own YAML file with full control over rewards, animations, particles, sounds, rarities, and broadcasting.

✨ Key Features

• CSGO Roulette Animation: Silky smooth horizontal scrolling with progressive deceleration. Items fly past and slow down to reveal the winning reward — just like the real thing. Players cannot close the animation (ESC/E are blocked until the reward is given).
• Physical & Virtual Keys: Give players real key items (with custom materials, names, lore, and glow) or virtual keys stored in the database. Both work seamlessly together.
• Unlimited Crate Types: Each crate is a separate YAML file in the crates/ folder. Create as many tiers as you want — just drop a new .yml file and /crate reload.
• Weighted Rewards: Set precise chance percentages for each reward. Supports items (with enchantments), commands, money, and multi-item bundles.
• ⭐ 6 Rarity Tiers: COMMON, UNCOMMON, RARE, EPIC, LEGENDARY, MYTHIC — each with their own color code and glass pane representation.
• Pity System: Guarantee rare rewards after X consecutive opens without one. Fully configurable per crate — your players will never feel cheated.
• Placement Wand: Get a special admin tool with /crate wand. Right-click any block → a GUI shows all crate types → click to place it. The crate automatically faces the player (lock/front toward you), supporting all 4 cardinal directions.
• PlaceholderAPI Support: Expose key counts, total opens, and per-crate stats via PAPI placeholders for scoreboards and menus.
• ️ Native Holograms: Beautiful floating text above each crate using invisible ArmorStands. No DecentHolograms or HolographicDisplays required!
• ✨ Idle Particles & Sounds: Configurable ambient particles around placed crates and custom sound effects for opening, ticking, and winning.
• Win Broadcasts: Announce rare wins to the entire server! Configure the minimum rarity threshold per crate.
• ️ Configurable Key Protection: Toggle key dropping, moving to chests, and keeping on death individually in config.yml. Give your admins full control over key behavior.
• Inventory Check: Players with a full inventory cannot open crates — the key is preserved and a warning message is shown. No more lost rewards!
• Crate Shop: Place a sign with [Crate] → players click it to open a purchase GUI. Each crate has a configurable price (Vault economy). Players receive a portable crate item they can open anywhere by right-clicking with a matching key.
• Portable Crates: Purchased crate items are unstackable, glow, and carry NBT data. Right-click with a key anywhere to trigger the roulette — no placed crate required!
• ⏱️ Cooldown System: Set cooldowns between crate opens per crate type.
• ️ Preview GUI: Right-click any placed crate to preview all possible rewards, sorted by rarity, with chances displayed. Paginated for large reward pools.
• ⚙️ Admin GUI: Manage all crates in-game via /crate admin. Left-click for 1 key, shift-click for 10 keys, right-click to preview.
• ️ Full In-Game Crate Editor: Create and edit crates entirely from a GUI — no file editing needed! Change names, block types, key settings, rewards, prices, toggles, and more. Supports chat-based input for text and numbers, click-to-toggle for booleans, and hold-item-to-set for materials. Saves directly to YAML and auto-reloads.
• YAML & MySQL Storage: Choose between flatfile or MySQL for player data — perfect for networks.
• Citizens NPC Integration: Link any Citizens NPC to act as a crate merchant! Command /crate npc link lets you link NPCs. Right-clicking the NPC opens the general crate Shop GUI.
• Multi-Language: Full English & French translations included with fallback system.

Commands & Permissions

Commands:

• /crate list — List all crate types.
• /crate preview <crate> — Preview rewards for a crate.
• /crate place <crate> — Place a crate at the targeted block (faces you).
• /crate remove — Remove the targeted crate.
• /crate wand — Get the placement wand tool (right-click block → GUI selection).
• /crate key give <player> <crate> [amount] [physical|virtual] — Give keys.
• /crate key giveall <crate> [amount] [physical|virtual] — Give keys to all online.
• /crate key take <player> <crate> [amount] — Take virtual keys.
• /crate key check [player] — Check a player's key inventory.
• /crate open <crate> [player] — Force-open a crate (admin, checks inventory).
• /crate shop — Open the crate shop GUI (also via [Crate] sign).
• /crate npc link — Link the selected Citizens NPC to the shop.
• /crate npc unlink — Unlink the selected Citizens NPC.
• /crate editor — Create a new crate from scratch (GUI wizard).
• /crate editor <id> — Edit an existing crate (or create a new one with that ID).
• /crate admin — Open the admin management GUI.
• /crate reload — Reload all configurations and crate files.

Permissions:

• addictocrate.open — Allows opening crates. (Default: true)
• addictocrate.preview — Allows previewing crate contents. (Default: true)
• addictocrate.key.give — Allows giving keys to players. (Default: op)
• addictocrate.admin — Full admin access (place, remove, wand, admin GUI, reload). (Default: op)

⚙️ Configuration
Per-crate shop config (in each .yml):
️ In-Game Crate Editor

No more editing YAML files! The built-in crate editor lets admins create and modify crates entirely from a beautiful GUI interface.

Main Editor Panel:

• Display Name — Click → type in chat (supports & color codes)
• Block Type — Hold a block in hand → click the slot to set
• Key Settings → — Opens sub-menu: material (hold item + click), name (chat input), glowing (toggle)
• ️ Hologram — Click to toggle on/off
• Broadcast — Left-click: toggle | Right-click: cycle minimum rarity
• ⏱ Cooldown — Click → type seconds in chat
• Pity System — Left: toggle | Right: set threshold | Shift: cycle rarity
• Shop — Left: toggle | Right: set price
• Rewards → — Opens paginated reward list

Reward Editor:

• View all rewards with rarity, chance %, and item preview
• Left-click a reward to edit — change name, rarity (click to cycle), chance %, item (hold + click), and commands (chat input with ; separator)
• Shift+Right-click to delete a reward
• ➕ Add Reward button to create new entries
• Paginated for crates with many rewards

Save & Management:

• Save — Writes the YAML file and auto-reloads everything (holograms included)
• ❌ Cancel — Discard all changes
• Delete — Shift-click to permanently remove a crate file

⚙️ Installation Instructions

• Make sure Vault is installed on your server. Citizens (for NPC merchants) and PlaceholderAPI are optional.
• Download Addict-O-Crate-1.1.1.jar and place it in /plugins/.
• Restart your server. Default crate configs (Common, Rare, Legendary) will be generated.
• Use /crate wand to get the placement tool, or /crate place <name> directly.
• Place a sign with [Crate] on line 1 to create a shop sign.
• Give keys with /crate key give and let players open crates!
• Add new crates by creating .yml files in plugins/Addict-O-Crate/crates/ and /crate reload.

Example Crate Configuration (you can edit in file or ingame GUI)