# Genetics (life.genetics)

## What it is for

Lets the player collect genes and give them to living species: a trait gene changes a species and all its colonies, widening a need or changing growth, size, colour or effect on the world.

It needs `life.ecosystem`, `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.genetics" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "life.genetics",
                              config: { "maxTraits": 4, "needsLab": true } }
```

## First example

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

```rust
#[test]
fn a_trait_gene_uses_copies_and_redefines_the_species() {
    let mut s = session();
    assert_eq!(
        call(&mut s, G, "apply", json!(["hardy", "moss"]))["reason"],
        json!("copies")
    );
    assert_eq!(call(&mut s, G, "grant", json!(["hardy", 3])), json!(3));
    assert_eq!(
        call(&mut s, G, "apply", json!(["hardy", "moss"])),
        json!({ "ok": true })
    );
    assert_eq!(call(&mut s, G, "owned", json!(["hardy"])), json!(1));
    // life.ecosystem now holds the species with the trait applied.
    let moss = call(&mut s, L, "get", json!(["moss"]));
    assert_eq!(moss["growth"], json!(4));
    assert_eq!(
        moss["needs"][0],
        json!({ "counter": "heat", "min": -10, "max": 30 })
    );
    assert_eq!(moss["size"], json!(1.5));
    assert_eq!(moss["tags"], json!(["hardy"]));
    // The size multiplier also scales the genome's height (0.2 → 0.3), within its range.
    assert_eq!(moss["genome"]["height"], json!(0.30000000000000004));
    assert_eq!(
        call(&mut s, G, "apply", json!(["hardy", "moss"]))["reason"],
        json!("duplicate")
    );
    assert_eq!(
        call(&mut s, G, "remove", json!(["hardy", "moss"])),
        json!(true)
    );
    assert_eq!(call(&mut s, L, "get", json!(["moss"]))["growth"], json!(2));
}
```

## Settings and defaults

Descriptions come from the kit manifest and stay in English.

| Setting | Type | Default | Range or values | Meaning |
|---|---|---|---|---|
| `maxTraits` | integer | `4` | 1–32 | Traits one species can carry. |
| `needsLab` | boolean | `true` |  | Applying a gene needs an open gene lab. |
| `labReach` | number | `4` | 1–30 | The screen of a gene lab closes when the player walks further than this. |
| `labLabel` | string | `"Use {name}"` |  | Prompt of a gene lab; {name} is its label. |

## Services, events, variables

- Service `life.genetics`: genes(), owned(gene), grant(gene, count?), canApply(gene, species) → { ok, reason? }, apply(gene, species) → { ok, reason?, leap? }, traits(species), effective(species), preview(gene, species), remove(gene, species), open(lab?), close(), current(), placeLab(at, yaw?, label?).
- Events emitted:
  - `genetics.granted` (`gene`, `count`, `owned`) — The player received copies of a gene; owned is the count after it.
  - `genetics.applied` (`gene`, `species`) — A species acquired a trait.
  - `genetics.leap` (`gene`, `from`, `to`) — A leap gene applied to species `from` unlocked species `to`.
  - `genetics.removed` (`gene`, `species`) — A trait was taken away from a species.
  - `genetics.failed` (`gene`, `species`, `reason`) — An application was refused; reason: unknown, locked, incompatible, duplicate, full, known, copies, lab, refused (a tap of the hook genetics.apply…
  - `genetics.opened` (`lab`) — The genetics screen opened; lab is empty when it was opened by its key.
  - `genetics.closed` — The genetics screen closed.
- Events listened to: `interaction.requested`, `entity.spawned`, `game.phase`
- Variables:
  - `genetics.open` (boolean) — Genetics screen open
  - `genetics.genes` (number) — Gene copies owned
- Verbs of the scripting layer:
  - `grant_gene` (action) — Give the player copies of a gene (default 1).
  - `apply_gene` (action) — Apply a gene to a species from a script: no lab and no copy needed; every other rule holds.
  - `has_gene` (condition) — The player owns at least `count` copies of the gene (default 1).
  - `species_has_trait` (condition) — The species carries that trait.
- Input actions: `genetics_menu`

## Hooks and modding

- Hooks (a game or a mod can intercept them):
  - `genetics.grant` (fields a tap may change: `count`; cancellable) — The player is about to receive count copies of a gene (a bonus copy, a gene the story withholds).
  - `genetics.apply` (fields a tap may change: `uses`; cancellable) — A gene is about to be applied to a species, every rule of the kit passed: kind says whether the species takes a trait or the gene unlocks the species to (a leap).
  - `genetics.remove` (cancellable) — A trait is about to be taken away from a species.
- Moddable settings: `maxTraits`, `needsLab`, `labReach`, `labLabel`
- Moddable collections: `genes`
- Components: `genetics_lab`

## Engines

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

## Versions

Kit version 1.2.1.