Skip to content

RevFramework – Sample Scene: 01_Currency_PolicyCaps

Goal

Teach how CurrencyPolicy cap rules shape currency operations before they are applied through the real ICurrencyService.

This scene focuses on min/max rules, Clamp vs Fail behaviour, policy preview, and caps-aware transfer preview.

What This Scene Demonstrates

This scene shows the policy decision flow for currency mutations.

The flow is:

Owner A → CurrencyPolicy → Preview → Apply through ICurrencyService → CurOpResult

  • Owner A is the wallet being inspected and mutated
  • Owner B is used for transfer preview and transfer apply
  • The selected CurrencyPolicy provides per-currency min/max rules
  • The panel previews Set / Credit / Debit against the selected rule
  • The panel previews transfer using TryComputeEffectiveTransferAmount
  • The live service result is still the final truth

Policy preview explains the cap rule only.

A preview can say OK and the real operation can still fail if another composed service rule blocks it. That is correct behaviour.

What To Look For

Use the CurrencyPolicyCapsPanel to compare policy preview against real service results.

  • Bindings

  • Owner A is the wallet being inspected and mutated

  • Owner B is used for A → B transfer behaviour
  • Policy is the CurrencyPolicy asset used for preview

  • Service shows the resolved ICurrencyService stack

  • Currency & Rule

  • Select a currency

  • Inspect the active min/max rule

  • Confirm whether the rule uses Clamp, Fail, or pass-through behaviour

  • Probe

  • Choose Set, Credit, or Debit

  • Enter an amount
  • Compare Tentative, Adjusted, and Outcome

  • Apply the operation through the real service

  • Transfer

  • Enter a requested transfer amount

  • Compare requested amount against effective amount
  • Apply a real transfer using the effective amount

Sample Scope

This scene covers:

  • Per-currency min/max cap rules
  • Clamp vs Fail behaviour
  • Policy-aware preview for Set / Credit / Debit
  • Insufficient-funds handling during Debit preview
  • Caps-aware transfer preview
  • Applying previewed operations through the real ICurrencyService

This scene does NOT cover:

  • Exchange tables or conversion rates
  • Escrow holds and expiry
  • Persistence or replay
  • Idempotency flows
  • Batch transactions or awaiters
  • Full multiplayer authority implementation

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 CurrencyPolicyCapsPanel with F8.

  3. Confirm the top bindings:

  4. Owner A is assigned

  5. Policy is assigned
  6. ICurrencyService is resolved
  7. Owner B is assigned if you want to test transfer behaviour
  8. Select a currency in the Currency & Rule section.

  9. Inspect the rule:

  10. min = lowest allowed balance

  11. max = highest allowed balance
  12. max = 0 means no upper limit
  13. Clamp adjusts into range
  14. Fail rejects the operation

  15. In Probe:

  16. Choose Set, Credit, or Debit

  17. Enter an amount
  18. Read Tentative, Adjusted, and Outcome
  19. Press Apply to run the real service call

  20. In Transfer:

  21. Enter a requested amount

  22. Read Requested, Effective, and Preview Code
  23. Press Transfer A → B to apply the effective transfer

Failure Behaviour

Failures are shown through preview outcome or the returned CurOpResult.

Common causes:

  • Play Mode required

  • The panel previews and applies 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

  • Policy preview needs a wallet to inspect and mutate

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

  • Policy missing

  • No CurrencyPolicy asset is available for preview

  • Fix: assign a policy asset in the Inspector

  • Owner B missing

  • Transfer preview cannot run without a target wallet

  • Fix: assign Owner B if testing transfer behaviour

  • Invalid CurrencyId

  • The selected CurrencyDefinition has an invalid Id

  • Fix: correct the CurrencyDefinition asset

  • Preview outcome is FAIL

  • The selected cap rule rejects the tentative value

  • Fix: change the amount, operation, currency, or policy rule

  • Preview allowed it, but service rejected it

  • Another service layer blocked the operation

  • Fix: check authority, escrow, debit rules, service composition, and policy/cap configuration

Behind The Scenes

The panel uses real Currency APIs and data:

  • CurrencyResolve.ServiceFrom

  • resolves the active ICurrencyService

  • CurrencyPolicy.TryGetCapRule

  • reads the selected currency cap rule

  • ICurrencyService

  • GetBalance

  • SetBalance
  • Credit
  • Debit
  • Transfer

  • TryComputeEffectiveTransferAmount

  • CurOpResult

  • Success

  • Code
  • Message

The preview calculations explain the selected policy rule.

The real service call still decides the final result.

Key Takeaway

Definitions describe the currency.

Policy defines allowed balance behaviour.

Preview explains the rule, but the ICurrencyService result is truth.