# Tie game numbers to world settings (world.bindings)

This guide goes deeper than the overview in [Environment of your world](guide:world-environment).

## What it is for

`world.bindings` ties a number of the game to a live setting of another kit, through a curve. One binding is one variable and
one setting: the habitability of a planet raises its seas and thickens its grass, a corruption meter strengthens the weather,
the day count turns the seasons. A binding reads a variable, maps it through points (linear between them, flat beyond), may
follow it slowly and hand over only steps. The kit knows no other kit by name: `targets()` lists every setting the installed kits
serve. It takes no gameplay decision of its own.

## Turn it on

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "world.bindings" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "world.bindings",
                              config: { "bindings": [ { "from": "counter.habitability",
                                "to": { "kit": "world.water", "key": "level" }, "curve": [[0, -4], [100, 1.5]] } ] } }
```

It requires `game.engine`.

## First example

<!-- test: kits/game_engine/host/tests/world_bindings.rs::a_var_drives_a_setting_through_its_curve -->
A binding reads the variable `warmth` and drives the setting `level` of a kit through the curve `[[0, 1], [100, 21]]`:

```json
{ "id": "sea", "from": "warmth", "to": { "capability": "probe.sea", "key": "level" }, "curve": [[0, 1], [100, 21]] }
```

With `warmth` at 25 the output is 6. With `warmth` at 80 the output is 17, but the target kit keeps its own range and answers 10:
`applied` is what the target answered. A binding aimed at a setting no kit serves stays `resolved: false`.

## Settings and defaults

| Setting | Type | Default | Meaning |
|---|---|---|---|
| `bindings` | list of up to 64 | `[]` | each binding drives one setting of one kit from one variable |

A binding has:

| Field | Meaning |
|---|---|
| `id` | name of the binding (default: derived from `from` and the target key) |
| `from` | the variable it reads (a number; true and false read as 1 and 0); a variable that is not yet a number leaves the target alone |
| `to` | `{ kit, key }` or `{ capability, key }`: the setting it drives |
| `curve` | `[[input, output], ...]`, at least two points; linear between points, flat before the first and after the last |
| `smoothing` | seconds, 0 to 3600; the output follows exponentially (about two thirds of the way per period); 0 or absent: at once |
| `step` | the least move worth handing over, so pieces that are expensive to rebuild are not rebuilt every tick; the end of a glide is always handed over |
| `when` | a condition; while it does not hold, the binding leaves its target alone |

The settings are moddable as one whole list: a mod that adds a binding repeats the ones it keeps.

## Services, events

- `world.bindings` (service): `bindings()` returns `[{ id, from, input, output, applied, target, resolved, enabled, active }]`;
  `set(id, enabled)` switches a binding on or off (switched-off bindings are saved); `targets()` returns every live setting
  `{ kit, capability, key, label, min, max, value }`; `force(id, input | null)` pins the input of a binding for a preview or a
  test, and is not saved.
- The kit emits no event and has no variable.

A kit offers a setting by serving `<capability>.settings` with `keys()`, `get(key)` and `set(key, value)`. Settings available
today include `level` of `world.water`, `coverage` of `world.grass`, `vegetation` of `world.terrain`, `coverage` and
`coverage.<slot>` of `world.scenery`, the ranged numbers of `world.lighting` and `intensity` of `world.weather`.

## Hooks and modding

The kit has no hook. A mod overrides `bindings` as one list:

```json
{ "schema": "gripforge.mod/1", "id": "stormy_corruption", "name": "Stormy corruption", "version": "1.0.0",
  "requires": { "world.bindings": "^1" },
  "config": { "world.bindings": { "bindings": [ { "from": "corruption",
    "to": { "capability": "world.weather", "key": "intensity" }, "curve": [[0, 0.1], [100, 1]], "smoothing": 8 } ] } } }
```

## Engines

The behaviour is one shared implementation for the web and native players; the target kits decide what each engine shows.

## When it does not do what you expect

- A binding stays `resolved: false`: no installed kit serves that setting; read `targets()` for the exact `kit` and `key`.
- The setting does not reach the value of the curve: the target clamps to its own range; compare `output` and `applied`.
- Nothing moves: the variable is not a number yet, `when` does not hold, or `step` is larger than the moves of the variable.
- After a load the values jump: every output is recomputed from the restored variables and handed over at once, by design.

## Limits

One variable to one setting per binding; the curve is piecewise linear; the kit cannot create settings, only drive those other
kits serve.

## Versions

Kit `world.bindings` 1.1.0 (declared moddable since 1.1.0), requires `game.engine@^1`.