Skip to content

💰 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

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

This is the contract.

🔹 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

  • 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.