Telekinesis

Lets the player grab objects at a distance, hold them with bounded spring-and-damper forces, throw them and pay an energy cost, while the engine keeps the bodies and collisions.

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

Also read offline — CLI: grip-forge docs interaction-telekinesisMCP tool: gripforge_docs { "topic": "interaction-telekinesis" }

Telekinesis (interaction.telekinesis) #

What it is for #

Lets the player grab objects at a distance, hold them with bounded spring-and-damper forces, throw them and pay an energy cost, while the engine keeps the bodies and collisions.

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: "interaction.telekinesis" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "interaction.telekinesis",
                              config: { "maxMass": 50, "grabRange": 8 } }

First example #

This is the body of the passing test grabbing_takes_energy_only_once_the_engine_confirms; the helper functions it calls are defined at the top of the same test file.

#[test]
fn grabbing_takes_energy_only_once_the_engine_confirms() {
    let mut s = tk();
    let p = req(&mut s, KIT, grab_cmd("rock", 4.0, json!([0, 0, 3])));
    assert_eq!(
        p["action"]["effect"],
        json!({"kind": "grab", "body": "rock", "mass": 4.0})
    );
    assert_eq!(energy(&mut s), 20.0);
    resolve(&mut s, KIT, &p, true);
    assert_eq!(energy(&mut s), 15.0);
    assert_eq!(held(&mut s), json!({"id": "rock", "mass": 4.0}));
}

Settings and defaults #

Descriptions come from the kit manifest and stay in English.

Setting	Type	Default	Range or values	Meaning
`maxMass`	number	`50`	0.001–100000	Maximum movable object mass in kilograms (kg).
`grabRange`	number	`8`	0.01–1000	Maximum initial actor-to-object distance in metres.
`holdRange`	number	`6`	0.01–1000	Maximum desired target distance from the actor in metres.
`breakRange`	number	`12`	0.01–2000	Distance in metres that releases a held body; at least grabRange and holdRange.
`stiffness`	number	`25`	0–1000	Position-error gain in inverse seconds squared for the hold acceleration.
`damping`	number	`10`	0–1000	Velocity damping gain in inverse seconds for the hold acceleration.
`maxForce`	number	`1500`	0.01–1000000000	Maximum total holding force in newtons (N), including gravity compensation.
`throwSpeed`	number	`20`	0–1000	Desired throw speed relative to the actor in metres per second.
`maxImpulse`	number	`500`	0.01–1000000000	Maximum throwing impulse in newton seconds; may limit achieved speed.
`maxEnergy`	number	`100`	0.01–1000000	Maximum stored telekinesis energy units.
`grabCost`	number	`5`	0–1000000	Energy units charged only when grabbing is confirmed.
`throwCost`	number	`10`	0–1000000	Energy units charged only when throwing is confirmed.
`drainPerKg`	number	`0.1`	0–1000	Holding energy units spent per kilogram per second after confirmed force application.
`energyRecovery`	number	`5`	0–1000000	Energy units recovered per idle simulation second.
`releaseCooldown`	number	`0.2`	0–60	Cooldown in seconds after releasing or throwing a body.

Services, events, variables #

Service interaction.telekinesis: create(id,config), request(id,command), remove(id), ids(). Commands: grab, release, throw, step, resolve, preview, status, config, save, load. Engine effects require resolve(token,success).
Events emitted:
- interaction.telekinesis.created (instance, preset) — An instance was created.
- interaction.telekinesis.removed (instance) — An instance was removed.
- interaction.telekinesis.changed (instance, op, result) — A decided command applied to an instance (never a read or a fixed step).
- interaction.telekinesis.refused (instance, op, by, reason) — A tap of interaction.telekinesis.request cancelled a command.
Verbs of the scripting layer:
- interaction_telekinesis_request (action) — Send a command to an instance of the kit (through the request hook).
- interaction_telekinesis_exists (condition) — The instance exists (default: default).

Hooks and modding #

Hooks (a game or a mod can intercept them):
- interaction.telekinesis.create (fields a tap may change: config; cancellable) — An instance is about to be created (create(id, config)).
- interaction.telekinesis.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: maxMass, grabRange, holdRange, breakRange, stiffness, damping, maxForce, throwSpeed, maxImpulse, maxEnergy, grabCost, throwCost, drainPerKg, energyRecovery, releaseCooldown
Moddable collections: interaction_telekinesis_presets

Engines #

Declared targets: rust, web. gripforge kit api interaction.telekinesis lists the exact settings and services of your version.

Versions #

Kit version 1.1.0.