A fully configurable GUI battle pass for Paper servers. Players earn Battle Pass XP from gameplay, level through a tier track, and claim rewards from multiple pass types — free, premium, gold, or any number of passes you create yourself. Every pass, reward, menu item and message is defined in YAML, so the entire system can be reskinned and rebalanced without touching a line of code.
Passes and rewards
- Unlimited pass types — each pass is one file in plugins/BattlePass/passes/. Three examples (free, gold, premium) ship with the plugin and /battlepass extractpasses restores fresh copies of them at any time, backing up your edits.
- Command-based rewards — every reward runs console commands (give, effect, whatever you need) with {player} support. Items, potions, currency payouts, ranks — if a command can do it, a reward can hand it out.
- Per-reward display states — each reward defines its own locked, unlocked and claimed item (material, name, lore, glow), with fallback templates for rewards that don't. Rewards are placed anywhere in the GUI via their own page and slot.
- Pass access control — each pass has its own permission node, declared with default: false and registered automatically, so ops never accidentally own a pass for free.
- Purchasable passes — charge real money through Vault or a PinnaPrison currency, with a fully configurable buy button, owned indicator, and clear messages for already-owned, insufficient funds and missing currency.
- Pass requirement chains — a pass can demand another pass first (required-pass: gold), with an optional requirement item that replaces the buy button and explains exactly what to buy. Configured requirements are validated on reload so a typo'd id can never silently lock a pass forever.
Earning XP and leveling
- Configurable XP sources — blocks, mobs and fishing, individually or combined. Per-material and per-mob XP values with decimal support (STONE: 0.01, DIAMOND_ORE: 8), plus a global XP cooldown.
- Two leveling formulas — linear or exponential tier costs, both configurable down to the decimal, with a configurable max tier.
- Visual progress track — a slot-per-level row in the GUI lights up as tiers are reached, continuing across pages, with configurable unlocked/locked items and placeholders ({level}, {xp}, {required_xp}, {progress_bar} and more).
Pass Multiplier and Credits
- Personal XP multiplier — players spend Credits to upgrade their own multiplier: 1.0x, 1.1x, 1.2x and so on, boosting the XP sources you choose. Every parameter is configurable — starting value, step, maximum (raise it to add more levels), base cost and cost increase per level.
- Credits currency — balances are stored with player data, shown via the %battlepass_credits% placeholder, and managed by admins with /battlepass credits give|take|set.
- Dedicated multiplier menu — a clean GUI showing the current level, current and next multiplier, cost and balance, fully reskinnable in gui.yml, opened from the main GUI or /battlepass multiplier.
Placeholders
Ships with a PlaceholderAPI expansion: %battlepass_level%, %battlepass_xp%, %battlepass_credits%, %battlepass_multiplier% and more, for scoreboards, leaderboards and chat formats.
Admin tools
- Player management — set/add levels and XP per player, open a per-player admin GUI, reset one player or everyone (with confirmation), including purchased passes when configured.
- Full control — survival-only mode, disabled worlds, configurable sounds for claims, level-ups, clicks and purchases, and a live reload of every config file.
Requirements and compatibility
- Runs on Paper 1.20+ (Java 17).
- Optional hooks: PinnaPrison (prison currencies for pass purchases), Vault (money purchases), PlaceholderAPI (placeholders). All hooks are soft dependencies — the plugin runs fine without any of them.
Commands
- /battlepass (or /bp, /pass) — open the battle pass GUI
- /battlepass multiplier — open the Pass Multiplier menu
- /battlepass credits <give|take|set> <player> <amount>
- /battlepass admin [player] — per-player admin GUI
- /battlepass setlevel, addlevel, setxp, addxp, reset, resetall
- /battlepass extractpasses, reload, help