Skip to content

RevFramework – Sample Scene: 08_Currency_Awaiters

Namespace: RevGaming.RevFramework.Runtime.Currency.Samples.Scenes

🎯 Purpose

Show how to use async Tasks and coroutines to wait for wallet changes without polling, using the CurrencyAwaiters API.
This scene demonstrates reactive, event-based logic for economy conditions like “wait until player has enough gold” or “detect wallet deltas”.

🧩 What This Scene Teaches

  • How to use CurrencyAwaiters for event-driven waiting instead of polling.
  • The difference between Task-based (C# async/await) and Coroutine-based (Unity yield) awaiters.
  • How to detect when a wallet reaches a target balance, changes by a threshold, or meets a custom predicate.
  • How to apply timeouts and cancellation tokens safely.
  • How to use delta-based triggers for more advanced, reactive systems.

🕹️ How to Use

  1. Enter Play Mode.
  2. Open the CurrencyAwaitersPanel (F8).
  3. Select a currency and configure:
  4. Target balance
  5. Delta threshold
  6. Timeout duration (optional)
  7. Start any test:
  8. WaitForBalanceAtLeastAsync → Completes when balance ≥ target.
  9. WaitForAnyChangeAsync → Completes on any wallet change.
  10. WaitForDeltaAsync → Completes when balance changes by N.
  11. WaitForPredicateAsync → Completes when a custom condition (v >= X) returns true.
  12. Use the Coroutine buttons to start or cancel Unity-style waits.
  13. Cancel waits early using the Cancel buttons for async and coroutine modes.

🔐 Authority (Important)

This sample scene includes a CurrencyAuthorityBinder configured for single-player use:

  • CurrencyAuthorityBinder
  • alwaysTrue = true

This allows all currency mutations so the demo works out of the box.

Why this exists

RevFramework currency mutations are authority-gated by default.

  • If no authority is present, all mutations are blocked.
  • This is intentional and required for multiplayer safety.

Multiplayer note

For multiplayer or server-authoritative games:

  • Do not use CurrencyAuthorityBinder
  • Implement your own ICurrencyAuthority
  • Validate all currency mutations on the server/host

This scene uses the permissive binder only to demonstrate behaviour in a local, single-player context.

💡 Key Takeaways

  • All awaiters subscribe to OnWalletChanged — no polling required.
  • Each awaiter supports timeouts and cancellation tokens for safety.
  • Both async and coroutine variants exist for flexible integration: ```csharp var gold = new CurrencyId("gold");

await CurrencyAwaiters.WaitForBalanceAtLeastAsync(svc, player, gold, 500); StartCoroutine( CurrencyAwaiters.WaitForBalanceAtLeast( svc, player, gold, 500, 10f, onComplete ) );

```
- Perfect for quest objectives, UI progress tracking, and economy-driven unlocks.
- Works with any decorated stack — Audit, Caps, Authority, Escrow, Idempotency.

⚙️ Stack Composition

Bootstrap: CurrencyServiceBootstrap
Service Stack:
SceneCurrencyService → CappedCurrencyService → AuditedCurrencyService → AuthorityCurrencyService → BatchEventCurrencyService
Teaching Panel: CurrencyAwaitersPanel

Scene Path:

Assets/RevFramework/Runtime/Systems/Currency/Samples/Scenes/08_Currency_Awaiters/

⚠️ Gotchas

  • If using timeouts, expired waits return immediately — always check completion state.
  • Coroutines stop automatically when their MonoBehaviour is disabled or destroyed.
  • Avoid spawning many concurrent awaiters on the same wallet — each subscribes to events.
  • Async waits won’t cancel automatically on scene reload — handle with proper CancellationToken.
  • Deltas and predicates are evaluated against the current wallet value on each change event.
  • If this scene is running the bootstrapped service stack, removing CurrencyAuthorityBinder will cause all currency mutations to fail with Unauthorized.

✅ Summary
CurrencyAwaiters let you build reactive economies — wait for it, don’t poll for it.
Async or Coroutine — one event, zero wasted frames.