💰 Economy System — Public API¶

This page defines the supported, stable public API for the RevFramework Economy System.

If something is not listed here, it is not supported as a public integration point — even if it appears accessible in code.

Audience: Developers integrating Economy into gameplay or UI
Scope: Runtime public API only (Editor / Teaching helpers excluded)
Stability: Breaking changes to items listed here are avoided or clearly versioned

📌 Core Concepts¶

Economy is service-based and adapter-driven (currency + optional inventory).
Integration is done through a façade (EconomyBootstrap) which returns interfaces only.
All operations return an EcoOpResult (success flag + code + optional message).
Semantics are explicit and guaranteed:
Shop & Crafting: all-or-nothing orchestration that attempts rollback on failure
Rewards: money granted first; no money rollback if item grants fail (by design)
Telemetry rules:
Currency operations propagate sourceId
Item operations do not propagate sourceId

🧱 Facade Entry Point¶

EconomyBootstrap¶

The canonical runtime entry point for wiring economy services for a player / owner.

All overloads return interfaces only; concrete implementations are internal and may change.

Currency-only builds¶

(IShopService shop, IRewardService rewards, ICraftingService crafting,
 IValueLedger ledger, IItemStore store)
BuildForPlayer(GameObject player, ICurrencyService currency, CurrencyPolicy policy = null);

Inventory is not present
store will be null
Item-based operations are disabled

Inventory-enabled builds (`REV_INVENTORY_PRESENT`)¶

(IShopService shop, IRewardService rewards, ICraftingService crafting,
 IValueLedger ledger, IItemStore store)
BuildForPlayer(
    GameObject player,
    ICurrencyService currency,
    IInventoryService inventory,
    Func<string, ItemDefinition> resolveDef,
    string container = "Backpack",
    CurrencyPolicy policy = null
);

Enables item-based pricing, crafting, and rewards
Inventory-backed IItemStore is wired automatically

🧩 Core Service Interfaces (Supported)¶

These interfaces define the supported gameplay contract for Economy.

IShopService¶

Handles purchase and sell transactions.

Buy
Charges currency
Removes item costs
Delivers items
Sell
Removes items first
Grants currency afterwards
All operations are atomic and rollback-safe

ICraftingService¶

Atomic crafting flow.

Charges currency
Removes ingredient items
Adds result item
Full rollback on failure

IRewardService¶

Reward / payout flow.

Money granted first
Item grants attempted afterwards
No money rollback if item grants fail (by design)

💳 Wallet Abstraction¶

IValueLedger¶

Abstracts all currency operations.

CanPay — UX preflight only (side-effect free)
Pay / Grant — authoritative mutations
Currency operations propagate sourceId when provided

Always depend on IValueLedger, never on concrete ledger implementations.

📦 Item Store Abstraction¶

IItemStore¶

Abstracts all item operations.

HasSpaceFor, CanRemove — UX preflight only
Add, Remove — authoritative mutations
Item operations do not propagate sourceId

Always depend on IItemStore, never on concrete store implementations.

🧾 Models & Results¶

These value types are part of the stable public contract.

EcoOpResult¶

Represents the outcome of any economy operation.

Contains Success, Code, and optional Message
Callers must explicitly inspect Success and/or Code
Implicit boolean conversion is not supported

EcoOpCode¶

Stable set of outcome codes describing failure and success reasons.

PriceBundle¶

Lightweight value bundle of optional money and/or item lines. Lists are treated as read-only by contract and are not cloned or frozen.

ChargeLine / ItemLine¶

Atomic representations of currency and item quantities.

🧠 Telemetry Contracts¶

EcoReasons¶

Canonical reason strings.

Use these constants to: - prevent analytics drift - keep logs consistent - avoid “same action, different reason” bugs

EcoSource¶

Canonical builder for sourceId correlation strings.

string src = EcoSource.Build(vendorId, requestId);

🧪 Debug-only Surface¶

IItemStoreDebug¶

Exposes an opaque debug handle for editor tooling only.

Intended for Teachables, inspectors, and diagnostics
Not supported for gameplay logic
Casting or relying on the handle type is unsupported

❌ Explicitly Not Supported¶

The following are not part of the supported public API:

Internal rollback helpers
Internal normalization / validation utilities
Internal policy computation helpers
Concrete service implementations
Concrete adapter implementations
Depending on namespaces under RevGaming.RevFramework.Economy.Internal.*
Casting or using debug handles in gameplay code

TL;DR¶

If it’s not on this page, it’s not part of the supported API.