# Automated extraction in your game (resource.extraction)

## What it is for

`resource.extraction` connects a machine to the resource node it stands on: a drill on an ore vein, a pump on a spring, a harvester on a crystal field. A machine of `machines.production` that carries the `extractor` component and is placed on (or near) a node marked `extractable` draws one gather from it each cycle instead of needing inputs, and fills its own output store. Neither the machine rules nor the node rules change: the node runs out and grows back by its own rules, or never runs out. Good for factory, survival, colony and idle games.

## Turn it on

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "resource.extraction" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "resource.extraction",
                              config: { "radius": 2, "infinite": false } }
```

It requires `machines.production`, `resource.nodes` and `game.engine`. It has no screen of its own. Targets: web and the Rust kit host.

## First example

<!-- test: kits/game_engine/host/tests/resource_extraction.rs::an_extractor_draws_from_the_node_it_stands_on -->
A node that is `extractable`, a machine, and a buildable that carries the component:

```json
{ "resource_nodes": [ { "id": "iron_vein", "name": "Iron vein", "item": "iron_ore", "uses": 20, "respawnSeconds": 120, "extractable": true } ],
  "machines": [ { "id": "drill", "name": "Drill", "seconds": 6 } ],
  "buildables": [ { "id": "drill", "name": "Drill", "cost": [{ "item": "plate", "count": 4 }],
                   "components": { "machine": { "machine": "drill" }, "extractor": { "rate": 1 } } } ] }
```

In the test, a drill with `attach(drill, 2)` standing near a vein of 2 uses (2 ore per gather) draws two gathers at rate 2, so its output store holds 8 ore, then the vein runs out. The nearer bush is ignored because it is not extractable, and `attach` on it answers false. After the vein grows back the drill starts again, and the link survives a save and load.

## Rules

- Who: a machine that carries the component `extractor` (`{ rate? }`), through a buildable's `components`, an archetype, a spawn, or `attach`.
- Where: the nearest free node within `radius` whose document says `extractable: true` and that has uses left. One machine per node. A machine with no node waits (inputs) and draws no power.
- What: each machine cycle draws one gather (the node `item`, `count` times `rate` units) into the output store. The machine waits while the node has nothing or while its store is full.
- The node loses one use per cycle, runs out and grows back by its own rules (`respawnSeconds`); the machine starts again when it does. The kit sweeps four times a second for nodes.

## Settings and defaults

| Setting | Type | Default | Meaning |
|---|---|---|---|
| `radius` | number (0.1 to 50) | `1.5` | Metres between a machine and the node it draws from, at most. |
| `infinite` | boolean | `false` | Extraction never uses up a node (the player gathering still does). |

The component `extractor` takes `rate` (0.01 to 1000, default 1): a multiplier of the units drawn per cycle.

## Service, events and hooks

Service `resource.extraction`:

- `extractors()`: `[{ machine, node, item, rate }]`, the current links.
- `attach(machine, rate?)`: makes a machine an extractor; false when it is not a machine.

| Name | Detail |
|---|---|
| `extraction.started` | `{ machine, node }` (entity ids): a machine began drawing from a node. |
| `extraction.stopped` | `{ machine, reason }`; reason is `depleted`, `removed` or `far`. |

The kit listens to `entity.spawned` and `entity.despawned`. The links are saved: a load goes on without announcing them again.

## Hooks and modding

| Hook | Payload | Mutable | Effect |
|---|---|---|---|
| `extraction.start` | `{ machine, node, machineId, nodeId }` | none | An extractor is about to be linked. Cancelled: no link and no `extraction.started`; the machine waits, and is not asked again while that node stays its best. |
| `extraction.extract` | `{ machine, node, nodeId, item, rate }` | `rate` | The draw at the end of a cycle. Cancelled: nothing is drawn and the node keeps its uses. |

```json
{ "id": "deep_drills", "hook": "extraction.extract", "match": { "nodeId": "iron_vein" }, "mul": { "rate": 2 } }
```

A mod may override `radius` and `infinite`. The yield of the node itself is the hook `resource.extract` of `resource.nodes` (see [Resource nodes](guide:resource-nodes)).

## When it does not do what you expect

- The machine never works: no node within `radius`, the node is not `extractable`, or it has no uses left (it waits, drawing no power).
- Two drills on one vein: only one links; the other waits.
- The player still depletes a node with `infinite` on: that setting only protects it from extractors.
- `extraction.stopped` with `far`: the machine or the node moved away.

## Limits

- It draws only from `resource.nodes`; the machine must belong to `machines.production`.
- One machine per node, one gather per cycle.

## Versions

Kit 1.2.0; service `resource.extraction` 1.0.0. Hooks and moddable config since 1.1.0; since 1.2.0 a refused link is saved with the game.