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 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 for deciding how much moves — Pay and the store operations are authoritative for that. It is decisive in one direction: a preflight that says no ends the operation there, so a refusal is a real outcome and not a hint. The money refusal reports its own reason — a Strict LedgerPreflightMode turning down a policy-adjusted charge comes back as PolicyBlocked, not as InsufficientFunds against a wallet that has the money.

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¶

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¶

TL;DR¶