# Machines (machines.production)

## What it is for

Adds machines that work on their own: each turns inputs into outputs on a cycle, makes or uses power on a shared grid and can push world counters such as oxygen, heat or pollution.

It needs `game.engine`; installing it brings them in.

## Turn it on

Install the kit in a project, then change a setting (the values shown are its defaults):

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "machines.production" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "machines.production",
                              config: { "useLabel": "Use {name}", "brownout": true } }
```

## First example

<!-- test: kits/game_engine/host/tests/machines_production.rs::a_short_grid_slows_consumers_or_stops_them -->
This is the body of the passing test `a_short_grid_slows_consumers_or_stops_them`; the helper functions it calls are defined at the top of the same test file.

```rust
#[test]
fn a_short_grid_slows_consumers_or_stops_them() {
    // Brownout: half the power, half the speed — one cycle of 0.1 s takes 12 ticks.
    let mut s = session(json!({}));
    let drill = call(&mut s, "place", json!(["drill", [0, 0, 0]]));
    call(&mut s, "place", json!(["solar", [1, 0, 0]]));
    step(&mut s, 11);
    assert_eq!(call(&mut s, "outputs", json!([drill])), json!({}));
    assert_eq!(
        call(&mut s, "power", json!([])),
        json!({ "produced": 2, "demand": 4, "ratio": 0.5 })
    );
    assert!(step(&mut s, 2).contains(&"machine.produced".to_string()));
    assert_eq!(call(&mut s, "outputs", json!([drill])), json!({ "ore": 2 }));
    // The store holds two cycles: then the drill is full, and no longer asks for power.
    step(&mut s, 30);
    assert_eq!(
        call(&mut s, "machines", json!([]))[0]["reason"],
        json!("full")
    );
    assert_eq!(s.host.state.get("power.demand"), Some(&json!(0)));
    // Without brownout a short grid stops its consumers.
    let mut s = session(json!({ "brownout": false }));
    call(&mut s, "place", json!(["drill", [0, 0, 0]]));
    call(&mut s, "place", json!(["solar", [1, 0, 0]]));
    step(&mut s, 30);
    let m = call(&mut s, "machines", json!([]));
    assert_eq!(
        (&m[0]["working"], &m[0]["reason"]),
        (&json!(false), &json!("power"))
    );
}
```

## Settings and defaults

Descriptions come from the kit manifest and stay in English.

| Setting | Type | Default | Range or values | Meaning |
|---|---|---|---|---|
| `useLabel` | string | `"Use {name}"` |  | Prompt of a machine that takes inputs or holds outputs. |
| `brownout` | boolean | `true` |  | Short of power, consumers slow down by the same share; off: they stop until the grid covers them all. |

## Services, events, variables

- Service `machines.production`: types(), machines(), power() → { produced, demand, ratio }, rates(), totals(), use(entity), toggle(entity, on?), place(machine, at, yaw?); world side, no player: outputs(entity) → { item: count }, wants(entity) → { item: room }, takeOutput(entity, item, n) → taken, putInput(entity, item, n) → added;
- Events emitted:
  - `machine.produced` (`machine`, `entity`, `outputs`) — A cycle ended.
  - `machine.collected` (`machine`, `entity`, `items`) — The player emptied it.
  - `machine.fed` (`machine`, `entity`, `items`) — The player loaded inputs.
  - `machine.state` (`machine`, `entity`, `working`, `reason`) — It started or stopped; reason: inputs, full, power, off.
  - `power.changed` (`produced`, `demand`, `ratio`)
- Events listened to: `interaction.requested`, `entity.spawned`
- Variables:
  - `power.produced` (number) — Power produced
  - `power.demand` (number) — Power needed
  - `machines.count` (number) — Machines
- Verbs of the scripting layer:
  - `place_machine` (action) — Stand a machine in the world.
  - `power_covered` (condition) — The grid makes at least the power its machines need.

## Hooks and modding

- Hooks (a game or a mod can intercept them):
  - `machine.produce` (fields a tap may change: `multiplier`; cancellable) — A machine is about to end a cycle (asked once per completed cycle, before the inputs leave and the outputs join its store; with a source, before its take).
  - `machine.collect` (fields a tap may change: `count`; cancellable) — The player is about to take count units of one item out of the output store (one use asks once per item held).
  - `machine.feed` (fields a tap may change: `count`; cancellable) — The player is about to load count units of one input from the bag into the input store (one use asks once per input that fits).
  - `machine.toggle` (cancellable) — A machine is about to be switched on or off (toggle).
  - `machine.place` (cancellable) — A machine of the collection is about to be stood in the world (place, place_machine).
- Moddable settings: `useLabel`, `brownout`
- Moddable collections: `machines`
- Components: `machine`

## Engines

Declared targets: `web`, `rust`. `gripforge kit api machines.production` lists the exact settings and services of your version.

## Versions

Kit version 1.3.1.