Installation

Requirements

• Java 21+ - required. The plugin is compiled to Java 21 bytecode; on Java 17 or older it fails with UnsupportedClassVersionError. Check with java -version.
• Paper / Folia (or a Paper fork). Spigot is not supported. api-version is 1.20.
• Minecraft 1.20+, built against 1.21.11. The server must run Java 21.
• An economy if you want the Premium Pass or the multiplier to be purchasable. Pick a provider per product with Multiplier.Economy and Premium-Pass.Economy: Vault (with a Vault economy), PlayerPoints or RivalCredits. Without one, that purchase denies.

Optional soft dependencies (hooked only if installed):

• PlaceholderAPI - required for the %optimalbattlepass_...% placeholders, and for resolving other plugins’ %...% inside messages and menu actions.
• Vault / PlayerPoints / RivalCredits - the purchase currency.
• PinnaPrison, EdDungeons, RivalHarvesterHoes - extra EXP sources. Each hook is pure reflection and registers only when its plugin is present.

Tier rewards are console commands, so whatever plugin grants them needs to be installed - the plugin does not hook it directly.

Steps

1. Confirm java -version reports 21 or higher.
2. Stop the server.
3. Drop OptimalBattlePass.jar into plugins/.
4. (Recommended) Add PlaceholderAPI.jar, your economy plugin, and any of the mining plugins above you want as EXP sources.
5. Start the server. The plugin generates its files and prints a startup banner with the tier count.
6. Run /plugins - OptimalBattlePass should be green.

XSeries downloads automatically on first startup via Paper’s library loader, so the first launch needs internet access and may take a few extra seconds. SQLite is not downloaded - the plugin uses the sqlite-jdbc driver Paper already bundles.

Only purchasable products pre-warm their economy hook at load. If a provider can’t be resolved, the console logs a warning and purchases with it deny cleanly rather than erroring.

Generated files

plugins/OptimalBattlePass/
├─ config.yml                       # experience, multiplier, premium pass, icons, sounds
├─ rewards.yml                      # every tier, in one file (15 ship)
├─ messages.yml                     # every message
├─ guis/
│  ├─ battlepass-menu.yml           # the main /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 testable out of the box: page 1 is tiers 1-9, page 2 is tiers 10-15. They call orbs, eco, tokens and crates commands, and the default economy for both purchases is RivalCredits - retarget both before going live.

Storage

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

Writes are buffered and flushed on Settings.Save-Interval (default 60 seconds), plus on quit and shutdown. A claim, a purchase and a tier-up are each flushed immediately, so a crash can never re-grant a reward or lose money that has already moved.

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