# The Economy Model

The whole economy hangs off one number per material: its **Value Point**, stored as `trade_value`
in `materials.json`. VP anchors everything else — food, water, gold, material swaps, tasks,
villager trades — so every price in the game is a choice you make, not a guess.

## In plain terms

VP is the "shelf price" of a material. A lump of dirt is worth 1 VP; a bar of iron is worth 30.
When a villager offers to swap one thing for another, the game reads the VP of both sides, applies
an efficiency haircut (you never get full value in a trade), and works out the rate. Raise a
material's `trade_value` and it buys more of everything; lower it and it buys less. There's no
separate price list to keep in sync. Change the anchor and every trade that touches that material
re-prices itself.

Gold, food, and water are the exceptions. They aren't priced *in* VP, they're the things VP
*buys*. Their rates live in `trades.json` as fixed offers, and you tune those directly.

## The VP anchor: every material's `trade_value`

These are the current `trade_value` numbers in `materials.json`. Only materials players are meant
to sell or swap carry one. Refined, processed, exotic, and Astrolabe-seeded materials have no
`trade_value`; they're priced through the gold offers and the Scout's Wager pools below.

| Material | `trade_value` (VP) | Tier | Role |
|---|---|---|---|
| `dirt` | `1` | 1 | The cheapest thing. The floor of the whole scale. |
| `wood` | `2` | (forest) | Surface timber; a hair above dirt. |
| `clay` | `3` | 1 | Early defense material. |
| `stone` | `3` | 2 | First pickaxe material. |
| `coal` | `3` | 2 | Primary early fuel. |
| `sulfur` | `5` | 2 | Variable-yield seam material. |
| `iron_ore` | `8` | 3 | First real ore. |
| `dense_stone` | `12` | 4 | Mid-depth hard stone. |
| `copper_ore` | `15` | 4 | Bronze input. |
| `tin_ore` | `15` | 4 | Bronze input. |
| `limestone` | `16` | 5 | Cement and steel input. |
| `deep_coal` | `16` | 5 | Hotter, longer-burning fuel. |
| `iron` | `30` | (refined) | Refined bar; the mid-game currency-in-kind. |
| `quartz` | `50` | 6 | The deepest sellable seam; top of the VP scale. |

The scale runs 1 to 50 across roughly six tiers. VP climbs with depth and digging difficulty, so
when you set a new material's `trade_value`, slot it between its depth neighbours. Price it too high
and it undercuts them; too low and it trivialises them.

## Exchange efficiency: why a swap never pays full price

When a villager swaps one material for another, the game values both sides in VP and applies a
**trading efficiency**: a multiplier below 1.0, the villager's cut. There are two, tuned in
`balance.json` → `trading`.

| Setting | Where it lives | Default | What it controls | Turn it up / down |
|---|---|---|---|---|
| `basic_efficiency` | `balance.json` → `trading` | `0.45` | The rate you get on a plain material-for-material swap: you receive 45 percent of what you give, measured in VP. | Higher = swaps pay out more (economy loosens); lower = swapping is a worse deal, pushing players to dig what they need. |
| `astrolabe_efficiency` | `balance.json` → `trading` | `0.85` | The much better rate unlocked after the Astrolabe ritual — 85 percent of VP. The late-game reward for reaching the Astrolabe. | Widen the gap from `basic` to make the Astrolabe feel more transformative; narrow it to flatten the payoff. |
| `astrolabe_auto_interval` | `balance.json` → `trading` | `30.0` | Seconds between automatic post-Astrolabe trades. Lower = the auto-trader fires more often. | Below ~10 s can flood the player with resources; keep it generous. |

A worked example: at `basic_efficiency` `0.45`, handing over one `iron` (30 VP) buys about 13.5 VP
of goods, say four-and-a-bit `stone` (3 VP each). After the Astrolabe, the same iron at `0.85` buys
about 25.5 VP. This one number decides whether trading is a crutch or a last resort.

## Food and water: bought, not priced in VP

Food and water are survival meters, not tradeable materials, so they carry no `trade_value`.
Instead, `trades.json` sets exactly how materials and gold convert into them.

### Material-for-food trades

From `trades.json` → `material_food_trades`. Read it as: give `cost` units of the material, receive
`food_per` food.

| Material | `cost` | `food_per` | Effective rate |
|---|---|---|---|
| `dirt` | `3` | `1` | 3 dirt buys 1 food |
| `clay` | `1` | `1` | 1 clay buys 1 food |
| `stone` | `1` | `1` | 1 stone buys 1 food |

These are the emergency-food lines: cheap surface materials the player always has on hand. They
skip the VP efficiency haircut, which makes them a deliberate safety valve. Keep them modest so
they don't replace actually growing food.

### Gold-for-supply and gold-for-goods trades

From `trades.json` → `gold_trades`. `type: "supply"` pours straight into the food or water meter;
`type: "item"` drops into inventory. `gold_cost` is the gold price; `gives_amount` is how much you
get.

| Gives | `gives_amount` | `gold_cost` | Type | Notes |
|---|---|---|---|---|
| `food` | `5` | `10` | supply | Emergency food top-up |
| `water` | `5` | `10` | supply | Emergency water top-up |
| `wood` | `20` | `15` | item | Bulk surface timber |
| `coal` | `20` | `20` | item | Bulk fuel |
| `deep_coal` | `8` | `40` | item | Premium fuel |
| `strange_root` | `5` | `25` | item | Only offered during the Black Rot challenge |
| `iron` | `2` | `25` | item | Refined bars without smelting |
| `ancient_clay` | `1` | `220` | item | Exotic; steep |
| `prismatic_shard` | `1` | `380` | item | Exotic |
| `void_iron` | `1` | `450` | item | Exotic |
| `ember_essence` | `1` | `600` | item | Exotic; the most expensive line |

Gold is the premium currency. It buys the exotics that have no `trade_value` and can't reliably be
dug. The steep exotic prices (220 to 600 gold) are the sink that stops a rich player from just
buying the endgame.

## Where gold comes from

Gold is minted by discoveries and by the villager economy, never by selling materials at a fixed
rate. The gold sources you tune:

- **Villager task rewards** — some tasks pay `gold` (see
  [Villager Tasks and Projects](/docs/underroot/villager-tasks-and-projects)).
- **The Scout's Wager** — a gamble in `trades.json` → `wager`: pay `cost` (default `25`, rising
  with population), and on a win (`success_chance` `0.05`, or `0.15` after the Astrolabe) receive an
  exotic material or cosmetic; otherwise a consolation material bundle. This is the main way exotics
  enter a run without gold, and its odds are the lever between "reliable" and "lottery".
- **Underground gold discoveries** — pockets seeded in `discoveries.json`.

## How the pieces connect

- A material's **`trade_value`** sets what it is worth in every swap.
- **`basic_efficiency` / `astrolabe_efficiency`** decide how much of that worth survives a trade.
- **`material_food_trades`** and **`gold_trades`** convert materials and gold into the survival
  meters and premium goods at fixed, hand-set rates.
- **Task rewards** (in `projects.json`) and the **Wager** (in `trades.json`) are the faucets that
  put food, water, and gold *into* the player's hands to spend.

Move the VP anchor and the swap economy shifts everywhere at once. Move a fixed food/water/gold
offer and only that one conversion changes. Knowing which of the two you're touching is the core of
an economy pass.

## Safe to change / handle with care

- **`trade_value` is load-bearing.** It feeds swap rates, some task reward scaling, and the value
  the villager economy puts on a delivery. Change one material's VP and it ripples through every
  trade that material appears in. Nudge, then playtest.
- **`basic_efficiency`** is a global multiplier on the whole swap economy. Going from `0.45` to
  `0.60` is a big loosening even though it looks small. Treat 0.05 as a meaningful step.
- **Never reward a task with a material it also asks for.** Shared depth-scaling turns the trade
  into a net loss for the player. See
  [Villager Tasks and Projects](/docs/underroot/villager-tasks-and-projects).

## Related
- [Where Balance Lives](/docs/underroot/where-balance-lives)
- [The Villager Economy](/docs/underroot/the-villager-economy)
- [Villager Tasks and Projects](/docs/underroot/villager-tasks-and-projects)
- [Materials and Mining Yield](/docs/underroot/materials-and-mining-yield)
- [The Safe Change Workflow](/docs/underroot/the-safe-change-workflow)