Skip to content

Economy – Adapters

⚠️ Adapters are implementation glue – not supported public API

Economy adapters exist to wire the Economy abstractions (IValueLedger, IItemStore) to backing systems such as Currency and Inventory.

Adapter types live under RevGaming.RevFramework.Economy.Internal.Adapters.* and are not supported extension points. They may change, move, or be replaced without notice.

Use the supported public entry points instead: - RevGaming.RevFramework.Economy.Abstractions (interfaces) - EconomyBootstrap (facade wiring) - RevGaming.RevFramework.Economy (model, results, reasons)

The Adapters layer connects the Economy abstractions (IValueLedger, IItemStore) to other RevFramework subsystems.

Adapters are implementation details — your game code should depend on the abstractions and let EconomyBootstrap wire the correct implementations.

Adapters encapsulate integration logic for Currency and Inventory, ensuring consistent behaviour, rollback semantics, and telemetry across all economy flows.

Currency Adapters

The built-in currency adapter provides an IValueLedger implementation backed by the Currency system.

Behaviour

  • Escrow-first execution (hold → commit / release).
  • Fallback to direct debit/credit with deterministic rollback if escrow is unavailable.
  • All currency operations propagate sourceId for telemetry, audit, and correlation.
  • Policy-aware UX preflight behaviour via LedgerPreflightMode:
  • Strict — UX disables if policy would adjust the nominal debit (fees, rounding, clamps).
  • PolicyApproved — UX enables if policy approves and the wallet covers the effective debit.
  • Deterministic normalisation ensures CanPay() and Pay() agree.
  • Currency-layer results are mapped into EcoOpResult / EcoOpCode.

This adapter is used internally by Shop, Crafting, and Reward flows when Currency is present.

Inventory Adapters

The built-in inventory adapter provides an IItemStore implementation backed by the Inventory system.

Behaviour

  • Preflight checks via HasSpaceFor and CanRemove.
  • Item add/remove operations via Inventory APIs.
  • Requires a resolver (guid → ItemDefinition) for item additions.
  • Item operations never propagate sourceId (by design of IItemStore).

Failure mapping

  • Missing inventory service or owner → ServiceMissing
  • Missing container → ContainerMissing
  • Unknown GUID / missing resolver → ResolverMissing
  • Invalid quantities or item lines → InvalidArgs

Usage guidelines

  • You never construct adapters manually.
  • Adapters are created automatically via EconomyBootstrap.BuildForPlayer():
  • Currency-only builds create a currency-backed ledger.
  • Inventory-enabled builds additionally create an inventory-backed item store.
  • Gameplay, UI, and netcode should depend only on:
  • IValueLedger
  • IItemStore

Adapters are not intended extension points.
Replace behaviour by supplying your own IValueLedger or IItemStore implementation, not by subclassing or copying adapters.

Stability & customisation

  • Adapters are replaceable via the abstraction layer.
  • If you remove a built-in adapter:
  • You must provide your own implementation of the corresponding abstraction.
  • This allows Economy to integrate with:
  • Custom currency systems
  • External inventory frameworks
  • Server-authoritative backends

See also

  • Economy – Abstractions
  • Economy – Services
  • Economy – Facade
  • Economy – Model
  • Economy – Internal (Implementation Details)