Skip to content

🔌 Economy System — Integration Surfaces

This page explains where new gameplay logic should integrate with the RevFramework Economy system.

If you're extending Economy behaviour or building systems on top of it, start here.

Economy is intentionally designed as an orchestration layer. It does not own money truth or item storage truth.
Instead, it coordinates those systems through a small set of explicit integration surfaces.

Choosing the correct surface keeps gameplay flows predictable, maintainable, and compatible with the rest of the framework.

🧠 Extension Surfaces Overview

Goal Extension Point Example
Change money semantics IValueLedger XP-as-currency, reputation ledger
Change item semantics IItemStore custom inventory backend
Change shop behaviour IShopService vendor tax, discount rules, custom storefront logic
Change crafting behaviour ICraftingService recipe-specific orchestration
Change reward behaviour IRewardService reward splitting, loot payout policies
Compose built-in services EconomyBootstrap standard player setup
Build telemetry reasons EcoReasons canonical operation labels
Build correlation ids EcoSource vendor/request tracing
Read outcomes safely EcoOpResult / EcoOpCode UI feedback, branching, analytics

⚙ Example Decision Flow

I want money to come from a custom progression system

Use:

IValueLedger

Economy should not care whether the money layer is gold, XP, credits, or reputation.
That abstraction belongs in the ledger.

I want Economy to use my own inventory solution

Use:

IItemStore

Economy only needs:

  • HasSpaceFor
  • CanRemove
  • Add
  • Remove

It should not know about container internals.

I want custom shop rules

Use:

IShopService

Shop behaviour belongs in the shop orchestration layer, not in Currency and not in the item store.

Examples:

  • vendor-specific pricing
  • tax
  • item bundles
  • buy restrictions

I want custom crafting behaviour

Use:

ICraftingService

Crafting is a gameplay transaction:

  • pay money
  • remove ingredients
  • add result
  • rollback is attempted if a later step fails

If you want different sequencing or recipe semantics, that belongs here.

I want custom reward logic

Use:

IRewardService

Rewards are intentionally not the same as shops or crafting.

If you want:

  • partial payouts
  • split rewards
  • special reward handling

that belongs in reward orchestration.

I want to plug together the default Economy stack quickly

Use:

EconomyBootstrap

Bootstrap is the supported composition façade for the built-in implementations.

🧩 Economy vs Currency vs Inventory

Economy coordinates other systems.
It should not absorb their responsibilities.

Behaviour Correct Surface
Debit / credit balances Currency
Enforce caps / policy Currency
Escrow / holds Currency
Store item stacks Inventory / IItemStore
Capacity rules Inventory / IItemStore
Buy / sell / craft / reward sequencing Economy

💥 Built-in Services vs Abstractions

The public contract is the abstraction surface.

Built-in implementations are internal details.

Public Surface Purpose
IValueLedger Money abstraction
IItemStore Item abstraction
IShopService Shop orchestration
ICraftingService Craft orchestration
IRewardService Reward orchestration
EconomyBootstrap Convenience composition

Do not integrate against internal service classes directly.

🧾 Results vs Flow Logic

Economy results should be consumed through:

EcoOpResult
EcoOpCode

Use those for:

  • gameplay branching
  • UI feedback
  • analytics / logging

Do not branch on message strings.

⚠ Common Mistakes

Avoid the following:

  • Putting vendor / crafting logic into IValueLedger
  • Treating IItemStore as a gameplay transaction engine
  • Calling internal Economy services directly
  • Assuming rollback is hard-atomic
  • Using message text instead of EcoOpCode
  • Treating EconomyBootstrap as the only valid architecture
  • Putting money truth into Economy instead of Currency

🧠 Architecture Summary

Gameplay Intent
      ↓
Preflight (optional)
      ↓
Money Phase (if applicable)
      ↓
Item Phase (if applicable)
      ↓
Delivery / Payout
      ↓
Rollback (best-effort, if required)
      ↓
EcoOpResult

Every Economy extension surface plugs into one of these stages.

🔗 Related Docs

  • Mental Model
  • Public API
  • System Guarantees Matrix
  • FAQ