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).
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.