Creating Tiers

Every tier lives in rewards.yml under the Rewards: section. The entry key is the tier number. You need optimalbattlepass.admin to reload.

1. Add a tier

Rewards:
  "16":
    Enabled: true
    Required-Exp: 800000
    Free:
      Lore:
        - " {secondary}- &f100,000,000 Orbs"
      Commands:
        - "orbs give {player} 100000000"
    Premium:
      Lore:
        - " {secondary}- &f5x Buff Tokens"
        - " {secondary}- &f1x Monthly Key"
      Commands:
        - "tokens give {player} buff 5"
        - "crates key give {player} monthly 1"

Field	Description
Enabled	false drops the tier from the track and from pagination.
Required-Exp	Cumulative EXP total. Not an increment over the previous tier.
Free	Optional. The reward everyone can claim.
Premium	Optional. Needs the Premium Pass to claim.

A tier may omit either section, or both. A row with no reward for that tier just shows filler, so a premium-only tier is fine.

Both Free and Premium take a Lore list (what the reward icon shows) and a Commands list (what actually runs). A section that exists but has no commands fails the load.

Full field list: rewards.yml reference.

2. Set the requirement

Required-Exp is a total, so the track should ascend:

"1":  Required-Exp: 1000
"2":  Required-Exp: 2500
"3":  Required-Exp: 10000

Tier 1 costs EXP too, so a brand-new player is tier 0 until they hit 1,000. A player’s tier is the highest one whose requirement they have passed, and EXP is never reset.

3. Reload

/battlepassadmin reload

The tier appears immediately. Test it with /battlepassadmin exp set <you> 800000, and /battlepassadmin premiumpass give <you> to check the premium row.

Tuning the earn rate

Three settings in config.yml set the pace:

Experience:
  Chance: 100.0
  Min-Amount: 1
  Max-Amount: 1

At the defaults every block break is 1 EXP, so tier 1 is 1,000 blocks and the full 15-tier track is 600,000. Scale Required-Exp to your server’s mining rates rather than fighting the amounts - a prison server doing millions of blocks a day needs very different numbers from a survival server.

To slow it down without touching every tier, drop Chance to something like 25.0. To speed it up, raise Max-Amount for a randomised 1-3 EXP per block.

Pagination

The three tier rows are equal-length slot lists in guis/battlepass-menu.yml:

Free-Reward-Slots: [9-17]
Progression-Slots: [18-26]
Premium-Reward-Slots: [27-35]

The list length is the tiers per page - nine by default. All three must be the same length; the n-th entry of each is one tier’s column. Adding tiers just adds pages, so you rarely need to touch this.

The menu opens on the page containing the player’s current tier.

Premium and free tracks

• A free reward is claimable by anyone who has reached the tier.
• A premium reward needs premiumPass on the player. Without it, clicking sends PREMIUM-REQUIRED and flashes the matching icon.
• They are claimed separately - reaching a tier does not claim either one.
• Granting the premium pass later makes every already-reached premium reward claimable at once. It does not retroactively claim them.

Sell the pass in-game with Premium-Pass.Purchasable: true, or keep it purchasable only through your webstore by setting that to false and running /battlepassadmin premiumpass give <player> from the donation command.

Notes

• Keys must be numeric and 1 or higher. A non-numeric key fails the load.
• Tiers sort by number, not by file order, so you can append new ones at the bottom.
• Reward lore recolors per state. {primary} and {secondary} in a tier’s Lore are filled from the Unclaimed / Locked / Claimed icon the player is looking at, which is why the defaults write bullets as " {secondary}- …".
• The {reward-lore} marker in the icon templates is where a tier’s Lore gets expanded. It is set in config.yml → Reward-Icons, not here.
• Rewards are console commands, so anything you can run from console you can hand out.