# Endings (game.endings)

## What it is for

Defines several endings chosen by what the player did, each a condition with a title and a text, and ends the game on the end screen when a final one is reached.

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: "game.endings" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "game.endings",
                              config: { "checkEvery": 0.25 } }
```

## First example

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

```rust
#[test]
fn the_highest_priority_wins_and_a_final_ending_ends_the_game() {
    let mut s = session(
        json!([
            { "id": "minor", "title": "Minor", "when": { "var": "day", "op": ">=", "value": 2 }, "final": false },
            { "id": "late", "title": "Too late", "text": "Nobody came.", "when": { "var": "day", "op": ">=", "value": 3 }, "priority": 1 },
            { "id": "good", "title": "Rescue", "when": { "var": "day", "op": ">=", "value": 3 }, "priority": 5 }
        ]),
        json!([]),
    );
    step(&mut s, 2);
    assert!(topics(&mut s).is_empty());
    set(&mut s, "day", json!(2));
    step(&mut s, 7);
    assert_eq!(topics(&mut s), vec!["game.ending"]);
    assert_eq!(s.host.state.get("ending.reached"), Some(&json!("minor")));
    assert_eq!(s.host.state.phase(), "playing");
    set(&mut s, "day", json!(3));
    step(&mut s, 7);
    assert_eq!(call(&mut s, "reached", json!([])), json!(["minor", "good"]));
    assert_eq!(call(&mut s, "final", json!([]))["id"], json!("good"));
    assert_eq!(s.host.state.phase(), "finished");
    assert_eq!(s.host.state.get("endscreen.title"), Some(&json!("Rescue")));
    assert_eq!(s.host.state.get("endscreen.text"), Some(&json!("")));
    // Ended: nothing else is reached.
    assert_eq!(call(&mut s, "reach", json!(["late"])), json!(false));
}
```

## Settings and defaults

Descriptions come from the kit manifest and stay in English.

| Setting | Type | Default | Range or values | Meaning |
|---|---|---|---|---|
| `checkEvery` | number | `0.25` | 0.05–10 | Seconds between two checks of the endings. |

## Services, events, variables

- Service `game.endings`: endings(), reached(), choose(ending, option) → boolean, choice(ending), pending(), reach(ending), endStats(lang) (ui.endstats).
- Events emitted:
  - `game.ending` (`ending`, `title`, `final`) — An ending was reached.
  - `ending.offered` (`ending`, `prompt`) — A choice is put to the player.
  - `ending.chosen` (`ending`, `option`) — The player answered a choice (var ending.choice.<ending>).
- Events listened to: `game.phase`
- Variables:
  - `ending.reached` (string) — Last ending reached
  - `ending.pending` (number) — Choices waiting for an answer
- Verbs of the scripting layer:
  - `reach_ending` (action) — Reach an ending now, whatever its condition.
  - `ending_choice` (condition) — The player answered that choice (with that option).

## Hooks and modding

- Hooks (a game or a mod can intercept them):
  - `ending.reach` (fields a tap may change: `final`; cancellable) — An ending is about to be reached (its condition holds and it has the highest priority, or reach_ending): an ending that must wait, one that no longer ends the game (final: false).
  - `ending.offer` (cancellable) — A choice is about to be put to the player.
  - `ending.choose` (fields a tap may change: `option`; cancellable) — The player is about to answer a pending choice with an option: an answer the story forbids, or forces (an option of that choice; anything else is ignored).
- Moddable settings: `checkEvery`
- Moddable collections: `endings`

## Engines

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

## Versions

Kit version 1.2.0.