Skip to content

💰 Currency – Definitions

Namespace: RevGaming.RevFramework.Currency.Definitions

The Definitions layer contains optional ScriptableObjects and helpers that describe currencies in a designer-friendly, UI-ready way.

All core currency logic operates purely on CurrencyId + long. Definitions exist to support UI, formatting, debugging, and persistence workflows — not gameplay logic.

If you delete this entire folder, Currency continues to function normally.

Purpose

  • Provide designer-authored metadata for currencies (names, icons, formatting).
  • Centralise currency identity for UI, HUDs, popups, and debug tooling.
  • Offer a lightweight discovery mechanism (CurrencySetLocator) for UI/persistence code.
  • Keep runtime logic free of ScriptableObject dependencies.

Definitions describe how a currency is presented, never how it behaves.

Core assets

CurrencyDefinition

Represents a single designer-authored currency.

Fields: - Id
Canonical key (e.g. "gold", "gems"). Stored as entered, but all lookups normalise (trimmed, lowercased) when converted to CurrencyId.

  • DisplayName
    UI-facing name.

  • Icon
    Sprite for UGUI / UITK.

  • DecimalPlaces
    Formatting only. All balances remain minor units (long). Major-unit values are computed via powers of ten.

  • Format
    Optional pattern string (e.g. "{amount} GP"). The {amount} token is replaced after formatting.

Example: 

Id: gold
DisplayName: Gold
DecimalPlaces: 0
Format: "{amount} GP"

Important
CurrencyDefinition is never used for logic.
All gameplay code should work with CurrencyId and long values only.

CurrencySet

A bundle of CurrencyDefinition assets.

Provides: - All → read-only list of definitions - ToIds() → array of normalised CurrencyId - TryGet(CurrencyId, out CurrencyDefinition) → lookup helper

Normalisation behaviour: - Deduplicates by id (last definition wins) - Removes null entries - Preserves authoring order while ensuring uniqueness

A CurrencySet is typically the source of truth for which currencies exist in a project.

CurrencyFormat

Formatting utilities used across UI, HUDs, popups, debug panels, and tools.

Number styles

  • Plain — 1234
  • Grouped — locale-aware separators (1,234 / 1.234)
  • Compact — 1.2K, 3.4M, 5.6B, 7.8T

CurrencyFormatOptions

Configurable formatting options: - culture - style - alwaysShowSign - maxFractionDigits - trimTrailingZeros

Example: 

var str   = CurrencyFormat.Format(def, balance);   // "1,234"
var delta = CurrencyFormat.FormatDelta(def, +500); // "+500"

DecimalPlaces affects display only — balances always remain long minor units.

Binders & locators

CurrencySetBinder

Scene component that advertises a CurrencySet for lookup.

  • Registers the set with CurrencySetLocator on enable
  • Unregisters on disable
  • Works across additive scenes

Attach this to any GameObject to make currency discovery reliable for UI and persistence.

CurrencySetLocator

Lightweight resolver for finding the active CurrencySet.

Resolution order: 1. Scene-scoped cache (from CurrencySetBinder) 2. Fallback: first CurrencySetBinder in the scene (includes inactive) 3. Final fallback (global, not scene-scoped):
Resources.Load<CurrencySet>("CurrencySet_Default")

Usage: 

var set = CurrencySetLocator.Resolve(this);
if (set && set.TryGet(new CurrencyId("gold"), out var def))
    Debug.Log(def.DisplayName);

The locator is designed for convenience, not strict authority. If no set is found, callers must handle null.

Best practices

  • Keep currency ids simple (gold, gems, tickets).
  • Maintain a single authoritative CurrencySet per scene where possible. If multiple binders exist, the first valid one found is used.
  • Use CurrencyDefinition for UI and display only, never logic.
  • Use CurrencyFormat consistently so UI and HUDs match.
  • Combine CurrencySet with persistence to serialise only known currencies.

Safe to delete

If you do not need: - UI icons / labels - Formatting helpers - Designer-facing currency assets

…you can delete this entire folder safely.

Currency runtime logic does not depend on Definitions.

  • Abstractions — contracts and primitives (CurrencyId, Money)
  • Core — factories, resolvers, helpers
  • UI — currency bars (UGUI / TMP / UITK)
  • Persistence — snapshot capture and restore