0.2.1 – Refactoring JSBSim VTOL Autolevel

By /

This update is focused on the VTOL control logic in JSBSim, along with a few fixes to ground handling.

  • Taxi Mode – Taxi Mode can now be entered and exited manually with a dedicated button.
  • Taxi Steering – Fixed a configuration error where the steering command was being applied to all landing-gear wheels. It is now applied strictly to the nose wheels.

JSBSim VTOL AutoLevel

The VTOL AutoLevel configuration has been simplified and separated into independent roll, pitch, and yaw control loops.
Each axis has its own enable property:

  • fcs/AutoLevelRoll
  • fcs/AutoLevelPitch
  • fcs/AutoLevelYaw

Setting the property to 1.0 enables the corresponding AutoLevel loop, while 0.0 disables its contribution.

Roll Stabilization Loops:

The roll controller uses two loops.

The outer loop converts roll-angle error into a target roll rate.
fcs/errRoll_rad is calculated from the commanded roll angle and the current aircraft roll angle:

    <summer name="roll_angle_error_summer">
      <input>fcs/refRoll_rad</input>
      <input>-attitude/phi-rad</input>
      <output>fcs/errRoll_rad</output>
    </summer>

The current gain is:

    <pid name="roll_angle_to_rate_pid">
      <input>fcs/errRoll_rad</input>
      <kp>0.8</kp>
      <output>fcs/refRoll_rps_from_angle_error</output>
    </pid>

kp 0.8 controls how aggressively the controller converts roll-angle error into a target roll rate.

The inner loop controls the actual roll rate against the target roll rate.
fcs/errRoll_rps is calculated from the target roll rate and the current aircraft roll rate:

    <summer name="roll_error_summer">
      <input>fcs/refRoll_rps_from_angle_error</input>
      <input>-velocities/p-rad_sec</input>
      <output>fcs/errRoll_rps</output>
    </summer>

The resulting error is passed to roll_rate_pid:

    <pid name="roll_rate_pid">
      <input>fcs/errRoll_rps</input>
      <kp>0.3</kp>
      <ki>0.0</ki>
      <kd>0.0</kd>
      <output>fcs/cmdRoll_rps</output>
    </pid>

To tune the roll AutoLevel response, the two relevant gains are therefore:

  • roll_angle_to_rate_pid / Kp = 0.8
  • roll_rate_pid / Kp = 0.3

Differential Thrust Roll

A dedicated Differential Thrust Roll action has been implemented to roll the aircraft in VTOL without tilting engine nacelles.
For the current aircraft configuration, the roll moment is generated through thrust asymmetry across the front engine pair.

How It Works in FlightControl.xml

The functions ManualRoll_FR and ManualRoll_FL calculate differential offsets proportional to base throttle, stick deflection, and manual gain:

inputThrottle_nd × inputRoll_nd × manualRoll_gain× (±1.0)

  • Front Right: negative offset → fcs/manualRoll_FR_nd
    Front Left: positive offset → fcs/manualRoll_FL_nd

These offsets are routed to Mixer_Engine_FR and Mixer_Engine_FL, increasing thrust on one side and decreasing it on the other to generate a roll moment from the thrust delta.

AutoLevel Dynamic Override

  • Stick Deflected (Input ≠ 0): Applying differential roll input temporarily overrides roll AutoLevel (fcs/AutoLevelRoll = 0.0), giving the pilot direct differential thrust control.
  • Stick Centered (Input = 0): Releasing the stick to neutral restores fcs/AutoLevelRoll to 1.0, immediately re-engaging wings-level stabilization (provided master VTOL AutoLevel is active).
  • AutoLevel Disabled: If master VTOL AutoLevel is toggled off, roll is controlled exclusively via this differential thrust path.

Modder & Tuning Guide (FlightControl.xml)

If you are tuning roll behavior or configuring a custom airframe, modify the following parameters:

Property:

  <!-- Manual roll authority gains (sensitivity scaling).                      -->
  <property value="0.2">fcs/manualRoll_gain</property>

Usage: Scales the maximum differential throttle delta. Increase this value for snappier, more aggressive roll response; decrease it for heavier or more sluggish aircraft.

Angle Envelope Limits:

Location: Inside fcs_function name="ManualRoll_FR" and fcs_function name="ManualRoll_FL" 

            <tableData>
              -180.0  1.0
                 0.0  1.0
                25.0  1.0
                30.0  0.0
               180.0  0.0
            </tableData>

The second column is a multiplier applied to the manual differential-thrust command:

  • 0°–25° → 1.0, full contribution
  • 25°–30° → interpolates from 1.0 to 0.0
  • 30° and above → 0.0

Controls & Input Mapping

  • Action: Differential Thrust Roll
  • Default Gamepad Binding: Modifier_RB + Left Stick
Scroll to Top