Skip to content

💰 Economy — Documentation Guide

🧭 Where should I start?

🔹 New to Economy?

Start with:

👉 System Overview (README + Mental Model)

This explains: - What the Economy system is - How Economy coordinates money and item flows - How Economy relates to Currency, Inventory, shops, crafting, and rewards - 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, value types, and result 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: - money orchestration - item orchestration - shop, crafting, and reward flows - bootstrap composition - telemetry and result handling

Then use:

👉 FAQ/

The FAQ answers questions like: - When should I use Economy instead of Currency directly? - Should this live in the ledger, item store, or service layer? - How does rollback actually behave? - Can I replace parts of the built-in stack? - 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 Economy is:

  • Orchestration-first
  • Abstraction-driven
  • Result-first
  • Best-effort rollback aware
  • UI-agnostic
  • Network-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:

  • Calling internal Economy services directly
  • Depending on concrete built-in implementations
  • Reflecting into runtime internals
  • Treating rollback as hard-atomic
  • Putting money or item truth inside Economy instead of the proper lower layer

  • Teaching Panels
    Add debug or teachable panels to inspect shop, crafting, reward, and mixed-resource flows live

  • Samples
    See /Samples/Economy/ for runnable examples

  • MkDocs site
    Mirrors this documentation for web browsing

🧠 System philosophy

Economy is:

  • An orchestration layer (not a ledger)
  • An abstraction-first system (money through IValueLedger, items through IItemStore)
  • A result-first API (explicit operation outcomes)
  • A coordination layer for gameplay meaning (buy, sell, craft, reward)

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

✅ TL;DR

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

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