Skip to content

💰 Currency / Definitions

🎯 Purpose

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

All core currency logic operates on CurrencyId and long values. Definitions support UI, formatting, debugging, and persistence workflows.

Definitions are not required for Currency to function.

⚠️ Important Notes

  • Definitions do not affect gameplay logic
  • Runtime systems operate on CurrencyId and long values only
  • Definitions describe presentation, not behaviour
  • Removing this folder does not affect core Currency functionality

🧩 What Lives Here

CurrencyDefinition

Represents a single designer-authored currency.

Fields:

  • Id — canonical key (e.g. "gold", "gems")
  • DisplayName — UI-facing name
  • Icon — sprite for UI
  • DecimalPlaces — formatting only
  • Format — optional display pattern

Lookups normalize identifiers (trimmed, lowercase) when converted to CurrencyId.

CurrencySet

A collection of CurrencyDefinition assets.

Provides:

  • All — read-only list of definitions
  • ToIds() — normalized CurrencyId array
  • TryGet(...) — lookup helper

Normalization behaviour:

  • May remove duplicates (last definition wins)
  • Removes null entries when normalized
  • Without normalization, the first matching definition is returned

CurrencyFormat

Formatting utilities for UI and tooling.

Supported styles:

  • Plain
  • Grouped (locale-aware)
  • Compact

CurrencyFormatOptions includes:

  • culture
  • style
  • alwaysShowSign
  • maxFractionDigits
  • trimTrailingZeros

Example:

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

🧠 Usage Guidance

Binders & locators

CurrencySetBinder

  • Registers a CurrencySet on enable
  • Unregisters on disable
  • Supports additive scenes

Attach to a GameObject to enable discovery for UI and persistence.

CurrencySetLocator

Resolves the active CurrencySet.

Resolution order:

  1. Scene cache (from CurrencySetBinder)
  2. First binder in scene (includes inactive)
  3. Resources fallback (CurrencySet_Default)

Example:

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

The locator may return null if no set is found.

Best practices

  • Use simple currency identifiers (gold, gems, tickets)
  • Prefer a single authoritative CurrencySet per scene
  • Use definitions for UI only
  • Keep formatting consistent via CurrencyFormat

🚫 Not for Production Use

Definitions should not be used for gameplay logic.

🧹 Safe to Remove

This folder may be removed if UI, formatting, and designer-authored assets are not required.

Core Currency functionality does not depend on Definitions.

  • Abstractions — core contracts and primitives
  • Core — factories, resolvers, helpers
  • UI — currency display components
  • Persistence — snapshot capture and restore