rewards.yml

Every tier lives in rewards.yml under a single Rewards: section. The entry key is the tier number. After editing, run /battlepassadmin reload.

Fifteen tiers ship by default, from 1,000 to 600,000 EXP. A walkthrough is in Creating Tiers; this page is the full reference.

Structure

Rewards:
  "1":
    Enabled: true
    Required-Exp: 1000
    Free:
      Lore:
        - " {secondary}- &f10,000,000 Orbs"
      Commands:
        - "orbs give {player} 10000000"
    Premium:
      Lore:
        - " {secondary}- &f1x Buff Tokens"
      Commands:
        - "tokens give {player} buff 1"

  "2":
    Enabled: true
    Required-Exp: 2500
    Free:
      Lore:
        - " {secondary}- &f25,000,000 Orbs"
      Commands:
        - "eco give {player} 25000000"

  "3":
    Enabled: true
    Required-Exp: 10000
    Premium:
      Lore:
        - " {secondary}- &f100,000,000 Orbs"
        - " {secondary}- &f2x Trait Token"
      Commands:
        - "eco give {player} 100000000"
        - "tokens give {player} trait 2"

Tier 2 is free-only and tier 3 is premium-only. A missing section leaves that slot showing the menu background.

Tier fields

Key	Default	Description
Enabled	true	false removes the tier from the track, the menu and the reward counters.
Required-Exp	0	Cumulative EXP total needed. Negative values become 0.
Free	none	The reward anyone who reached the tier can claim.
Premium	none	The reward that also needs the Premium Pass.

The key must be a whole number, 1 or higher. Anything else fails the load with the key printed to console. Tiers are sorted by number, not by file order, so new ones can go at the bottom. Numbers do not have to be consecutive.

Required-Exp should rise with the tier number. The plugin does not enforce it, but a player’s tier is “the highest tier whose requirement is reached”, so a requirement that dips makes the numbering confusing.

Free and Premium

Both take the same two fields:

Key	Required	Description
Lore	no	Lines describing the reward. Shown where the state icon has its {reward-lore} line.
Commands	yes	Console commands run on claim, with {player} replaced by the player’s name. An empty list fails the load.

A section that is absent is fine. A section that exists with no Commands is an error, so don’t leave a half-written block behind.

    Premium:
      Lore:
        - " {secondary}- &f5x Buff Tokens"
        - " {secondary}- &f1x Monthly Key"
      Commands:
        - "tokens give {player} buff 5"
        - "crates key give {player} monthly 1"

Commands run one by one from console, starting on the next server tick (on Folia, on the global region).

Lore and colors

Lore is display only, it never affects what is granted. Keep it in step with Commands by hand.

{primary} and {secondary} inside a tier’s Lore are filled from the state icon the player is looking at, not from the tier. That is why the defaults write lines as " {secondary}- &f...": the same line renders gold on an unclaimed reward, red on a locked one and green on a claimed one, straight from the Primary / Secondary values in Reward-Icons.

The rest of the icon (material, name, the surrounding lore, the {type} label) also comes from those templates. This file only supplies the reward lines and the commands.

Claiming

Clicking a reward icon runs these checks in order:

1. Premium gate. A premium reward without the pass sends PREMIUM-REQUIRED and flashes Premium-Required.
2. EXP gate. Below Required-Exp sends REWARD-LOCKED and flashes Locked.
3. Already claimed sends ALREADY-CLAIMED and flashes Already-Claimed.
4. The claim is saved to the database immediately.
5. The Commands run, REWARD-CLAIMED is sent, the CLAIM sound plays and the menu repaints.

Free and premium claims are tracked separately, so both halves of a tier take two clicks. Getting the pass later makes every already-reached premium reward claimable at once; nothing is claimed automatically.

Claims are stored by tier number. If you renumber tiers on a live server, players keep the claims of the old numbers.

Pagination

The menu shows as many tiers per page as guis/battlepass-menu.yml has slots for, nine by default. With 15 tiers that is page 1 = tiers 1-9 and page 2 = tiers 10-15.

Disabled tiers are left out entirely, so turning one off shifts everything after it up a slot.

Validation

Checked on startup and on every reload. These fail loudly rather than being skipped:

• A missing Rewards: section
• A tier key that is not a number, or is below 1
• A Free or Premium section with an empty Commands list

The console names the offending tier.