📊 Using the Economy System¶

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

Default setup¶

RevFramework ships a ready-made integration where:

IValueLedger is provided via a built-in adapter backed by the Currency system (optional).
IItemStore is provided via a built-in adapter backed by the Inventory system (optional, requires Inventory).

Truth: Economy itself does not require Currency — it requires an IValueLedger.
The provided EconomyBootstrap wiring composes the built-in adapters when the relevant systems are present.

🔐 Multiplayer & Authority¶

Economy is multiplayer-ready, not multiplayer-opinionated:

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/policy is enforced by your active 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 never mutate economy state directly.

We give you the keys. You decide who’s allowed to turn them.

Core rules¶

Currency operations that support correlation propagate sourceId (telemetry / idempotency / audit correlation).
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 map¶

Area	Purpose
Abstractions/	Public contracts: `IValueLedger`, `IItemStore`, `IShopService`, `ICraftingService`, `IRewardService`.
Model/	Stable value types: `PriceBundle`, `ChargeLine`, `ItemLine`, `EcoOpResult`, `EcoOpCode`, `EcoReasons`, `EcoSource`, etc.
Facade/	`EconomyBootstrap` convenience wiring entry point.
Internal/	Implementation details: services, adapters, utilities. Not supported public API.
Diagnostics/	Teaching/sample helper assets and spec types (optional).

Teaching panels and sample scenes are shipped with RevFramework, but may live under the package’s Teaching/ and Samples/ folders rather than inside this runtime system folder.

✅ Required / optional folders (built-in pipeline)¶

This table applies only when using the built-in Economy pipeline via EconomyBootstrap. If you provide your own implementations of the Economy abstractions, required folders may differ.

Folder	Required	Notes
`Abstractions/`	✅	Core public API.
`Model/`	✅	Value types and results used everywhere.
`Facade/`	❌	Convenience wiring only; manual composition is allowed.
`Internal/`	✅	Required for built-in services and adapters.
`Adapters/Currency/`	❌	Only needed for the built-in currency-backed `IValueLedger`.
`Adapters/Inventory/`	❌	Only needed for inventory-backed item flows.
`Diagnostics/`	❌	Teaching/sample helper assets.

🧩 Abstractions¶

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

IValueLedger
IItemStore
IShopService
ICraftingService
IRewardService

📊 Model¶

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

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

🛠 Built-in services semantics (important)¶

Buy / Sell / Craft¶

✅ Built-in Shop / Sell / Craft orchestration is all-or-nothing and attempts rollbacks on partial failure.

Rewards¶

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

This behaviour is intentional and documented in IRewardService.

🧮 Facade — `EconomyBootstrap`¶

The recommended wiring entry point for the built-in pipeline. It returns interfaces only so internals remain swappable.

Example — Currency-only setup (money-only purchases)¶

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

// Currency-only build returns store == null.
// Item prices/deliveries require an IItemStore and will fail if attempted without one.
var price = PriceBundle.MoneyOnly(new[]
{
    new ChargeLine("gold", 100),
});

var result = shop.Buy(
    player,
    ledger,
    store: null,
    price,
    deliver: null,
    vendorId: "VendorA",
    requestId: "req123"
);

Example — Currency + Inventory setup (money + items)¶

var (shop, rewards, crafting, ledger, store) =
    EconomyBootstrap.BuildForPlayer(
        player,
        currencyService,
        inventoryService,
        resolveDef: guid => myGuidMap.Resolve(guid),
        container: "Backpack",
        policy: policy
    );

var price = new PriceBundle(
    money: new[] { new ChargeLine("gold", 50) },
    items: new[] { new ItemLine("wood_guid", 3) }
);

var deliver = new[] { new ItemLine("sword_guid", 1) };

var result = shop.Buy(player, ledger, store, price, deliver, "VendorA", "req123");

📘 See Also¶

Samples (shipped with the package):

00_Economy_Quickstart
01_Economy_WithInventory