# Air drop and parachutes (drop.parachute)

## What it is for

The opening of a battle royale: a carrier flies across the map with every contestant aboard. Each one jumps when it likes (the player with the jump key, bots at a random point of the line, everybody at the end of the line), falls, opens its parachute (a second press, or by itself near the ground), steers and lands. When the last one is down the drop is over and the storm of `zone.shrink` can start.

## Turn it on

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "drop.parachute" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "drop.parachute",
                              config: { "radius": 140, "altitude": 90, "seconds": 24 } }
```

Needs `input.actions`, `game.engine`; installing the kit brings them along. Optional: `zone.shrink` (with `startZone`, the storm starts when the last contestant has landed).

## First example

<!-- test: kits/game_engine/host/tests/parity.rs::rust_host_matches_the_typescript_traces (fixture drop.parachute.drop) -->
A short drop over a small island: the carrier crosses in 4 seconds, parachutes open by themselves 12 m above the ground, and landings are kept within 25 m of the centre, even when a rule asks for a farther point.

```json
{ "config": { "radius": 30, "altitude": 30, "seconds": 4, "chuteHeight": 12, "landRadius": 25 },
  "hooks": [{ "id": "north", "hook": "drop.land", "set": { "z": 200 } }] }
```

## Settings and defaults

| Setting | Default | Meaning |
|---|---|---|
| `tag`, `players` | `contestant`, `true` | Tag of the entities taken aboard; the player character is taken aboard too. |
| `center`, `radius` | `[0, 0]`, 140 | The carrier flies a diameter of this circle, in a random direction. |
| `altitude`, `seconds` | 90, 24 | Height of the carrier and the time it takes to cross. |
| `gravity`, `terminal`, `steer` | 24, 32, 20 | Free fall: gravity, fastest fall (m/s), horizontal steering speed (m/s). |
| `chuteHeight`, `chuteSpeed`, `chuteSink` | 40, 11, 5.5 | Height at which the parachute opens by itself, horizontal speed and descent speed (m/s) under it. |
| `landRadius` | 139 | Landings are kept within this radius of `center`. |
| `cameraDistance`, `cameraHeight` | 14, 4 | Chase camera while the player rides and falls (0 distance: leave the camera alone); given back on landing. |
| `autoStart`, `startZone` | `true`, `true` | The carrier takes off when the game starts (off: call `start()`); the storm starts after the last landing. |

## Services, events, variables

- Service `drop.air`: `state()` (`phase`, `progress`, `carrier`, `riders`), `jump(entity)`, `start()`, `riders()`.
- Events: `drop.started` (`from`, `to`, `riders`), `drop.jumped` (`entity`, `x`, `z`), `drop.opened` (`entity`, `height`), `drop.landed` (`entity`, `x`, `z`), `drop.finished` (`landed`).
- Variables: `drop.phase` (idle, flying, falling, done), `drop.stage` (carrier, fall, chute, landed), `drop.height`, `drop.timer`. The input action `drop.jump` (Space) jumps, then opens the parachute. Models: the asset slots `drop_carrier` and `drop_chute`.

## Hooks and modding

| Hook | Meaning |
|---|---|
| `drop.jump` | A contestant is about to leave the carrier at `x`, `z`; cancelled, it stays aboard (a cancel is ignored for the forced jump at the end of the line, `forced`). |
| `drop.land` | A contestant is about to land at `x`, `z` (both mutable); the new point is kept within `landRadius`. |

Moddable settings: all the ones above except `tag`, `players`, `center` and `autoStart`.

## Limits

Runs on the web player and the native player; Godot, Unity and Unreal have no native delivery of this kit. The kit moves the contestants and the camera; it does not place spawn points or draw the island: pair it with a spawn kit and a ground.

## Versions

Kit 1.0.0; service `drop.air` 1.0.0. It relies on `input.actions` ^1 and `game.engine` ^1.