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 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. |
| 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 is the map — one row per data file, telling you which file controls what.
- Want to understand how prices relate? 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 is the exact edit-and-verify loop. Read it before your first change.