Skip to content

🧠 Economy System — Mental Model

This page explains how to think about Economy in RevFramework.

It is not an API reference.
It is a conceptual map that helps you decide:

  • What does Economy own?
  • What should still belong to Currency?
  • Where do item stores fit in?
  • Which extension point should I use?

If you understand this page, the Economy API will feel obvious.

🎯 The Core Idea

Economy is an orchestration layer, not a ledger.

Economy does not own money truth.
It does not replace Currency.

It exists to coordinate higher-level gameplay transactions such as:

  • buying
  • selling
  • crafting
  • rewards
  • mixed money + item exchanges

Economy answers:

“What does this transaction mean in gameplay?”

The ledger answers:

“Can money move, and what happens when it does?”

🔗 The Dependency Truth

Economy depends on the IValueLedger abstraction, not on a specific currency implementation.

Economy uses a money layer through the IValueLedger abstraction.

That means:

  • The ledger owns balances
  • The ledger enforces caps/policy
  • The ledger handles authority
  • The ledger may provide audit, escrow, or batching depending on implementation

In the built-in setup, the ledger is typically backed by Currency.

Economy does not duplicate wallet logic.
It composes around it.

🧱 The Two Resource Channels

Economy coordinates two different kinds of resources.

1. Money

Handled through:

IValueLedger

This is the money-facing seam.

A ledger might be backed by:

  • Currency
  • XP
  • reputation
  • another abstract value system

2. Items

Handled through:

IItemStore

This is the item-facing seam.

An item store answers:

  • can this item be removed?
  • can this item be added?
  • is there space?
  • does the owner have enough?

Economy does not care how the inventory works internally.
It only coordinates the supported item operations.

🧭 What Economy Actually Owns

Economy owns transaction meaning and sequencing.

It decides things like:

  • what gets charged first
  • what gets removed second
  • what gets delivered last
  • what gets rolled back on failure
  • which failures are best-effort vs partial-success

That means Economy is responsible for flows like:

  • Shop purchase
    Pay money → remove item costs → deliver purchased items

  • Sell flow
    Remove items → grant payout

  • Crafting
    Pay money → remove ingredients → add crafted result

  • Rewards
    Grant money → attempt item rewards

These are gameplay transactions, not raw wallet operations.

🪜 The Economy Pipeline

A typical Economy operation follows this conceptual structure:

Intent
↓
Preflight (optional)
↓
Money phase (if applicable)
↓
Item phase (if applicable)
↓
Delivery / payout
↓
Rollback (best-effort, if required)
↓
Result

Not every service uses every phase, but this is the general pattern.

🔍 Stage 1: Intent

“What gameplay action is being requested?”

This is where Economy interprets meaning:

  • buy this
  • sell that
  • craft this result
  • grant this reward

🧪 Stage 2: Preflight

“Should this operation even start?”

Economy performs best-effort checks before mutating anything.

Examples:

  • ledger.CanPay(...)
  • store.CanRemove(...)
  • store.HasSpaceFor(...)

Preflight is for UX and early failure, not authority.

💰 Stage 3: Money Phase

“What money movement happens?”

Money moves through IValueLedger.

Economy never edits balances directly.

🎒 Stage 4: Item Phase

“What item movement happens?”

Items move through IItemStore.

Economy coordinates item movement, but does not own inventory internals.

🔁 Stage 5: Rollback

“If this fails halfway through, what should be undone?”

Rollback behaviour depends on the service.

Shop / Crafting

These use best-effort rollback to undo partial progress.

Reward flows

These intentionally allow:

  • money granted first
  • item failure afterwards
  • no rollback of money

🧾 Results, Not Exceptions

Economy communicates outcomes through:

  • EcoOpResult
  • EcoOpCode

Callers should branch on result codes, not message strings.

🏪 Built-in Services

Economy ships with built-in service implementations:

  • IShopService
  • ICraftingService
  • IRewardService

These orchestrate gameplay flows using:

  • IValueLedger
  • IItemStore

🧩 Bootstrap vs Custom Composition

EconomyBootstrap is a convenience façade.

It returns composed services but only exposes abstractions.

Bootstrap is optional.

🚫 What Economy Is Not

Economy is not:

  • a money ledger
  • an inventory system
  • a networking framework
  • a database
  • an ACID transaction engine

🧠 Responsibility Split

Ledger owns

  • balance truth
  • debit / credit
  • policy
  • authority
  • audit
  • escrow (if implemented)

Economy owns

  • gameplay meaning
  • sequencing
  • mixed money + item flows
  • rollback orchestration

Inventory owns

  • item storage truth
  • capacity
  • stacking rules

🧠 The One‑Sentence Model

Economy coordinates gameplay transactions while delegating money truth to the ledger and item truth to the item store.

TL;DR

  • Economy is not a ledger
  • Economy depends on abstractions
  • IValueLedger handles money
  • IItemStore handles items
  • Services orchestrate gameplay flows
  • Rollback is best-effort, not guaranteed