# Platform traps (hazard.traps)

## What it is for

Adds timed platform traps as data: spikes, flame jets, crushers, falling platforms, bouncers, conveyors and rotating bars, where a hit sends the player back to the checkpoint.

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: "hazard.traps" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "hazard.traps",
                              config: { "levelVar": "course.id", "grace": 1 } }
```

## First example

The kit has no dedicated test yet; this installs it and sets two of its settings to their defaults.

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "hazard.traps" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "hazard.traps",
                              config: { "levelVar": "course.id", "grace": 1 } }
```

## Settings and defaults

Descriptions come from the kit manifest and stay in English.

| Setting | Type | Default | Range or values | Meaning |
|---|---|---|---|---|
| `levelVar` | string | `"course.id"` |  | The state variable naming the current level; traps of another level are not in the world. |
| `grace` | number | `1` | 0–10 | Seconds after a hit during which no trap hits again. |
| `playerHeight` | number | `1.8` | 0.2–5 | Height of the player tested against the traps, metres. |
| `playerRadius` | number | `0.35` | 0–3 | Radius of the player tested against bars, metres. |
| `standTolerance` | number | `0.15` | 0.01–2 | Feet this close to the top of a solid trap stand on it, metres. |
| `dropGravity` | number | `20` | 0–100 | How fast a fallen platform drops out of sight, m/s². |

## Services, events, variables

- Service `hazard.traps`: traps(), state(id), gap(id), angle(id), grace().
- Events emitted:
  - `hazard.hit` (`trap`, `type`) — A trap hit the player (then world.platforms kill, when installed).
  - `hazard.bounce` (`trap`, `speed`)
  - `hazard.triggered` (`trap`, `type`) — A falling platform starts shaking.
  - `hazard.fell` (`trap`)
  - `hazard.restored` (`trap`)

## Hooks and modding

- Hooks (a game or a mod can intercept them):
  - `trap.hit` (fields a tap may change: `kill`; cancellable) — A trap is about to hit the player (spikes out, a lit flame, a closing crusher, a sweeping bar), the grace time of the last hit being over.
  - `trap.bounce` (fields a tap may change: `speed`; cancellable) — A bouncer is about to throw the player up at speed m/s (the strength of the trap).
  - `trap.trigger` (cancellable) — A falling platform is about to start shaking under the player (it then falls after its delay and comes back after its respawn).
- Moddable settings: `grace`, `playerHeight`, `playerRadius`, `standTolerance`, `dropGravity`
- Moddable collections: `traps`

## Engines

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

## Versions

Kit version 1.1.1.