# Free flight (movement.flight)

## What it is for

Lets the character fly: take off, climb, dive, cruise where the camera looks, boost and land, with an optional flight stamina that drains in the air and recovers on the ground.

It needs `input.actions`, `character.control`, `physics.port`, `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: "movement.flight" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "movement.flight",
                              config: { "cruiseSpeed": 12, "boostSpeed": 28 } }
```

## First example

The kit has no dedicated test yet; this installs it and sets two of its settings to their defaults.

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "movement.flight" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "movement.flight",
                              config: { "cruiseSpeed": 12, "boostSpeed": 28 } }
```

## Settings and defaults

Descriptions come from the kit manifest and stay in English.

| Setting | Type | Default | Range or values | Meaning |
|---|---|---|---|---|
| `cruiseSpeed` | number | `12` | 1–200 | Horizontal speed in the air (m/s). |
| `boostSpeed` | number | `28` | 1–400 | Speed while sprint is held (m/s). |
| `climbSpeed` | number | `7` | 0.5–100 | Climb and dive speed (m/s). |
| `accel` | number | `18` | 1–200 | How fast the speed follows the stick (m/s²). |
| `takeoffSpeed` | number | `5` | 0–30 | Upward speed given at take-off (m/s). |
| `takeoffHeight` | number | `2` | 0–50 | After a take-off the flier climbs (at climbSpeed) until it is this many metres above where it left the ground, unless descend is… |
| `doubleJumpTakeoff` | boolean | `true` |  | A second press of jump in the air takes off (besides the flight key). |
| `pitchSteer` | boolean | `false` |  | The vertical speed also follows where the camera looks (the eyes of a first-person character, the free-look camera): climb by… |
| `maxAltitude` | number | `0` | 0–5000 | Metres above the ground the flier cannot climb past (0: no ceiling). |
| `landingHeight` | number | `0.6` | 0.05–5 | Diving to this height above the ground lands. |
| `hoverSink` | number | `0` | 0–20 | Slow sink in m/s when neither climb nor dive is held (0: the flier hovers in place). |
| `stamina` | number | `0` | 0–10000 | Flight stamina (0: unlimited flight). |
| `drain` | number | `6` | 0–1000 | Stamina spent per second in the air. |
| `boostDrain` | number | `14` | 0–1000 | Stamina spent per second of boost (instead of drain). |
| `regen` | number | `12` | 0–1000 | Stamina back per second on the ground. |
| `regenDelay` | number | `1` | 0–30 | Seconds on the ground before the stamina comes back. |
| `recoverRatio` | number | `0.3` | 0–1 | An exhausted flier takes off again once its stamina is back to this share of the maximum. |

## Services, events, variables

- Service `movement.flight`: flying() → view|null, takeOff(), land(), boost(on), stamina(), altitude(), speed(); the hooks flight.takeoff, flight.land, flight.boost (held) and flight.zone (held per zone).
- Events emitted:
  - `flight.takeoff` (`entity`, `x`, `y`, `z`, `how`) — The flier left the ground.
  - `flight.landed` (`entity`, `x`, `y`, `z`, `seconds`, `reason`) — The flight ended: on the ground, asked for, out of stamina, refused by a zone, or the flier left the world (then it falls).
  - `flight.boost` (`entity`, `on`) — The boost started (on) or stopped.
  - `flight.exhausted` (`entity`) — The flight stamina is empty: the flier comes down and cannot take off until recoverRatio is back.
  - `flight.recovered` (`entity`) — An exhausted flier can take off again.
  - `flight.refused` (`entity`, `decision`, `reason`) — A tap of one of the kit's hooks cancelled a decision (never emitted without a tap).
- Variables:
  - `flight.flying` (boolean) — Flying
  - `flight.altitude` (number) — Altitude
  - `flight.speed` (number) — Flight speed
  - `flight.boosting` (boolean) — Boosting
  - `flight.stamina` (number) — Flight stamina
  - `flight.stamina.max` (number) — Flight stamina maximum
- Verbs of the scripting layer:
  - `take_off` (action) — The player takes off (through the hook flight.takeoff).
  - `land` (action) — The player stops flying and falls to the ground (through the hook flight.land).
  - `is_flying` (condition) — The player is in flight.
- Input actions: `fly_toggle`, `fly_down`

## Hooks and modding

- Hooks (a game or a mod can intercept them):
  - `flight.takeoff` (fields a tap may change: `speed`; cancellable) — The player is about to take off (the flight key, a second jump in the air, takeOff(), the take_off action): speed is the upward speed given, stamina what is left (the maximum when unlimited).
  - `flight.land` (cancellable) — The flier asks to stop flying in the air (the flight key, land(), the land action) and would fall from altitude metres.
  - `flight.boost` (fields a tap may change: `speed`; cancellable) — The flier is about to boost (sprint held in the air): speed is the boost speed.
  - `flight.zone` (cancellable) — Whether flying is allowed where the flier is: zones are the ids of the zones it is inside (none: the open world).
- Moddable settings: `cruiseSpeed`, `boostSpeed`, `climbSpeed`, `accel`, `takeoffSpeed`, `takeoffHeight`, `doubleJumpTakeoff`, `pitchSteer`, `maxAltitude`, `landingHeight`, `hoverSink`, `stamina`, `drain`, `boostDrain`, `regen`, `regenDelay`, `recoverRatio`

## Engines

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

## Versions

Kit version 1.0.0.