Skip to content

📊 Using the Economy System

🎯 Purpose

Economy is a modular orchestration layer for shops, crafting, and rewards using abstract money and items.

You integrate Economy by supplying implementations of:

  • Money via IValueLedger
  • Items via IItemStore

🧠 Usage Guidance

Default setup

RevFramework ships ready-made composition helpers:

  • EconomyBootstrap → currency-only composition
  • EconomyInventoryBootstrap → inventory-backed composition

Economy itself does not require Currency — it requires an IValueLedger. The provided bootstrap helpers compose the built-in implementations when the relevant systems are present.

⚠️ Important Notes

Multiplayer & Authority

Economy is designed to work in multiplayer scenarios, but does not provide networking or authority.

  • No networking, replication, prediction, or anti-cheat
  • No built-in authority gate
  • Designed to work in authoritative setups (server-side / host-side), but does not enforce authority by itself

Authority and policy are enforced by your money/inventory implementations and/or by the caller.

In a multiplayer game:

  • Clients request an economic action
  • Your server/host validates authority
  • Your server/host calls Economy
  • Clients do not mutate economy state directly

🧠 Core Rules

  • Currency operations that support correlation pass through sourceId
  • Item operations do not propagate sourceId (by design of IItemStore)
  • CanPay is preflight only (UX hint). Authoritative calls are Pay and Grant
  • Preflight behaviour is controlled by LedgerPreflightMode (Strict vs PolicyApproved)

📦 Folder Overview

Area Purpose
Abstractions/ Public contracts: IValueLedger, IItemStore, IShopService, ICraftingService, IRewardService
Model/ Value types: PriceBundle, ChargeLine, ItemLine, EcoOpResult, EcoOpCode, EcoReasons, EcoSource
Facade/ EconomyBootstrap (currency-only) and EconomyInventoryBootstrap (inventory integration)
Internal/ Implementation details: services, adapters, utilities (not public API)
Diagnostics/ Debug interfaces and helpers (e.g. IItemStoreDebug)

Teaching panels and sample scenes live under the package’s Teaching/ and Samples/ folders.

The Diagnostics/ folder contains optional debug-facing contracts and helpers and is not required for normal gameplay integration.

🧩 What Lives Here

Abstractions

Located in Abstractions/ — code against these in gameplay, UI, analytics, and netcode:

  • IValueLedger
  • IItemStore
  • IShopService
  • ICraftingService
  • IRewardService

Model

Located in Model/ — value types safe for UI, logging, analytics, and persistence:

  • ChargeLine, ItemLine, PriceBundle
  • EcoOpResult, EcoOpCode, EcoReasons, EcoSource
  • LedgerPreflightMode

⚠️ Important Notes

Built-in services semantics

Buy / Sell / Craft

Built-in Shop / Sell / Craft orchestration applies operations in sequence and attempts rollback on partial failure.

Rewards

Money is applied first; item failure does not roll back money (by design).

🧠 Composition Modes

Economy supports two composition paths:

  • Currency-only → EconomyBootstrap
  • Currency + Inventory → EconomyInventoryBootstrap

This keeps dependencies explicit and allows systems to be used independently.

🧠 Usage Guidance

Currency-only setup

var (shop, rewards, crafting, ledger, store) =
    EconomyBootstrap.BuildForPlayer(player, currencyService, policy);

// store == null → no IItemStore is available

Currency + Inventory setup

var (shop, rewards, crafting, ledger, store) =
    EconomyInventoryBootstrap.BuildForPlayer(
        player,
        currencyService,
        inventoryService,
        resolveDef: guid => myGuidMap.Resolve(guid),
        container: "Backpack",
        policy: policy
    );
  • Abstractions
  • Model
  • Facade
  • Integrations / Economy
  • Teaching Panels

These systems are designed to be modular.

Use only what you need, and integrate at the level appropriate for your game.