💰 Currency Samples — Scenes & Diagnostics¶

The Currency Samples folder contains demonstration scenes and diagnostic tools used for learning, testing, and validating the Currency system.

They are intended for:

teaching core concepts
debugging integrations
profiling usage patterns
prototyping gameplay flows

They are not intended for production use.

📂 Folder Layout¶

Samples/
  Scenes/        // Currency feature demos (00–08)
  Diagnostics/   // Performance smoke tests and profiling tools

🎬 Scene Samples¶

Scene	Demonstrates	Notes
00_Currency_Basics	Core `ICurrencyService` usage — credit, debit, events.	Minimal setup.
01_Currency_PolicyCaps	Min/max caps via policy rules.	Uses `CurrencyPolicy`.
02_Currency_Exchange	Multi-currency conversion.	`TryQuote` / `TryExchange`.
03_Currency_Persistence	Snapshot capture/restore + audit inspection.	Uses `StableId`.
04_Currency_UIBars	Runtime UI sync (UGUI / UITK).	UI-agnostic behaviour.
05_Currency_Escrow	Holds, commit, release, expiry.	Escrow decorators.
06_Currency_Idempotency	Duplicate-safe replay handling.	RID-based operations.
07_Currency_BatchAndTxn	Atomic transactions + batch events.	Uses `CurrencyTxn`.
08_Currency_Awaiters	Awaitable balance checks.	Async + coroutine usage.

🧪 Diagnostics¶

The Diagnostics folder contains runtime tools for profiling Currency behaviour.

These are:

diagnostic-only
not benchmarks
not production systems

Example:

CurrencyMutationPerfSmoke
→ Stress-tests mutation throughput and event fanout
→ Helps identify misuse patterns (e.g. excessive listeners or mutation frequency)

Use diagnostics to answer:

“Is the system slow — or is my usage slow?”

▶️ Usage¶

Open any sample scene from:

Assets/RevFramework/Samples/Systems/Currency/Scenes/

Common scene setup includes:

A currency service bootstrap (with relevant decorators)
Wallet owners (with StableId)
Optional UI or test objects
Teaching panels for interaction and feedback

🧠 Teachable Panels¶

💡 Teachable Panels

Teachable panels are provided as debug and learning tools.

They are safe to run at runtime (no UnityEditor dependencies)
They interact only through the public API
They can be used in your own scenes for debugging, inspection, and validation

However:

They are not designed for shipping builds
They are not optimised UI
They are not a supported gameplay layer

Think of them as:

👉 Hostile-consumer debug tools that prove the API works

🔐 Design Rationale: Currency Authority¶

The Currency system is designed to be multiplayer-ready and abuse-resistant by default, while still remaining easy to use in single-player projects.

Currency is one of the most cheat-sensitive systems in any game:

Frequently mutated from UI
Often represents real player value
Easy to exploit if left permissive

Currency mutations are authority-gated when the Authority decorator is used.

If Authority is present:
No authority → all mutations are denied

This is intentional.

Why Demo Scenes Still “Just Work”¶

All sample scenes include a permissive authority binder:

CurrencyAuthorityBinder (Demo – Allow All)

Configured to allow all mutations.

This exists purely to:

Keep demos functional out of the box
Make authority behaviour visible
Show exactly what to replace in real projects

It is not production code.

Single-Player vs Multiplayer¶

Context	Recommended Setup
Single-player	Use demo binder or omit Authority
Multiplayer	Implement `ICurrencyAuthority` (server-side validation)

Currency does not handle:

Replication
Prediction
Rollback
Reconciliation

Those belong to your networking solution.

⚠️ Gotchas¶

The Samples folder is not required for runtime and can be removed safely
Only one active currency bootstrap should exist per scene
Diagnostics scripts are stress tools, not performance guarantees
Sample scripts prioritise clarity over robustness — do not treat them as production-ready

Core — Currency service, factories, and orchestration
Decorators — Caps, Audit, Escrow, Authority, Idempotency
Persistence — Snapshot and restore flows
Teaching Panels — Interactive system demonstrations