Skip to content
BattleStudio

Information

OptimalBattlePass features, EXP and tiers, the premium pass and multiplier, commands, permissions, placeholders and tokens in one reference.

BattleStudio plugin

OptimalBattlePass

Players earn pass EXP from mining and other activity, climb tiers and claim free rewards, plus premium ones with the Premium Pass.

Requires
Paper / FoliaMC 1.21.11+Java 21+OptimalLibraryPlaceholderAPI
Buy on BuiltByBitInstallation guideGet support

OptimalBattlePass gives players a tiered reward track. Breaking blocks (and any other source you switch on) earns pass EXP. EXP is cumulative and never resets on its own, so reaching 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.

Players can also buy a personal EXP multiplier in steps, up to a configurable cap. Both the pass and the multiplier are bought in the menu through a confirmation screen, with the currency of your choice: Vault, PlayerPoints, RivalCredits, or a currency from another Optimal plugin such as OptimalCredits.

OptimalBattlePass runs on top of OptimalLibrary, a free shared plugin that has to be installed next to it. See Installation.

The menu

Section titled “The menu”

/battlepass opens a paginated 5-row menu with three tier rows:

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

Nine tiers per page by default. Every time the menu opens it jumps to the page holding the player’s current tier. Around the rows sit the profile head (buys the Premium Pass), the multiplier potion (buys a multiplier step), the page arrows and a page indicator. Layout, slots and items are all in menus.

EXP and tiers

Section titled “EXP and tiers”
  • EXP is cumulative. Required-Exp on a tier is a running total, not a step over the previous tier. Only /battlepassadmin exp and /battlepassadmin reset ever lower it.
  • Tier 1 itself costs EXP (1,000 by default), so a fresh player sits at tier 0.
  • A player’s tier is the highest enabled tier whose requirement they have reached.
  • Crossing one or more tiers sends TIER-UP (with its screen title), plays the TIER-UP sound and saves the player’s progress immediately.
  • Rewards are never auto-claimed. The player clicks each one. The free and premium rewards of a tier are claimed separately.
  • Rewards are console commands, so anything you can run from console can be a reward.

The multiplier

Section titled “The multiplier”

A personal EXP multiplier that starts at 1.0x and rises by Multiplier.Step (default 0.1) per purchase, up to Multiplier.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 and 1 EXP otherwise. That keeps fractional multipliers fair on whole-number EXP instead of rounding them away.

Admins can set any multiplier of 1.0 or higher with /battlepassadmin multiplier, including values above Max.

EXP sources

Section titled “EXP sources”

Each source is toggled under Experience.Events in config.yml. Only block breaking is on by default.

Source Counts Notes
Block-Break A block broken by a player On by default.
Block-Place A block placed by a player
Mob-Kill A non-player entity killed by a player Player kills never count. No block type, so the Blocks whitelist does not apply.
PinnaPrison PinnaPrison block mining Hooked only when PinnaPrison is installed.
EdDungeons EdDungeons sword swings Hooked only when EdDungeons is installed.
RivalHarvesterHoe RivalHarvesterHoes block breaks Hooked only when RivalHarvesterHoes is installed.
OptimalGens Blocks dug by hand in an OptimalGens mining or farming region Hooked only when OptimalGens is installed. Each block in a harvest gets its own chance and amount roll, paid out as one award.

Cancelled block break, block place and death events never pay. The toggles are read every time an event fires, so /battlepassadmin reload applies them without a restart (a third-party hook itself is only registered at startup if its plugin is present).

Every source goes through the same checks: the Chance roll, then Ignore-Creative, the Worlds and Blocks whitelists, the Min-Amount/Max-Amount roll, and finally the player’s multiplier.

Features

Section titled “Features”
  • Cumulative EXP tiers with separate free and premium reward tracks
  • Any number of tiers, paginated automatically
  • Purchasable Premium Pass and stepped EXP multiplier, each with its own currency and price
  • Confirmation menu before any money moves; cancelling or closing it returns to the pass
  • Currencies: Vault, PlayerPoints, RivalCredits, or another Optimal plugin’s currency (OptimalCredits, OptimalGens, OptimalMobcoins)
  • EXP from block breaks, block places and mob kills, plus PinnaPrison, EdDungeons, RivalHarvesterHoes and OptimalGens
  • Chance and random amount per action, world and block whitelists, creative mode ignored by default
  • Reward icons per claim state (Unclaimed / Locked / Claimed) that recolor each tier’s own reward lore
  • Progress bars with percentages on every tier
  • Temporary feedback icons on refused clicks
  • Tier-up message with a screen title and sound
  • PlaceholderAPI placeholders
  • Offline-capable admin commands
  • SQLite storage, saved on an interval and immediately on every claim, purchase and tier-up
  • Folia-ready

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 - show the admin help.
  • /battlepassadmin exp <give|take|set> <player> <amount> - give, take or set pass EXP. <amount> is a whole number, 0 or higher. Taking more than the player has leaves them at 0.
  • /battlepassadmin multiplier <player> <value> - set the multiplier directly. <value> is a decimal of 1.0 or higher and is not capped by Multiplier.Max.
  • /battlepassadmin premiumpass <give|take> <player> - grant or revoke the Premium Pass.
  • /battlepassadmin reset <player> - wipe the player’s EXP, multiplier, Premium Pass and every claim.
  • /battlepassadmin reload - reload every config file, the tiers and the currency hooks.

Every player command above works on offline players too, as long as they have joined the server before. The change is written straight to the database.

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 of their own. /battlepassadmin and its aliases are hidden from players without optimalbattlepass.admin; /battlepass is visible to everyone.

Placeholders

Section titled “Placeholders”

Requires PlaceholderAPI. Identifier optimalbattlepass.

Placeholder Value
%optimalbattlepass_exp% Pass EXP, plain number (12345).
%optimalbattlepass_exp_formatted% Pass EXP, comma-grouped (12,345).
%optimalbattlepass_tier% Current tier (0 before tier 1 is reached).
%optimalbattlepass_multiplier% Multiplier with one or two decimals (1.0, 1.1, 1.25).
%optimalbattlepass_premiumpass% true or false.

They answer for online players only; for anyone else they return an empty string.

With PlaceholderAPI installed, %...% placeholders from other plugins also resolve inside messages, message titles, menu items and menu action arguments.

Tokens

Section titled “Tokens”

These are the plugin’s own {...} tokens. Where each one works is listed on the config pages; this is the summary.

Token Value Where
{exp} Pass EXP, comma-grouped. Menus, reward and progression icons, REWARD-LOCKED, EXP-GAINED.
{tier} Current tier, or the tier of the icon / message. Menus, icons, tier messages.
{required} The tier’s Required-Exp, comma-grouped. Reward and progression icons, REWARD-LOCKED, the Locked temporary icon.
{progress-bar}, {percent} Progress toward the tier ({percent} with two decimals, e.g. 37.50). Progression icons.
{type} Free-Label/Premium-Label in icons; Reward-Types in REWARD-CLAIMED. Reward icons, REWARD-CLAIMED.
{primary}, {secondary} The colors of the reward icon’s current state. Reward icons and the tier’s reward Lore.
{reward-lore} Expands into the tier reward’s Lore lines. Reward icon lore.
{multiplier} Current multiplier (1.1). Menus, MULTIPLIER-PURCHASED, MULTIPLIER-SET.
{next-multiplier} What the next purchase gives, capped at Max. Menus.
{multiplier-price}, {premium-price}, {price} Prices, comma-grouped. {price} is the price of the purchase in question. Menus, INSUFFICIENT-FUNDS.
{status}, {claimed-rewards}, {total-rewards} Pass status and reward counters. Main menu items.
{max} Multiplier.Max. MULTIPLIER-MAXED, the Multiplier-Maxed temporary icon.
{player} A player name. Admin messages, menu action arguments, reward Commands.

Formatting

Section titled “Formatting”

Every text field supports legacy & codes, &#RRGGBB hex, MiniMessage (<gradient>, <rainbow>, <bold>, <#RRGGBB>, …) and, with PlaceholderAPI installed, %...%. Messages also support [center] to center a line in chat.

Reference

Section titled “Reference”