Skip to content

RevFramework – Sample Scene: 07_Currency_BatchAndTxn

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

🎯 Purpose

Show how to stage and commit multiple currency operations atomically using the CurrencyTxn system, and how to use batch events to receive a single consolidated update after a transaction completes.
This scene highlights atomic commits, rollbacks, and the event model for multi-operation changes.

🧩 What This Scene Teaches

  • How to compose multi-step wallet operations with CurrencyTxn.
  • How to commit staged operations as one atomic transaction.
  • How to capture deltas via CurrencyBatch during multi-op commits.
  • How to subscribe to ICurrencyBatchEvents.OnWalletBatchChanged for consolidated updates.
  • How rollback works automatically if any operation in the batch fails.

🕹️ How to Use

  1. Enter Play Mode.
  2. Open the CurrencyBatchAndTxnPanel (F8).
  3. Observe bindings for Owner A, Owner B, and the active service.
  4. Batch Events Section
  5. Click Subscribe to listen for consolidated batch events.
  6. Commit a transaction to see all deltas logged together in a single event.
  7. Transaction Section
  8. Select a currency.
  9. Add multiple staged operations (Credit, Debit, Set, Transfer).
  10. Click Commit Txn to apply all operations atomically.
  11. If any operation fails, all previously staged changes rollback automatically.

🔐 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

  • CurrencyTxn provides a fluent builder for multi-operation sequences:
    var result = CurrencyTxn.Begin(svc, "QuestReward", "rid:789")
    .Debit(player, gold, 250)
    .Credit(player, gems, 5)
    .Credit(player, tokens, 1)
    .Commit();
  • All operations inside a transaction are atomic — either all succeed or all rollback.
  • Batch events are fired once per commit via:
    ICurrencyBatchEvents.OnWalletBatchChanged
  • CurrencyBatch collects deltas for UI updates and persistence layers.
  • Ideal for store purchases, quest rewards, loot bundles, or compound transactions.
  • Compatible with all decorators (Audit, Caps, Authority, Escrow, Idempotency).

⚙️ Stack Composition

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

Scene Path:

Assets/RevFramework/Runtime/Systems/Currency/Samples/Scenes/07_Currency_BatchAndTxn/

⚠️ Gotchas

  • If any operation fails, the entire transaction rolls back — partial state is never left behind.
  • Batch events trigger after successful commits only; failed transactions emit no events.
  • Use reason and sourceId to trace grouped transactions in audit logs.
  • Decorators (like Caps or Escrow) may alter commit results — always inspect the returned CurOpResult.
  • Nested transactions aren’t supported; create discrete commits for complex flows.
  • If this scene is running the bootstrapped service stack, removing CurrencyAuthorityBinder will cause all currency mutations to fail with Unauthorized.

✅ Summary
This scene shows the real muscle of RevFramework’s Currency layer:
Atomic transactions, single event updates, and guaranteed rollback safety.