# Platformer character (character.platformer)

## What it is for

Camera-relative third-person platforming: accelerated movement, a jump whose height depends on how long the key is held, coyote
time, jump buffering, a heavier fall and checkpoint respawn. It owns the entity tagged `player`, provides `character.control` and
`camera.third_person`, and keeps the records and settings of the campaign of courses. For the choice between character kits, see
the [character guide](guide:character).

## Turn it on

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "character.platformer" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "character.platformer",
                              config: { "moveSpeed": 7, "jumpImpulse": 10, "coyoteTime": 0.15 } }
```

It requires `input.actions`, `world.platforms`, `physics.character`, `physics.port` and `game.engine`, and conflicts with the other
controlled-character kits.

## First example

<!-- test: kits/game_engine/host/tests/physics_async_lot1.rs::the_platformer_stands_on_its_loop -->
Install the kit with a player spawn and a floor: the capsule settles on the ground (never through it) and every tick of the
game loop stays under 8 ms.

```json
{ "spawns": [{ "kind": "player", "at": [0, 0.1, 0] }] }
```

## Settings and defaults

All settings are numbers, bounded by the manifest and moddable.

| Setting | Default | Meaning |
|---|---|---|
| `moveSpeed` / `acceleration` | 6.8 / 42 | top ground speed (m/s) and ground acceleration (m/s²) |
| `jumpImpulse` / `gravity` | 9.5 / 23 | take-off speed and gravity while rising |
| `coyoteTime` / `jumpBuffer` | 0.12 / 0.14 | seconds a jump is still allowed after an edge, and a press is remembered before landing |
| `airControl` | 0.68 | fraction of the acceleration available in the air |
| `jumpCut` / `jumpCutSpeed` | 0.48 / 2 | upward speed kept when the key is released early, above this speed |
| `fallGravity` | 1.25 | gravity multiplier while falling |
| `turnTime` / `turnSpeed` | 0.075 / 0.15 | heading time constant, and the speed under which the heading holds |
| `ceilingRatio` / `landingSnap` | 0.2 / 0.08 | ceiling detection; landing distance of the headless port, metres |
| `radius` / `height` | 0.35 / 1.8 | capsule size, metres |
| `landTime` / `runSpeed` | 0.1 / 0.2 | seconds of the landing clip; speed above which the run clip plays |
| `cameraDistance` / `cameraHeight` | 9 / 5 | chase camera, metres |

## Services, events, variables

- `character.platformer` (service): `grounded()`, `velocity()`, `launch(vy)` (a spring), `push(dx, dz)` (a conveyor), `teleport`,
  `campaign()`, `records()`, `settings()`, `setSettings({ muted, quality })`, `restart()`, `reopenLabel(lang)`.
- `character.control` and `camera.third_person` (services): see the [character guide](guide:character).
- Events: `platformer.jump`, `platformer.land` (payload `id`); it listens to `course.finished`.
- Variables: `player.speed`, `player.grounded`, `course.muted`, `course.cloudQuality`, `course.saved`.

## Hooks and modding

Hooks `character.jump` (mutable `speed`, 0 to 30; cancelling consumes the press) and `character.respawn` (mutable `x`, `y`, `z`; asked at
a scene entry or on the scene's player instance, not on a load, while driving or for a fall teleport), both cancellable. Every
setting above is moddable.

## Limits

Third-person only: no free look or aim camera. Needs `world.platforms` (not `world.ground`). The Rust rules run on the web and in the
native player; Godot, Unity and Unreal receive the kit as files and do not run its hooks yet (the jump and the placement behave
as without any tap).

## Versions

Kit 1.7.0 (campaign records and settings kept in the local save store); service `character.platformer` 1.1.0.