Rail traversal

Adds movement along rails: attaching, speed and slope acceleration, braking, looping, switching to a nearby rail and jumping off, from one shared Rust core.

Source: module-kits:kits/movement_grind/usage/en.mdView Markdown source

Also read offline — CLI: grip-forge docs movement-grindMCP tool: gripforge_docs { "topic": "movement-grind" }

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):

gripforge_gamekit_install   { project_id: "gkp_…", id: "movement.grind" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "movement.grind",
                              config: { "rails": [], "maxSpeed": 30 } }

First example #

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.

#[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.