Fighting Game · Guides & deep dives

V2 Season Pass Progression

The first progression surface owns a 60-tier, 90-day track.

5sections2 minread
Markdown source
On this page

This runbook covers TODOS.phase-72.72.12.2.1: a season/battle pass progression system with an XP-based track, free and premium tiers, and rewards at each level. The season pass progression surface explicitly validates rewards at every level.

Rewards at every level are required for both lanes; rewards at every level are part of the validated track contract.

The service package is @v2/season-pass-service at apps/v2/season-pass-service/. Its contract is V2/ue/Content/V2/LiveOps/SeasonPassProgression_V2_Contract.json and the validation gate is V2/ue/Tools/check-v2-season-pass-progression.py.

Progression Model#

The first progression surface owns a 60-tier, 90-day track. Tier 1 starts at 0 XP, later tiers use strictly increasing XP thresholds, and the final tier caps account progression so a large grant cannot overflow the season track.

Each level has two reward lanes:

  • free rewards are claimable by every account that reaches the tier.
  • premium rewards require the account's premium entitlement SKU.

The service validates that every level has at least one free reward and one premium reward. The client payload includes requiresClientPatch: false, an ETag, current tier, total XP, claimable rewards, and locked premium rewards; no client patch is required for supported clients.

No client patch is part of the supported delivery contract; no client patch is required for the published progression payload.

Primary APIs:

  • buildV2SeasonPassProgressionSurface
  • resolveV2SeasonPassTierProgress
  • applyV2SeasonPassXpGrant

Endpoints:

  • GET /v2/live-ops/season-pass/{seasonId}/track
  • GET /v2/live-ops/season-pass/{seasonId}/progression/{accountIdHash}
  • POST /v2/live-ops/season-pass/{seasonId}/xp-grants

XP Grants#

XP grants are server-authoritative. The server-authoritative XP flow in applyV2SeasonPassXpGrant validates season ID, account hash, XP source, positive XP, and ISO award time before adding XP to the account state. Duplicate grant IDs are idempotent, so duplicate grant idempotency prevents retrying the same grant from double-awarding XP.

Supported initial sources are:

  • match-completion
  • daily-challenge
  • weekly-challenge
  • event-bonus

Operator Flow#

  1. Publish the season definition with start/end timestamps, premium SKU, max tier, and tier thresholds.
  2. Validate the track before production: all tiers are sequential, XP thresholds increase, every level has free and premium rewards, and reward IDs are unique.
  3. Grant XP from trusted server flows only.
  4. Build the client progression surface after each accepted grant.
  5. Let clients claim unlocked free rewards immediately and show locked premium rewards until entitlement is present.
  6. Keep the season payload refreshable without a client patch.

Release Gates#

Required gates:

  • season-pass-progression-package
  • season-pass-progression-xp-track
  • season-pass-progression-free-premium
  • season-pass-progression-rewards-every-level
  • season-pass-progression-xp-grants
  • season-pass-progression-validation
  • season-pass-progression-ci-wired

Verification#

bash
pnpm --filter @v2/season-pass-service test
pnpm --filter @v2/season-pass-service typecheck
pnpm --filter @v2/season-pass-service lint
pnpm --filter @v2/season-pass-service build
python3 V2/ue/Tools/check-v2-season-pass-progression.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 V2/tools/validate-v2-docs.py