# Launch pad (launch.pad)

## What it is for

Sends big one-shot projects from a pad, such as a rocket or an expedition: a launch is a document with a cost, a flight time and what it does on arrival, like changing a world counter or running actions.

It needs `inventory.items`, `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: "launch.pad" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "launch.pad",
                              config: { "padLabel": "Use {name}", "padReach": 6 } }
```

## First example

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

```rust
#[test]
fn a_launch_is_paid_flies_and_acts_on_arrival() {
    let mut s = session();
    let pad = call(&mut s, L, "placePad", json!([[0, 0, 0]]));
    assert_eq!(
        call(&mut s, L, "launch", json!(["probe", pad]))["reason"],
        json!("cost")
    );
    call(&mut s, "inventory.items", "give", json!(["fuel", 5]));
    assert_eq!(
        call(&mut s, L, "launch", json!(["probe"]))["reason"],
        json!("pad")
    );
    assert_eq!(
        call(&mut s, L, "launch", json!(["probe", pad])),
        json!({ "ok": true })
    );
    assert_eq!(
        call(&mut s, "inventory.items", "count", json!(["fuel"])),
        json!(3)
    );
    // The craft is still climbing: the pad is busy.
    assert_eq!(
        call(&mut s, L, "launch", json!(["probe", pad]))["reason"],
        json!("busy")
    );
    assert_eq!(s.host.state.get("launch.flights"), Some(&json!(1)));
    let save = s.apply(&json!({ "op": "save" })).unwrap();
    assert_eq!(save["kits"][L]["flights"][0]["launch"], json!("probe"));
    s.apply(&json!({ "op": "reload" })).unwrap();
    let told = step(&mut s, 40);
    assert!(told.contains(&"launch.arrived".to_string()), "{told:?}");
    assert_eq!(call(&mut s, L, "launched", json!(["probe"])), json!(1));
    // The multiplier is held before the amount is pushed: 4 × 2.
    assert_eq!(
        call(&mut s, "world.stages", "value", json!(["oxygen"])),
        json!(8)
    );
    assert_eq!(s.host.state.get("launch.total"), Some(&json!(1)));
    assert_eq!(call(&mut s, L, "current", json!([])), Json::Null);
}
```

## Settings and defaults

Descriptions come from the kit manifest and stay in English.

| Setting | Type | Default | Range or values | Meaning |
|---|---|---|---|---|
| `padLabel` | string | `"Use {name}"` |  | Prompt of a pad; {name} is its label. |
| `padReach` | number | `6` | 1–40 | The launch screen closes when the player walks further than this from the pad. |
| `liftoffSeconds` | number | `8` | 0–60 | How long the craft is seen climbing before it is gone. |
| `liftoffHeight` | number | `220` | 5–5000 | Height it reaches over that time (meters). |

## Services, events, variables

- Service `launch.pad`: launches(), launch(id, pad?) → { ok, reason? }, flights(), launched(id), open(pad) / close() / current(), unlock(id), unlocked(id), placePad(at, yaw?).
- Events emitted:
  - `launch.started` (`launch`, `pad`, `craft`, `seconds`) — The cost was taken and the craft lifts off.
  - `launch.arrived` (`launch`, `count`) — The flight ended: its effects apply.
  - `launch.failed` (`launch`, `reason`) — reason: unknown, locked, cost, busy, once, pad, or the reason of the tap of launch.start that cancelled it (default refused).
  - `launch.unlocked` (`launch`)
- Events listened to: `interaction.requested`, `entity.spawned`, `game.phase`
- Variables:
  - `launch.open` (boolean) — Launch screen open
  - `launch.flights` (number) — Crafts in flight
  - `launch.total` (number) — Launches arrived
- Verbs of the scripting layer:
  - `start_launch` (action) — Send a launch from a script: no cost, no pad needed.
  - `unlock_launch` (action) — Reveal a locked launch.
  - `launched` (condition) — At least count (1) launches of that kind have arrived.

## Hooks and modding

- Hooks (a game or a mod can intercept them):
  - `launch.start` (fields a tap may change: `seconds`; cancellable) — A launch is about to leave (launch(id, pad), the launch screen, start_launch): after the checks unknown, locked, once, pad, busy and cost, before the cost is taken.
  - `launch.unlock` (cancellable) — A locked launch is about to be revealed (unlock(id), unlock_launch).
- Moddable settings: `padLabel`, `padReach`, `liftoffSeconds`, `liftoffHeight`
- Moddable collections: `launches`
- Components: `launch_pad`

## Engines

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

## Versions

Kit version 1.1.1.