# Powered movement (movement.boost)

## What it is for

Provides powered movement with a flat boost or an opt-in 3D jetpack thrust, bounded fuel, throttle, recharge and a speed limit, from one shared Rust core.

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: "movement.boost" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "movement.boost",
                              config: { "mode": "planar", "maxSpeed": 25 } }
```

## First example

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

```rust
#[test]
fn boosting_accelerates_along_the_direction_and_drains_energy() {
    let mut s = boost(json!({"acceleration": 20, "drain": 10, "energyMax": 50}));
    let r = step(&mut s, json!({}));
    assert_eq!(r["started"], true);
    assert_eq!(r["active"], true);
    assert!(near(&r["velocity"][0], 2.0), "20 m/s2 for 0.1 s");
    assert!(near(&r["energy"], 49.0), "10 per second for 0.1 s");
    assert!(near(&r["rechargeLeft"], 0.5));
    let r = step(&mut s, json!({"velocity": r["velocity"]}));
    assert_eq!(r["started"], false, "already running");
    assert!(near(&r["velocity"][0], 4.0));
}
```

## Settings and defaults

Descriptions come from the kit manifest and stay in English.

| Setting | Type | Default | Range or values | Meaning |
|---|---|---|---|---|
| `mode` | string | `"planar"` | `planar`, `flight` | Planar preserves local-up velocity; flight integrates 3D thrust and supplied gravity, with a total speed limit. |
| `maxSpeed` | number | `25` | 0.1–200 | Planar target speed; flight total speed limit, including unpowered terminal fall speed. |
| `acceleration` | number | `20` | 0.1–500 | Planar steering rate; flight thrust acceleration at full throttle. |
| `braking` | number | `30` | 0.1–500 | Deceleration on the plane, or all three axes in flight. |
| `energyMax` | number | `100` | 0.001–1000000 | Capacity and initial energy. |
| `drain` | number | `20` | 0–1000000 | Powered consumption; zero means unlimited powered time. |
| `recharge` | number | `15` | 0–1000000 | Energy recovered after rechargeDelay. |
| `rechargeDelay` | number | `0.5` | 0–60 | Delay after powered movement before energy recovers. |
| `allowAir` | boolean | `false` |  | Allow boost while the engine reports airborne. |

## Services, events, variables

- Service `movement.boost`: Named instances: create(id, config), request(id, command), remove(id), ids(). Optional move(id, entity, command) uses PhysicsPort. Commands: step, refill; status, config, preview, save, load. Default instance uses installed config.
- Events emitted:
  - `movement.boost.created` (`instance`, `preset`) — An instance was created.
  - `movement.boost.removed` (`instance`) — An instance was removed.
  - `movement.boost.changed` (`instance`, `op`, `result`) — A decided command applied to an instance (never a read or a fixed step).
  - `movement.boost.refused` (`instance`, `op`, `by`, `reason`) — A tap of movement.boost.request cancelled a command.
- Verbs of the scripting layer:
  - `movement_boost_request` (action) — Send a command to an instance of the kit (through the request hook).
  - `movement_boost_exists` (condition) — The instance exists (default: default).

## Hooks and modding

- Hooks (a game or a mod can intercept them):
  - `movement.boost.create` (fields a tap may change: `config`; cancellable) — An instance is about to be created (create(id, config)).
  - `movement.boost.request` (fields a tap may change: `command`; cancellable) — A decided command (every op but the reads and the fixed steps) is about to apply to an instance.
- Moddable settings: `mode`, `maxSpeed`, `acceleration`, `braking`, `energyMax`, `drain`, `recharge`, `rechargeDelay`, `allowAir`
- Moddable collections: `movement_boost_presets`

## Engines

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

## Versions

Kit version 1.2.0.