# VehicleRecovery

> Talos 0.7 · Since 0.7

Automatic recovery: a vehicle flipped, stuck, fallen out of the world or drowned is put back where it can go on, and `vehicle-recovered` { entity, why, from, position } is raised (`from`: where it was before the move).

Absent: none of it, and the vehicle behaves exactly as without the feature (`ctx.vehicle.reset()` still works); present, a field left out takes its default.

## Fields

| Field | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|
| `flippedAfter` | `number` | no | `0` |  | Seconds upside down before it recovers, 0 or more; 0 is never. Defaults to 0.7. Upside down is its up axis below 0.35 of world up. |
| `stuckAfter` | `number` | no | `1` |  | Seconds driven and getting nowhere before it recovers, 0 or more; 0 is never. Defaults to 1.6. Driven is throttle or brake held; getting somewhere is moving more than `stuckSpeed` x `stuckAfter` / 2 metres, or turning to a new heading. |
| `stuckSpeed` | `number` | no | `2` |  | METRES PER SECOND, greater than zero: slower than this is getting nowhere. Defaults to 2. Measured over half of `stuckAfter`. |
| `fellAfter` | `number` | no | `0` |  | Seconds falling before it recovers, 0 or more; 0 is never. Defaults to 0.25. Falling is no ground within 8 m below. |
| `waterDepth` | `number` | no | `0` |  | METRES of its chassis under water for 0.2 s before it recovers, 0 or more; 0 is never. Defaults to 0.6. Only in a scene with water, and never on a vehicle with a `water` block. |
| `to` | `VehicleRecoveryTarget` | no |  | `lastGood`, `road`, `upright` | Where it goes back to: `lastGood` (the default), `road` or `upright`. `lastGood` is its newest good spot. That is the newest spot at least 0.9 s old where it was on its wheels and upright. `road` is the nearest point on a road to that spot, facing along the road (`lastGood` with no road in the scene). `upright` is where it is, back on its wheels. |
| `dropInSpeed` | `number` | no | `0` |  | The share of its speed before the trouble it is given back, forward, 0..1. Defaults to 0.5. Never more than half its top speed. |
| `protectFor` | `number` | no | `1` |  | Seconds after a recovery with no new one and its spin damped, 0 or more. Defaults to 1.2. |
| `guard` | `boolean` | no | `true` |  | The physics guard: runaway spins and launches are undone. Defaults to true. A spin over 20 rad/s is cancelled and a gain of more than 12 m/s in one tick is undone; a body that keeps doing it, or reads NaN, recovers. |

## See also

- `VehicleRecoveryTarget`