Fighting Game · Guides & deep dives

V2 Currency Definition System

display units, currency kind, display style, caps, tradability, premium flags, visibility, negative-balance rules, sign rules, and sort order.

4sections1 minread1table
Markdown source
On this page

CurrencyDefinition.V2 defines the shared economy currency catalog used by quests, vendors, rewards, analytics, and later economy systems. It supports soft currencies such as gold, premium currencies such as gems, event tokens, and reputation-style currencies with signed display.

Runtime Surface#

  • FV2CurrencyDefinition stores ids, localization ids, display codes, symbols, display units, currency kind, display style, caps, tradability, premium flags, visibility, negative-balance rules, sign rules, and sort order.
  • FV2CurrencyDefinitionCatalog stores multiple definitions and resolves by CurrencyId.
  • FV2CurrencyAmount stores an amount in minor units so decimal currencies can be added later without changing ledger APIs.
  • FV2CurrencyDisplayResult returns deterministic FormattedAmount, FormattedWithUnit, and FormattedWithSymbol strings for UI, debug, and telemetry surfaces.

Default Catalog#

The default catalog includes:

Currency Kind Display
currency.gold Soft 123,456 Gold, 123,456 G
currency.gems Premium 250 Gems, 250 Gem
currency.festival_tokens Token 42 Festival Tokens
currency.lotus_reputation Reputation +750 Lotus Reputation

Premium currency is explicitly marked with bPremiumCurrency and EV2CurrencyKind::Premium. Reputation can allow negative balances and can show a positive sign for gains.

Authoring Rules#

  1. Currency ids use the currency. prefix and must remain stable after release.
  2. DisplayCode values such as GOLD, GEMS, TOKEN, and LOTUS_REP must be unique inside one catalog.
  3. DisplayNameTextId, ShortNameTextId, and DescriptionTextId use loc.currency.* ids so localization can own display names independently from runtime ids.
  4. FractionDigits is capped at four digits. Store amounts in minor units when decimals are enabled.
  5. Soft and premium currencies cannot be negative unless bAllowNegativeBalance is explicitly enabled.
  6. Soft caps and hard caps are non-negative; a soft cap cannot exceed a hard cap when the hard cap is set.

Validation Commands#

Run these checks when touching currency definitions:

bash
python3 V2/ue/Tools/check-v2-currency-definition.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 -m json.tool V2/ue/Content/V2/Gameplay/Economy/CurrencyDefinition_V2_Contract.json
python3 -m json.tool V2/ue/Build/Horde/v2-buildgraph-job.json
python3 V2/tools/validate-v2-docs.py