Skip to content

📦 Economy — Facade

🎯 Purpose

The Facade layer provides convenience entry points for composing built-in Economy services while returning public abstractions only.

It exists to:

  • Centralise built-in Economy wiring
  • Avoid direct coupling to internal services or adapters
  • Provide default composition helpers for runtime use
  • Keep currency-only and inventory-backed composition clearly separated

🧩 What Lives Here

EconomyBootstrap

Currency-only Economy composition.

Use this when your game uses Currency/Economy without Inventory.

Returns:

  • IShopService
  • IRewardService
  • ICraftingService
  • IValueLedger
  • IItemStore (null in currency-only builds)

EconomyInventoryBootstrap

Inventory-backed Economy composition.

Use this when Economy needs to work with Inventory through an IItemStore.

Requires:

  • REV_INVENTORY_PRESENT
  • ICurrencyService
  • IInventoryService
  • Func<string, ItemDefinition> resolver
  • Inventory container name

🧠 Currency-Only Usage

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

// store == null

Safe Variant

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

Explicit Preflight Mode

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

🧠 Currency + Inventory Usage

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

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

Safe Variant

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

Explicit Preflight Mode

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

⚠️ Important Notes

  • The facade returns interfaces only
  • Concrete implementations remain internal
  • BuildForPlayer throws ArgumentNullException for missing required inputs
  • TryBuildForPlayer returns false instead of throwing
  • EconomyBootstrap is currency-only
  • EconomyInventoryBootstrap is for Inventory-backed composition
  • When store == null, item-dependent operations require a non-null IItemStore
  • Null or whitespace inventory container names are normalized to "Backpack"
  • LedgerPreflightMode affects CanPay() preflight only
  • Authoritative mutations still go through Pay() / Grant()
  • Abstractions README
  • Internal Adapters README
  • Internal Services README
  • Model README
  • Integrations / Economy / InventoryIntegration README