> ## Documentation Index
> Fetch the complete documentation index at: https://docs.czautoz.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Flight Model

> Physics-based flight simulation — unique handling per helicopter, ground effect, ETL, and autorotation.

Every helicopter in CZ Autoz is built on DayZ 1.29's **CarScript** base — the correct script-driven aircraft foundation. No two aircraft fly the same way — a nimble MD500 and a heavy AW101 Merlin require very different technique, each tuned around its own mass, drag, and control parameters.

## How It Works

All helicopter motion is computed each physics tick from your inputs and applied as a **velocity-kinematic drive** (`SetVelocity` + `dBodySetAngularVelocity`), which restores the responsive 1.28 flight feel on the 1.29 engine. Pilot inputs are read locally and replicated through DayZ's **native client-side prediction** pipeline for low-latency control. Passengers, co-pilots and bystanders receive movement through native CarScript interpolation between network updates, so everyone sees and hears the helicopter whether or not a pilot is seated. Handling and motion through the world are smooth and fully kinematic; on-screen visual body-frame smoothing on 1.29 is still being refined.

| Force               | Control                           | Parameter                     |
| ------------------- | --------------------------------- | ----------------------------- |
| Lift                | Main rotor thrust                 | `flight.liftMultiplier`       |
| Pitch               | W / S keys                        | `control.pitchStrength`       |
| Roll                | A / D keys                        | `control.bankStrength`        |
| Yaw                 | Q / E keys                        | `control.yawStrength`         |
| Forward drag        | Air resistance                    | `flight.dragForward`          |
| Weathervane         | Auto nose alignment               | `control.weathervaneStrength` |
| Bank-to-turn        | Roll-coupled turn rate            | `control.b2tStrength`         |
| Bank-to-turn ramp   | How quickly bank-to-turn eases in | `control.b2tRampRate`         |
| Tilt lift retention | Lift kept while tilted            | `control.tiltLiftComp`        |

<Note>
  Tuning units are natural: **altitude values are entered in feet** and **maximum airspeed in knots**. Mass is read directly from each model's physics body (set via `mass` in `config.cpp` per variant) rather than from a config key.
</Note>

## Control Response (Tau Smoothing)

Each control axis uses a time-constant (Tau) smoothing model under `control.response` — separate constants govern how quickly the axis ramps up to an input (accel) and how quickly it settles back when the input is released (decay). Lower values feel sharper and more immediate; higher values feel heavier and more damped.

| Setting                                            | What it does                      |
| -------------------------------------------------- | --------------------------------- |
| `control.response.rollAccelTau` / `rollDecayTau`   | Roll (bank) ramp-up / settle time |
| `control.response.pitchAccelTau` / `pitchDecayTau` | Pitch ramp-up / settle time       |
| `control.response.yawAccelTau` / `yawDecayTau`     | Yaw ramp-up / settle time         |

This replaces the old per-axis acceleration/decay multipliers.

## Ground Effect

When flying close to the ground, the helicopter receives additional lift:

* Configured via `aerodynamics.groundEffectBonus` (default `0.12` = +12% lift)
* `aerodynamics.groundEffectAlt` sets the altitude (feet) below which the bonus applies
* Fades linearly as altitude increases
* Makes low hovering feel slightly more stable

## Effective Translational Lift (ETL)

Forward flight generates extra lift:

* Configured via `aerodynamics.etlBonus` (default `0.10` = +10% at cruise speed)
* `aerodynamics.etlSpeed` sets the speed at which the full bonus applies
* A helicopter will fly more efficiently in forward flight than in a stationary hover

## Tilt & Inverted Flight

Lift acts along the rotor's axis, so the more the helicopter tilts, the less of that thrust holds you up. The flight model compensates for normal banked and nose-down flight (tunable per helicopter via `control.tiltLiftComp`), but once you tilt **past vertical** the rotor can no longer hold you — you lose lift and **fall under the helicopter's own weight**, just like real physics. It is fully recoverable: roll or pitch back toward upright and lift returns as the rotor comes back over you.

* There is **no artificial tilt limit** — loops, rolls and upside-down passes are all possible
* `control.tiltLiftComp` (per helicopter) caps how much lift is retained while tilted — higher holds a steep attitude longer, lower drops you sooner
* Past roughly 90° of tilt, lift is gone regardless of the setting and gravity takes over until you right the aircraft

<Note>
  This is realistic, physics-driven behaviour added in **v0.2.2** — the fall is the aircraft's actual weight, and you steer it with tilt the whole way down.
</Note>

## Autorotation

If the engine stops (fuel out, engine destroyed, or manually shut down), the rotor continues spinning through inertia:

* The helicopter enters a controlled descent rather than an immediate freefall
* **Tilting the cyclic during autorotation now translates the helicopter** — you can glide forward and steer the descent rather than only rotating in place
* `autorotation.gravityFactor` controls how much gravity is cancelled during the glide (default `0.60`)
* `autorotation.descentCap` sets the maximum descent rate in knots (default `20`)
* `autorotation.flareStrength` controls how much vertical lift a collective flare recovers (default `6.0`)
* `autorotation.coastMinutes` sets how long the rotor keeps turning visually and audibly after a mid-air engine cut (default `4.0`) — the rotor coasts down gradually instead of snapping to a stop, and engine and rotor audio fade together over that time
* A skilled pilot can perform a survivable landing using autorotation technique

**Descent rate scales with helicopter mass.** Heavier helicopters have higher rotor disc loading, so their rotors provide proportionally less lift during autorotation — they descend significantly faster than light scouts. The gravity factor and descent cap set the baseline, but the actual descent rate at any given rotor spool is heavier for larger aircraft. This reflects real-world rotor disc loading behaviour.

The autorotation tuning is the **same uniform default across all six helicopters**:

| Setting                      | Default (all helicopters) |
| ---------------------------- | ------------------------- |
| `autorotation.gravityFactor` | 0.60                      |
| `autorotation.descentCap`    | 20 kts                    |

<Note>
  The descent cap is the configured maximum. In practice, a heavier helicopter reaches that cap much faster than a lighter one at the same rotor spool level — a Merlin drops to the cap noticeably sooner than an MD500 even though both share the same baseline values. Plan accordingly: heavier helicopters require earlier and more aggressive flare inputs to arrest descent before landing. Both values are editable per variant in each helicopter's JSON config.
</Note>

## Service Ceiling

Each helicopter has a configurable altitude ceiling above which lift drops to zero:

| Setting              | What it does                                                                      | Default                                                                     |
| -------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `altitude.ceiling`   | Altitude in feet where lift reaches zero — the helicopter cannot climb above this | Per-helicopter (matches the service ceiling listed on each helicopter page) |
| `altitude.liftStart` | Altitude in feet where lift begins tapering off                                   | Slightly below `altitude.ceiling`                                           |

The lift reduction is gradual — performance starts degrading before the ceiling is hit, not suddenly at it.

***

## Never-Exceed Speed (VNE)

Each helicopter has a maximum airspeed — set per variant via `flight.maxAirspeed` (in knots) and shown on each helicopter's page. Flying above this threshold causes the flight model to apply increasingly heavy drag, pushing the nose down and arresting further speed gain. The previous fixed hard cap has been removed — top speed is now tuned per variant — and the behaviour at the envelope boundary can be tuned separately:

| Setting                          | What it does                                                                                       | Default |
| -------------------------------- | -------------------------------------------------------------------------------------------------- | ------- |
| `aerodynamics.envelopeThreshold` | Fraction of max airspeed at which drag penalty begins (`0.80` = drag kicks in at 80% of top speed) | `0.80`  |
| `aerodynamics.envelopeDragScale` | Drag multiplier applied above the threshold — higher = harder speed cap, lower = softer            | `6.5`   |

<Note>
  The VNE system is intentional — it prevents helicopters from being flown beyond their realistic performance envelope. The top speed is set per helicopter via `flight.maxAirspeed` (in knots). You can soften or harden the approach to that limit using `aerodynamics.envelopeThreshold` and `aerodynamics.envelopeDragScale`.
</Note>

See [Per-Helicopter Settings](/server-config/per-helicopter-settings) for default values and the full list of tunable flight parameters.

***

## Ground Flip Recovery

If a helicopter ends up inverted on the ground (bank angle ≥ 90°), pressing `X` will flip it upright.

* Disabled by default — enable with `features.groundFlipRecovery` set to `1` in `mod_config.json`
* Only activates when grounded and inverted — not in flight

## Pilot Exits In Flight

* If the **control-holding pilot voluntarily exits** while airborne, Autohover engages automatically to hold position
* If the **pilot is killed in their seat**, the helicopter continues on its last heading with no Autohover snap — it will fly freely until it crashes or someone takes control