# vehicle

> Talos 0.6 · Since 0.6

A drivable vehicle — a car, van or kart — with the engine's own vehicle physics: raycast wheels with suspension and tyre grip, a drivetrain, brakes and steering, all as data.

With `input` "auto" (the default) it drives from the input actions `throttle`, `brake`, `steer` (+1 right) and `handbrake` with no script. Its wheels are `wheel` components on entities below it, whose meshes steer, spin and follow the suspension. docs/VEHICLES.md. The entity needs a `rigidbody` of kind `dynamic` and a non-trigger `collider` of its own — the vehicle IS that body, and the collider is the bodywork the wheels hang off and the thing the geometric rules measure against. Without them `vehicle-needs-dynamic-body` fires. Name a `preset` and override what differs, or write every part out. A component with neither is `vehicle-invalid`.

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

## Fields

| Field | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|
| `preset` | `string` | no |  |  | A class preset to build on, one of "sedan", "suv", "pickup" or "van", shipped as data in `crates/vehicles/presets/`. Every other field then overrides it: objects merge field by field, and `gears` and `torqueCurve` are replaced whole. The preset's wheels are defaults by corner for the `wheel` entities under the body, which the scene always supplies. A plain string rather than an enum, because resolution is a rule and not a shape here for the same reason it is for an entity or asset id: a name nothing answers to is reported as `vehicle-invalid` with a list of what does, which is a better thing for an agent to read than a shape error. Without a preset the component has to carry every part itself. |
| `model` | `VehicleModel` | no |  | `arcade`, `simulation` | Which solver drives this vehicle. Absent means "arcade". |
| `chassis` | `VehicleChassis` | no |  |  |  |
| `wheels` | `string[]` | no |  |  | The wheels this vehicle drives: ids of entities with a `wheel` component below this body, in the order the vehicle knows them by. Absent: every wheel below this body, in scene order. A preset's defaults reach each wheel by corner — ahead of the body's origin (z < 0) is front, x < 0 is left — and the wheel's own fields always win. |
| `drivetrain` | `VehicleDrivetrain` | no |  |  |  |
| `brakes` | `VehicleBrakes` | no |  |  |  |
| `tyres` | `VehicleTyres` | no |  |  |  |
| `aero` | `VehicleAero` | no |  |  | Absent means no aerodynamics at all, which is what an arcade vehicle usually wants. |
| `assists` | `VehicleAssists` | no |  |  | Absent means every assist off. |
| `steering` | `VehicleSteering` | no |  |  | Absent means the documented steering defaults, not an unsteerable vehicle. `maxAngle` is worth setting per class: it is what decides the turning circle. |
| `drift` | `VehicleDrift` | no |  |  | Absent means no drift: the handbrake just brakes. |
| `input` | `ControllerInputMode` | no |  | `auto`, `script` | Who drives it. `auto` (the default): the engine reads the input actions `throttle`, `brake`, `steer` and `handbrake` every tick — keyboard, pad and `POST /input` alike — so the vehicle drives with no script. A button reads 0 or 1 and an axis1 its value; `steer` +1 turns right, and `brake` at a standstill reverses. An action the scene does not declare reads 0. `script`: the engine reads nothing and a behaviour drives it with `ctx.vehicle.drive`. |

## Rules that can refuse it

- `input-read-without-routing`
- `input-reader-not-player`
- `play/no-player`
- `vehicle-capability-absent`
- `vehicle-invalid`
- `vehicle.not-finite`
- `wheel-invalid`