Skip to content

RevFramework – Economy System

Overview

The Economy module is the bridge between currency and inventory — it handles real-world game flows like buying, selling, crafting, and rewarding with rollback-safe, policy-aware transactions.
It unifies money and items under a single API while staying fully decoupled and adapter-driven.

Key design goals

  • Unified flow control: Money (IValueLedger) + Items (IItemStore) under consistent semantics.
  • Atomic transactions: All-or-nothing — partial success automatically rolls back.
  • Telemetry-first: Every operation carries reason and optional sourceId for clean analytics.
  • Adapter-based: Integrates any ICurrencyService or IInventoryService without coupling.
  • Pipeline-agnostic: Works across URP, HDRP, Built-in — pure runtime logic.
  • Production-safe: Deterministic rollback, clear failure codes, and simple debugging.

What's included

Category Purpose
Interfaces (Abstractions) Stable public contracts (IValueLedger, IItemStore, IShopService, ICraftingService, IRewardService).
Model Types Core DTOs (PriceBundle, ChargeLine, ItemLine, EcoOpResult, EcoOpCode, EcoReasons, EcoSource).
Services Internal implementations of Shop, Crafting, and Reward with deterministic rollback.
Adapters Bridges: CurrencyValueLedger (money) and InventoryItemStore (items).
Utilities Shared helpers (PriceBundleUtil, EcoRollbackUtil, EcoReasonUtil, EcoEditorBridge).
Facade EconomyBootstrap — safe entry point returning interfaces only.
Teaching Panels Runtime IMGUI panels (EconomyQuickstartPanel, EconomyWithInventoryPanel).
Diagnostics Overlay UI, specs, and ItemGuidMap for test scenes.
Samples Playable examples: Quickstart (currency only) and Full Inventory (rollback showcase).

Hook-up summary

1️⃣ Bootstrap the economy

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

or, with inventory:

var (shop, rewards, crafting, ledger, store) =
    EconomyBootstrap.BuildForPlayer(player, currencyService, inventoryService, guidMap.Resolve, "Backpack", policy);

2️⃣ Perform operations

// Buy
var result = shop.Buy(player, ledger, store, price, deliver, "VendorA", "rid:" + Guid.NewGuid());
if (!result.Success) Debug.LogWarning(result.Code);

// Craft
var r = crafting.Craft(player, ledger, store, cost, resultItem);

// Reward
rewards.Grant(player, ledger, store, payout);

3️⃣ Handle results

All calls return an EcoOpResult: 

if (!r.Success)
    Debug.LogWarning($"Failed: {r.Code} {r.Message}");

Interaction with other RevFramework modules

Module Interaction
Currency Economy uses IValueLedger on top of ICurrencyService to debit/credit wallets.
Inventory InventoryItemStore adapts any inventory container for item flows.
Crafting (Inventory Module) Integrates recipes, ingredients, and outputs with full refund/rollback safety.
Pickups Pickups can trigger rewards through the IRewardService.
Economy UI / Storefronts Expose Buy/Sell logic via the Economy interfaces.
Netcode Wrap operations with your network binder; sourceId supports idempotent retries.

🧩 Rollback semantics

Every operation is atomic: | Operation | Rollback behaviour | |------------|-------------------| | Buy | Refunds money + removes delivered items on failure. | | Sell | Restores removed items if payout fails. | | Craft | Refunds money and restores ingredients on failure. | | Reward | Money credited first; item add failure does not roll back money (by design). |

Telemetry & analytics

  • reason strings come from EcoReasons.* — canonicalised for analytics consistency.
  • sourceId built via EcoSource.Build(vendor, request) → e.g. "VendorA|rid:xyz".
  • Currency ops propagate sourceId; item ops don’t (correlate via logs).
  • Editor warnings via EcoEditorBridge catch invalid reason usage automatically.

Teaching & samples

Scenes

Scene Description
00_Economy_Quickstart Currency-only demo showing Buy/Craft/Reward and preflight policy behaviour.
01_Economy_WithInventory Full buy/sell/craft/reward demo with rollback and force-fail toggles.

Panels

Panel Purpose
EconomyQuickstartPanel Currency-only. Demonstrates ledger, policy, and telemetry.
EconomyWithInventoryPanel Currency + inventory. Showcases rollback and fail paths.

Toggle with F8 in play mode.

Extension points

  • Implement custom IValueLedger for exotic currency systems (XP, reputation, etc.).
  • Implement custom IItemStore to integrate external or networked inventories.
  • Override EconomyBootstrap for non-Unity or ECS composition.
  • Extend teaching panels or create new ones via TeachablePanelBase.

Typical one-liner usage

var cost = new PriceBundle(
    new [] { new ChargeLine("gold", 100) },
    new [] { new ItemLine("sword_iron", 1) });

var result = shop.Buy(player, ledger, store, cost, deliver: null, "VendorA", "rid:" + Guid.NewGuid());
if (!result.Success)
    Debug.LogWarning($"Buy failed: {result.Code}");

Where to learn

  • MkDocs Site: /economy/ (this page)
  • Videos: "Economy Quickstart", "Rollback Deep Dive", "Shop & Crafting", "Telemetry & SourceId Explained"
  • In-Editor Panels: Add EconomyQuickstartPanel or EconomyWithInventoryPanel for live demonstration.

✅ Summary
The Economy System connects currency and inventory through a clean, rollback-safe transaction layer.
It’s adapter-driven, telemetry-aware, and ready for production — one unified API for all your game’s money and item flows.