Fighting Game · Guides & deep dives

V2 Player Compensation System

Primary APIs:

4sections1 minread
Markdown source
On this page

This runbook covers TODOS.phase-72.72.12.2.12: a player compensation system to grant items and currency to affected players after bugs or outages.

The service package is @v2/player-compensation-service at apps/v2/player-compensation-service/. Its contract is V2/ue/Content/V2/LiveOps/PlayerCompensation_V2_Contract.json, and the focused gate is V2/ue/Tools/check-v2-player-compensation.py.

Runtime Contract#

Primary APIs:

  • buildV2PlayerCompensationSurface
  • planV2PlayerCompensationGrants
  • applyV2PlayerCompensationGrant

Service endpoints:

  • GET /v2/live-ops/compensation/campaigns
  • POST /v2/live-ops/compensation/campaigns/{campaignId}/grants/plan
  • POST /v2/live-ops/compensation/campaigns/{campaignId}/grants/apply

Campaigns are tied to an incidentId, reason, affected-player evidence, grant bundle, and approval records. The supported reasons are:

  • bug
  • outage

The grant bundle must include item grants and currency grants. Item grants carry catalogRef and entitlementRef metadata, while currency grants carry a currency id and positive amount. Affected-player rows must include an accountIdHash, affected window id, evidence reference, severity, and affected time span.

Grant Flow#

  1. Live ops creates a compensation campaign after a bug or outage incident.
  2. Incident evidence selects affected players and records the affected window.
  3. An approver signs the campaign before grants are planned.
  4. planV2PlayerCompensationGrants builds idempotent item and currency grants.
  5. applyV2PlayerCompensationGrant applies each grant to the account ledger and skips already processed grant ids.

The service is server-authoritative and keeps requiresClientPatch: false.

Required Gates#

  • player-compensation-package
  • player-compensation-affected-players
  • player-compensation-bug-outage
  • player-compensation-item-grants
  • player-compensation-currency-grants
  • player-compensation-idempotency
  • player-compensation-validation
  • player-compensation-ci-wired

Verification#

sh
pnpm --filter @v2/player-compensation-service test
pnpm --filter @v2/player-compensation-service typecheck
pnpm --filter @v2/player-compensation-service lint
pnpm --filter @v2/player-compensation-service build
python3 V2/ue/Tools/check-v2-player-compensation.py