Skip to content

💰 Economy System — Public API

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

If something is not listed here, it is not supported as a public integration point.

Audience: Developers integrating Economy into gameplay or UI
Scope: Runtime public API only (Editor / Teaching helpers excluded)

📌 Core Concepts

  • Economy is service-based and adapter-driven (money + optional items).
  • Integration is commonly done through the EconomyBootstrap façade, which returns interfaces only.
  • All operations return an EcoOpResult (success flag + code + optional message).
  • Semantics are explicit and consistent:
  • Shop & Crafting: multi-step orchestration with rollback attempts
  • Rewards: money granted first; no money rollback if item grants fail (by design)

Rollback semantics

Rollback attempts are best-effort, not hard transactional guarantees.

Failures in underlying systems (inventory, policy, authority, etc.) may prevent perfect rollback. Callers should always rely on the returned EcoOpResult rather than assuming strict atomicity.

Telemetry rules

  • Currency operations pass through sourceId when supported by the underlying implementation
  • Item operations do not propagate sourceId

🧱 Composition Entry Point

EconomyBootstrap

A convenience façade for composing the built-in Economy services.

It wires the default implementations and returns abstractions only, keeping concrete service implementations internal.

Using EconomyBootstrap is optional. Developers may construct their own implementations of the public interfaces.

Currency-only builds

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

Characteristics:

  • Inventory is not present
  • store will be null
  • Item-based operations require a non-null IItemStore to succeed

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
);

Characteristics:

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

🧩 Core Service Interfaces

These interfaces define the supported gameplay contract for Economy.

IShopService

Handles purchase and sell transactions.

Buy

  1. Charge currency
  2. Remove item costs
  3. Deliver purchased items

Rollback is attempted if later stages fail.

Sell

  1. Remove items first
  2. Grant currency afterwards

Rollback of item removal is attempted if payout fails.

ICraftingService

Sequential crafting flow with best-effort rollback:

  1. Charge currency
  2. Remove ingredient items
  3. Add crafted result

If a later step fails, previously applied steps attempt rollback.

IRewardService

Reward / payout flow.

  1. Money granted first
  2. Item grants attempted afterwards

If item grants fail, money is not rolled back (intentional design choice).

💳 Wallet Abstraction

IValueLedger

Abstracts all currency operations used by Economy.

Methods

  • CanPay — UX preflight only (side-effect free)
  • Pay — authoritative debit
  • Grant — authoritative credit

Currency operations pass through sourceId when supported.

Gameplay code should depend on IValueLedger, not on specific implementations.

📦 Item Store Abstraction

IItemStore

Abstracts item storage and mutation operations.

Methods

  • HasSpaceFor
  • CanRemove
  • Add
  • Remove

Preflight methods are best-effort checks for UX logic.

Item operations do not propagate sourceId.

Gameplay code should depend on IItemStore, not on concrete inventory implementations.

🧾 Models & Results

These value types are part of the public contract.

EcoOpResult

Represents the outcome of any economy operation.

Fields:

  • Success
  • Code
  • Message (optional)

Callers must explicitly inspect Success or Code.
Implicit boolean conversion is not supported.

EcoOpCode

Enumeration describing operation outcomes such as:

  • InvalidArgs
  • InsufficientFunds
  • PolicyBlocked
  • NoSpace
  • NotOwned
  • ServiceMissing
  • ContainerMissing
  • Overflow
  • EscrowUnavailable

These codes are intended for gameplay branching, UI feedback, and telemetry.

PriceBundle

Represents a bundle of optional:

  • money lines (ChargeLine)
  • item lines (ItemLine)

Lists are not cloned or frozen. Callers should treat them as read-only; mutating them may affect consumers.

ChargeLine

Represents a currency line:

  • normalized currency id
  • amount in minor units

ItemLine

Represents an item quantity:

  • item GUID/key
  • quantity

🧠 Telemetry Contracts

EcoReasons

Canonical reason strings for economy operations.

Using these constants helps prevent analytics drift and inconsistent logging.

EcoSource

Canonical builder for sourceId correlation strings.

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

The resulting sourceId is passed through currency operations that support telemetry.

🧪 Debug-only Surface

IItemStoreDebug

Optional diagnostics interface used for:

  • Teachables
  • Editor tooling
  • Debug UI

This interface is public only for diagnostics tooling.

Gameplay code must not depend on it.

❌ Explicitly Not Supported

The following are not part of the supported public API:

  • Internal rollback helpers
  • Internal normalization utilities
  • Internal policy computation helpers
  • Concrete service implementations
  • Concrete adapter implementations
  • Any namespace under:
RevGaming.RevFramework.Economy.Internal.*
  • Casting or relying on debug handles in gameplay code

TL;DR

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