# V2 Limited-Time Game Mode System

This runbook covers `TODOS.phase-72.72.12.2.7`: a limited-time game mode system
that can enable and disable game modes on schedule, including event-exclusive
modes.

The implementation lives in `@v2/limited-time-game-mode-service` at
`apps/v2/limited-time-game-mode-service/`. Its contract is
`V2/ue/Content/V2/LiveOps/LimitedTimeGameMode_V2_Contract.json` and the
validation gate is `V2/ue/Tools/check-v2-limited-time-game-mode.py`.

## Schedule Definitions

Limited-time mode definitions include:

- `scheduleId`
- `modeId`
- `queueId`
- `rulesetId`
- `startsAt`
- `endsAt`
- `eventExclusive`
- `eventId`
- `regions`
- `activationTags`

The service validates start/end windows, duplicate schedule IDs, overlapping
mode or queue windows, event-exclusive mode ownership, region lists, and
activation tags before an active queue can be published.

## Enable And Disable

`buildV2LimitedTimeGameModeSurface` publishes upcoming, enabled, and disabled
game mode sets from the same server-authoritative schedule. Enabled modes expose
their queue and ruleset IDs only while the generated timestamp is inside the
mode window. `resolveV2LimitedTimeGameModeState` is the shared state resolver
for upcoming, enabled, and disabled windows.

Event-exclusive modes must declare an owning `eventId`. The active event
exclusive set is published separately so matchmaking and event UI can hide those
queues outside the event surface without requiring a client patch.

Primary APIs:

- `buildV2LimitedTimeGameModeSurface`
- `resolveV2LimitedTimeGameModeState`

Service endpoints:

- `GET /v2/live-ops/game-modes/limited-time/schedule`
- `GET /v2/live-ops/game-modes/limited-time/active`
- `POST /v2/live-ops/game-modes/limited-time/{scheduleId}/state`

## Operator Flow

1. Author limited-time game mode definitions with start/end times, queue IDs,
   rulesets, regions, and event-exclusive ownership.
2. Publish through `buildV2LimitedTimeGameModeSurface`.
3. Send only `enabledGameModes` and `activeEventExclusiveGameModes` to
   matchmaking and event UI.
4. Let the service disable expired modes automatically after `endsAt`.
5. Keep `requiresClientPatch: false`; changing a schedule or event-exclusive
   owner is a data update.

## Gates

- `limited-time-game-mode-package`
- `limited-time-game-mode-schedule`
- `limited-time-game-mode-enable-disable`
- `limited-time-game-mode-event-exclusive`
- `limited-time-game-mode-active-queue`
- `limited-time-game-mode-validation`
- `limited-time-game-mode-ci-wired`

## Verification

```sh
pnpm --filter @v2/limited-time-game-mode-service test
pnpm --filter @v2/limited-time-game-mode-service typecheck
pnpm --filter @v2/limited-time-game-mode-service lint
pnpm --filter @v2/limited-time-game-mode-service build
python3 V2/ue/Tools/check-v2-limited-time-game-mode.py
```