# Balance Docs Overview

You balance Underroot by editing JSON, not by writing code. Each page in this section tells you
what a number does to the player, where it lives, and how far you can move it safely.

## Who these docs are for

Designers and producers who tune the game without touching GDScript. Nearly every value that
shapes a run — how fast the Maw eats, how quickly food drains, what a villager pays for a lump of
coal, how much a wall costs — sits in a plain-text file under `data/`. Open the file, change a
number, save, run two quick checks. That loop is the whole job.

One rule keeps it safe: the golden rule below. Follow it and you can retune anything without a
line of code.

## The golden rule: tune the JSON, not the script

Most tunable numbers appear twice: in the data file (`data/*.json`, the one you edit) and sometimes
as a matching constant in a script, kept only as a fallback. **The JSON is the tuning surface.**
When a data file supplies a value, the game uses it and ignores the script's copy. The constant
steps in only if the JSON key is missing, and a missing key is a bug, not a tuning choice (see
[The Safe Change Workflow](/docs/underroot/the-safe-change-workflow) for the validator that catches
exactly that).

So change the number in the JSON. Don't go hunting for the same number in a `.gd` file. When the
two disagree, the JSON wins, and editing the script just leaves you wondering why nothing changed.

## Key terms

A few words show up on every page. Here they are once.

| Term | What it means |
|---|---|
| **Tile** | One 32-pixel square of the world grid. Depth, dig time, and the Maw's chewing are all measured in tiles. The ground surface is depth 0; underground goes *down* in positive numbers. |
| **Multiplier** | A number the game multiplies something by. `1.0` means "no change", `2.0` means "double", `0.5` means "half". Multipliers often stack — two `1.5` multipliers together make `2.25`, not `3.0` — so small ones compound faster than they look. |
| **Tier** | A rank number that sorts materials and tools from soft/early (tier 1) to hard/late (tier 7). A pickaxe can dig its own tier and one tier above it (at heavy tool wear); anything harder it cannot touch. |
| **VP (Value Point)** | The single price anchor the whole economy is built on — the `trade_value` field on each material. See [The Economy Model](/docs/underroot/the-economy-model). |
| **Value / default / fallback** | The "default" in these tables is the exact number currently in the data file. Where a script also carries a hardcoded copy, the JSON overrides it; the constant is only the safety net. |

## Where to start

- **Looking for a specific knob?** [Where Balance Lives](/docs/underroot/where-balance-lives) is the
  map — one row per data file, telling you which file controls what.
- **Want to understand how prices relate?** [The Economy Model](/docs/underroot/the-economy-model)
  explains the VP anchor that food, water, gold, materials, tasks, and trades all price off.
- **About to make an edit?** [The Safe Change Workflow](/docs/underroot/the-safe-change-workflow)
  is the exact edit-and-verify loop. Read it before your first change.

## The rest of the Management section

### The threat and survival
- [Maw Threat and Escalation](/docs/underroot/maw-threat-and-escalation)
- [Survival and Supply Drain](/docs/underroot/survival-and-supply-drain)
- [Layers and Progression Pacing](/docs/underroot/layers-and-progression-pacing)

### The village economy
- [The Villager Economy](/docs/underroot/the-villager-economy)
- [Villager Tasks and Projects](/docs/underroot/villager-tasks-and-projects)

### Content tuning
- [Materials and Mining Yield](/docs/underroot/materials-and-mining-yield)
- [Tools and Durability](/docs/underroot/tools-and-durability)
- [Machine Tuning](/docs/underroot/machine-tuning)

### Systems tuning
- [The Astrolabe Consequence Curve](/docs/underroot/the-astrolabe-consequence-curve)
- [Weather and Storms](/docs/underroot/weather-and-storms)
- [Village Buildings](/docs/underroot/village-buildings)

### Modifiers and the cheat sheet
- [Challenge and Harrow Modifiers](/docs/underroot/challenge-and-harrow-modifiers)
- [The Levers That Matter Most](/docs/underroot/the-levers-that-matter-most)

## Related
- [Where Balance Lives](/docs/underroot/where-balance-lives)
- [The Economy Model](/docs/underroot/the-economy-model)
- [The Safe Change Workflow](/docs/underroot/the-safe-change-workflow)
- [The Levers That Matter Most](/docs/underroot/the-levers-that-matter-most)