# Rail traversal (movement.grind)

## What it is for

Adds movement along rails: attaching, speed and slope acceleration, braking, looping, switching to a nearby rail and jumping off, 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.grind" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "movement.grind",
                              config: { "rails": [], "maxSpeed": 30 } }
```

## First example

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

```rust
#[test]
fn attach_snaps_to_the_nearest_point_and_keeps_the_speed() {
    let mut s = grind();
    let p = attach(&mut s, "line", json!([3, 1, 0]), json!([4, 0, 0]));
    assert_eq!(p["active"], true);
    assert!(near(&p["distance"], 3.0));
    assert_eq!(p["position"], json!([3.0, 0.0, 0.0]));
    assert_eq!(p["velocity"], json!([4.0, 0.0, 0.0]));
}
```

## Settings and defaults

Descriptions come from the kit manifest and stay in English.

| Setting | Type | Default | Range or values | Meaning |
|---|---|---|---|---|
| `rails` | array | `[]` |  | Immutable world-space rails: at most 128 rails, 2048 supplied points each, 8192 stored points total; minimum segment 0.01 m. |
| `maxSpeed` | number | `30` | 0.1–200 | Maximum movement speed along a rail, in metres per second. |
| `acceleration` | number | `12` | 0–200 | Acceleration from full throttle. |
| `braking` | number | `25` | 0.1–500 | Deceleration while brake is held. |
| `attachRadius` | number | `2` | 0.01–100 | Maximum snap distance for attachment. |
| `switchDistance` | number | `4` | 0.01–100 | Maximum gap to the next rail; engine must validate transition clearance. |
| `gravityScale` | number | `1` | 0–10 | Multiplier of supplied gravity projected along the rail tangent. |

## Services, events, variables

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

## Hooks and modding

- Hooks (a game or a mod can intercept them):
  - `movement.grind.create` (fields a tap may change: `config`; cancellable) — An instance is about to be created (create(id, config)).
  - `movement.grind.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: `rails`, `maxSpeed`, `acceleration`, `braking`, `attachRadius`, `switchDistance`, `gravityScale`
- Moddable collections: `movement_grind_presets`

## Engines

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

## Versions

Kit version 1.1.0.