Fighting Game · Guides & deep dives

V2 Economy Design, Balancing, And Monitoring

flags, minor units, negative-balance rules, and hard caps.

6sections5 minread
Markdown source
On this page

This guide covers TODOS.phase-72.72.18.1.15: the economy documentation for design principles, balancing methodology, and monitoring. It is the operating map for the V2 economy surface; individual runtime docs remain the source of truth for structs, helper APIs, and feature-specific validation.

Runtime Map#

  • CurrencyDefinition.V2 owns stable currency ids, display metadata, premium flags, minor units, negative-balance rules, and hard caps.
  • CurrencyLedger.V2 records every currency mutation as an immutable audit trail with transaction ids, source ids, reasons, timestamps, and before/after balances.
  • ServerCurrencyAuthority.V2 is the only gameplay path that applies trusted currency mutations. Client-authored balance writes are rejected before ledger application.
  • PremiumCurrencySystem.V2 fulfills platform-verified premium currency receipts through ServerCurrencyAuthority.V2 with SourceId = platform.iap.
  • PriceTable.V2, vendor shops, auction house, and direct trade resolve item prices and player-to-player exchange while preserving currency ids and ledger auditability.
  • V2LootTable, V2LootTableDebugger, V2EconomySimulation, and EconomyBalanceTuning.V2 are the authoring and live-ops surfaces used before rewards, prices, and drop rates ship.
  • @v2/economy-analytics, @v2/economy-analytics-dashboard, EconomyExploitDetection.V2, and ServerEconomyValidation.V2 provide the monitoring and enforcement loop after changes are live.

Design Principles#

  1. Keep the ledger server-authoritative. Economy state changes must flow through ServerCurrencyAuthority.V2 and CurrencyLedger.V2; direct client balance writes, local-only spend approvals, and untrusted source ids are not valid economy state.
  2. Use stable ids and minor units. Currency ids, item ids, and price rows must be stable across patches, and all currency amounts must use minor units so rounding never changes a spend or grant.
  3. Put caps and premium rules in data. CurrencyDefinition.V2 hard caps, negative-balance permissions, and premium currency flags are the rules that fulfillment, pricing, and display surfaces consume.
  4. Make every grant and sink attributable. A transaction needs a unique transaction id, source id, reason, timestamp, account id, and audit tag set before its audit trail is acceptable for review or rollback analysis.
  5. Separate earned, purchasable, and reputation economies. Soft currencies, premium currency, time-limited tokens, and reputation-style balances must have separate ids, sources, caps, and sink expectations.
  6. Treat monetization as explicit fulfillment. Real-money purchases require store server verification, account binding, replay protection, refund rejection, and platform.iap ledger grants. Gameplay rewards must not mimic store receipts.
  7. Prefer deterministic reward decisions. Loot and reward seeds should be derived from stable server context so replaying the same table, context tags, pity counters, and grant ids produces explainable results.
  8. Balance sources and sinks before widening access. New earn rates, vendors, auction fees, repairs, crafting costs, rerolls, and event rewards need a source/sink hypothesis and monitoring threshold before they reach production.

Balancing Methodology#

  1. Define the currency role and player cohort. For each proposed change, record whether the target is soft currency, premium currency, token, or reputation; identify the level bands, player segments, and item families affected.
  2. Model the source/sink plan in V2EconomySimulation. Include quest rewards, match payouts, vendor sell grants, live-event grants, repairs, crafting, auction fees, rerolls, and repeatable vendor spends. The simulation must show whether the economy is stable, inflating, or deflating over the target N-hour window.
  3. Validate reward randomness with V2LootTableDebugger. Use production-like context tags, deterministic seeds, pity counters, expected rates, and sample limits before a loot table or reward pool is allowed into a canary.
  4. Validate prices with PriceTable.V2. Buy prices, sell prices, dynamic multipliers, regional overrides, and quantity quotes must be checked against CurrencyDefinition.V2 currency ids and the expected sink/source ratio.
  5. Preview live-ops edits through EconomyBalanceTuning.V2. Drop rates, prices, and rewards must publish as remote config only when validation passes and the preview shows requiresClientPatch: false.
  6. Canary the smallest meaningful population. Release to a narrow segment, compare against baseline cohorts, and watch inflation, deflation, earn/spend rates, item price effectiveness, and support reports before a wider rollout.
  7. Document acceptance and rollback criteria before publish. Each balance change needs an owner, reason, target metric movement, abort threshold, rollback path, and the validation commands that passed.

Monitoring And Alerts#

  • @v2/economy-analytics tracks currency earn/spend rates, inflation tracking, and item price effectiveness.
  • @v2/economy-analytics-dashboard tracks currency supply velocity, average player wealth by level, item price trends, and sink/source ratios.
  • EconomyExploitDetection.V2 flags impossible currency gains, item duplication, untrusted currency sources, and exploit velocity; ranked and tournament economy signals queue fair-play review and fail closed.
  • ServerEconomyValidation.V2 remains the online validation boundary for suspicious spend/grant requests before downstream monitoring sees them.
  • Daily launch checks review supply velocity, average player wealth by level, active-player wealth by cohort, top source ids, top sink ids, premium currency fulfillment, refund/replay rejection, and item price movement.
  • Weekly balance review compares modeled source/sink expectations against live sink/source ratios, inflation and deflation trends, economy bot behavior, support incidents, and exploit evidence ids.
  • Alerts should fire when total supply velocity, wealth concentration, item price trends, or earn/spend rates exceed the documented canary threshold, or when impossible gains, duplicate item instances, receipt replay, or untrusted source ids appear in production.

Live-Ops Change Workflow#

  1. Open a balance proposal with the player cohort, currency role, source/sink hypothesis, expected player impact, and rollback owner.
  2. Run simulation, loot-table debugging, price-table validation, and remote-config preview in staging.
  3. Record the accepted validation output, target metrics, and alert thresholds in the proposal before publish.
  4. Ship through canary remote config, never by client patch unless the owning feature contract explicitly requires one.
  5. Watch the economy dashboard for the first day, then include the change in the weekly balance review until metrics return to the normal range.
  6. Roll back immediately when ledger integrity, premium purchase fulfillment, fair-play evidence, or hard-cap enforcement is in doubt.

Validation Commands#

Run these checks when changing economy design guidance, balancing methodology, monitoring docs, or CI/Horde wiring:

bash
python3 V2/ue/Tools/check-v2-economy-documentation.py
python3 V2/ue/Tools/check-v2-economy-simulation.py
python3 V2/ue/Tools/check-v2-economy-balance-tuning.py
python3 V2/ue/Tools/check-v2-economy-exploit-detection.py
python3 V2/ue/Tools/check-v2-economy-analytics.py
python3 V2/ue/Tools/check-v2-economy-analytics-dashboard.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 -m json.tool V2/ue/Content/V2/Gameplay/Economy/EconomyDocumentation_V2_Contract.json
python3 -m json.tool V2/ue/Build/Horde/v2-buildgraph-job.json
python3 V2/tools/validate-v2-docs.py