Installation

Requirements

• OptimalLibrary - required. A free plugin that holds the shared runtime of every Optimal plugin (text and MiniMessage, menus, storage, currency hooks). OptimalBattlePass will not enable without it.
• Paper or Folia (or a Paper fork). Spigot is not supported. Supported versions: 1.21.11, 26.1.1, 26.1.2, 26.2 and 26.3.
• Java 21 for 1.21.11, Java 25 for the 26.x versions. Check with java -version.
• A currency if you want the Premium Pass or the multiplier to be purchasable in-game. Each product picks its own with Economy in config.yml. Without an available currency, that purchase is refused with PURCHASE-UNAVAILABLE.

Optional soft dependencies (hooked only when installed):

• PlaceholderAPI - needed for the %optimalbattlepass_...% placeholders, and for resolving other plugins’ %...% inside messages, menus and action arguments.
• Vault (with a Vault economy), PlayerPoints, RivalCredits - purchase currencies.
• OptimalCredits, OptimalGens, OptimalMobcoins - purchase currencies through their <PROVIDER>_<currency> names, e.g. OPTIMALCREDITS_CREDITS.
• PinnaPrison, EdDungeons, RivalHarvesterHoes, OptimalGens - extra EXP sources. Each hook only registers when its plugin is present, and still has to be switched on under Experience.Events.

Tier rewards are console commands, so whatever plugin grants them (your economy, crates, tokens) has to be installed too, but OptimalBattlePass does not hook it directly.

Steps

1. Confirm java -version reports the right version for your server (21 or 25).
2. Stop the server.
3. Drop OptimalLibrary.jar and OptimalBattlePass.jar into plugins/.
4. (Recommended) Add PlaceholderAPI.jar, your currency plugin, and any of the EXP source plugins above that you want to use.
5. Start the server. The plugin generates its files and prints a startup banner with the tier count.
6. Run /plugins - OptimalLibrary and OptimalBattlePass should both be green.

On first start, OptimalLibrary downloads its libraries (SQLite, MySQL and HikariCP drivers, XSeries) through Paper’s library loader, so that first launch needs internet access and may take a few extra seconds.

If a purchasable product’s currency can’t be found at startup or reload, the console logs a warning and that purchase is refused in-game until it is fixed. An Economy name that is not a known provider at all stops the load with an error naming it.

Generated files

plugins/OptimalBattlePass/
├─ config.yml                       # EXP, multiplier, premium pass, progress bar, icons, sounds
├─ rewards.yml                      # every tier, in one file (15 ship)
├─ messages.yml                     # every message, plus the reward type names
├─ guis/
│  ├─ battlepass-menu.yml           # the /battlepass menu
│  ├─ confirm-multiplier-menu.yml   # multiplier purchase confirmation
│  └─ confirm-premium-menu.yml      # premium pass purchase confirmation
└─ data/
   └─ data.db                       # SQLite player data (do not edit by hand)

Fifteen tiers ship in rewards.yml, from 1,000 to 600,000 EXP, so pagination is visible out of the box: page 1 is tiers 1-9, page 2 is tiers 10-15. Their rewards call orbs, eco, tokens, crates, dragoneggs, robots, credits, cubes and lootbox commands, and both purchases default to the RivalCredits currency. Retarget all of these at your own plugins before going live.

Deleted keys stay deleted

config.yml, rewards.yml and the guis/ files are not refilled from the defaults when you remove something from them, so a tier or menu item you delete stays gone after a reload or update. messages.yml is the exception: missing message keys are written back with their defaults.

Storage

Player state (EXP, multiplier, Premium Pass and the claimed free and premium tiers) is stored in SQLite at data/data.db, one player_pass row per player. There is no MySQL option.

• A player’s data is loaded while they log in. If it cannot be loaded, the login is refused with the PROFILE-LOAD-FAILED message instead of letting them play with an empty pass.
• Changes are kept in memory and saved every Settings.Save-Interval seconds (default 60), when the player quits, and on server shutdown.
• A claim, a purchase and a tier-up are each saved immediately, so a crash can never re-grant a reward or lose a purchase that was already paid for.
• Admin commands on offline players write straight to the database.

Continue to Creating Tiers, or read the Information overview first.