Skip to content

RevFramework – Sample Scene: 02_Currency_Exchange

Goal

Teach the quote-first exchange loop:

Build exchanger from CurrencyExchangeTable → select From / To → TryQuote → TryExchange through the real ICurrencyService.

What This Scene Demonstrates

This scene shows how table-driven exchange converts one currency into another.

The flow is:

Owner → ICurrencyService → CurrencyExchangeTable → ICurrencyExchange → Quote → Execute → CurOpResult

  • Owner is the wallet being debited and credited
  • From is the currency being debited
  • To is the currency being credited
  • TryQuote previews the destination amount from the exchange table
  • TryExchange is the real operation
  • TryExchange re-quotes internally before mutating balances
  • Debit and credit are performed through the resolved ICurrencyService

Quote is preview.

TryExchange is truth.

What To Look For

Use the CurrencyExchangePanel to follow the quote-to-execute flow.

  • Bindings

  • Owner is the wallet being mutated

  • Service shows the resolved ICurrencyService stack
  • Exchange Table is the data asset defining rates, fees, min/max, and rounding

  • Exchanger confirms whether an exchange engine was built from the table

  • Reason / Source

  • Reason explains why the exchange happened

  • SourceId identifies what triggered it

  • Audited stacks can record these values

  • From / To

  • From is debited

  • To is credited
  • Same-currency pairs are prevented

  • Swap only changes selection; it does not mutate balances

  • Balances

  • Shows live service balances for the selected owner

  • These are not cached quote values

  • Quote

  • Calls TryQuote

  • Shows what the table would produce for the selected pair and amount

  • Does not mutate balances

  • Execute

  • Calls TryExchange

  • Re-quotes internally
  • Debits source and credits destination through the live service
  • Returns a CurOpResult

Sample Scope

This scene covers:

  • Table-driven exchange rules
  • Directional From / To conversion
  • Quote preview using TryQuote
  • Execution using TryExchange
  • Live balance verification after exchange
  • Reason / SourceId metadata passed into the exchange call
  • Service-driven failure reporting through CurOpResult

This scene does NOT cover:

  • Authoring every possible exchange table configuration
  • Policy caps in depth
  • Escrow holds and expiry
  • Persistence or replay
  • Idempotency flows
  • Batch transactions or awaiters
  • Multiplayer replication or networking

Those are taught in dedicated scenes.

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, currency mutations must be validated and executed through your own authority and networking layer.

How To Use

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

  3. Confirm the top bindings:

  4. Owner is assigned

  5. ICurrencyService is resolved
  6. Exchange Table is assigned
  7. Exchanger is ready
  8. Use From / To to select the conversion pair.
  9. Enter a source amount in Quote.
  10. Read the quote result.
  11. Press the Execute button to run TryExchange.
  12. Check the returned result.
  13. Compare the live From / To balances after execution.

Failure Behaviour

Failures are shown through quote text, disabled execute state, or the returned CurOpResult.

Common causes:

  • Play Mode required

  • The panel quotes and executes 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 missing

  • Exchange needs a wallet to debit and credit

  • Fix: assign an owner or tag the player GameObject as Player

  • Exchange Table missing

  • No table is assigned

  • Fix: create and assign a CurrencyExchangeTable

  • Exchange Engine not built

  • The table could not produce an exchanger

  • Fix: check the table, then re-enable the component or re-enter Play Mode

  • Need at least two currencies

  • Exchange requires a From and To currency

  • Fix: assign at least two CurrencyDefinition assets or provide a CurrencySet

  • Invalid From / To CurrencyId

  • One selected currency has an invalid Id

  • Fix: correct the CurrencyDefinition asset

  • Quote failed

  • The table has no valid result for this pair or amount

  • Fix: check From/To route, source min/max, fee, and rounding setup

  • Quote succeeds but execution fails

  • TryExchange produced a quote, but the live service rejected the mutation

  • Fix: check source balance, caps, authority, escrow, idempotency, and service composition

Behind The Scenes

The panel uses real Currency and Exchange APIs:

  • CurrencyResolve.ServiceFrom

  • resolves the active ICurrencyService

  • CurrencyFactories.BuildExchange

  • builds the exchange engine from the assigned CurrencyExchangeTable

  • ICurrencyExchange

  • TryQuote

  • TryExchange

  • ICurrencyService

  • provides the live wallet mutation path used by exchange

  • provides live balances for display

  • CurOpResult

  • Success

  • Code
  • Message

The visible quote is a UI hint only.

TryExchange re-quotes internally before mutating.

The returned CurOpResult is the final result.

Key Takeaway

The table defines conversion behaviour.

The service decides whether the mutation is allowed.

Exchange is quote first, then execute through the live service.