# Mission system (mission.system)

## What it is for

Runs data-driven missions and trigger rules as a step machine over objectives such as go to, wait, interact, event and escape a zone, with conditions, actions, rewards and zone markers.

It needs `spawn.entities`, `world.zones`, `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: "mission.system" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "mission.system",
                              config: { "autoStart": "first", "markerColor": "#ffcc00" } }
```

## First example

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

```rust
#[test]
fn the_first_mission_starts_by_itself_by_default() {
    let mut s = session(json!({}));
    step(&mut s, 1);
    assert_eq!(var(&s, "mission.status"), json!("active"));
    assert_eq!(var(&s, "mission.objective.label"), json!("Reach A"));
    assert_eq!(
        call(&mut s, SVC, "active", json!([])).unwrap()["missionId"],
        "m1"
    );
    assert_eq!(
        call(&mut s, SVC, "objective", json!([])).unwrap(),
        json!({"id": "a", "label": "Reach A", "type": "event", "index": 0})
    );
}
```

## Settings and defaults

Descriptions come from the kit manifest and stay in English.

| Setting | Type | Default | Range or values | Meaning |
|---|---|---|---|---|
| `autoStart` | string | `"first"` |  | none, first, or a mission id to start when the world is ready. |
| `markerColor` | string | `"#ffcc00"` |  | Objective zone marker colour. |
| `failOnDeath` | boolean | `true` |  | Fail the active mission when the player is arrested or dies. |

## Services, events, variables

- Service `mission.run`: start(id), abort(id), active(), currentStep(); the advance(state, event) machine.
- Service `mission.objectives`: registerStep(handler) for kit-defined step types.
- Service `triggers.rules`: when → then rules with registrable condition / action verbs.
- Events emitted:
  - `mission.started` (`missionId`, `title`)
  - `mission.objective.started` (`missionId`, `id`, `label`, `type`, `index`)
  - `mission.objective.completed` (`missionId`, `id`, `label`, `type`, `index`)
  - `mission.objective.skipped` (`missionId`, `id`, `label`, `type`, `index`, `reason`)
  - `mission.objective.failed` (`missionId`, `id`, `label`, `reason`) — A step failure or timeout of mission.failed, re-emitted by the kit with the step it came from.
  - `mission.completed` (`missionId`, `title`, `rewards`)
  - `mission.failed` (`missionId`, `title`, `reason`)
  - `mission.aborted` (`missionId`, `title`)
- Events listened to: `zone.entered`, `zone.exited`, `interaction.requested`, `world.ready`, `police.arrested`, `player.died`, `i18n.language`
- Variables:
  - `mission.status` (string) — Mission status
  - `mission.objective.label` (string) — Current objective
  - `mission.timer` (number) — Objective timer

## Hooks and modding

- Hooks (a game or a mod can intercept them):
  - `mission.start` (cancellable) — The kit is about to start a mission (the start policy, a giver zone, the service start): a mission the story keeps closed.
  - `mission.fail` (fields a tap may change: `reason`; cancellable) — The kit is about to fail the active mission because the player died or was arrested (failOnDeath): a second chance, another reason.
- Moddable settings: `autoStart`, `markerColor`, `failOnDeath`
- Moddable collections: `missions`, `triggers`

## Engines

Declared targets: `web`, `godot`, `unity`, `unreal`, `rust`. `gripforge kit api mission.system` lists the exact settings and services of your version.

## Versions

Kit version 1.3.1.