> For the complete documentation index, see [llms.txt](https://enchantedmobs.superiormc.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://enchantedmobs.superiormc.cn/for-ultimatequest/configuration/battlepasses.md).

# Battle Passes

Battle passes provide a seasonal progression system. Players complete challenges to earn points, advance through levels, and claim free or premium rewards. Use `/uq battlepass` to browse passes and select one to view its rewards and challenges.

## Creating a battle pass

Create `battlepasses/<id>.yml`. Passes have a season, cumulative points, automatically assigned challenges, and free/premium level tracks. Example (metadata and task/reward sections belong to the same file):

```yaml
enabled: true
name: '{lang:defaults.battlepasses.example.name}'
categories:
- adventure
season: season_1
season-name: '{lang:defaults.battlepasses.example.season-name}'
season-prefix: expedition
rotation:
  enabled: true
  reset-mode: CRON
  reset-time: 0 0 0 1 * ?
premium-by-permission: true
premium-permission: ultimatequest.battlepass.example.premium
cap-experience: true
claim-grace-seconds: 604800
auto-claim: false
paused: false
leveling:
  count: 30
  base: 100
  increment: 10
  multiplier: 1.0
```

```yaml
tasks:
  stone:
    points: 25
    group: daily
    reset: daily
    categories: [gathering]
    unlock-week: 1
    catch-up: true
    premium: false
    source: {quest: miner, amount: 64}
levels:
  '1':
    free:
      food:
        type: item
        item: {material: BREAD, amount: 8}
    premium:
      gem:
        type: item
        item: {material: DIAMOND, amount: 1}
```

## Challenges and levels

Each `tasks.<id>` needs positive integer `points` and normal `source`/`objectives`. Challenge categories are independent of catalog categories. `reset` is daily/weekly/season and defaults to `group`, or season when absent. `group`/`group-name` controls browsing. `unlock-week` starts at 1; `catch-up: true` permits later completion, false limits availability to the unlock week. `premium: true` requires premium access for that challenge.

Completion automatically settles challenge points. Challenges occupy `battlepass-task` slots; the reward-track container does not. Assignment follows configured order and retries when slots free up.

`levels.<n>.required` is a strictly increasing cumulative threshold; levels start at 1 without gaps. Alternatively, `leveling` generates thresholds by adding `ceil((base + increment * (level - 1)) * multiplier^(level - 1))` per level. Count is 1–10000, base positive, increment nonnegative, multiplier finite and at least 1. Explicit thresholds override generated values. `cap-experience: true` caps points at the last threshold.

Premium comes from persisted admin entitlement or the configured permission when `premium-by-permission` is enabled. `auto-claim` attempts eligible stage claims. Time windows, paused state, and claim grace apply. Random stage rewards lock when unlocked.

## Seasons and boosts

Rotation uses [reset formats](/for-ultimatequest/configuration/periods.md), deriving the season ID from `season-prefix` and the cycle start. First installation enters the current calendar cycle. Saved seasons use `<id>@<season>`; ended seasons stop progress and retain their claim grace.

```
/uq battlepass season pause example
/uq battlepass season resume example
/uq battlepass season end example
/uq battlepass season start example season_2 2592000
/uq battlepass season schedule example season_3 2026-11-01T00:00:00Z 2026-12-01T00:00:00Z
/uq battlepass season globalboost example 2 3600
```

Manual start/schedule/end disables rotation. Player, global, and permission boosts use the highest multiplier, not their product. Configure `permission-boosters.<id>.permission` and `.multiplier`. See [commands](/for-ultimatequest/information/commands-permissions.md) and [rewards](/for-ultimatequest/configuration/rewards.md).