Skip to content

📦 Economy — Abstractions

🎯 Purpose

This folder contains the public interfaces for the Economy subsystem.

These interfaces are the primary contracts for integrating money, items, shops, crafting, and reward flows.

Concrete services, adapters, and utilities live elsewhere and may change over time. Game code should depend on these abstractions rather than concrete implementations.

The abstractions define the public API surface and operation shapes. Implementation details and orchestration strategy live in built-in services or custom implementations.

⚠️ Important Notes

  • Economy does not enforce multiplayer or network authority by itself
  • Authority and policy checks depend on the caller and the underlying implementations

🧠 Usage Guidance

Design notes

The Economy abstractions are designed around these principles:

  • Explicit authority — operations are performed through explicit ledger, store, and service calls
  • Result-based failure reporting — public operations return EcoOpResult / EcoOpCode
  • Telemetry inputs — reason and, where supported, sourceId
  • Separation of concerns — money and item operations are abstracted behind separate contracts

🧩 What Lives Here

IValueLedger

Money-only value abstraction.

Represents any ledger capable of debiting and crediting numeric value.

  • May be backed by currency, XP, reputation, points, or similar systems
  • May support telemetry correlation via sourceId
  • Does not manage items

Methods

  • CanPay(owner, price) Side-effect-free UX preflight only. Pay() is authoritative

  • Pay(owner, price, reason, sourceId) Attempts to debit the money portion of a bundle

  • Grant(owner, payout, reason, sourceId) Attempts to credit the money portion of a bundle

Returns

EcoOpResult.Ok or a failure result

IItemStore

Abstract item-container surface for add/remove operations.

  • Can be backed by any game-specific item system
  • Item operations do not accept sourceId

Methods

  • HasSpaceFor(item) — side-effect-free add preflight
  • CanRemove(item) — side-effect-free remove preflight
  • Add(item, reason) — attempts to add items
  • Remove(item, reason) — attempts to remove items

Returns

EcoOpResult.Ok or a failure result

IShopService

High-level buy/sell abstraction using money and item contracts.

  • Uses IValueLedger for money operations
  • Uses IItemStore for item removal and delivery
  • Built-in implementations may apply transaction steps in sequence and may attempt compensation on later failure

Methods

  • Buy(buyer, ledger, store, price, deliver, vendorId, requestId) Attempts a purchase using the supplied cost bundle and optional deliveries

  • Sell(seller, ledger, store, itemsToSell, payout, vendorId, requestId) Attempts a sale using item removal plus a payout bundle

ICraftingService

Craft transaction abstraction for converting money and/or ingredients into a result item.

Method

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

Notes

  • Currency operations may carry sourceId
  • Item operations do not

Built-in implementations may process money cost, ingredient removal, and result delivery as one craft transaction and may attempt compensation if a later step fails.

IRewardService

Reward abstraction for granting money and/or items.

Method

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

Built-in implementations may grant currency before attempting item grants. If a later item grant fails, previously granted currency may remain applied.

🧠 Usage Guidance

  • Prefer coding against these interfaces rather than concrete implementations
  • Built-in implementations are typically obtained through the Economy facade/bootstrap layer
  • You may provide your own implementations of IValueLedger and IItemStore
  • These interfaces are runtime-facing and UI-agnostic
  • Concrete service classes are implementation details of the built-in Economy layer
  • Model README
  • Facade README
  • Adapters README
  • Diagnostics README