# Dash (movement.dash)

## What it is for

Adds a quick dodge: a short burst of movement through the character motor with an invulnerability window, charges that recharge over time and hooks for boons.

It needs `input.actions`, `character.control`, `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.dash" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "movement.dash",
                              config: { "distance": 5, "duration": 0.18 } }
```

## First example

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

```rust
#[test]
fn bounded_dash_moves_once_with_gravity_in_both_views(){
 for first in [false,true]{let mut s=session(first);let mut baseline=session(first);let p=pos(&mut s);
 assert_eq!(call(&mut s,"movement.dash","dash",json!([std::f64::consts::FRAC_PI_2])),true);
 step(&mut s,1);let q=pos(&mut s);assert!((q[0]-p[0]-1.6).abs()<0.003);step(&mut baseline,1);assert!((q[1]-pos(&mut baseline)[1]).abs()<0.003);
 step(&mut s,3);assert!((pos(&mut s)[0]-p[0]-4.).abs()<0.003);assert_eq!(call(&mut s,"character.control","pushing",json!([])),false);
 }
}
```

## Settings and defaults

Descriptions come from the kit manifest and stay in English.

| Setting | Type | Default | Range or values | Meaning |
|---|---|---|---|---|
| `distance` | number | `5` | 1–20 | Meters travelled. |
| `duration` | number | `0.18` | 0.05–1 | Seconds the burst lasts. |
| `charges` | integer | `1` | 1–5 |  |
| `recharge` | number | `0.9` | 0.1–10 | Seconds per charge. |
| `invulnerable` | number | `0.22` | 0–1 | Invulnerable seconds from the dash start (applied through combat.health when installed). |
| `cooldown` | number | `0.08` | 0–2 | Minimum gap between two dashes. |

## Services, events, variables

- Service `movement.dash`: dash(yaw), charges, recharge, invulnerability window, sinceDash.
- Events emitted:
  - `dash.started` (`entity`, `yaw`, `from`, `to`, `charges`)
  - `dash.ended` (`entity`, `at`)
  - `dash.recharged` (`charges`)
- Events listened to: `player.pushed`
- Variables:
  - `dash.charges` (number) — Dash charges
  - `dash.max` (number) — Dash max charges
- Input actions: `dash`

## Hooks and modding

- Hooks (a game or a mod can intercept them):
  - `dash.start` (fields a tap may change: `distance`, `duration`, `cooldown`, `invulnerable`; cancellable) — The player is about to dash (the dash action was just pressed, or movement.dash.dash() was called), after the kit's own checks: a charge, the cooldown, a live attached player, a direction.
- Moddable settings: `distance`, `duration`, `charges`, `recharge`, `invulnerable`, `cooldown`
- Components: `dash`

## Engines

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

## Versions

Kit version 1.4.0.