Skip to content

💰 Currency – Reason Text

Namespace: RevGaming.RevFramework.Common.UX
(Conditionally compiled when REV_CURRENCY_PRESENT is defined)

🎯 Purpose

ReasonText.Currency provides human-readable messages for currency operation results.

It converts:

  • CurOpCode → readable string
  • CurOpResult → readable reason (preferring Message when available)

This utility is used by:

  • UI messages (shop errors, tooltips)
  • Debug overlays
  • Teaching panels
  • Logging and diagnostics

It ensures consistent wording across all systems that surface Currency outcomes.

🧩 What it covers

ReasonText.Currency maps all canonical currency operation codes:

Code Meaning
Ok Success (returns empty string by default)
UnknownError Unexpected error
InvalidArgs Invalid request (null owner, negative amount, invalid id)
ServiceMissing Required currency service or backend capability unavailable
NotFound Currency target not found (wallet, rule, or lookup target)
InsufficientFunds Not enough balance for Debit/Transfer
Overflow Amount exceeds allowed limits
BelowMinimum Cap policy (Fail mode) minimum violation
AboveMaximum Cap policy (Fail mode) maximum violation
Unauthorized Authority binder denied the mutation

Messages are intentionally short, neutral, and developer-friendly. They are suitable for tooling, logs, and teaching panels.

For player-facing UX, wrap, rephrase, or localise them as appropriate.

✔ API

string ReasonText.Currency(CurOpCode code)

Returns a readable string for the enum value.

string ReasonText.Currency(CurOpResult result)

Returns:

  • result.Message if present
  • Otherwise, the mapped string for result.Code

Example:

var r = svc.Debit(player, gold, 500);
Debug.Log(ReasonText.Currency(r));
// "Not enough balance."

💡 Usage examples

UI popup (shop error)

var r = CurrencyPurchase.TrySpend(svc, player, cost, "Shop", itemId);
if (!r.Success)
{
    ShowPopup(ReasonText.Currency(r));
}

Tooltip for disabled buttons

var (id, shortBy) = svc.FirstShortfall(player, item.Cost);
tooltip.text = shortBy > 0
    ? ReasonText.Currency(CurOpCode.InsufficientFunds)
    : string.Empty;

Logging & diagnostics

var r = svc.SetBalance(player, gold, -5);
Debug.LogWarning($"SetBalance failed: {ReasonText.Currency(r)}");

📝 Best practices

  • Use this utility whenever surfacing CurOpResult to UI, logs, or tooling.
  • Teaching panels should always display ReasonText.Currency(result) for consistency.
  • For player-facing text:
  • Localise
  • Rephrase
  • Or map to your own UX copy

If you extend CurOpCode in future systems, mirror the mapping here.

🧠 Design notes

  • This helper intentionally lives in Common.UX, not Currency Core.
  • It has no runtime dependency on decorators or services.
  • Conditional compilation prevents accidental linkage when Currency is not present.

Safe to delete

If you do not need standardised currency messaging:

  • Logs can format results manually
  • UI can provide its own wording

Removing this file does not affect Currency logic.

  • Currency Core — CurOpCode, CurOpResult
  • Decorators — sources of currency failure reasons
  • UI — components surfacing currency state
  • Teaching — panels surfacing live currency feedback