Prison Pass (Battlepass)

PrisonPass adds a seasonal battle pass to your prison server. Players earn pass XP by mining and completing daily and weekly tasks, climb through tiers and claim a free reward at each one. Premium pass owners also get a second reward track, extra tasks and bonus XP.

The short version

Upload the jar to plugins/ and restart the server. Then open plugins/prisonpass/seasons/season-1/season.yml, set start, end and timezone for your first season, and run:

/pass admin reload
/pass admin season info
/pass
/pass admin tier give <your name> 3
/pass claimall

1. /pass admin reload loads your new dates.
2. /pass admin season info shows the season's state. It should say Active. If it says Starting soon or Ended, check the dates and the timezone.
3. /pass opens the battle pass hub. Your first daily and weekly tasks are rolled within a few seconds of the season going active, and you get a chat message when they're ready.
4. /pass admin tier give <your name> 3 moves you to tier 3, so you've got something to claim.
5. /pass claimall claims the free rewards of tiers 1 to 3. With the bundled tiers, that's tokens, gems and money.

To wipe your test progress afterwards, run /pass admin resetplayer <your name>.

What you need

Seasons

A season is a folder under plugins/prisonpass/seasons/ with a season.yml and a tiers.yml. active-season in config.yml names the one that's running. These are the settings you'll change in season.yml:

display-name: '&d&lSeason 1 Pass'
start: '2026-09-25 00:00'
end: '2026-11-06 00:00'
claim-grace: 72h
timezone: 'Europe/London'
daily-reset: '00:00'
weekly-reset-day: MONDAY
tiers: 50
xp-per-tier: '1000 + {tier} * 30'

• Dates. Write them as yyyy-MM-dd HH:mm in the season's timezone. Leave start blank to start straight away, or end blank for a season that never ends.
• States. Before start, the pass is locked. Between start and end, it's Active: XP and tasks only move in this state. After end, players have claim-grace to claim what they've unlocked. After that, the season is over.
• XP curve. xp-per-tier is the XP each tier costs, and {tier} is the tier being unlocked. It accepts + - * / ^ ( ), so '1000' gives a flat curve and '800 * 1.03 ^ {tier}' a steep one. To change the cost of a single tier, add xp-required to that tier in tiers.yml.

To run a new season, copy seasons/season-1 to seasons/season-2, edit it, then run /pass admin season start season-2. Everyone starts again from tier 0, and the old season's progress stays archived in the database. /pass admin season end sets the active season's end to now, which starts the claim grace period.

Tiers and rewards

tiers.yml lists what each tier gives on the free track and the premium track. Rewards are ids from rewards.yml, and a tier can have several on each track:

'1':  { free: [tokens-100k],               premium: [tokens-250k, common-pet-egg] }
'2':  { free: [gems-1k],                   premium: [mine-key-3] }

rewards.yml sets how each reward looks in the tier menu and what claiming it does:

tokens-100k:
  material: SUNFLOWER
  name: '&e100k Tokens'
  lore: ['&7A handful of tokens.']
  actions: ['give-eco tokens 100k']

A line with no prefix is a PinnaPrison action, such as give-eco. Prefixed lines can run a console command ([console]), run a command as the player ([player]), send a [message], [broadcast], [title] or [actionbar], play a [sound], give a PinnaPrison personal [booster], add raw [passxp] or hand over an [item]. Use {player}, {uuid}, {tier} and {season} in any line. The comment block at the top of rewards.yml shows each format.

Players have to claim their rewards: they click them in /pass tiers, or claim everything at once with /pass claimall or the Claim All button. If a reward gives items and the player's inventory is too full, the claim waits until they make room.

After the last tier, the overflow section of config.yml gives a repeatable bonus reward every every-xp XP (5,000 by default).

Daily and weekly tasks

At each daily and weekly reset, every player rolls their own set of tasks from tasks/daily.yml and tasks/weekly.yml. The tasks section of config.yml sets how many:

• count is the number of free tasks (5 daily and 7 weekly by default).
• premium-extra adds premium slots (2 daily and 3 weekly). Free players can see these tasks, but only premium players can progress them.
• difficulty-mix sets how many of the free slots are easy, medium and hard.
• rerolls is how many tasks a player can reroll per reset. They right-click a task in the menu, or run /pass reroll. The prisonpass.rerolls.<n> permission raises this limit, and reroll-cost can charge a currency for each reroll.

Each entry in a task file is a template:

jackhammer-easy:
  type: PROC_ENCHANT
  filter: jackhammer
  name: '&6Proc Jackhammer {required} times'
  material: ANVIL
  required: 60-100
  xp: 110
  difficulty: easy
  weight: 12

required can be a range, and each player gets a random amount within it. weight sets how often a task comes up, and 0 takes it out of the rotation. Add premium-only: true to keep a task for premium slots, or scaling to grow the amount with a player's progress, such as their rebirths. The top of tasks/daily.yml lists every task type and what its filter matches.

Edits to the task files apply to tasks rolled after you reload. Tasks players already have keep their amounts and XP until the next reset.

The weekly pool has CUSTOM tasks for opening crates, hatching pet eggs and voting. They're set to weight: 0 because something else has to report the progress. To turn one on, get the other plugin to run pass admin progress <player> <key> 1 -s as a console command each time it happens (the keys are open-crate, hatch-egg and vote). Then raise the task's weight.

How players earn pass XP

• Tasks. Each completed task pays its xp.
• Playing. xp-sources in config.yml gives XP for mining (1 XP per 500 blocks by default), enchant procs, and earning or spending currencies. Fractions add up, so 0.2 XP per proc is 1 XP every 5 procs.
• Multipliers. Premium players get multipliers.premium-bonus extra (+10% by default). prisonpass.multiplier.<n> permissions multiply XP too, for example prisonpass.multiplier.1.5 for 1.5x. Set permission-stacking to HIGHEST to use the best one, or SUM to add them up.
• XP events. /pass admin booster start 2 2h doubles everyone's pass XP for two hours and shows a boss bar. It keeps running through a restart.
• Tier skips. Players can buy tiers with a currency in /pass shop or with /pass skip. The tier-skip section sets the currency (Gems), the price per tier (25k) and the limit per season (10). A skip moves the player to the start of the next tier, so XP they'd already earned towards it isn't added on top.

Pass XP is also a PinnaPrison currency called passxp, so any PinnaPrison action can hand it out, for example give-eco passxp 500. XP given this way, by [passxp] rewards or by /pass admin xp, skips the multipliers.

Giving players premium

Premium unlocks the premium track, the premium task slots and the premium XP bonus. If a player gets premium halfway through a season, the premium rewards of every tier they've already reached become claimable straight away. There are three ways to give it:

• From your store. Have the store run pass admin premium give <player> -s from the console, with your store's player-name variable in place of <player>. Store tier skips use pass admin tier give <player> <tiers> -s, and XP packs use pass admin xp give <player> <amount> -s. These work while the player is offline, and store tier skips don't count towards tier-skip.max-per-season.
• With a permission. prisonpass.premium gives premium for as long as the player has it, in every season. It's useful as a rank perk.
• In game. Players can buy premium with /pass premium or the Premium Pass button in /pass. They click or run it once to see the price, then again within confirm-seconds to buy. The premium-purchase section of config.yml sets the currency (Credits) and the price (1,000). To charge a different price in one season, add premium-cost to its season.yml. Players can only buy while the season is Active.

Premium that's bought or given is saved for the current season only. When you start a new season, those players start without it.

Commands

Player commands need prisonpass.use, which everyone has by default. /pass also works as /battlepass, /bp and /prisonpass.

Admin commands all need prisonpass.admin and work from the console. Add -s as the last argument to hide every reply, which is useful for store and vote commands. XP and progress amounts accept values like 2.5k, but tier counts must be whole numbers.

Permissions

Permission changes take effect within about 30 seconds, or straight away if you run /pass admin reload.

Files

The menus are PinnaPrison GUI files. PrisonPass installs them the first time it starts and never overwrites them, so your edits are safe across updates. /pass admin reload doesn't touch them: use /pinna reload. To get a default menu back, delete its file and restart the server. The comments at the top of each menu file list the tokens and button actions you can use. For general GUI syntax, see the PinnaPrison docs.

Placeholders

PrisonPass registers PinnaPrison variables, so they work in PinnaPrison's scoreboards, menus and messages without PlaceholderAPI. Each one is %pinnaprison_variable_pass_<key>%, for example %pinnaprison_variable_pass_tier%. Inside the pass menus, the same values are available as {key} tokens, written with dashes instead of underscores (for example {tier-xp}).

The leaderboard refreshes every leaderboard.refresh (5 minutes by default), and only includes players with some XP this season.

Troubleshooting

Players say the season isn't running, or their XP and tasks don't move. Run /pass admin season info. If the state isn't Active, the current time is outside the season's dates. Fix start, end and timezone in the active season's season.yml, or leave end blank, then run /pass admin reload. New tasks are only rolled while a season is Active.

Crate key rewards don't arrive. The bundled key rewards use a command that PrisonCrates doesn't understand. Change their actions in rewards.yml as described in Tiers and rewards, then run /pass admin reload.

A store purchase didn't do anything. -s hides every reply, errors included. Run the same command from the console without -s to see what's wrong. "Player not found" means the name is misspelt or the player has never joined your server. They have to join once before you can give them anything. tasks and progress also need the player to be online.

I removed premium, but the player still has it. They probably have prisonpass.premium, for example from a rank. /pass admin premium remove only removes premium that was bought or given with a command, so take the permission away as well.

/pass says a menu isn't loaded, or menu edits don't show. Check that the file is in plugins/PinnaPrison/guis/prisonpass/ and that its YAML is valid, then run /pinna reload. If you deleted the file, restart the server to reinstall the default.

The plugin disables itself on start, or /pass admin reload fails. Read the console. active-season in config.yml has to match a folder under seasons/ that contains a season.yml. "Could not open the pass database" points to your MySQL details, or to a first start without internet access, when Paper couldn't download the drivers. If config.yml has a YAML error, PrisonPass runs on its built-in defaults until you fix the file and reload.