Fighting Game · Guides & deep dives

V2 Config Documentation And Operational Runbook

This document is the operator-facing index for the V2 live-service config system.

6sections4 minread
Markdown source
On this page

This runbook covers TODOS.phase-72.72.12.1.15: config documentation and an operational runbook for live configuration, feature flags, maintenance mode, config dashboard review, and message-of-the-day announcements.

Authority#

This document is the operator-facing index for the V2 live-service config system. The detailed source runbooks remain:

  • V2/docs/live-service/remote-config-service.md
  • V2/docs/live-service/feature-flag-service.md
  • V2/docs/live-service/config-dashboard.md
  • V2/docs/live-service/message-of-the-day.md

The validated contract is V2/ue/Content/V2/LiveOps/ConfigDocumentationRunbook_V2_Contract.json, and the release gate is V2/ue/Tools/check-v2-config-documentation-runbook.py.

Operator Scope#

Operators use this runbook when they need to:

  • change game parameters without a client patch through @v2/remote-config-service
  • enable, disable, gradually roll out, or kill-switch feature flags through @v2/feature-flag-service
  • inspect active remote configs, current values, segment targeting, and flag states through the apps/v2/web/live-service/config-dashboard surface
  • open or close maintenance-mode redirects during server updates
  • push message-of-the-day announcements for events, downtime, and patch notes

No client patch is required for the supported live config workflows when the client already supports the documented refresh surfaces.

Every production change must leave an audit trail that answers who changed what, when it changed, why it changed, and how it was validated.

Change Lifecycle#

change-intake#

Create a change record before editing any production-bound config. The record must include owner, requested environment, affected keys or flag IDs, expected player impact, rollback owner, rollout window, and whether the change is tied to an incident ID.

risk-classification#

Classify each change before staging:

  • Standard: low-risk tuning, copy, or scheduling changes.
  • Guarded: economy, progression, matchmaking, combat balance, targeting, or rollout-percentage changes.
  • Emergency: kill switch, maintenance-mode, critical downtime, rollback, or any player-impacting mitigation tied to an incident ID.

Guarded and emergency changes require four-eyes approval before production. Emergency changes must include the incident ID in the published audit metadata.

validation-rules#

Run validation before staging and before production promotion. Remote config changes must pass the validation-rules surface, including known parameter keys, numeric bounds, positive enemy health, drop-rate caps, and non-decreasing XP curves. Feature flags must keep rollout percentages in range and preserve clientPatchRequired: false.

preview-staging#

Preview production-bound changes in staging before promotion. The staging review must compare current value, default value, proposed value, segment targeting, feature flag state, ETag, generated timestamp, and audit reason in the config dashboard.

production-rollout#

Roll production changes in the smallest useful scope:

  1. Publish to staging and verify the staging client payload.
  2. Confirm the config dashboard shows the expected active values and flag state.
  3. Promote to production with owner, reason, change summary, and incident ID when applicable.
  4. Watch the active ETag, client refresh TTL, dashboard propagation state, and any affected gameplay telemetry.
  5. Leave the old version available for rollback until post-change monitoring is complete.

Incident Controls#

rollback#

Use remote config version history for instant rollback when a published config is bad. Rollback publishes a new version that restores a previous parameter map, marks the bad version rolled back, preserves requiresClientPatch: false, and records the rollback reason in audit-log-traceability.

kill-switch#

Use the feature flag kill-switch path when a shipped feature must be disabled across refresh-capable clients without a patch. The kill switch sets the target flag to force-disabled, sets rollout percentage to 0, invalidates the previous ETag, emits a cache-bust token, and caps max client staleness.

maintenance-mode#

Use maintenance-mode when server updates require all clients to leave gameplay or matchmaking. The maintenance command must publish title, message, reason, estimated resume time, status page URL, support URL when available, and a bounded maxClientStalenessSeconds. Closing maintenance must publish a clearing version so clients leave /maintenance.

message-of-the-day#

Use the message-of-the-day service for player-facing communications around events, downtime, and patch notes. Downtime messages should be non-dismissible when acknowledgement is required. Dismissible announcements must preserve per-account dismissal.

post-incident-review#

After an emergency change, attach the production version ID, incident ID, active ETag, rollback or kill-switch result, operator, reviewer, and screenshots or logs from the config dashboard to the incident review.

Audit Evidence#

Required evidence for every production change:

  • change request link or incident ID
  • operator and reviewer
  • source runbook used
  • validation report
  • staging preview result
  • production version ID and ETag
  • affected config keys, feature flags, maintenance state, or MOTD message IDs
  • rollback plan and rollback owner
  • post-change monitoring result

Audit-log-traceability must be enough for another operator to reconstruct the who, what, when, and why without relying on chat history.

Verification#

Run the relevant service gates for the affected surface, then run the cross-runbook gate:

bash
pnpm --filter @v2/remote-config-service test
pnpm --filter @v2/remote-config-service typecheck
pnpm --filter @v2/feature-flag-service test
pnpm --filter @v2/feature-flag-service typecheck
pnpm --filter @v2/message-of-the-day-service test
pnpm --filter @v2/message-of-the-day-service typecheck
python3 V2/ue/Tools/check-v2-remote-config-service.py
python3 V2/ue/Tools/check-v2-remote-config-validation-rules.py
python3 V2/ue/Tools/check-v2-remote-config-preview-staging.py
python3 V2/ue/Tools/check-v2-remote-config-delivery-optimization.py
python3 V2/ue/Tools/check-v2-remote-config-maintenance-mode.py
python3 V2/ue/Tools/check-v2-feature-flag-service.py
python3 V2/ue/Tools/check-v2-feature-flag-kill-switch.py
python3 V2/ue/Tools/check-v2-config-dashboard.py
python3 V2/ue/Tools/check-v2-message-of-the-day.py
python3 V2/ue/Tools/check-v2-config-documentation-runbook.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 V2/tools/validate-v2-docs.py

Required gates:

  • config-documentation-runbook-doc
  • config-documentation-runbook-change-lifecycle
  • config-documentation-runbook-validation-staging
  • config-documentation-runbook-rollout-rollback
  • config-documentation-runbook-incident-controls
  • config-documentation-runbook-audit-evidence
  • config-documentation-runbook-ci-wired