# Ecosystem (life.ecosystem)

## What it is for

Lets the player put living species on a world that then live by rules: each species has needs by biome, dependencies, growth and spread, and colonies grow toward the capacity of their biome.

It needs `world.biomes`, `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: "life.ecosystem" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "life.ecosystem",
                              config: { "tickSeconds": 1, "speed": 1 } }
```

## First example

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

```rust
#[test]
fn the_colonies_survive_a_save() {
    let mut s = session();
    call(&mut s, L, "implant", json!(["algae", "sea", 40]));
    call(&mut s, L, "implant", json!(["moss", "plain", 12]));
    step(&mut s, 30);
    s.apply(&json!({ "op": "save" })).unwrap();
    assert_eq!(
        call(&mut s, L, "remove", json!(["moss", "plain"])),
        json!(true)
    );
    assert_eq!(
        call(&mut s, L, "population", json!(["moss", "plain"])),
        json!(0)
    );
    s.apply(&json!({ "op": "reload" })).unwrap();
    let moss = call(&mut s, L, "population", json!(["moss", "plain"]));
    assert!(moss.as_f64().unwrap() > 12.0, "{moss}");
    assert_eq!(
        call(&mut s, L, "viability", json!(["moss", "sea"]))["habitat"],
        json!(false)
    );
}
```

## Settings and defaults

Descriptions come from the kit manifest and stay in English.

| Setting | Type | Default | Range or values | Meaning |
|---|---|---|---|---|
| `tickSeconds` | number | `1` | 0.05–60 | The simulation step: every colony grows, acts and may spread once per step. |
| `speed` | number | `1` | 0–1000 | A multiplier on growth, decay and spread, for pacing (0 freezes the populations). |
| `maxVisible` | integer | `150` | 0–2000 | Visible individuals in the whole world, all colonies together. |
| `implantAmount` | number | `20` | 1–1000000 | Individuals put down by one use of a species item (and by implant() without an amount). |
| `neighbourDistance` | number | `5` | 0–10000 | Two biomes are neighbours when their shapes overlap or lie within this distance. |
| `plantLooks` | string | `"genome"` | `genome`, `model` | How a species that carries a `genome` is shown: `genome` (generated plants that grow, the bound model ignored) or `model` (its… |
| `publish` | array | `[]` |  | World counters SET every step to the total population of the matching species ({ "counter": "plants", "kinds": ["algae", "moss"]… |

## Services, events, variables

- Service `life.ecosystem`: species(), get(id), colonies(), population(species, biome?), viability(species, biome), implant(species, biomeOrPoint, amount?), remove(species, biome), unlock(id), unlocked(id), define(doc), total(filter?), neighbours(biome), open(), close(), isOpen(); scope(id), scopeId() — the colonies of one wor
- Events emitted:
  - `life.implanted` (`species`, `biome`, `population`) — Individuals were put in a biome; population is the colony after it.
  - `life.rejected` (`species`, `reason`) — An implant was refused; reason: unknown, locked, no_biome, closed, habitat, refused (a tap of the hook life.implant cancelled it).
  - `life.spread` (`species`, `from`, `to`) — A settled colony seeded a neighbouring biome.
  - `life.extinct` (`species`, `biome`) — A colony fell under one individual and is gone.
  - `life.thriving` (`species`, `biome`) — A colony passed 90 % of the capacity of its biome (once per colony).
  - `life.unlocked` (`species`) — A locked species became available.
- Events listened to: `inventory.used`, `game.phase`
- Variables:
  - `life.colonies` (number) — Living colonies
  - `life.population` (number) — Living individuals
  - `life.open` (boolean) — Life screen open
- Verbs of the scripting layer:
  - `implant_species` (action) — Put individuals of a species in a biome (refused when it is locked, the biome is closed or the habitat does not fit).
  - `unlock_species` (action) — Make a locked species available.
  - `species_alive` (condition) — The species lives — in that biome, or anywhere — with at least `min` individuals (default 1).
  - `species_unlocked` (condition) — The species is available to implant.
- Input actions: `life_menu`

## Hooks and modding

- Hooks (a game or a mod can intercept them):
  - `life.implant` (fields a tap may change: `amount`; cancellable) — Individuals of a species are about to be put in a biome (the species is known and unlocked, the biome open, the habitat fits).
  - `life.colonize` (fields a tap may change: `seed`; cancellable) — A settled colony is about to seed a neighbouring biome (a colony is born): asked after the draw of this step succeeded.
  - `life.die` (cancellable) — A colony is about to fall under one individual and die out.
  - `life.unlock` (cancellable) — A locked species is about to become available.
- Moddable settings: `tickSeconds`, `speed`, `maxVisible`, `implantAmount`, `neighbourDistance`, `plantLooks`, `publish`
- Moddable collections: `species`

## Engines

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

## Versions

Kit version 1.6.0.