How to Make a Battlepass

A battlepass is the star of the show: one config file that defines how much XP each tier needs, how many tiers exist, and which rewards players earn on the Free and Premium tracks. This page takes you from an empty file to a working pass you can open in game.

Quick start

1. Open the /plugins/EcoBattlepass/battlepasses/ folder and copy _example.yml to a new file, e.g. seasonal.yml. The file name is the pass ID.

2. Set the name and the battlepass: block: xp-formula, max-tier, command, premium-permission, and the battlepass-start / battlepass-end dates.

3. Under tiers:, add a tier number and list the reward IDs it grants, each marked free or premium. See How to make a reward for the reward files themselves.

4. Run /ecobattlepass reload.

5. Run your pass command (e.g. /seasonal) and confirm the GUI opens with your tiers and rewards.

Naming and IDs

The file name without .yml is the battlepass ID. You use this ID in your category configs, in effect filters, and as the command name.

The structure of a battlepass

# === Settings: how the pass behaves ===
name: "&6Example Battlepass" # Display name shown in the GUIs
battlepass:
  xp-formula: "1.5 * %level% + 5" # XP needed per tier; %level% scales it per tier
  max-tier: 100 # Highest tier players can reach
  command: "battlepass" # Command that opens this pass's GUI
  premium-permission: "example.pass.premium" # Permission that grants the Premium track
  battlepass-start: 2025-01-01 00:00 # Start date, server time; format YYYY-MM-DD HH:MM
  battlepass-end: 2025-05-01 00:00 # End date, server time; format YYYY-MM-DD HH:MM

# === Tiers: what each tier awards ===
tiers:
  - tier: 1 # Skip a tier entirely to give it no reward
    rewards:
      - id: coins_5000 # Reward ID; the file name in /rewards/
        tier: free # "free" anyone can claim, "premium" needs the premium permission
      - id: coins_10000
        tier: premium

Settings

The battlepass: block controls how the pass runs.

battlepass:
  xp-formula: "1.5 * %level% + 5" # XP for the next tier; %level% is the current tier
  max-tier: 100 # Highest reachable tier
  command: "battlepass" # Command that opens the GUI
  premium-permission: "example.pass.premium" # Permission for the Premium track
  battlepass-start: 2025-01-01 00:00 # Start date, server time
  battlepass-end: 2025-05-01 00:00 # End date, server time

Tiers

Each entry under tiers: is a tier number and the rewards it grants.

tiers:
  - tier: 1 # Tiers you don't list simply have no reward
    rewards:
      - id: diamond_block # Reward ID, defined in /rewards/
        tier: free # "free" anyone, "premium" needs the premium permission
      - id: money_1000
        tier: premium

Display overrides

Each tier can optionally override the button appearance from config.yml for specific states. These beat the defaults, which is handy for highlighting milestone tiers.

tiers:
  - tier: 1
    rewards:
      - id: diamond_block
        tier: free
    display:
      # Generic override: used in combined layout, and as the fallback in split layout
      # States: unlocked, locked, in-progress, claimed, unlocked-free, premium-required, hidden
      unlocked:
        item: diamond_block
        name: "&6&lSPECIAL TIER"
        lore:
          - "&7Special rewards await!"
          - "%free-rewards%"
          - "%premium-rewards%"

      # Split-layout overrides: only used when layout: split in config.yml
      free-track:
        unlocked:
          item: emerald_block
          name: "&a&lFREE TIER - SPECIAL"
      premium-track:
        premium-required:
          item: gold_block
          name: "&6&lUPGRADE NEEDED"

Override priority, highest to lowest: track-specific override, then generic override, then track-specific config.yml default, then config.yml default.

Internal placeholders

Where to go next

• Rewards: How to make a reward defines what each tier grants.

• Quests: Configuring a category adds the quest system that feeds XP into the pass.

• GUI appearance: Plugin config is the full annotated config.yml.

• Placeholders: Internal placeholders lists everything usable in lore and names.

• Defaults: the shipped configs live here.