Skip to content

💰 Currency – Adapters

Namespace: RevGaming.RevFramework.Currency.Adapters

This folder contains integration bridges that adapt external systems (for example Inventory) to the Currency service layer.

Adapters allow the Currency system to treat non-currency data (such as item stacks) as valid wallets without polluting the core currency contracts.

All adapters are optional and gated behind compile symbols.

Purpose

  • Provide lightweight connectors that expose other systems as currency sources or sinks.
  • Allow Currency to operate on existing data models (inventory, items, pickups).
  • Keep all integrations optional via compile-time guards (e.g. REV_INVENTORY_PRESENT).
  • Preserve the purity of the core currency layer — no hard dependencies on external systems.

If an adapter is not present, Currency continues to function normally.

Key Files

ItemBackedCurrencyAdapter.cs

Bridge between Inventory item stacks and ICurrencyService.

  • Implements ICurrencyService directly.
  • Each adapter instance represents one currency, backed by a single ItemDefinition.
  • Treats the provided ItemDefinition stack as the currency balance.
  • Uses cached reflection to integrate with inventory containers without a hard API dependency.

Required container capabilities:

  • CountOf(string guid)
  • TryAddAllResult(ItemStack stack)
  • TryRemoveResult(string guid, int quantity)

Behaviour

  • Supports:
  • Balance reads
  • Credit / Debit
  • Absolute SetBalance
  • Transfers between owners (delegates to Inventory's transfer implementation)
  • Emits CurrencyDelta events post-commit, exactly like any other currency service.
  • Returns CurOpCode.ServiceMissing if required container APIs are unavailable.
  • Compiles only when REV_INVENTORY_PRESENT is defined.

Transfer semantics (including atomicity) depend on the underlying IInventoryService implementation.

Factory helpers

Adapters are not constructed directly.

Use the provided factory helpers so concrete adapter types remain internal:

#if REV_INVENTORY_PRESENT
var svc = CurrencyInventoryFactories.InventoryBacked(
    inventoryService,
    coinItemDefinition,        // ItemDefinition representing the coin
    "Backpack"                // Inventory container name
);
#endif

Packaged helpers are also available:

#if REV_INVENTORY_PRESENT
var svc = CurrencyInventoryFactories.InventoryBackedWithCapsThenAudit(
    inventoryService,
    coinItemDefinition,
    policy,
    auditCapacityPerOwner: 256
);
#endif

All returned values are still just ICurrencyService — consumers never see the adapter type.

Identity & CurrencyId

  • The CurrencyId used with the adapter does not need to match the item’s GUID.
  • Internally, the adapter always operates on the ItemDefinition GUID.
  • The CurrencyId exists for external identity:
  • UI binding
  • Audit entries
  • Policy / cap rules
  • Exchange rules

If you want ID-specific caps, policies, or UI formatting, ensure the CurrencyId value you use (e.g. "gold") matches your configuration assets.

Gotchas & Notes

  • If the target inventory container does not expose the expected methods, operations fail with CurOpCode.ServiceMissing.

  • Escrow, caps, audit, idempotency, batch events, and authority all work normally when wrapped around an adapter-backed service.

  • Persistence is independent:

  • Inventory systems typically save item state
  • Currency persistence saves wallet balances

  • The adapter does not synchronize persistence between systems.

  • Each adapter instance represents exactly one currency. If you need multiple item-backed currencies, create one adapter per item.

  • Credits attempt to ensure/create the target inventory container when possible. Debits require the container to already exist and return CurOpCode.NotFound otherwise.

You may choose one, both, or neither depending on your game architecture.

Safe to delete

If you are not integrating Inventory (or similar systems) as a currency backend, this entire folder can be deleted safely.

No other part of the Currency system depends on Adapters.

  • Abstractions — foundational contracts (ICurrencyService, CurrencyId, Money)
  • Core — factories, composition helpers, and resolvers
  • Internal — decorator implementations (caps, audit, escrow, idempotency, batching)
  • Policies — cap rules and escrow requirements