Boonbox

Boonbox

Animated lootbox crates with cinematic roulette reveal and odds GUI.

Boonbox adds keyless lootbox-style crates to PaperMC servers. Right-click any block while holding a crate to launch a full-screen roulette animation — a chest rises, items spawn, a vertical wheel spins, eight contenders are whittled down to one, and the winner glides to the player's gaze. Left-click opens an inventory GUI showing the exact drop chances.
Crates are fully modular: 4 tiers ship by default, admins can add unlimited custom ones in config.yml with their own loot table, color, icon, and particle. Loot entries support vanilla materials, custom amounts (including > 64), and full custom items (named, enchanted, NBT-tagged).
Features

Cinematic roulette animation (~10s) — chest rise, item clump, vertical spinning wheel, 7 elimination rounds, winner glides to the player's gaze
Multi-tier modular crates — 4 defaults (Common / Rare / Epic / Legendary), unlimited custom via config or in-game commands
Odds GUI — left-click any crate to see every possible drop with rarity, chance, amount, and weight
Weighted loot tables — rarity tier auto-computed from each item's share of total weight
Custom items in loot — named, enchanted, NBT-tagged, custom model data, items from other plugins
Multi-stack rewards — a single drop can deliver 128, 256, or more (auto-split into multiple stacks on pickup)
Per-crate permissions — restrict tiers to donor ranks (contraband.use.<crate-id>)
Configurable cooldowns — anti-spam by radius and per-player time window
Fully customizable messages — every player-facing string is editable for translation or rebranding
Hot reload — /cb reload applies config changes without a server restart
Crash-resilient — disconnect, death, or server restart mid-animation drops the loot at the crate location, no item lost

Requirements

PaperMC server 1.21.5+ (compiled against 1.21.11)
Java 21

Installation
1. Download boonbox-1.0.0.jar from the releases page
2. Drop it into your server's plugins/ folder
3. Start the server once — Boonbox writes plugins/Boonbox/config.yml with 4 default crates
4. (Optional) Edit config.yml to customize or add crates, then /cb reload
5. Test in-game: /cb give legendary <yourName>, then right-click any block
Player interactions

Right-click block with a crate → Launches the roulette animation
Left-click air or block with a crate → Opens the drop-chances GUI

Commands
Main command: /contraband (alias /cb). All admin subcommands require contraband.admin.

/cb help — Show in-game help (everyone)
/cb give <crate> <player> [amount] — Give crates to a player
/cb crate list — List all configured crates
/cb crate items <crate> — Show all loot entries with indices, amount, rarity, drop chance
/cb crate addloot <crate> [weight] [amount] — Add the held item to a crate's loot table
/cb crate removeloot <crate> <index|material> — Remove a loot entry by index (see items) or first matching material
/cb cancel — Cancel running animations (within 20 blocks, or all from console)
/cb reload — Reload config.yml (re-registers per-crate permissions)

Tab-completion is provided for: subcommands, crate IDs, player names, materials, loot indices, and common weight / amount presets.
addloot — adding custom loot in-game
The held item is captured as-is — material, amount, custom name, enchantments, lore, NBT, custom model data. Examples:

Code:

# Add 1 plain bread, default weight 10
/cb crate addloot common
# Add 64 bread (held in hand) with weight 20
/cb crate addloot common 20
# Override amount to 128 (bypasses the 64-per-stack hand limit)
/cb crate addloot common 20 128
# Add a named/enchanted sword to the legendary crate with weight 5
/give @s diamond_sword
# rename via anvil to "Excalibur", enchant Sharpness V
/cb crate addloot legendary 5

Every addloot saves to config.yml immediately. No reload needed.
removeloot — by index or material
/cb crate items legendary shows numbered entries:

Code:

Legendary Crate (8 items)
 - [1] NETHERITE_INGOT x1 : 18.52% (w=25)
 - [2] NETHERITE_INGOT x4 : 11.11% (w=15)
 - [3] ELYTRA x1 : 14.81% (w=20)
 - [4] DIAMOND_SWORD x1 : 3.70% (w=5) ★

The ★ marker means the entry has custom meta (name, enchants, lore, NBT). Use the index for unambiguous removal:

Code:

/cb crate removeloot legendary 4    # removes the Excalibur entry
/cb crate removeloot legendary ELYTRA  # removes the first ELYTRA entry

Permissions

contraband.use (default: true) — Allows opening crates at all
contraband.use.<crate-id> (default: true) — Per-crate gate, auto-registered for every crate in config
contraband.admin (default: op) — Access to all /cb admin subcommands

To restrict tier access to donor ranks (e.g. LuckPerms):

YAML:

groups:
  default:
    permissions:
      - "-contraband.use.epic"
      - "-contraband.use.legendary"
  vip:
    permissions:
      - "contraband.use.epic"
  donor:
    permissions:
      - "contraband.use.legendary"

Rarity tiers
Tier is computed per crate, from each item's share of the crate's total weight:

Legendary — under 5% — GOLD
Epic — under 15% — LIGHT_PURPLE
Rare — under 30% — AQUA
Uncommon — under 50% — GREEN
Common — 50% or more — GRAY

The same material can be Rare in one crate and Common in another — Boonbox computes it dynamically.
Configuration
plugins/Boonbox/config.yml is fully commented. Top-level sections:

YAML:

cooldown:
  radius-blocks: 3        # min distance between simultaneous animations
  per-player-ms: 1000     # min ms between right-clicks per player
messages:
  no-permission: "No permission"
  no-permission-crate: "You don't have permission to use %crate%"
  unknown-crate: "Unknown crate: %crate%"
  cooldown: "Slow down! Wait a moment before opening another crate"
  too-close: "Another crate is opening nearby"
  loot-added: "Added %amount%x %material% (weight %weight%) to %crate%"
  # ... (all chat messages are configurable — see the default config for the full list)
crates:
  legendary:
    display-name: "Legendary Crate"
    color: GOLD                # NamedTextColor (GOLD, AQUA, LIGHT_PURPLE, GRAY, ...)
    icon: TRIAL_SPAWNER        # Material — used as both the held item AND the animated chest
    particle: END_ROD          # Particle played during open + reveal
    loot:
      # Short form (vanilla material, amount 1)
      - { material: DIAMOND, weight: 25 }
      # With explicit amount (can exceed 64; gets split into stacks on pickup)
      - { material: BREAD, weight: 20, amount: 128 }
      # Full ItemStack form — custom names, enchantments, lore, NBT
      - weight: 5
        item:
          type: DIAMOND_SWORD
          amount: 1
          meta:
            display-name: "&6&lExcalibur"
            enchants:
              SHARPNESS: 5
              UNBREAKING: 3
            lore:
              - "&7A legendary blade"
              - "&7granted by fortune"

Loot entry forms

Short form — { material: X, weight: N } — vanilla item, amount 1. Example: { material: DIAMOND, weight: 25 }
With amount — { material: X, weight: N, amount: M } — vanilla item, any amount including > 64. Example: { material: BREAD, weight: 20, amount: 128 }
Full ItemStack — { item: {...}, weight: N } — custom name, enchants, lore, NBT, custom model data. See the Excalibur example above.

The full item: form follows Bukkit's ItemStack.serialize() schema, so any item that exists in-game can be embedded.
Adding a new crate

YAML:

crates:
  mythic:
    display-name: "Mythic Crate"
    color: DARK_PURPLE
    icon: DRAGON_HEAD
    particle: DRAGON_BREATH
    loot:
      - { material: DRAGON_EGG, weight: 1 }
      - { material: NETHERITE_BLOCK, weight: 5, amount: 4 }

Then /cb reload. The per-crate permission contraband.use.mythic is auto-registered.
Roadmap

bStats metrics integration
Per-server update checker
Vault economy integration (buy crates with in-game currency)
Brigadier-native subcommand args (typed arguments, better tab UX)

Contact
Discord: inidde
Feel free to message me, i can do custom stuff too if needed.

Boonbox v1.0

Overview History