World bindings

Drive a live setting of another kit from a game variable through a curve, with smoothing, a minimum step and a condition: habitability raising the seas, corruption thickening the fog.

Source: module-kits:kits/world_bindings/usage/en.mdView Markdown source

Also read offline — CLI: grip-forge docs world-bindingsMCP tool: gripforge_docs { "topic": "world-bindings" }

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

This guide goes deeper than the overview in Environment of your world.

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 #

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 #

A binding reads the variable warmth and drives the setting level of a kit through the curve [[0, 1], [100, 21]]:

{ "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:

{ "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.