# controller

> Talos 0.7 · Since 0.6; changed in 0.7

Use it in a scene entity's `components` list as `{ "type": "controller", … }`. The contract writes the fields flat and refuses unknown keys.

## Fields

| Field | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|
| `kind` | `ControllerKind` | yes |  | `player` |  |
| `speed` | `number` | yes |  |  |  |
| `jump` | `number` | yes |  |  |  |
| `crouch` | `boolean` | no |  |  |  |
| `input` | `ControllerInputMode` | no |  | `auto`, `script` | Who drives the controller. `auto` (the default): the engine feeds the player's move, jump, crouch and look actions into it every tick, from the devices and POST /input, before behaviours run. `script`: the engine writes nothing to it, and a behaviour owns it through ctx.controller. |
| `inputBasis` | `ControllerInputBasis` | no |  | `world`, `controller`, `camera` | For `auto` input only: the frame the move stick is read in. `camera` (the default): the rendered view's heading, so forward is away from the camera and right is screen-right; with no camera, world -Z. `world`: forward is world -Z. `controller`: the controller's heading, which look turns. |
| `gravity` | `number` | no |  |  | Downward acceleration in m/s², 0 or more. Default: the length of the scene's meta.gravity. ctx.controller.gravityScale multiplies it. |
| `maxFallSpeed` | `number` | no | `55` |  | Terminal velocity: the fastest the character falls, in m/s, more than 0. Default 55. |
| `accel` | `number` | no | `50` |  | Ground acceleration, m/s², above 0. Default 50. |
| `decel` | `number` | no |  |  | Ground braking, m/s², above 0. Default: `accel`. |
| `turnRate` | `number` | no | `720` |  | Root-motion turn rate, deg/s, above 0. Default 720. |
| `step` | `number` | no | `0` |  | Tallest ledge the character walks up without jumping, in metres: more than 0 and under 1.8, the character's standing height. Default 0.3. The navmesh the playtester, the critic and POST /path route on is fitted to the same number. |

## Rules that can refuse it

- `animator-transition-unheard`
- `character-unanimated`
- `collider-detail-ignored`
- `controller-invalid`
- `input-read-without-routing`
- `input-reader-not-player`
- `null-handle`
- `play/no-player`
- `play/nothing-to-drive`
- `player-spawn`
- `steering-gameplay`
- `terrain/entity-floating`
- `terrain/spawn-slope`

## Example

From the contract's tested fixture `fixtures/contract/full20/scene.json#player`.

```json
{
  "type": "controller",
  "kind": "player",
  "speed": 3.2,
  "jump": 4.5,
  "crouch": true
}
```