Skip to content

RevFramework – Economy FAQ

This FAQ answers decision questions about using the Economy system: how to integrate it, which extension point to use, and what is supported vs. discouraged.

It complements the Mental Model, Public API, and System Guarantees Matrix by focusing on practical integration decisions.

How do I integrate the Economy system?

Minimal setup (currency only)

  1. Add SceneCurrencyService to the scene.
  2. Resolve the currency service.
  3. Build the Economy services using EconomyBootstrap.
var (shop, rewards, crafting, ledger, store) =
    EconomyBootstrap.BuildForPlayer(player, currencyService, policy);

In this mode:

  • store will be null
  • Item-based flows (crafting ingredients, shop item costs) require an IItemStore to succeed
  • Currency-only rewards and purchases still work

Inventory-enabled setup

When using RevFramework Inventory:

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

This wires the default built-in implementations for money and items.

The result is a full economy pipeline supporting:

  • item costs
  • crafting ingredients
  • item rewards
  • shop deliveries
  • rollback of partial operations (best-effort)

When should I use Economy instead of Currency directly?

Use Currency when you only need:

  • wallet balance changes
  • direct debits or credits
  • currency transfers

Use Economy when the operation involves gameplay meaning, such as:

  • buying items
  • selling items
  • crafting
  • mixed item + money transactions
  • reward bundles

In short:

Currency moves money.
Economy explains why that movement happens.

Is Economy required to use Currency?

No.

Economy is optional.

You can use Currency alone if your game only needs:

  • wallet balances
  • direct spending
  • currency transfers

Economy exists to support multi-resource gameplay flows.

Can I replace parts of the system?

Yes.

The system is designed around abstractions:

Replace Interface
Currency implementation ICurrencyService
Money orchestration IValueLedger
Inventory implementation IItemStore
Shop logic IShopService
Crafting logic ICraftingService
Reward logic IRewardService

EconomyBootstrap is a convenience builder, not a required architecture.

How do rollbacks work?

Economy operations apply multi-step orchestration with best-effort rollback on failure.

Typical execution pattern:

Preflight
↓
Money phase
↓
Item phase
↓
Delivery
↓
Rollback (best-effort) if failure occurs

Rollback is not guaranteed.

Underlying systems (currency policy, authority rules, inventory failures) may prevent perfect reversal.

Always rely on the returned EcoOpResult.

Why doesn't Reward roll back money if item grants fail?

This is intentional.

Reward flows follow:

Grant money
↓
Attempt item rewards

If item rewards fail:

  • the operation fails
  • the money is not rolled back

This supports gameplay patterns such as:

  • quest payouts
  • event rewards
  • battle rewards

What is IValueLedger?

IValueLedger is the money abstraction used by Economy.

It exposes:

  • CanPay — UX preflight
  • Pay — debit
  • Grant — credit

The built-in implementation is provided by the default Economy wiring.

What is IItemStore?

IItemStore is the item abstraction used by Economy.

It exposes only the operations Economy needs:

  • HasSpaceFor
  • CanRemove
  • Add
  • Remove

The built-in implementation is provided by the default Economy wiring.

What is sourceId used for?

sourceId is a correlation identifier for telemetry.

It allows you to link multiple operations together in logs or analytics.

Typical format:

VendorA|rid:abc123

You can build this using:

var src = EcoSource.Build(vendorId, requestId);

Currency operations pass through sourceId when supported.
Item operations do not.

Why are there canonical reason strings?

EcoReasons defines canonical telemetry reasons such as:

  • ShopBuy
  • ShopSell
  • Craft
  • Reward

Using these constants helps prevent:

  • analytics drift
  • inconsistent logs
  • duplicate semantic meanings

Editor builds may warn when non-canonical reasons are used.

Why does EconomyBootstrap return a tuple?

The tuple makes the bootstrap simple and explicit:

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

This avoids:

  • service locators
  • hidden dependencies
  • complex builders

The returned values are interfaces only, keeping implementations internal.

Can I use Economy without Inventory?

Yes.

Currency-only builds work perfectly.

In that mode:

  • crafting ingredients are unavailable
  • item pricing is unavailable
  • reward items require an item store

Currency-only rewards and purchases still work.

What should I avoid?

Avoid the following patterns:

❌ Calling internal services directly
❌ Instantiating internal adapters manually
❌ Writing shop logic in gameplay scripts
❌ Treating item stores as wallet systems
❌ Assuming rollback is guaranteed

Always interact through the public abstractions.

When should I contact support?

Before reporting an issue, check:

  • Are you using EconomyBootstrap or equivalent composition?
  • Is your IItemStore correctly wired?
  • Is the currency service resolved correctly?
  • Are your PriceBundle lines valid?
  • Are you checking EcoOpResult properly?

When reporting bugs include:

  • Unity version
  • active services/adapters
  • operation being executed
  • returned EcoOpResult