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

```text
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

<!-- test: kits/interaction_telekinesis/tests/interaction_telekinesis.rs::grabbing_takes_energy_only_once_the_engine_confirms -->
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.

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