Battle Pass

Battle Pass

The Battle Pass module adds a seasonal progression track on top of the rest of the plugin. Players earn Battle Pass XP from quests, daily rewards, prestiges and rebirths, climbing tiers that grant rewards on two parallel tracks: a Free track everyone gets, and a Premium track unlocked by permission or your store. When a season ends you start a new one and progress resets — giving players a fresh reason to grind every month.

---

Overview

Feature	Details
Storage	Database
Tracks	Free + Premium
Tiers	Unlimited (set max-tier)
XP curve	base + (tier - 1) × increment, with optional per-tier overrides
XP sources	Quests, daily rewards, prestige, rebirth (and the API)
Premium unlock	Permission or /bp setpremium
Seasons	Reset any time with /bp newseason <id> (old progress archived)

---

Commands

/battlepass                          Open the Battle Pass menu (aliases: /bp, /pass)
/bp addxp <player> <amount>          Admin: give Battle Pass XP
/bp setpremium <player> <true|false> Admin: grant/revoke premium for a player
/bp newseason <id>                   Admin: start a fresh season with a new id

---

The Battle Pass Menu

/battlepass opens a fully configurable, paginated menu. The free track renders across one row of slots and the premium track across a parallel row below it, so each tier shows both rewards side by side. A central info icon shows the player's tier, total XP, XP to the next tier and premium status.

Each tier reward shows one of four states, controlled by gui.status in battlepass.yml:

State	Meaning
Claimed	Already claimed
Click to claim	Reached and ready — click to claim
Locked	Tier not reached yet
Premium required	Premium-track reward, premium not unlocked

---

Creating Unlimited Tiers

There is no cap on the number of tiers. To add more:

1. Set max-tier to however high you want (e.g. 100).
2. The XP needed for each tier is generated automatically from the xp.base and xp.increment curve, so every tier always has a requirement — even ones you don't list.
3. Add a tiers.<number> entry for any tier you want to grant a reward. A tier may have a free track, a premium track, or both. Tiers without an entry simply require XP but grant nothing (useful as filler between reward tiers).

max-tier: 100
xp:
  base: 1000
  increment: 500
  overrides:        # optional: hand-tune specific tiers
    100: 250000

tiers:
  42:
    free:
      display:
        material: DIAMOND
        name: "<white>Tier 42"
        lore:
          - "<gray>Reward: <green>$1,000,000"
          - ""
          - "%status%"
      rewards:
        commands:
          - "money give %player% 1000000"
        messages:
          - "<green>+ $1,000,000"
        sound: UI_TOAST_CHALLENGE_COMPLETE
    premium:
      display: { material: BEACON, name: "<light_purple>Tier 42 Premium", lore: ["<gray>Reward: <green>100 Gems", "", "%status%"] }
      rewards:
        commands: ["gems give %player% 100"]
        messages: ["<green>+ 100 Gems"]

Every reward is a reward bundle — an unlimited list of commands (with %player%), an unlimited list of messages, and an optional sound. Run any command your server has (give currency, crate keys, items, ranks, broadcasts…).

---

Premium Track

A player is treated as premium if either:

• they have the xprison.battlepass.premium permission (set premium.permission in the config), or
• they were granted premium directly with /bp setpremium <player> true (stored per season).

This makes premium easy to sell on your store (give the permission or run the command on purchase) without any pay-to-win, since the free track stays meaningful.

---

Seasons

The active season is defined under season: in battlepass.yml (id, display-name, optional start-date / end-date). Starting a new season with /bp newseason <id> (or changing the id and reloading) gives everyone a clean slate; the previous season's rows stay in the database as an archive.

---

Permissions

Permission	Description
xprison.battlepass.admin	Use the /bp admin subcommands
xprison.battlepass.premium	Treats the player as premium (configurable key)

---

PlaceholderAPI

Placeholder	Returns
%xprison_battlepass_tier%	Current tier
%xprison_battlepass_max_tier%	Highest tier this season
%xprison_battlepass_xp%	Total season XP
%xprison_battlepass_xp_next%	XP remaining until the next tier
%xprison_battlepass_premium%	Yes / No
%xprison_battlepass_season%	Current season display name

---

Titles & Sounds

Key moments fire a configurable on-screen title and a sound, configured under effects: in battlepass.yml. Each block has an optional title (with enabled, title, subtitle and fade-in/stay/fade-out in seconds) and an optional sound (with enabled, sound, volume, pitch). Set either enabled: false to silence just that part — everything ships on by default.

Event	Title	Sound	Placeholders
tier-up	✔	✔	%tier%, %season%
claim	–	✔	%tier%

effects:
  tier-up:
    title:
      enabled: true
      title: "<gradient:#00c6ff:#0072ff><bold>TIER %tier%</bold></gradient>"
      subtitle: "<white>Open <yellow>/bp <white>to claim your rewards"
      fade-in: 1
      stay: 3
      fade-out: 1
    sound:
      enabled: true
      sound: UI_TOAST_CHALLENGE_COMPLETE
      volume: 1.0
      pitch: 1.0
  claim:
    sound:
      enabled: true
      sound: ENTITY_PLAYER_LEVELUP

Sound names are standard Bukkit/XSound names.

---

How the Engagement Loop Fits Together

The Battle Pass is the seasonal meta that ties the engagement modules together: Daily Rewards and Quests both grant Battle Pass XP, so logging in and completing goals feeds tier progression, and the monthly season reset keeps players coming back.

---

Related Pages

• battlepass.yml — Default Config
• Quests
• Daily Rewards
• Commands & Permissions
• Placeholders
• Developer API