Skip to content

RevFramework – Sample Scene: 03_Currency_Persistence_Audit

Goal

Teach the currency save/restore loop:

StableId owners → WalletSnapshot → JSON SaveBlob → load → restore through ICurrencyService → optional audit inspection.

What This Scene Demonstrates

This scene shows how wallet state can be captured, serialized, restored, and audited.

The flow is:

StableId owner → selected CurrencyId scope → WalletSnapshot → SaveBlob → JSON file → restore by StableId → CurOpResult

  • Wallets are identified by StableId, not scene object references
  • Capture creates WalletSnapshot data for selected currencies
  • JSON is only the transport format
  • Restore maps saved owner ids back to scene objects
  • Restore applies balances through the real ICurrencyService
  • Audit is optional and depends on the composed service stack

Restore is not a silent field overwrite.

The service result is truth.

What To Look For

Use the CurrencyPersistenceAuditPanel to follow save, load, restore, and audit verification.

  • Setup tab

  • Shows the resolved ICurrencyService

  • Shows whether audit reading is available
  • Shows discovered StableId owner count
  • Shows valid captured currency count
  • Shows the JSON file name

  • Provides Reason / SourceId metadata for restore operations

  • Persistence tab

  • File field controls the save file name under Application.persistentDataPath

  • Save Now captures wallets and writes JSON to disk
  • Load Now reads JSON and restores wallets through the service
  • Show JSON (live) builds JSON from current wallet state without saving

  • Clear JSON Buffer only clears the visible text area

  • JSON area

  • Shows the exact JSON written or loaded

  • Can be edited manually before loading

  • Negative balances are normalized to zero by the demo wrapper

  • Audit tab

  • Selects a discovered StableId owner

  • Filters recent entries by kind and currency
  • Shows restore, set, credit, debit, or transfer entries when audit is available

Sample Scope

This scene covers:

  • Discovering wallet owners by StableId
  • Capturing selected currency balances into WalletSnapshot data
  • Wrapping snapshot dictionaries in a JsonUtility-friendly SaveBlob
  • Saving and loading JSON under Application.persistentDataPath
  • Restoring balances through CurrencyPersistence.Restore
  • Applying Reason / SourceId metadata during restore
  • Inspecting audit entries when ICurrencyAuditReader is available

This scene does NOT cover:

  • Cloud saves
  • Async file IO
  • Encryption or save tamper protection
  • Versioned migration pipelines
  • Multiplayer replication or networking
  • Full production save-slot management

Those are project-level concerns or dedicated integration work.

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 restore and mutation flows must be validated and executed through your own authority and networking layer.

How To Use

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

  3. In Setup:

  4. Confirm ICurrencyService is resolved

  5. Confirm valid currencies are available
  6. Check whether audit is available
  7. Set Reason / SourceId for restore operations if desired
  8. Use another panel or gameplay to create wallet balances.

  9. In Persistence:

  10. Press Show JSON (live) to inspect current captured wallet state

  11. Press Save Now to write wallet JSON to disk
  12. Change balances so restore is visible
  13. Press Load Now to restore from the saved JSON

  14. In Audit:

  15. Select an owner

  16. Choose Last N
  17. Filter by kind or currency if needed
  18. Confirm restore entries appear when audit is available

Failure Behaviour

Failures are shown through dependency messages, save/load results, restore counts, or audit availability messages.

Common causes:

  • Play Mode required

  • The panel scans scene StableId objects and reads live wallet state

  • Fix: enter Play Mode

  • Service missing

  • No ICurrencyService was resolved

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

  • Audit not available

  • The active service does not expose ICurrencyAuditReader

  • Fix: compose audit support into the service stack if this scene is meant to show audit

  • Persistence still works without audit

  • No capture currencies available

  • No valid currencies were found from CurrencySet or bound CurrencyDefinition assets

  • Fix: assign a CurrencySet or valid CurrencyDefinitions before saving or building JSON

  • Save error

  • File writing failed

  • Fix: check file name, path permissions, and valid capture currencies

  • Load file missing

  • The named JSON file does not exist

  • Fix: press Save Now first or enter an existing save file name

  • Load parse error

  • JSON does not match the expected SaveBlob format

  • Fix: correct the JSON structure and owner/currency ids

  • Missing owners during restore

  • Saved owner ids do not match any current scene StableId

  • Fix: check StableId values in the scene against ownerId values in the JSON

  • Restore failed for an owner

  • The service rejected one or more restored balances

  • Fix: inspect service rules, authority, caps, and the selected currency data

Behind The Scenes

The panel uses real Currency persistence and audit APIs:

  • CurrencyResolve.ServiceFrom

  • resolves the active ICurrencyService

  • StableId

  • provides persistent owner identity

  • CurrencyPersistence.Capture

  • captures selected currency balances into a WalletSnapshot

  • CurrencyPersistence.Restore

  • restores a snapshot through the resolved ICurrencyService

  • WalletSnapshot

  • stores captured currency lines

  • SaveBlob

  • wraps owner snapshot data so JsonUtility can serialize it

  • JsonUtility.ToJson

  • serializes the save data

  • JsonUtility.FromJson

  • parses loaded save data

  • Application.persistentDataPath

  • stores the demo save file

  • ICurrencyAuditReader

  • enables audit display when composed into the service stack

  • CurrencyAudit.Get

  • reads recent audit entries for the selected owner

JSON stores data.

StableId maps that data back to scene owners.

ICurrencyService decides what actually restores.

Key Takeaway

Persistence saves wallet state by stable owner identity, not scene references.

Restore goes back through the real currency service.

Audit, when available, proves what changed and why.