# Climbing, swimming and gliding (movement.traversal)

## What it is for

Lets the on-foot character explore freely: climb steep surfaces, wall jump, pull up over ledges, swim, glide and slide down slopes, with one shared stamina pool and a gauge.

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.traversal" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "movement.traversal",
                              config: { "climb": true, "climbSpeed": 1.6 } }
```

## First example

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

```rust
#[test]
fn the_stamina_pool_is_spent_exhausted_and_recovers() {
    let mut s = session(json!({ "staminaMax": 50 }));
    let stamina = |s: &mut Session, m: &str, a: Json| call(s, "movement.stamina", m, a);
    assert_eq!(stamina(&mut s, "max", json!([])), json!(50));
    assert_eq!(stamina(&mut s, "spend", json!([60])), json!(false));
    assert_eq!(stamina(&mut s, "spend", json!([20])), json!(true));
    assert_eq!(stamina(&mut s, "value", json!([])), json!(30));
    assert_eq!(stamina(&mut s, "spend", json!([60, true])), json!(true));
    assert_eq!(stamina(&mut s, "exhausted", json!([])), json!(true));
    assert_eq!(stamina(&mut s, "spend", json!([1, true])), json!(false));
    // Recovery `full`: exhausted until the gauge is full again.
    stamina(&mut s, "restore", json!([49]));
    assert_eq!(stamina(&mut s, "exhausted", json!([])), json!(true));
    stamina(&mut s, "restore", json!([5]));
    assert_eq!(stamina(&mut s, "exhausted", json!([])), json!(false));
    assert_eq!(stamina(&mut s, "value", json!([])), json!(50));
    stamina(&mut s, "setMax", json!([80, true]));
    assert_eq!(stamina(&mut s, "value", json!([])), json!(80));
}
```

## Settings and defaults

Descriptions come from the kit manifest and stay in English.

| Setting | Type | Default | Range or values | Meaning |
|---|---|---|---|---|
| `climb` | boolean | `true` |  | Climb surfaces steeper than climbMinSlope. |
| `climbSpeed` | number | `1.6` | 0.2–10 |  |
| `climbMinSlope` | number | `55` | 30–90 | Degrees: steeper surfaces are climbable. |
| `climbCost` | number | `8` | 0–100 | Stamina per second while climbing (a third while hanging still). |
| `climbJump` | boolean | `true` |  | Jump while climbing: a quick leap up the wall, or off the wall when pulling back. |
| `climbJumpCost` | number | `20` | 0–100 |  |
| `climbJumpDistance` | number | `2` | 0.5–10 |  |
| `wallJumpSpeed` | number | `5` | 0–20 | Horizontal speed of a jump off the wall. |
| `swim` | boolean | `true` |  |  |
| `swimDepth` | number | `1.1` | 0.3–3 | Water depth (m) at which the character starts swimming. |
| `swimSpeed` | number | `2.2` | 0.2–10 |  |
| `swimFastSpeed` | number | `4.5` | 0.2–20 | With sprint held. |
| `swimCost` | number | `3` | 0–100 | Stamina per second swimming (30 % treading water). |
| `swimFastCost` | number | `18` | 0–100 |  |
| `drowning` | boolean | `true` |  | Out of stamina in deep water: damage (combat.damage) and back to the last safe ground. |
| `drownDamage` | number | `20` | 0–10000 |  |
| `glide` | boolean | `true` |  | Open a glider in the air (glide action, or jump when glideWithJump). |
| `glideWithJump` | boolean | `true` |  |  |
| `glideSpeed` | number | `6` | 0.5–40 |  |
| `glideSink` | number | `1.6` | 0.1–20 | Metres lost per second while gliding. |
| `glideCost` | number | `3` | 0–100 |  |
| `glideMinHeight` | number | `2.5` | 0.5–50 | Height above the ground needed to open the glider. |
| `windDrift` | number | `0.3` | 0–2 | Fraction of the world.weather wind added to the glide. |
| `slide` | boolean | `true` |  | Slide down slopes steeper than slideMinSlope. |
| `slideMinSlope` | number | `40` | 10–89 |  |
| `slideMaxSpeed` | number | `12` | 1–60 |  |
| `staminaMax` | number | `100` | 1–10000 |  |
| `regen` | number | `30` | 0–10000 | Stamina per second on the ground. |
| `regenDelay` | number | `0.8` | 0–30 | Seconds after the last effort before refilling. |
| `recovery` | string | `"full"` | `full`, `partial` | Exhausted until the gauge is full again, or until 30 %. |
| `slipWetness` | number | `0.35` | 0–1 | Wetness (rain, wet state) above which climbing walls slip. |
| `slipInterval` | number | `2.5` | 0.2–30 |  |
| `slipDistance` | number | `0.9` | 0–10 |  |

## Services, events, variables

- Service `movement.traversal`: mode(), wall(), glide(), release(), waterAt(pos). Rust KitHost also provides start(mode, instance, controls, priority?), steer(controls), velocity(), interrupt(owner, velocity, priority?), anchors() (1.4.0: the grapple anchors of the active scene).
- Service `movement.stamina`: value(), max(), exhausted(), spend(amount, partial), restore(amount), setMax(max, refill).
- Events emitted:
  - `traversal.mode` (`entity`, `from`, `to`) — walk, climb, climb_jump, mantle, leap, swim, glide or slide.
  - `traversal.jumped` (`entity`, `kind`)
  - `traversal.mantled` (`entity`, `at`) — Pulled up over a ledge.
  - `traversal.slipped` (`entity`, `distance`) — Slid down a wet wall.
  - `traversal.exhausted` (`entity`, `mode`) — Let go of a wall or closed the glider out of stamina.
  - `traversal.drowned` (`entity`, `at`)
  - `stamina.exhausted` (`entity`)
  - `stamina.recovered` (`entity`)
- Variables:
  - `stamina.value` (number) — Stamina
  - `stamina.max` (number) — Stamina max
  - `stamina.exhausted` (boolean) — Exhausted
  - `traversal.mode` (string) — Traversal
- Input actions: `glide`, `drop`

## Hooks and modding

- Hooks (a game or a mod can intercept them):
  - `traversal.climb` (cancellable) — The player is about to grab a climbable surface: pushing into it on foot, in the air or while sliding, steering the glider into it, or reaching a bank from the water (from = the mode it leaves).
  - `traversal.jump` (fields a tap may change: `cost`, `speed`; cancellable) — The climber pressed jump on a wall: a leap up the wall (kind climb; speed = meters per second up the wall during the leap, climbJumpDistance over its 0.35 s) or a jump off the wall when pulling back…
  - `traversal.mantle` (cancellable) — The climber reached the top of a wall and is about to pull up onto the ledge at the point at (surface: the entity that owns the ledge collider, empty for the terrain and for anonymous colliders).
  - `traversal.glide` (cancellable) — The player is about to open the glider (glide or jump pressed in the air, or movement.traversal.glide()), after the kit's own checks: the move is on, stamina is left, the ground and the water are far…
  - `traversal.drown` (fields a tap may change: `damage`; cancellable) — The swimmer ran out of stamina in deep water with drowning on: it is about to take damage (drownDamage, through combat.damage) and to be put back on the last safe ground with a full gauge.
- Moddable settings: `climb`, `climbSpeed`, `climbMinSlope`, `climbCost`, `climbJump`, `climbJumpCost`, `climbJumpDistance`, `wallJumpSpeed`, `swim`, `swimDepth`, `swimSpeed`, `swimFastSpeed`, `swimCost`, `swimFastCost`, `drowning`, `drownDamage`, `glide`, `glideWithJump`, `glideSpeed`, `glideSink`, `glideCost`, `glideMinHeight`, `windDrift`, `slide`, `slideMinSlope`, `slideMaxSpeed`, `staminaMax`, `regen`, `regenDelay`, `recovery`, `slipWetness`, `slipInterval`, `slipDistance`
- Components: `traversal`, `climbable`, `grind_rail`, `grapple_anchor`

## Engines

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

## Versions

Kit version 1.5.0.