# multirotor

> Talos next · Since next

A drone: a dynamic body (`multirotor-without-body`) held up and steered by rotors, with a flight controller.

Angle mode holds level, heading and altitude and drifts with the wind; velocity mode also holds its point; rate mode is acro. Numbers outside their ranges are clamped (`multirotor-out-of-range`). docs/VEHICLES.md.

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

## Fields

| Field | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|
| `preset` | `MultirotorPreset` | no | `camera-quad` | `camera-quad`, `utility-quad`, `heavy-hex`, `racer` | The starting numbers; fields below override them. Default `camera-quad`. |
| `rotors` | `MultirotorRotor[]` | no |  |  | The rotor layout, 4..8 rotors (`multirotor-invalid`). Default: the preset's ring. |
| `thrustToWeight` | `number` | no |  |  | Full thrust of all rotors over the body's weight, 1.05..20. |
| `motorTime` | `number` | no |  |  | Motor time constant, seconds, 0..1. |
| `dragArea` | `number` | no |  |  | Drag coefficient times frontal area, m², 0..20, against the air (wind included). |
| `maxTilt` | `number` | no |  |  | Most tilt from level in angle and velocity modes, radians, 0.05..1.4. |
| `maxRate` | `number` | no |  |  | Most roll and pitch rate, rad/s, 0.1..40. |
| `maxYawRate` | `number` | no |  |  | Most yaw rate, rad/s, 0.1..20. |
| `maxSpeed` | `number` | no |  |  | Most ground speed in velocity mode, m/s, 0..100. |
| `maxClimb` | `number` | no |  |  | Most climb rate, m/s, 0..50. |
| `maxDescent` | `number` | no |  |  | Most descent rate, m/s, 0..50. |
| `endurance` | `number` | no |  |  | Hover time on a full battery, seconds, 0..86400; 0 never runs down. |
| `mode` | `MultirotorMode` | no |  | `rate`, `angle`, `velocity` | Starting flight mode. Default `angle` (`rate` for `racer`). |
| `input` | `ControllerInputMode` | no |  | `auto`, `script` | `auto` (default): flown from the input actions `lift`, `yaw` (+1 left), `pitch` (+1 forward) and `roll` (+1 right), with `move` for pitch and roll when the map binds none of them. `script`: only a behaviour flies it. |
| `propellers` | `string[]` | no |  |  | Entities spun about their own +Y at each rotor's speed, in rotor order (its prop meshes). Visual only. |

## Rules that can refuse it

- `multirotor-invalid`
- `multirotor-out-of-range`
- `multirotor-without-body`