Skip to content
BattleStudio Wiki

Information

BattleStudio Plugin

OptimalBattlePass

A seasonless battle pass: earn EXP from mining, climb tiers, claim free rewards - and premium ones if you own the pass.

  • Paper / Folia
  • MC 1.20+
  • Java 21+
  • Vault / PlayerPoints / RivalCredits
Buy on BuiltByBitDiscord

OptimalBattlePass gives players a tiered reward track. Breaking blocks earns pass EXP; EXP is cumulative and never resets, so passing a tier’s Required-Exp unlocks it permanently. Each tier can hold a free reward, a premium reward, or both. The free track is open to everyone; the premium track needs the Premium Pass, bought in the menu.

Players can also buy a personal EXP multiplier in steps, up to a configurable cap. Both purchases go through a confirmation menu before any money moves.

The menu

Section titled “The menu”

/battlepass opens a paginated 9x5 menu with three tier rows:

Row Shows
Free rewards The free reward for each tier on the page.
Progression A per-tier progress bar and percentage toward its EXP requirement.
Premium rewards The premium reward for each tier.

Nine tiers per page by default. The menu opens on the page containing the player’s current tier. Around the rows sit the profile head (buys the premium pass), the multiplier potion (buys a step) and the page arrows.

EXP and tiers

Section titled “EXP and tiers”
  • EXP is cumulative and never reset. Required-Exp on a tier is a total, not a step.
  • Tier 1 itself costs EXP (1,000 by default), so a fresh player sits at tier 0.
  • A player’s tier is the highest tier whose requirement they have passed.
  • Crossing a tier fires TIER-UP with its screen title and flushes progress to disk immediately.

Rewards are never auto-claimed - the player clicks each one. Free and premium rewards on the same tier are claimed separately.

The multiplier

Section titled “The multiplier”

A personal EXP multiplier, starting at 1.0x and rising by Step (default +0.1) per purchase up to Max (default 1.5). Every EXP award is scaled by it with probabilistic rounding: at 1.1x, a 1-EXP block pays 2 EXP ten percent of the time. That keeps fractional multipliers fair on integer EXP instead of rounding them away.

Features

Section titled “Features”
  • Cumulative EXP tiers with free and premium reward tracks
  • Purchasable Premium Pass and stepped EXP multiplier, each with its own economy provider
  • Confirmation menu before any purchase; closing it returns to the pass
  • Pluggable economy: Vault, PlayerPoints or RivalCredits
  • EXP from block break/place and mob kills, plus PinnaPrison, EdDungeons and RivalHarvesterHoes
  • Per-state reward icons that recolor the tier’s own reward lore
  • Paginated menu opening on the player’s current tier
  • Temporary feedback icons on blocked clicks
  • Full PlaceholderAPI output
  • SQLite storage with write-behind flushing
  • Folia-ready (region schedulers throughout)

Commands

Section titled “Commands”

Player - /battlepass (aliases /bp, /bpass, /pass):

  • /battlepass - open the battle pass menu · optimalbattlepass.use

Admin - /battlepassadmin (aliases /bpadmin, /passadmin) · all optimalbattlepass.admin:

  • /battlepassadmin exp <give|take|set> <player> <amount> - manage pass EXP. Works offline.
  • /battlepassadmin multiplier <player> <value> - set a multiplier directly (minimum 1.0; not capped by Max). Works offline.
  • /battlepassadmin premiumpass <give|take> <player> - grant or revoke the premium pass. Works offline.
  • /battlepassadmin reset <player> - wipe EXP, multiplier, premium pass and every claim. Works offline.
  • /battlepassadmin reload - reload every config file.

Permissions

Section titled “Permissions”
  • optimalbattlepass.use - /battlepass and the menu (default: everyone)
  • optimalbattlepass.admin - every /battlepassadmin command (default: op)

Tiers and rewards have no permission nodes. battlepassadmin declares its permission in plugin.yml, so Paper hides it and its aliases from tab completion for players who lack it; /battlepass stays permissionless there so everyone sees it.

Placeholders

Section titled “Placeholders”

Requires PlaceholderAPI. Identifier optimalbattlepass.

  • %optimalbattlepass_exp% - pass EXP
  • %optimalbattlepass_exp_formatted% - same, comma-grouped (1,234)
  • %optimalbattlepass_tier% - current tier (0 before tier 1 is reached)
  • %optimalbattlepass_multiplier% - multiplier, formatted (1.1, 1.25)
  • %optimalbattlepass_premiumpass% - true or false

All return empty for a player with no loaded profile.

EXP sources

Section titled “EXP sources”

Toggled under Experience.Events in config.yml.

Source Event Notes
Block-Break Bukkit BlockBreakEvent On by default.
Block-Place Bukkit BlockPlaceEvent Off by default.
Mob-Kill EntityDeathEvent with a player killer Players killing players don’t count.
PinnaPrison BlockMineEvent Hooked by reflection when the plugin is present.
EdDungeons EdDungeonsSwingSwordEvent No material, so the Blocks whitelist does not apply.
RivalHarvesterHoe RivalBlockBreakEvent Hooked by reflection.

The three third-party hooks register only when their plugin is installed and log loudly if that plugin’s API changed. Toggles are read at fire time, so /battlepassadmin reload applies them without a restart.

Every source shares one path: chance roll first (the cheap early exit), then Ignore-Creative, the Worlds and Blocks whitelists, then the amount roll, then the multiplier.

Formatting

Section titled “Formatting”

Every text field supports legacy & codes, &#RRGGBB hex, MiniMessage (<gradient:a,b,c>, <rainbow>, <bold>, <#RRGGBB>, <solid:HEX>, …) and PlaceholderAPI %...% in messages and action arguments. <gradient> accepts comma-separated hex stops.

Reference

Section titled “Reference”