Skip to content

RevFramework – Sample Scene: 07_Currency_BatchAndTxn

Goal

Teach grouped currency changes from both sides:

Stage operations with CurrencyTxn → commit through ICurrencyService → optionally observe grouped deltas through ICurrencyBatchEvents.

What This Scene Demonstrates

This scene shows two related currency concepts:

  • batch events are optional grouped readout
  • CurrencyTxn is a public fluent helper for staging and committing multiple service operations

The flow is:

Owner A / Owner B → ICurrencyService → local stages → CurrencyTxn.Begin → Commit() → CurOpResult → optional OnWalletBatchChanged

  • Owner A is the primary wallet
  • Owner B is used for Owner-B operations and transfers
  • Stages are local until Commit Txn is pressed
  • CurrencyTxn commits staged operations through the real service
  • Batch events are only available when the stack exposes ICurrencyBatchEvents
  • Missing batch support does not stop transactions from working

Batch is readout.

Transaction is orchestration.

The service result is truth.

What To Look For

Use the CurrencyBatchAndTxnPanel to separate staging, commit, and grouped readout.

  • Setup tab

  • Owner A is required

  • Owner B is optional until using Owner-B operations or transfers
  • Service shows the resolved ICurrencyService stack
  • BatchEvents shows whether ICurrencyBatchEvents is available

  • Reason / SourceId are passed into the transaction builder

  • Batch tab

  • Subscribe listens for OnWalletBatchChanged

  • Last batch displays grouped CurrencyDelta entries
  • No batch appears until a supported stack emits one

  • Missing batch support is not a transaction failure

  • Txn tab

  • Select a currency

  • Enter Amount and SetVal values
  • Add staged operations locally
  • Review the staged list

  • Press Commit Txn to build and commit a CurrencyTxn

  • Staging list

  • +A / -A stage Credit / Debit for Owner A

  • +B / -B stage Credit / Debit for Owner B
  • Set A / Set B stage absolute balance writes
  • A → B / B → A stage transfers
  • Nothing mutates until commit

Sample Scope

This scene covers:

  • Detecting optional ICurrencyBatchEvents
  • Subscribing to batch event readout
  • Staging local transaction operations
  • Building a transaction with CurrencyTxn.Begin
  • Committing staged operations through Commit()
  • Reading success/failure through CurOpResult
  • Observing grouped deltas when batch events are supported
  • Explaining rollback as an attempted recovery path, not magic

This scene does NOT cover:

  • Database transactions
  • Guaranteed rollback across arbitrary external side effects
  • Internal decorator inspection
  • Persistent transaction logs
  • Backend transaction coordinators
  • Multiplayer replication or networking

Those are project-level or backend concerns.

Authority Note

This scene may include a permissive sample authority setup so it runs without additional configuration.

Networking Reminder

RevFramework does not include networking.

For multiplayer projects, grouped currency operations must be validated and executed through your own authority and networking layer. Batch events are local service readout, not network replication.

How To Use

  1. Enter Play Mode.
  2. Toggle the CurrencyBatchAndTxnPanel with F8.

  3. In Setup:

  4. Confirm Owner A is assigned

  5. Confirm ICurrencyService is resolved
  6. Confirm whether BatchEvents is present
  7. Assign Owner B if testing Owner-B stages or transfers

  8. In Batch:

  9. Press Subscribe if batch events are present

  10. Leave the tab after subscribing if you want to commit from Txn

  11. In Txn:

  12. Select a currency

  13. Enter Amount for Credit / Debit / Transfer stages
  14. Enter SetVal for Set stages
  15. Add one or more stages
  16. Review the staging list
  17. Press Commit Txn
  18. Check the result message.
  19. If subscribed and supported, return to Batch and inspect the grouped delta list.
  20. Use another panel or live balance display to verify wallet changes if needed.

Failure Behaviour

Failures are shown through dependency messages, staging errors, commit results, or missing batch readout.

Common causes:

  • Play Mode required

  • Batch events and transaction commits run against live wallet state

  • Fix: enter Play Mode

  • Service missing

  • No ICurrencyService was resolved

  • Fix: add SceneCurrencyService, add CurrencyServiceBootstrap, or publish a composed service

  • Owner A missing

  • Owner A is required for transaction staging

  • Fix: assign Owner A or tag the player GameObject as Player

  • BatchEvents missing

  • The service stack does not expose ICurrencyBatchEvents

  • Fix: compose batch event support if you want grouped delta readout

  • Transactions still work without it

  • Owner B missing

  • Owner-B operations and transfers need Owner B

  • Fix: assign Owner B or use Owner-A-only stages

  • No currencies bound

  • No CurrencyDefinition assets are available for staging

  • Fix: assign currencies in the Inspector or provide a CurrencySet

  • Invalid currency stage

  • A stage references a missing or invalid currency

  • Fix: remove the stage and add it again with a valid CurrencyDefinition

  • Invalid amount

  • Credit, Debit, and Transfer need positive amounts; Set needs zero or greater

  • Fix: remove the bad stage and add it again with a valid amount

  • Commit failed

  • One staged operation was rejected by the live service

  • Fix: check the first failing stage, balances, caps/policy, authority, escrow, idempotency, and service composition

  • Rollback did not behave as expected

  • Rollback is constrained by the same live service rules as forward operations

  • Fix: inspect the result, balances, and stack rules; do not assume rollback can bypass the original failure condition

  • No batch received after commit

  • Batch events may be unsupported, not subscribed, or no successful batch was emitted

  • Fix: confirm BatchEvents is present, subscribe, then commit a successful transaction

Behind The Scenes

The panel uses real Currency APIs:

  • CurrencyResolve.ServiceFrom

  • resolves the active ICurrencyService

  • ICurrencyBatchEvents

  • OnWalletBatchChanged

  • CurrencyDelta

  • owner

  • currency
  • before

  • after

  • CurrencyTxn

  • Begin

  • Credit
  • Debit
  • Set
  • Transfer

  • Commit

  • ICurrencyService

  • all staged operations still execute through the resolved service stack

  • CurOpResult

  • Success

  • Code
  • Message

The panel does not inspect decorators.

CurrencyTxn is not a database transaction.

It stages public service operations, commits them in order, and reports the result.

Key Takeaway

Batch events tell you what changed after a grouped operation.

CurrencyTxn helps stage and commit multiple service calls together.

Neither bypasses the live service stack: policy, authority, escrow, idempotency, and rollback constraints s