# V2 Currency Definition System

`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
```