Skip to content

Economy – Abstractions

This folder contains the public interfaces for the Economy subsystem.
These are the stable contracts you should code against when integrating money, items, shops, crafting, and reward flows.

Concrete services, adapters, and utilities live elsewhere and may change over time.
Your game code should depend only on these abstractions.

The abstractions define what must happen — not how it is implemented.

Design guarantees

All Economy abstractions are designed around the following rules:

  • Explicit authority — no implicit permissions or side effects
  • Deterministic orchestration — built-in services apply steps in a fixed order and attempt rollbacks where defined
    (exceptions are explicitly documented, e.g., rewards)
  • Clear failure signalling — EcoOpResult / EcoOpCode, never exceptions
  • Telemetry support — reason + optional sourceId where supported

Important:
Economy does not enforce multiplayer/network authority by itself.
Authority/policy decisions are enforced by the underlying money/inventory implementations and/or by the caller.

Interfaces

IValueLedger

Money-only wallet abstraction.

Represents any value ledger capable of debiting and crediting numeric balances.

  • May be backed by any numeric value system (currency, XP, reputation, points, etc.).
  • Implementations that support correlation SHOULD propagate sourceId.
  • Does not manage items.

Methods

  • CanPay(owner, price)
    Best-effort UX preflight only.
    Must not mutate state.
    Authority is always Pay().

  • Pay(owner, price, reason, sourceId)
    Debits money.
    Implementations may use a two-phase strategy (e.g., hold/commit/release) or direct debit with rollback on partial failure.

  • Grant(owner, payout, reason, sourceId)
    Credits money.
    Enforces policy/caps and rolls back partial failures where applicable.

Returns

EcoOpResult.Ok or a specific failure from EcoOpCode.

IItemStore

Abstract surface over an item container (inventory, bags, banks, etc.).

  • Backed by any item system.
  • Item operations do NOT propagate sourceId by design.
    Correlate item effects via surrounding service logs if required.

Methods

  • HasSpaceFor(item) — capacity preflight
  • CanRemove(item) — ownership preflight
  • Add(item, reason) — add items
  • Remove(item, reason) — remove items

Returns

EcoOpResult.Ok or a specific failure code.

IShopService

High-level buy / sell orchestration using abstract money + items.

  • Uses IValueLedger for money.
  • Uses IItemStore for items.
  • All-or-nothing semantics (built-in implementation attempts rollbacks on failure).
  • Builds a canonical sourceId from vendorId + requestId.

Methods

  • Buy(buyer, ledger, store, price, deliver, vendorId, requestId)
    Money debit → item cost removals (if any) → item deliveries (if any) → rollback on failure.

  • Sell(seller, ledger, store, itemsToSell, payout, vendorId, requestId)
    Item removal → money payout → rollback on failure.

ICraftingService

Crafting orchestration: ingredients + money → result.

Method

  • Craft(crafter, ledger, store, cost, result, reason, sourceId)

Execution order: 1. Money debit
2. Ingredient removal
3. Result item add

Any failure attempts to roll back prior steps.

Notes

  • Currency refunds propagate sourceId.
  • Item rollbacks never propagate sourceId (API limitation of IItemStore).

IRewardService

Reward orchestration: money first, then items.

Method

  • Grant(owner, ledger, store, payout, reason, sourceId)

Execution order: 1. Money grant
2. Item grant (optional)

⚠ Important semantic difference
Money is not rolled back if item delivery fails.
This behaviour is intentional and guaranteed by the contract.

Usage guidelines

  • Always code against these interfaces — never concrete classes.
  • To use the built-in implementations, construct them via EconomyBootstrap (Facade).
  • You may provide your own implementations of:
  • IValueLedger
  • IItemStore
  • All interfaces are:
  • Runtime-only
  • UI-agnostic
  • Pipeline-agnostic
  • Concrete services (ShopService, RewardService, CraftingService, etc.) are implementation details and may change between versions.

See Also