# Where Balance Lives

Every tunable number in Underroot lives in a JSON file under `data/`. This page is the map: one row
per file, what it governs, and which deep-dive page has the exact keys and safe ranges. Find the
file here, then follow the link.

## The data folder at a glance

| File | What you tune here | Deep-dive page |
|---|---|---|
| `data/balance.json` | The master dials for every system: the Maw's hunger and escalation, survival drain rates, village needs, day length, trading efficiency, walls, dynamite, world collapse, and the Astrolabe consequence curve. If a number governs *pacing or difficulty* rather than a specific object, it is almost certainly here. | [Maw Threat and Escalation](/docs/underroot/maw-threat-and-escalation), [Survival and Supply Drain](/docs/underroot/survival-and-supply-drain), [The Astrolabe Consequence Curve](/docs/underroot/the-astrolabe-consequence-curve) |
| `data/materials.json` | Everything a material *is*: its Value Point (`trade_value`), dig time, terrain and wall hit-points, chew resistance, durability cost, tier, fuel value, and variable-yield weights. The single largest content file. | [Materials and Mining Yield](/docs/underroot/materials-and-mining-yield), [The Economy Model](/docs/underroot/the-economy-model) |
| `data/tools.json` | The pickaxe and axe ladders, plus storage structures: dig/gather speed, durability, which materials each tool may break (`allowed_materials`), tier reach (`max_material_tier` and the 4x overreach rule), and silo/tower upgrade tiers. | [Tools and Durability](/docs/underroot/tools-and-durability) |
| `data/recipes.json` | Every crafting recipe: inputs, output, craft time, unlock gating (`unlocked_from_start`, `required_layer`, `unlock_requires_astrolabe_uses`, `unlock_requires_schematics`), and the `category` that decides *where* the recipe shows up (or whether it shows up at all). | [Materials and Mining Yield](/docs/underroot/materials-and-mining-yield), [Machine Tuning](/docs/underroot/machine-tuning) |
| `data/machines.json` | Placed machines: work rate, fuel capacity, footprint size, durability and repair cost, how many may be placed (`max_placed`), which recipe a processor runs, and the apothecary's dose/brew schema. | [Machine Tuning](/docs/underroot/machine-tuning) |
| `data/black_hollow.json` | Wren's Expeditions: the five routes (entry cost, cooldown, days-away, gate layer), the depth-band gold multipliers, and the special depth floors — plus the 15-note chronicle. Special *spawn rates* and the schematic/resonant per-descent caps are code constants (see below). | [Black Hollow Expeditions](/docs/underroot/black-hollow-expeditions) |
| `data/layers.json` | The depth bands of the world: where each layer starts and ends (`depth_start`/`depth_end`), its main material, its colour, and the ore inclusions salted through it. This is the shape of the whole descent. | [Layers and Progression Pacing](/docs/underroot/layers-and-progression-pacing) |
| `data/discoveries.json` | Hidden underground pockets: water pockets, mushroom patches, gold, and exotic finds — their spawn chance per layer and the rewards they give. | [Layers and Progression Pacing](/docs/underroot/layers-and-progression-pacing) |
| `data/projects.json` | Villager tasks: each task's category, the material it asks for and how much, the reward type/scale/pool, the penalty for refusing, the minimum depth before it appears, and its spawn weight. | [Villager Tasks and Projects](/docs/underroot/villager-tasks-and-projects) |
| `data/trades.json` | The villager visit economy: material-for-food trades, gold-for-supply and gold-for-goods offers, tool and cosmetic offers, and the Scout's Wager odds and prize pools. | [The Villager Economy](/docs/underroot/the-villager-economy), [The Economy Model](/docs/underroot/the-economy-model) |
| `data/buildings.json` | The three bell buildings (farm, longhouse, watchtower): which support metric each raises (food/shelter/safety), the material cost of each level, and the support bonus each level grants. | [Village Buildings](/docs/underroot/village-buildings) |
| `data/cosmetics.json` | The player-appearance registry: every digger form, skin, headwear, hair, tunic, boots, and extra — how each is unlocked (free, milestone, discovery, scout, secret) and any gameplay `effect` a cosmetic carries. | [Challenge and Harrow Modifiers](/docs/underroot/challenge-and-harrow-modifiers) |
| `data/codes.json` | Redeemable reward codes, keyed by the SHA-256 hash of the code text (never the plaintext), each mapping to the tools, materials, or cosmetics it grants. | [The Safe Change Workflow](/docs/underroot/the-safe-change-workflow) |

## A note on `balance.json`

`balance.json` holds so much that it's split into named sections. The ones you'll reach for most:

| Section | Governs |
|---|---|
| `survival` | Food/water drain per second, work and idle multipliers, storage cap, well trickle. |
| `village` | Population needs, support weights, shelter targets, breach losses, building milestones, the Artificer population gate. |
| `maw` | Grace period, chew rate, hunger pressure growth and cap, threat distances, repel and breach behaviour, light surges. |
| `walls` | Max stack height, mixed-material defense bonus, roots required to bind. |
| `dynamite` / `mining_charge` | Fuse timing, blast size, and the food/water damage each explosive does to nearby supplies. |
| `world` | Cave-in / collapse ranges and fill chances. |
| `time` | `day_duration` — the length of one game-day in seconds (the master pacing clock). |
| `crafting` | Global craft-speed multiplier. |
| `trading` | Swap efficiencies (basic and post-Astrolabe) and the auto-trade interval. |
| `astrolabe` | The consequence curve: how much each ritual raises the Maw's hunger and seeds exotics. |

## What is NOT in the data files

A few systems are tuned in script constants, not JSON. Know these so you don't go hunting for a
knob that isn't there:

- **Weather and storms** — most storm cadence, death range, and stock-loss numbers live in
  `WeatherManager`, not `balance.json`. See [Weather and Storms](/docs/underroot/weather-and-storms).
- **Challenge and Harrow effect magnitudes** — the built-in Challenge multipliers and the Harrow
  dials live in `ChallengeManager` (and its Harrow companion). See
  [Challenge and Harrow Modifiers](/docs/underroot/challenge-and-harrow-modifiers).
- **Black Hollow special rates and caps** — the per-tile schematic/resonant/exotic/relic spawn
  rates, the one-schematic-per-descent cap, the `RESONANT_DIVE_CAP` soft cap, the hazard risk curve,
  and the bones cut are constants in `BlackHollowOverlay`, not `black_hollow.json`. See
  [Black Hollow Expeditions](/docs/underroot/black-hollow-expeditions).

When a data value also has a hardcoded fallback in a script, the golden rule holds: the JSON
overrides the constant. Edit the JSON.

## Related
- [Balance Docs Overview](/docs/underroot/balance-docs-overview)
- [The Economy Model](/docs/underroot/the-economy-model)
- [Black Hollow Expeditions](/docs/underroot/black-hollow-expeditions)
- [The Safe Change Workflow](/docs/underroot/the-safe-change-workflow)
- [The Levers That Matter Most](/docs/underroot/the-levers-that-matter-most)