# Tools and Durability

`data/tools.json` holds the hand tools the player digs and harvests with: how fast each one
works, how long it lasts, and which materials it can break. Change these to set the shape of
the tool progression ladder and how often players craft replacements.

## In plain terms

A tool is one entry in `tools.json`. Two numbers set its speed (`dig_speed_multiplier`,
`gather_speed_multiplier`), one sets its lifespan (`max_durability`), and two together set
what it can break and how much that costs (`max_material_tier` plus the `allowed_materials`
list). Pickaxes and axes come in families (`family`, `tier`) that form an upgrade ladder.
Storage tools — silos, towers, the well — are a different shape entirely and use
`storage_upgrades` instead of speed.

Terms used below:

- **multiplier** — a factor applied to a base value. A `dig_speed_multiplier` of `4.0` means
  four times faster than the 1x baseline, so a 8-second material takes 2 seconds.
- **tier** — a material's difficulty rank (`material_tier` in `materials.json`). A tool's
  `max_material_tier` is the highest tier it breaks cleanly.
- **durability** — a wear counter. Each dig subtracts the material's `durability_cost`; at
  zero the tool breaks and the player drops back to bare hands.

## The tuning fields

| Setting | Where it lives | What it controls | Turn it up / down |
|---|---|---|---|
| `dig_speed_multiplier` | `tools.json` → `<tool>` | How fast this tool digs buried tiles. A material's `dig_time` is divided by this. | Higher = faster mining. The main way each pickaxe tier feels like an upgrade. Fallback `1.0`. |
| `gather_speed_multiplier` | `tools.json` → `<tool>` | How fast this tool harvests surface/forest nodes (trees for axes). Material `gather_time` is divided by this. | Higher = faster harvesting. The axe family's headline stat. |
| `max_durability` | `tools.json` → `<tool>` | Total wear the tool absorbs before breaking. `-1` means infinite (bare hands, storage tools, the well). | Higher = the tool lasts longer between crafts. The lever on how disposable a tier feels. |
| `max_material_tier` | `tools.json` → `<tool>` | Highest material tier the tool breaks at normal cost. It can also break exactly one tier higher, at 4x durability cost (the overreach rule below). | Raising it lets the tool reach deeper materials — collapses the reason to craft the next tier. |
| `allowed_materials` | `tools.json` → `<tool>` | The explicit list of material ids this tool may dig. A material must be listed or the tool refuses it. Each pickaxe's list includes exactly one overreach material one tier above its rating. | Add/remove ids to change what a tool can touch. This is the hard gate, `max_material_tier` is the cost rule. |
| `allowed_resource_nodes` | `tools.json` → `<tool>` | Surface node types the tool can harvest (e.g. `["tree"]` for axes). Empty means it is a digging tool, not a harvester. | Set `["tree"]` to make a tool an axe-type harvester. |
| `family` / `tier` | `tools.json` → `<tool>` | Groups a tool into an upgrade ladder (`pickaxe` 1-6, `axe` 1-3) and its rung on it. Used to auto-equip the best owned tool. | Keep tiers contiguous within a family so auto-equip picks the strongest. |
| `recipe_id` | `tools.json` → `<tool>` | The crafting recipe (in `recipes.json`) that builds this tool. Empty for hands. | Points the craft menu at the right recipe; the actual cost lives in `recipes.json`. |
| `tool_type` | `tools.json` → `<tool>` | Marks non-digging tools: `storage` (silos/towers) or `well`. Absent for normal dig/gather tools. | Only set this for infrastructure tools, not pickaxes. |
| `storage_upgrades` | `tools.json` → `<tool>` | For silos/towers: the ordered list of capacity upgrades, each with a `cap`, a `bonus` (instant fill), and a material `cost`. | See the storage section below. |

Some tool behavior is set by script constants and the skill system, not by `tools.json`:

- A tool can be owned in a stack of up to **5** copies (`TOOL_MAX_STACK` in `ToolState`). When
  one copy breaks, the next full-durability copy auto-equips.
- The active challenge and Wavellite Flux repairs scale a tool's effective durability at
  runtime (`ChallengeManager.tool_durability_mult()`, `FLUX_REPAIR_FRACTION = 0.20`, temper
  ceiling `1.5x`). The `max_durability` in JSON is the un-modified base.
- **The Miner class handicap** drains durability **×1.15** — a Miner run wears its tools 15%
  faster on every dig and gather. It's data-driven
  (`class_info.miner.handicap.mults.tool_durability` in `balance.json → skills`), applied in
  `ToolState` via `SkillManager.class_penalty("tool_durability")`, and is the price the Miner
  pays for the game's fastest digging. The Miner carries a second, off-tool penalty as well —
  **−12% craft speed** (`craft_speed` 0.88, applied in `CraftMenu`) — added because the
  tool-wear hit alone barely bit and left the class effectively un-handicapped. See
  [Skills, Classes, and Handicaps](/docs/underroot/skills-classes-and-handicaps).

## The overreach rule (4x durability)

Each pickaxe lists, in `allowed_materials`, exactly one material one tier above its
`max_material_tier` — its "overreach" material. The tool *can* break it, but every such dig
costs **4x** that material's `durability_cost` instead of 1x (`get_dig_cost` in
`TerrainDigging.gd`). Two guards on the rule: bare hands are exempt, and a material with no
tier set (`material_tier` 0 or missing) is always charged its base cost.

Example: the base Pickaxe is `max_material_tier 3`, but its `allowed_materials` includes Dense
Stone (tier 4). Dense Stone's `durability_cost` is `2.0`, so digging it with a base Pickaxe
costs `8.0` durability per tile and burns through the tool's 80 durability in ten tiles.
That's intentional. Overreach lets a player push one layer deeper in a pinch while strongly
nudging them to craft the next pickaxe.

## The pickaxe ladder

The core dig progression. Each rung is faster, tougher, and reaches one tier deeper.

| Tool | `dig_speed_multiplier` | `max_durability` | `max_material_tier` | Overreach material (4x) | Top material it breaks cleanly |
|---|---|---|---|---|---|
| Bare Hands | `0.5` | `-1` (infinite) | `1` | none | Clay |
| Shovel | `2.0` | `60` | `2` | (none listed) | Stone |
| Pickaxe (t1) | `2.0` | `80` | `3` | Dense Stone (tier 4) | Iron Ore |
| Iron Pickaxe (t2) | `4.0` | `150` | `4` | Limestone / Deep Coal (tier 5)* | Copper / Tin / Dense Stone |
| Bronze Pickaxe (t3) | `6.0` | `280` | `5` | Quartz (tier 6) | Limestone / Deep Coal |
| Steel Pickaxe (t4) | `9.0` | `500` | `6` | (none above listed) | Quartz |
| Quartzite Pick (t5) | `13.0` | `900` | `7` | — (top of the craftable ladder) | All exotics (tier 7) |
| Grand Pick (t6, Smith champion) | `16.0` | `5000` | `8` | — (no tier-8 material exists) | All exotics (tier 7) |

*The Iron Pickaxe's `allowed_materials` lists both Limestone and Deep Coal (both tier 5), so
both are overreach digs at 4x cost until the player crafts the Bronze Pickaxe.

The **Grand Pick** is a champion-only masterwork: only a Smith run can craft it, and only after
building the Grand Anvil landmark at Crafting skill node 3. It's the fastest and most durable
pickaxe in the game (16x speed, 5000 durability) — a payoff for the Smith's whole class arc, not
a rung an ordinary run reaches. See [Machine Tuning](/docs/underroot/machine-tuning) and
[Skills, Classes, and Handicaps](/docs/underroot/skills-classes-and-handicaps).

Bare Hands and the Shovel sit below the family ladder (no `family`/`tier`) and dig only the
handful of materials in their `allowed_materials`. Hands also carry a code guard: they can
only dig on surface/dirt/clay layers regardless of the list.

## The axe ladder (harvesting)

Axes fell trees fast. They share a `dig_speed_multiplier` of `1.0` (they're poor diggers)
and climb on `gather_speed_multiplier` and lifespan instead.

| Tool | `gather_speed_multiplier` | `max_durability` | `allowed_resource_nodes` | `max_material_tier` |
|---|---|---|---|---|
| Axe (t1) | `3.0` | `50` | `["tree"]` | `1` |
| Iron Axe (t2) | `5.0` | `200` | `["tree"]` | `1` |
| Steel Axe (t3) | `7.0` | `600` | `["tree"]` | `1` |

All three can also chip Dirt and Clay in a pinch (`allowed_materials: ["dirt","clay"]`).

## Storage tools and the well

These are infrastructure, not diggers: `max_durability -1` (never wear out) and no speed
stats. The Food Silo and Water Tower both start the village at a 500 cap and climb through
three `storage_upgrades`, each adding 500 to the cap and instantly granting a `bonus` of 500.

| Upgrade step | `cap` | `bonus` | Material `cost` (identical for silo and tower) |
|---|---|---|---|
| Reinforced | `1000` | `500` | 6 steel, 8 dense_stone, 4 bronze |
| Expanded | `1500` | `500` | 8 refined_iron, 6 obsidian_plate, 4 binding_resin, 2 chromium_alloy |
| Vault | `2000` | `500` | 6 chromium_alloy, 4 vault_block, 5 binding_resin, 6 refined_iron |

Without a silo/tower, food and water can't be stockpiled above the base limit. The Well
(`tool_type: well`) is required before any pump can be placed; crafting one also adds a random
300-500 water immediately (that range is a script constant, not JSON).

## Safe to change / handle with care

- **`max_material_tier`** is the strongest progression gate. Raise a pickaxe's tier and it
  skips the next upgrade entirely; lower it and you can strand players who need it for a
  layer. Keep it in step with the overreach material listed in `allowed_materials`.
- **`dig_speed_multiplier`** compounds with `max_durability`. A fast tool that also lasts long
  removes almost all crafting pressure. The ladder deliberately raises both together, so keep
  the gaps between rungs meaningful. The Grand Pick tops both on purpose — it's a champion
  reward, not a baseline tool.
- **`allowed_materials`** is the true gate. Add a deep material to an early tool's list
  without meaning to, and that tool can now reach it (at 1x or 4x depending on tier). Audit
  the list, not just the tier number.
- **`max_durability`** set too low makes a tier feel disposable and floods the craft loop; too
  high makes replacements pointless. Compare against the `durability_cost` of the materials
  that tier is meant to dig — and remember a Miner run burns durability 15% faster than the
  raw number.

Any edit to `tools.json` needs the data validator and, for gameplay-affecting numbers, the
smoke test — see [The Safe Change Workflow](/docs/underroot/the-safe-change-workflow).

## Related

- [Materials and Mining Yield](/docs/underroot/materials-and-mining-yield)
- [Machine Tuning](/docs/underroot/machine-tuning)
- [Skills, Classes, and Handicaps](/docs/underroot/skills-classes-and-handicaps)
- [Survival and Supply Drain](/docs/underroot/survival-and-supply-drain)
- [Layers and Progression Pacing](/docs/underroot/layers-and-progression-pacing)
- [The Safe Change Workflow](/docs/underroot/the-safe-change-workflow)