Skip to content

RevFramework — Economy System

Overview

The Economy module is a service-based orchestration layer for gameplay transactions involving money and items.

It coordinates higher-level flows such as:

  • shops (buy / sell)
  • crafting
  • rewards
  • mixed money + item exchanges

Economy does not own balances or inventory state.
It composes those systems through explicit abstractions.

This page is a high-level overview for developers who are not reading the full MkDocs site.
It does not duplicate the full Economy documentation or API reference.

Key design goals

  • Orchestration-first: Economy coordinates gameplay transactions across money and item systems.
  • Abstraction-driven: Integration is done through IValueLedger (money) and IItemStore (items).
  • Result-driven: Every operation returns an EcoOpResult with an explicit outcome code.
  • Composable: Behaviour can be replaced by implementing interfaces (IShopService, ICraftingService, etc.).
  • Low lock-in: Concrete implementations remain internal; public APIs expose abstractions only.

Operations are sequential with best-effort rollback.
Hard transactional guarantees are not provided.

What Economy does (and does not do)

Economy owns

  • Gameplay transaction meaning
  • Sequencing of multi-step operations
  • Coordination of money + item flows
  • Best-effort rollback orchestration
  • Result reporting (EcoOpResult)

Economy does not own

  • Money truth (balances, policy, authority)
  • Inventory truth (storage, stacking, capacity)
  • Networking or replication
  • ACID-style transactional guarantees

Core concepts

Money abstraction

IValueLedger

  • Represents a wallet or value system
  • Handles:
  • CanPay (preflight)
  • Pay (debit)
  • Grant (credit)

Typically backed by Currency in the built-in setup.

Item abstraction

IItemStore

  • Represents an item container
  • Handles:
  • HasSpaceFor
  • CanRemove
  • Add
  • Remove

Typically backed by Inventory in the built-in setup.

Services

  • IShopService
  • ICraftingService
  • IRewardService

These coordinate gameplay flows using the abstractions above.

Built-in behaviour (high level)

Economy operations follow a common pattern:

Intent
↓
Preflight (optional)
↓
Money phase (if applicable)
↓
Item phase (if applicable)
↓
Delivery / payout
↓
Rollback (best-effort, if required)
↓
EcoOpResult

Important

  • Preflight is best-effort only
  • Mutations are authoritative through abstractions
  • Rollback is attempted, not guaranteed

EconomyBootstrap provides a convenience entry point for wiring the built-in stack.

It returns:

  • IShopService
  • ICraftingService
  • IRewardService
  • IValueLedger
  • IItemStore

Only abstractions are exposed; implementations remain internal.

Integration with other modules

Module Role
Currency Provides money truth, policy, authority, escrow (when implemented)
Inventory Provides item storage and capacity rules
Economy Orchestrates gameplay transactions across both

Multiplayer note

Economy is network-agnostic.

  • No replication
  • No prediction
  • No authority enforcement

Authority must be handled by:

  • the caller
  • or the underlying money/item implementations

Typical pattern:

  • client requests action
  • server validates
  • server calls Economy
  • clients never mutate state directly

Extension points (supported)

  • Implement IValueLedger to change money semantics
  • Implement IItemStore to change inventory behaviour
  • Implement service interfaces for custom orchestration
  • Compose services manually instead of using EconomyBootstrap

Avoid depending on internal services or adapters.

Typical usage

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

if (!result.Success)
    Debug.LogWarning(result.Code);

Where to learn more

  • Full MkDocs documentation: /economy/
  • System Guarantees Matrix
  • Public API reference
  • Integration Surfaces guide
  • In-Editor Teaching Panels

Summary

The Economy System provides a clean orchestration layer for gameplay transactions:

  • Explicit and result-driven
  • Abstraction-first
  • Best-effort rollback semantics
  • Composable and replaceable
  • UI-agnostic and network-agnostic

Use abstractions. Compose deliberately. Keep gameplay meaning out of lower layers.