Skip to content

Economy – Facade

The Facade layer exposes EconomyBootstrap, a convenience entry point for wiring the built-in Economy services for a player.

It returns interfaces only, ensuring your game code never depends on concrete implementations.

The facade exists to:

  • Centralise built-in Economy wiring in one place
  • Prevent accidental coupling to internal services or adapters
  • Provide safe and explicit construction paths for runtime use

EconomyBootstrap

EconomyBootstrap is the supported way to construct the built-in Economy pipeline using the provided adapters and services.

You are not required to use the facade — you may supply your own implementations of the Economy abstractions — but the facade provides a safe default composition.

All overloads return a tuple of interfaces:

  • IShopService
  • IRewardService
  • ICraftingService
  • IValueLedger
  • IItemStore

Concrete implementations are intentionally hidden and may change between versions.

Currency-only wiring

Use this when your game uses money only and does not require item flows.

var (shop, rewards, crafting, ledger, store) =
    EconomyBootstrap.BuildForPlayer(player, currencyService, policy);

// store == null → no IItemStore is available
// Item-related operations will fail if invoked

Safe variant

if (EconomyBootstrap.TryBuildForPlayer(player, currencyService, out var services, policy))
{
    var (shop, rewards, crafting, ledger, store) = services;
    // use services
}

Explicit preflight mode

var (shop, rewards, crafting, ledger, store) =
    EconomyBootstrap.BuildForPlayer(
        player,
        currencyService,
        policy,
        LedgerPreflightMode.PolicyApproved
    );

Currency + Inventory wiring

Use this when your economy includes items (shops, crafting ingredients, item rewards).

⚠ Availability

Inventory-enabled overloads are available only when REV_INVENTORY_PRESENT is defined and the Inventory system is included.

Func<string, ItemDefinition> resolveDef = guid => MyGuidMap.Resolve(guid);

var (shop, rewards, crafting, ledger, store) =
    EconomyBootstrap.BuildForPlayer(
        player,
        currencyService,
        inventoryService,
        resolveDef,
        "Backpack",
        policy
    );

Safe variant

if (EconomyBootstrap.TryBuildForPlayer(
        player,
        currencyService,
        inventoryService,
        resolveDef,
        out var services,
        "Backpack",
        policy))
{
    var (shop, rewards, crafting, ledger, store) = services;
    // use services
}

Explicit preflight mode (currency + inventory)

var (shop, rewards, crafting, ledger, store) =
    EconomyBootstrap.BuildForPlayer(
        player,
        currencyService,
        inventoryService,
        resolveDef,
        "Backpack",
        policy,
        LedgerPreflightMode.Strict
    );

Behaviour notes

  • The facade never exposes concrete types.
  • Prefer the TryBuildForPlayer overloads when wiring dynamically at runtime.
  • BuildForPlayer overloads throw ArgumentNullException when required dependencies are missing.
  • When store == null, item-related operations that require an IItemStore (item prices, deliveries, crafting ingredients) will fail.
  • A valid container name is required for inventory-backed builds.
  • Null or whitespace defaults to "Backpack".
  • Providing a CurrencyPolicy may enable:
  • Policy-aware effective debits
  • Balance caps and bounds
  • Escrow requirements (if supported by the underlying currency implementation)
  • LedgerPreflightMode controls UX preflight behaviour only.
  • Authoritative mutations always go through Pay() / Grant().

Stability

  • The facade API is stable across minor versions.
  • New overloads may be added, but existing signatures are preserved.
  • When using the built-in Economy services, prefer wiring via EconomyBootstrap to remain forward-compatible.

See Also