# V2 Season Pass Reward Definitions

This runbook covers `TODOS.phase-72.72.12.2.2`: a season pass reward definition
format for cosmetics, currency, items, emotes, and titles per tier.

The implementation extends `@v2/season-pass-service` at
`apps/v2/season-pass-service/`. Its contract is
`V2/ue/Content/V2/LiveOps/SeasonPassRewardDefinitions_V2_Contract.json` and the
validation gate is `V2/ue/Tools/check-v2-season-pass-reward-definitions.py`.

## Reward Definition Format

The reward definition format flattens each season tier into explicit free and
premium reward records. Each record includes:

- `seasonId`
- `tierLevel`
- `lane` (`free` or `premium`)
- `rewardId`
- `rewardKind`
- `displayName`
- `quantity`
- `catalogRef`
- `entitlementRef`
- `localizedNameKey`
- `grantPayload`

Supported reward kinds:

- `cosmetic`
- `currency`
- `item`
- `emote`
- `title`

Every level must retain at least one free reward and one premium reward. The
definition surface validates rewards at every level, required reward kinds,
catalog references, entitlement references, localization keys, and grant
payloads. The generated format keeps `requiresClientPatch: false`. No client
patch is required for the supported reward definition payload; no client patch
is part of the contract. no client patch.

Primary APIs:

- `buildV2SeasonPassRewardDefinitionSurface`
- `validateV2SeasonPassRewardDefinitionFormat`

Endpoints:

- `GET /v2/live-ops/season-pass/{seasonId}/reward-definitions`
- `POST /v2/live-ops/season-pass/{seasonId}/reward-definitions/validate`

## Operator Flow

1. Author each tier with free and premium reward lanes.
2. Use supported reward kinds only: cosmetics, currency, items, emotes, and
   titles.
3. Validate the reward catalog before publishing a season track.
4. Confirm every per-tier definition has catalog, entitlement, localization, and
   grant payload metadata.
5. Publish the reward definition format with the season pass progression payload
   so clients can render tier rewards and servers can fulfill grants without a
   client patch.

## Release Gates

Required gates:

- `season-pass-reward-definitions-format`
- `season-pass-reward-definitions-cosmetic-currency-item`
- `season-pass-reward-definitions-emotes-titles`
- `season-pass-reward-definitions-per-tier-lanes`
- `season-pass-reward-definitions-grant-metadata`
- `season-pass-reward-definitions-validation`
- `season-pass-reward-definitions-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-reward-definitions.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 V2/tools/validate-v2-docs.py
```