# Dig tools: decisions

Decided 2026-10-19. The resonance drill went in on 2026-10-20, and the same day its widths were
reworked so that each one has a use. Handling of stray bits was added on 2026-10-22 and revised
the same day: rock too hard for the bit never crumbles, and world generation makes no tiny hard
specks instead. The code is in `src/sim/drill.js` and `src/sim/worldgen.js` (`clearHardSpecks`).

## Main tool: Resonance drill
It replaced the old "darken and delete" drill cursor.

- **How it works.**
  - Holding the button sends pulses from the bot toward the cursor.
  - Each pulse is a fan of rays leaving the whole face of the bot, so rock right beside the bot
    is hit too.
  - Rock a pulse passes through shakes: it pales, shivers, and shows cracks that grow finer as
    it nears breaking. Then it shatters into its loose grains.
  - The pulse loses energy as it goes deeper.
- **Pulse width** is changed on the fly with Q/E while the drill is selected. Each width has its
  own reach.

  | Width | Shape | Reach | Good for |
  |---|---|---|---|
  | Narrow | A beam a little wider than the bot | ×1.45 the bit's reach | The fastest and longest tunnels, big enough to fly down |
  | Medium (default) | A cone | ×1 | General digging |
  | Wide | A broad fan | ×0.7 | Opening the most rock per second, but only close to the bot |

  Measured with a stone bit, moving with the face: narrow tunnels about 13 grains a second,
  medium about 9, and wide about 7. Wide opens the most rock per second.
- **Tuning** (R over a material, R again to untune): the pulse passes through everything else
  and shatters only that material.
- **Loose grains** a pulse passes are jostled back toward the bot, so a shattered vein pours out
  of the wall and a bore clears itself.
- **Hardness and base reach** still come from the cast bit tiers: stone, copper, iron, steel.
- **Built blocks, machines and molds** soak up pulses unharmed and shield what is behind them.
- **Trees** in the path come apart into wood chunks (not with a tuned pulse).
- **The bot** never moves loose material. Sand, rubble and water pass straight through it.

### Stray bits
Most leftover obstacles were specks of rock too hard for the current bit, such as iron ore or
granite inside stone when you have a stone bit.

The rule: **rock too hard for your bit never breaks, crumbles or comes loose, however small.**
Crumbling it into ore would let players get ore without the right bit, and confuse them.
Crumbling it into stone would lose ore.

These keep specks out of the way instead:
- **World generation makes no tiny hard specks.**
  - Iron and zinc come in fewer, chunkier veins, with the same total ore.
  - Any piece of 30 grains or fewer that is harder than the rock around it becomes that rock
    (`SPECK_MIN`).
  - Older saves get this cleanup once, when loaded.
  - Basalt dikes in the granite were removed, because they walled off parts of it.
- **Cut-off pieces fall apart.** When a grain breaks and leaves a piece of natural rock of 16
  grains or fewer touching nothing else, the piece falls into its loose grains. This only happens
  if the bit could break every grain of it. A piece with too-hard rock in it stays whole.
- **Thin rock breaks faster.** Corners, nubs and slivers with open space on two or more sides
  shake apart quicker than a flat face.
- **The bot slips around lips.** Flying straight into a ledge a grain or two deep, it slides past
  instead of stopping dead. A real wall still stops it.
- **Tuned pulses** do none of this; they only touch the tuned material.

Upgrade ideas, not built yet:
- Amplifier: reaches deeper per pulse.
- Tuning fork: tuning could become an upgrade instead of being there from the start.
- Harmonics: breaks granite, then basalt (could replace the bit tiers).

The owner wants the whole upgrade system redesigned. The bit mold does not really fit a
resonance drill (see NOTES.md).

## Later: Grav pick (upgrade tool)
A gravity field locks onto a lump of rock, pries it out whole and carries it. It then crushes it
into grains or throws it, into a hopper or a furnace.

It is too slow for normal digging, but useful for selective digging and for moving material.
Upgrades:
- field coil: bigger lumps;
- stabilizer: range;
- compressor: crushes faster;
- sling: throws.

## Late game: Mining charges
Placed charges that blast a radius and throw debris, for digging out big areas.

## Concept art
Animated concepts for both tools are on the "Dig Tool Concepts" design canvas in claude.ai (not
in this repository).