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

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.

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.

*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 and 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.

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.

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.

Related

• Materials and Mining Yield
• Machine Tuning
• Skills, Classes, and Handicaps
• Survival and Supply Drain
• Layers and Progression Pacing
• The Safe Change Workflow