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 simply leaves that slot covered by the menu filler.

Tier fields

Key	Default	Description
Enabled	true	false removes the tier from the track and from pagination.
Required-Exp	0	Cumulative EXP total needed. Negative values are clamped to 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 numeric and 1 or higher. A non-numeric key fails the load with the key printed to console. Tiers are sorted by number, not by file order, so new ones can be appended at the bottom.

Required-Exp should ascend with the tier number. The plugin does not enforce it, but a player’s tier is “the highest tier whose requirement is passed”, so a requirement that dips would make lower tiers unreachable as a current tier.

Free and Premium

Both take the same two fields:

Key	Required	Description
Lore	no	Lines describing the reward. Expanded wherever the state icon has a {reward-lore} line.
Commands	yes	Console commands run on claim, with {player} replaced. 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"

On Folia, commands are dispatched on the global thread.

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 currently looking at, not from the tier. That is why the defaults write bullets 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

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. Claim mark. Already claimed sends ALREADY-CLAIMED and flashes Already-Claimed.
4. The claim is flushed to the database immediately.
5. Commands run, then REWARD-CLAIMED is sent and the menu repaints.

Free and premium claims are tracked separately, so both halves of a tier are claimed with two clicks. Granting the premium pass later makes every already-reached premium reward claimable at once

• it does not claim them retroactively.

Nothing is ever auto-claimed. TIER-UP only tells the player something is waiting.

Pagination

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

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

Validation

Checked on load and on every reload; these fail loudly rather than being skipped:

• A missing Rewards: section
• A non-numeric or below-1 tier key
• A Free or Premium section with an empty Commands list