Skip to content

💰 Currency – UI

Namespace: RevGaming.RevFramework.Currency.UI

The Currency UI layer provides drop-in components for displaying wallet balances across Unity’s supported UI systems.

These components are purely presentational: - They never modify currency state - They never own wallet logic - They react to ICurrencyService.OnWalletChanged

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

🎯 Purpose

  • Display live wallet balances in UI.
  • Support UGUI, TextMeshPro, and UI Toolkit without branching gameplay code.
  • Bind UI elements to a wallet owner + CurrencyDefinition.
  • Remain fully compatible with any composed currency stack (Caps, Audit, Authority, Escrow, Idempotency, BatchEvents).

UI components are event-driven for updates, with a lightweight, throttled probe used only to detect late service wiring or service swaps.

Shared behaviour (all bars)

All currency bars:

  • Bind to:
  • a wallet owner (GameObject)
  • a CurrencyDefinition (for id, name, icon, formatting)
  • Resolve the active service via CurrencyResolve.ServiceFrom(this)
  • Subscribe to ICurrencyService.OnWalletChanged
  • Update only when (owner, currencyId.value) matches
  • Fall back cleanly to 0 when service or owner is missing
  • Unsubscribe automatically on disable / destroy
  • Auto-rebind if the resolved currency service changes (including override republishes in additive scenes) (throttled probe)

Currency matching is performed using the normalised CurrencyId.value string, not object reference equality.

Components

CurrencyBar (UGUI)

Uses UnityEngine.UI.Text and optional Image.

Fields

  • owner — wallet owner (falls back to a Player-tagged object on Awake)
  • currency — CurrencyDefinition
  • label — optional Text for display name
  • amountText — required Text for balance
  • icon — optional Image for sprite

Behaviour

  • Resolves the service at runtime via CurrencyResolve.
  • Subscribes to wallet change events.
  • Updates when the bound owner’s balance for the configured currency changes.
  • Auto-rebind if the resolved currency service changes (including override republishes in additive scenes).
  • Shows 0 when no service or owner is available.
  • Previews label and icon in the Editor (OnValidate).

Notes

  • Player-tag fallback runs once during Awake.
  • Updates are driven by currency id string, not asset reference.

CurrencyBarTMP (TextMeshPro)

TextMeshPro-based variant of CurrencyBar.

Differences from UGUI

  • Uses TextMeshProUGUI for label and amount
  • Optional autoRebind toggle:
  • When enabled, periodically re-resolves the service
  • Useful for late-loaded services or dynamic scene composition

All other behaviour matches the UGUI variant.

CurrencyBarUITK (UI Toolkit)

UI Toolkit implementation backed by a UIDocument.

Query names

  • nameLabel — Label for currency display name
  • amountLabel — Label for numeric balance
  • iconElement — Image for currency icon

Behaviour

  • Queries elements via rootVisualElement.Q<T>(queryName)
  • Subscribes to wallet change events
  • Automatically rebinds if the active service swaps or appears late
  • Previews name and icon in the Editor

Icon note (UITK)

UITK Image elements use Texture2D (or VectorImage). This implementation assigns CurrencyDefinition.Icon.texture; for atlas-backed sprites this may reference the entire atlas texture. For precise sprite rendering, prefer StyleBackground in USS/UXML.

🕹️ Usage

  1. Create one or more CurrencyDefinition assets.
  2. Add a bar component (CurrencyBar, CurrencyBarTMP, or CurrencyBarUITK).
  3. Assign a wallet owner (recommended). Leaving it blank falls back to a GameObject tagged "Player" (single-player convenience only).
  4. Assign the currency definition.
  5. Wire up UI fields or query names.

At runtime:

  • The service resolves via CurrencyResolve.
  • The bar subscribes to events.
  • UI updates automatically.

⚙️ Refresh API

All bars expose:

bar.RefreshNow();       // Force redraw
bar.SetOwner(newOwner); // Rebind to another wallet

Use these when: - Setting fields dynamically - Rebinding owners at runtime - Instantiating bars procedurally

⚠️ Gotchas

  • UITK bars require a valid PanelSettings asset.
  • TMP bars require the TextMeshPro package.
  • UGUI bars require the Unity UI module.
  • When instantiating dynamically, call RefreshNow() after setup.
  • Changing a CurrencyDefinition or its Id at runtime does not automatically rebind existing bars. Re-enable the component or call RefreshNow() after making changes.

Safe to delete

If your project does not need built-in currency UI components, you can delete this entire folder safely.

Currency runtime logic does not depend on UI.

  • Core — wallet events & service resolution
  • Decorators — batch/audit layers feed UI updates
  • Persistence — snapshot restore triggers UI refresh
  • Samples — 04_Currency_UIBars demonstrates all variants

✅ Summary

Currency UI components provide fast, event-driven visibility of wallet balances, with safe auto-rebinding for late service wiring. Assign an owner, choose a CurrencyDefinition, and the UI stays in sync automatically.