Currency — Documentation Guide¶

Where should I start?¶

New to Currency?¶

Start with:

👉 System Overview (README + Mental Model)

This explains: - What the Currency system is
- How the ledger and decorator composition model works
- How Currency integrates with Inventory, Economy, Crafting, and UI
- Typical setup and usage patterns

Want to know what you can safely depend on?¶

Read:

👉 PublicAPI/

This document defines: - The supported runtime surface - Stable interfaces, helpers, and event contracts - Guaranteed behaviours - Explicitly unsupported usage

This is the contract

If something is not listed there, it is not supported — even if it appears public in code.

Adding gameplay or extending the system?¶

Start with:

👉 Integration Surfaces/

This shows exactly where logic belongs: - balance mutation - caps and policies - audit and batching - authority and idempotency - escrow and transactions

Then use:

👉 FAQ/

The FAQ answers questions like: - Should I use transactions or direct calls? - Where should I enforce caps or rules? - How does escrow actually work? - How do I make this multiplayer-safe? - What should I avoid?

It focuses on decision-making, not API reference.

How these documents work together¶

Document	Purpose
Overview	Explains the system
Public API	Defines what is supported
FAQ	Guides correct usage choices
Integration Surfaces	Shows where new logic should plug in
Mental Model	Explains how to think about the system
Guarantees Matrix	Defines behavioural contracts

Each document serves a specific purpose.
You do not need to read everything — start with what matches your task.

Important support note¶

RevFramework Currency is:

Service-driven
Ledger-based
Deterministic
Decorator-composed
Authority-aware (when configured)
UI-agnostic
Netcode-agnostic

Support is provided for

Behaviour defined in PublicAPI
Usage patterns described in Overview, FAQ, and Integration Surfaces
Guarantees listed in the Guarantees Matrix

Support is not provided for

Bypassing CurrencyResolve
Referencing concrete service implementations directly
Depending on undocumented decorator behaviour
Reflecting into runtime internals
Mutating balances outside ICurrencyService

Teaching Panels
Add debug or teachable panels to inspect balances, transactions, escrow, and audit live
Samples
See /Samples/Currency/ for runnable examples
MkDocs site
Mirrors this documentation for web browsing

System philosophy¶

Currency is:

A guarded ledger (not a UI value)
A service-controlled system (not direct state mutation)
A composed pipeline (policy, authority, audit, etc.)
A result-first API (no silent failures)

Every extension seam exists for a reason.
If something feels unclear, you're likely using the wrong layer.

TL;DR¶

TL;DR

Want to understand Currency → Overview
Want to build safely → Public API
Want to choose correctly → FAQ
Want to extend cleanly → Integration Surfaces

If you stay within these boundaries, Currency will behave predictably and remain supportable.