# Village Buildings

The bell tower periodically offers the player a village building to construct. Each building permanently boosts one of the three village "support" scores. This page lists every building in `buildings.json` with its exact per-level material cost and per-level bonus, and explains the `village.building_milestones` schedule that decides how often the bell offers one. It also covers the **class landmarks** — the champion-only signature buildings that sit outside the bell schedule.

## In plain terms — what a building does

The village runs on three **support** scores: **food**, **shelter**, and **safety**. Each building feeds exactly one of them. Building it, and leveling it up, adds a flat number to that metric's score.

Two words there need defining. **Support** is an internal points score; the village's overall health is set by whichever of the three scores is *lowest*, so a building is worth most when it shores up your weakest metric. **Flat** means the bonus stacks on top of whatever the metric already earns from food stocks, fuel reserves, or wall strength — it's an addition, not a multiplier.

One thing to watch on levels: the bonus is the value **for that level**, not cumulative. A Farm at level 2 grants a flat `65` to food support — not `30 + 65`. Leveling up replaces the previous bonus with the higher one.

## The three buildings

There are exactly three buildings, one per metric. All values below are from `buildings.json`. (`VillageManager` holds a fallback copy of this same data in `BUILDING_DEFS`, used only if the JSON file is missing — the JSON is the tuning surface.)

Each building has three levels. `costs[0]` builds level 1, `costs[1]` upgrades to level 2, `costs[2]` upgrades to level 3. `bonus[i]` is the flat support at that level.

### Farm — food support (champion: Elder Maren)

| Level | Materials to build/upgrade | Flat food support at this level |
|---|---|---|
| 1 | 20 wood, 10 stone | `30` |
| 2 | 10 wood, 5 iron, 30 gold | `65` |
| 3 | 15 stone, 8 bronze, 60 gold | `110` |

### Longhouse — shelter support (champion: Bjorn the Carpenter)

| Level | Materials to build/upgrade | Flat shelter support at this level |
|---|---|---|
| 1 | 25 wood, 10 clay | `30` |
| 2 | 15 wood, 8 coal, 40 gold | `65` |
| 3 | 20 stone, 8 iron, 70 gold | `110` |

### Watchtower — safety support (champion: Guard Captain Siv)

| Level | Materials to build/upgrade | Flat safety support at this level |
|---|---|---|
| 1 | 15 stone, 12 wood | `30` |
| 2 | 10 stone, 8 iron, 40 gold | `65` |
| 3 | 20 stone, 15 iron, 80 gold | `110` |

All three buildings share the same bonus ladder (`30 / 65 / 110`). What separates them is the material cost and which metric they feed. Want one metric cheaper or more powerful to shore up? Change that building's `costs` or `bonus` array on its own.

## How often the bell offers a building

The bell rings — offering a building choice — when the village crosses a population milestone, or on a fallback timer if population growth stalls.

| Setting | Where it lives | Default | What it controls | Turn it up / down |
|---|---|---|---|---|
| `building_milestones` | `balance.json` → `village` | `[63, 85, 113, 137, 167, 213, 263, 321, 376]` | The population counts at which the bell rings to offer a building. Nine milestones, gaps widening as the village grows. | Read by `VillageManager`. Lower/tighter numbers hand out buildings faster; spreading them out makes each building a bigger commitment. Each value is deliberately kept a wide margin from every multiple of 50 so a bell never collides with the population-growth cutscene (which fires at 50, 100, 150, …) — preserve that spacing if you retune. |
| `fallback_bell_days` | `balance.json` → `village` | `6` | Days between fallback bells once population growth stalls, so a player who plateaus below the next milestone still keeps earning buildings. | Lower = buildings keep coming even on a stalled village; higher = a plateaued village waits longer. |

Three buildings, three levels each, is nine total upgrades — matched by nine population milestones plus the fallback timer, so a long-lived village can fully upgrade all three. The milestones control the *pace* at which that happens.

## Class landmarks (champion-only)

Separate from the bell schedule, each **class** unlocks one signature landmark once its champion reaches **skill node 3**. These are built from the craft menu (not offered by the bell), gated by `unlock_requires_champion_skill` + `unlock_requires_skill_node` in `recipes.json`, and each is capped at **1** placement (the Bulwark allows 2). Four are village-side buildings and are covered here; two (the Miner's Deepdrill and the Smith's Grand Anvil) are machines — see [Machine Tuning](/docs/underroot/machine-tuning). Full skill/class context is in [Skills, Classes, and Handicaps](/docs/underroot/skills-classes-and-handicaps).

All the tuning values below live in `machines.json` (the landmark defs), even for the buildings.

### Smokehouse — Hunter (food)

A `2×2` fuel-burning building that cures passive food, the Hunter's answer to the hunting lodge but hands-off. It banks food up to a target, then idles to save fuel.

| Setting | Where it lives | Default | What it controls |
|---|---|---|---|
| `food_per_day` | `machines.json` → `smokehouse` | `30` | Food produced per game-day while burning. |
| `food_target` | `machines.json` → `smokehouse` | `250` | Larder ceiling — the Smokehouse stops burning once food on hand reaches this, matching the lodge/sawmill banking rule. |
| `max_fuel` | `machines.json` → `smokehouse` | `2500` | Fuel-tank size (seconds of burn). |
| `durability_min` / `durability_max` | `machines.json` → `smokehouse` | `60` / `90` | Lifespan before repair. |
| `repair_cost` / `repair_materials` | `machines.json` → `smokehouse` | `200` gold, or 8 wood + 6 stone | Repair bill. |

### Bulwark — Mason (defense)

A `1×1`, `no_fuel` structure placed on the **wall line** (not the village), max **2**. It auto-**roots** the wall columns in its stretch for free, and while the Maw attacks it **braces** its covered columns so the Maw chews through them slower. Bracing runs on a stamina duty-cycle: it braces for a stretch, then must rest at full chew-rate before recharging.

| Setting | Where it lives | Default | What it controls |
|---|---|---|---|
| `root_radius` | `machines.json` → `bulwark` | `2` | How many columns to each side it auto-roots for free. |
| `brace_mult_normal` | `machines.json` → `bulwark` | `1.35` | Chew-rate divisor on covered columns in normal conditions — the Maw grinds ~35% slower. |
| `brace_mult_surge` | `machines.json` → `bulwark` | `1.6` | Stronger divisor while that Maw front is surging (~60% slower) — the Bulwark is hardest to break exactly when the Maw is angriest. |
| `brace_seconds` | `machines.json` → `bulwark` | `18.0` | How long a brace burst lasts before forced rest. |
| `rest_seconds` | `machines.json` → `bulwark` | `9.0` | The recovery window at full chew-rate before it can brace again. |

Roots persist offline; the brace slowdown is live-only (the duty-cycle needs the running Maw tick). Raise the brace mults to make a Mason wall much harder to breach; shorten `rest_seconds` (or lengthen `brace_seconds`) to raise the duty-cycle uptime.

### Mead Hall — Chieftain (all metrics)

A `3×2`, `no_fuel` building. While it stands it lifts **every** support metric — food, shelter, and safety — by a flat amount, so it always shores up whichever is currently lowest.

| Setting | Where it lives | Default | What it controls |
|---|---|---|---|
| `support_bonus` | `machines.json` → `mead_hall` | `45` | Flat points added to each of the three support scores while placed (`VillageManager._mead_hall_bonus`). |

Because village health tracks the lowest metric and the bonus hits all three at once, +45 everywhere is worth more than a single bell-building level (`30 / 65 / 110` to one metric). Treat it as a high-impact lever and keep it flat — support already compounds through population.

### Trading Post — Merchant (gold)

A `2×2`, `no_fuel` building that trickles passive gold, day and night, scaling with village size.

| Setting | Where it lives | Default | What it controls |
|---|---|---|---|
| `gold_per_pop` | `machines.json` → `trading_post` | `1.0` | Gold per game-day **per villager** (`gold_per_pop × population`). At population 100 that's ~100 gold/day. |

Gold accrues live and on the idle clock (offline it's idle-scaled, mirroring the live tick). Because it multiplies by population, it grows naturally with a Chieftain-less but well-fed village — raise it and gold stops being a bottleneck for the endgame exotic buys and cosmetic sinks.

## Safe to change / handle with care

- **The lowest metric is what matters.** Overall village health tracks the weakest of food/shelter/safety, so a building bonus only helps if it lifts the metric that's currently lowest. When you retune `bonus` values, think about which metric a player struggles with at that stage, not the raw number.
- **Keep milestones clear of the 50s.** Every `building_milestones` value is spaced away from multiples of 50 on purpose, to avoid overlapping the population-growth cutscene. If you edit the list, keep a comfortable margin from 50/100/150/… or two cutscenes will fight for the screen.
- **Gold costs gate the higher levels.** Levels 2 and 3 all require gold, a traded or earned resource rather than a mined one. Raise gold costs and upgrades come later; drop them and a cash-rich village powers straight up the ladder.
- **The class landmarks are champion-only power.** Each lands at skill node 3 for one class, so their tuning shifts how strong a given calling feels rather than the baseline run. The Mead Hall (all metrics) and Bulwark (defense during a surge) are the two with the widest reach — move them in small steps.

After editing `buildings.json`, `machines.json`, or the `village` block, re-run the data validator and smoke test — see [The Safe Change Workflow](/docs/underroot/the-safe-change-workflow).

## Related

- [Machine Tuning](/docs/underroot/machine-tuning)
- [Skills, Classes, and Handicaps](/docs/underroot/skills-classes-and-handicaps)
- [The Villager Economy](/docs/underroot/the-villager-economy)
- [Villager Tasks and Projects](/docs/underroot/villager-tasks-and-projects)
- [Survival and Supply Drain](/docs/underroot/survival-and-supply-drain)
- [The Astrolabe Consequence Curve](/docs/underroot/the-astrolabe-consequence-curve)
- [Where Balance Lives](/docs/underroot/where-balance-lives)