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, Survival and Supply Drain, 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, 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
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, 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
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
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
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
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
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, 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
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
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

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:

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