Creating Tiers

Tiers are config, not commands. Every tier lives in rewards.yml under the Rewards: section, and the entry key is the tier number. You need optimalbattlepass.admin to reload.

1. Add a tier

Append a new entry under Rewards::

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 leave out either section. A row without a reward for that tier just shows the background, so a premium-only or free-only tier is fine.

Free and Premium each take a Lore list (what the reward icon shows) and a Commands list (what actually runs from console, with {player} replaced). A section that exists without commands fails the load.

Full field list: rewards.yml reference.

2. Set the requirement

Required-Exp is a running total, so it should go up with every tier:

"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 reach 1,000. A player’s tier is the highest one whose requirement they have reached, and EXP never goes down unless an admin changes it.

3. Reload and test

/battlepassadmin reload

The tier shows up in /battlepass immediately. To test it:

/battlepassadmin exp set <you> 800000
/battlepassadmin premiumpass give <you>

Then claim both rewards in the menu, and put yourself back with /battlepassadmin reset <you>.

Writing reward lore

The reward icon itself (material, name, the UNCLAIMED/LOCKED/CLAIMED footer) comes from Reward-Icons in config.yml. The tier’s Lore is dropped in where that template has its {reward-lore} line.

Use {primary} and {secondary} in your lore lines instead of fixed colors. They take the colors of the state the player is looking at, so this one line:

- " {secondary}- &f3x Pearl Keys"

shows a gold bullet while unclaimed, a red one while locked and a green one once claimed.

Lore is display only. Keep it in step with Commands yourself.

Tuning the earn rate

The pace is set in config.yml:

Experience:
  Chance: 100.0
  Min-Amount: 1
  Max-Amount: 1
  Worlds: []
  Blocks: []

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

• To slow it down without touching every tier, lower Chance (for example 25.0).
• To speed it up, raise Max-Amount for a random 1-3 EXP per block.
• To limit where EXP counts, list worlds in Worlds or materials in Blocks.
• To reward other activity, switch on sources under Experience.Events (mob kills, block placing, PinnaPrison, EdDungeons, RivalHarvesterHoes, OptimalGens).

Remember the multiplier sits on top: a player at 1.5x climbs half again as fast.

Pagination

The menu shows nine tiers per page by default, set by the length of the three slot lists in guis/battlepass-menu.yml. Adding tiers just adds pages, so you rarely need to touch them. The menu always opens on the page with the player’s current tier.

Notes

• Keys must be whole numbers, 1 or higher. Anything else fails the load.
• Tiers sort by number, not by file order, so you can append new ones at the bottom.
• Disable instead of delete with Enabled: false. Claims are stored by tier number, so a tier you re-enable later keeps the claims players already made on it.
• Free and premium are claimed separately, and nothing is ever auto-claimed. TIER-UP only tells the player something is waiting.
• Rewards are console commands, so anything you can run from console you can hand out.
• Check the console after a reload. A broken tier stops the reload with the tier named.