yasim-xml

Provide a detailed specification for writing YASim XML files.

YASim is one of two flight dynamics models commonly used in FlightGear, alongside JSBSim. It uses the geometry of the aircraft to generate the base flight characteristics. While this suggests a 'realistic' or out-of-the-box approach, it is a only rough approximation that will require much tweaking before you get a result that approaches realism. If you have solid flight data for your aircraft such as wind-tunnel data or you are looking to eventually generate a hyper-realistic simulation, JSBSim is probably a better approach. If you lack such data but know the geometry of the aircraft and have access to the same flight characteristics and limits as a real pilot would, then YASim can provide a solution that is more than sufficient for most simulation needs.

Coordinate system notes

All positions specified are in metres (which is weird, since all other units in the file are English). The X axis points forward, Y is left, and Z is up. Take your right hand, and hold it like a gun. Your first and second fingers are the X and Y axes, and your upwards-pointing thumb is the Z. This is slightly different from the coordinate system used by JSBSim. Sorry. The origin can be placed anywhere, so long as you are consistent. I use the nose of the aircraft.

(In the JSBSim coordinate system, X and Z are the same as in YASim, but Y points to the right instead of left.)

XML Elements

airplane

The top-level element for the file. It contains the following attributes:

• mass: The empty (no fuel) weight, in pounds. It does include the weight of the engine(s), so when you add the engine weight in its tag, it acts just like a ballast.
• version: The version attribute is used to maintain compatibility when updating yasim (e.g. bugfixes). If this attribute is not given, the original version will be used. Several bugfixes to YASim were implemented in FlightGear 3.2, some more are fixed in FlightGear 2017.2.

Available versions are:

• YASIM_VERSION_ORIGINAL explicitly use the old buggy calculations (same as no version attribute at all)
• YASIM_VERSION_32 enable bugfixes up to version 3.2
• 2017.2 enable bugfixes up to version 2017.2
• 2018.1 use this version if your aircraft makes use of new features in YASim 2018.1.
• YASIM_VERSION_CURRENT use latest version compiled into the users FlightGear. (recommended)
• mtow-lbs and mtow-kg: use one of them to specify max. takeoff weight. Does not affect the FDM, but is used by CLI tool to calculate some numbers.

approach

The approach parameters for the aircraft. The solver will generate an aircraft that matches these settings (by adjusting the parameters of the surface like drag and lift). It is extremely important to give parameters which could be really achieved by defined aircraft geometry, otherwise, it gives an unstable or not flyable result. The element can (and should) contain <control> elements indicating pilot input settings, such as flaps and throttle, for the approach.

• speed: The approach airspeed, in knots TAS.
• aoa: The approach angle of attack, in degrees
• fuel: Fraction (0-1) of fuel in the tanks. Default is 0.2.

cruise

The cruise speed and altitude for the solver to match. As above, this should contain <control> elements indicating aircraft configuration. Especially, make sure the engines are generating enough thrust at cruise!

• speed: The cruise speed, in knots TAS.
• alt: The cruise altitude, in feet MSL.
• fuel: Fraction (0-1) of fuel in the tanks. Default is 0.2.

cockpit

The location of the cockpit (pilot eyepoint).

• x,y,z: eyepoint location (see coordinates note)

fuselage

This defines a tubelike structure. It will be given an even mass and aerodynamic force distribution by the solver. You can have as many as you like, in any orientation you please.

• ax,ay,az: One end of the tube (typically the front)
• bx,by,bz: The other ("back") end.
• width: The width of the tube, in metres.
• taper: The approximate radius at the "tips" of the fuselage expressed as a fraction (0-1) of the width value.
• midpoint: The location of the widest part of the fuselage, expressed as a fraction of the distance between A and B.
• idrag: Multiplier for the "induced drag" generated by this object. Default is one. With idrag=0 the fuselage generates only drag.
• cx,cy,cz: Factors for the generated drag in the fuselages "local coordinate system" with x pointing from end to front, z perpendicular to x with y=0 in the aircraft coordinate system. E.g. for a fuselage of a height of 2 times the width you can define cy=2 and (due to the doubled front surface) cx=2.

Surfaces

wing

This defines the main wing of the aircraft. You can have only one (but see below about using vstab objects for extra lifting surfaces). The wing should have a <stall> subelement to indicate stall behavior, control surface subelements (flap0, flap1, spoiler, slat) to indicate what and where the control surfaces are, and <control> subelements to map user input properties to the control surfaces.

• x,y,z: The "base" of the wing, specified as the location of the mid-chord (not leading edge, trailing edge, or aerodynamic center) point at the root of the LEFT (!) wing.
• length: The length from the midchord point of the base of the wing to the midchord point at the tip. Note that this is not the same thing as span.
• chord: The chord of the wing at its base, along the X axis (not normal to the leading edge, as it is sometimes defined).
• incidence: The incidence angle at the wing root, in degrees. Zero is level with the fuselage (as in an aerobatic plane), positive means that the leading edge is higher than the trailing edge (as in a trainer).
• twist: The difference between the incidence angle at the wing root and the incidence angle at the wing tip. Typically, this is a negative number so that the wing tips have a lower angle of attack and stall after the wing root (washout).
• taper: The taper fraction, expressed as the tip chord divided by the root chord. A taper of one is a hershey bar wing, and zero would be a wing ending at a point. Defaults to one.
• sweep: The sweep angle of the wing, in degrees. Zero is no sweep, positive angles are swept back. Defaults to zero. [This looks to be the sweep of the mid-chord of the wing, not the sweep of the leading edge.]
• dihedral: The dihedral angle of the wing. Positive angles are upward dihedral. Defaults to zero.
• idrag: Multiplier for the "induced drag" generated by this surface. In general, low aspect wings will generate less induced drag per-AoA than high aspect (glider) wings. This value isn't constrained well by the solution process, and may require tuning to get throttle settings correct in high AoA (approach) situations.
• effectiveness: Multiplier for the "normal" drag generated by the wing. Defaults to 1. Arbitrary, dimensionless factor.
• camber: The lift produced by the wing at zero angle of attack, expressed as a fraction of the maximum lift produced at the stall AoA.
• flow: The flow regime for the wing. Valid values are "SUBSONIC" (default) and "TRANSONIC". Setting surface to transonic adds more lift above mach number 0.6 by applying a Prandl/Glauert correction term to each surface-element. The effect is a more balanced lift/drag distribution reported by the solver. Use for anything that flies faster than mach 0.6 or has supercritical airfoils.
• mcrit: The critical mach number for the wing. This point defines the begin of exponential drag rise due to mach speed. Default "0.6", only available if flow="TRANSONIC".

Wing section support:

Wing section support to define variable geometry (geometry parameters per section)

• More than one <wing>-element is allowed now.
• x, y, z, chord and incidence attribute shall be specified only for the first <wing> in the XML file. They will be overridden for subsequent <wing>-elements.
• Use append="1" for additional wing elements to skip x, y, z, chord and incidence attribute as they will be calculated from previous wing element tip chord. This workaround is currently needed due to limitations in the XML parser.

hstab

These define the horizontal stabilizer of the aircraft. Internally, it is just a wing object and therefore works the same in XML. You are allowed only one hstab object; the solver needs to know which wing's incidence to play with to get the aircraft trimmed correctly.

• hstab supports sections in the same way wing does, but it is still considered as /the/ (only) hstab used by the solver.
• incidence-min-deg and incidence-max-deg: optional attributes to limit valid result range for the solver. Use with care or you won't get a solution.

vstab

A "vertical" stabilizer. Like hstab, this is just another wing, with a few special properties. The surface is not "mirrored" as are wing and hstab objects. If you define a left wing only, you'll only get a left wing. The default dihedral, if unspecified, is 90 degrees instead of zero. But all parameters are equally settable, so there's no requirement that this object be "vertical" at all. You can use it for anything you like, such as extra wings for biplanes. Most importantly, these surfaces are not involved with the solver computation, so you can have none, or as many as you like.

mstab

A mirrored horizontal stabilizer. Exactly the same as wing, but not involved with the solver computation, so you can have none, or as many as you like.

stall

A subelement of a wing (or hstab/vstab/mstab) that specifies the stall behavior.

• aoa: The stall angle (maximum lift) in degrees. Note that this is relative to the wing, not the fuselage (since the wing may have a non-zero incidence angle).
• width: The "width" of the stall, in degrees. A high value indicates a gentle stall. Low values are vicious for a non-twisted wing, but are acceptable for a twisted one (since the whole wing will not stall at the same time).
• peak: The height of the lift peak, relative to the post-stall secondary lift peak at 45 degrees. Defaults to 1.5. This one is deep voodoo, and probably doesn't need to change much. Bug me for an explanation if you're curious.

flap0, flap1, slat, spoiler

These are subelements of wing/hstab/vstab objects, and specify the location and effectiveness of the control surfaces.

• start: The position along the wing where the control surface begins. Zero is the root, one is the tip.
• end: The position where the surface ends, as above.
• lift: The lift multiplier for a flap or slat at full extension. One is a no-op, a typical aileron might be 1.2 or so, a giant jetliner flap 2.0, and a spoiler 0.0. For spoilers, the interpretation is a little different -- they spoil only "prestall" lift. Lift due purely to "flat plate" effects isn't affected. For typical wings that stall at low AoA's essentially all lift is pre-stall and you don't have to care. Jet fighters tend not to have wing spoilers, for exactly this reason. This value is not applicable to slats, which affect stall AoA only.
• drag: The drag multiplier, as above. Typically should be higher than the lift multiplier for flaps.
• aoa: Applicable only to slats. This indicates the angle by which the stall AoA is translated by the slat extension.

Rotor and rotorgear

YASim has also possibility to simulate rotorcraft blades.

rotor

A rotor. Used for simulating helicopters. You can have one, two or even more.

If you specify a rotor, you do not need to specify a wing or hstab, the settings for approach and cruise will be ignored then. You have to specify the solver results manually. See below.

The rotor generates downwash acting on all stabs, surfaces and fuselages. For all fuselages in the rotor downwash you should specify idrag="0" to get realistic results.

• name: The name of the rotor. (some data is stored at /rotors/name/) The rpm, cone angle, yaw angle and roll angle are stored for the complete rotor. For every blade the position angle, the flap angle and the incidence angle are stored. All angles are in degree, positive values always mean "up". This is not completely tested, but seem to work at least for rotors rotating counterclockwise. A value stall gives the fraction of the rotor in stall (weighted by the fraction they have on lift and drag without stall). Use this for modifying the rotor-sound.

• x,y,z: The position of the rotor center

• nx,ny,nz: The normal of the rotor (pointing upwards, will be normalized by the computer)

• fx,fy,fz: A Vector pointing forward, if not perpendicular to the normal it will be corrected by the computer

• diameter: The diameter in meter [D]

• numblades: The number of blades

• weightperblade: The weight per blade in pounds

• relbladecenter: The relative center of gravity of the blade. Maybe not 100% correct interpreted; use 0.5 for the start and change in small steps [b/R]

• chord: The chord of the blade at its base, along the X axis (not normal to the leading edge, as it is sometimes defined). [c]

• twist: The difference between the incidence angle at the blade root and the incidence angle at the wing tip. Typically, this is a negative number so that the rotor tips have a lower angle of attack.

• taper: The taper fraction, expressed as the tip chord divided by the root chord. A taper of one is a bar blade, and zero would be a blade ending at a point. Defaults to one. [d/c]

• rel-len-where-incidence-is-measured: If the blade is twisted, you need a point where to measure the incidence angle. Zero means at the base, 1 means at the tip. Typically it should be something near 0.7

• rel-len-blade-start: Typically the blade is not mounted in the center of the rotor [a/R]

• rpm: rounds per minute.

• phi0: initial position of this rotor

• ccw: determines if the rotor rotates clockwise (="0") or counterclockwise (="1"), (if you look on the top of the normal, so the bo105 has counterclockwise rotor). "true" and "false" are not any longer supported to increase my lifespan. ;

• maxcollective: The maximum of the collective incidence in degree

• mincollective: The minimum of the collective incidence in degree

• maxcyclicele: The maximum of the cyclic incidence in degree for the elevator like function

• mincyclicele: The minimum of the cyclic incidence in degree for the elevator like function

• maxcyclicail: The maximum of the cyclic incidence in degree for the aileron like function

• mincyclicail: The minimum of the cyclic incidence in degree for the aileron like function

• airfoil-incidence-no-lift: non symmetric airfoils produces lift with no incidence. This is the incidence, where the airfoil is producing no lift. Zero for symmetrical airfoils (default)

• incidence-stall-zero-speed:

• incidence-stall-half-sonic-speed: the stall incidence is a function of the speed. I found some measured data, where this is linear over a wide range of speed. Of course the linear region ends at higher speeds than zero, but just extrapolate the linear behavior to zero.

• lift-factor-stall: In stall airfoils produce less lift. Without stall the c-lift of the profile is assumed to be sin(incidence-"airfoil-incidence-no-lift")*liftcoef; And in stall: sin(2*(incidence-"airfoil-incidence-no-lift"))*liftcoef*"lift-factor-stall"; Therefore this factor is not the quotient between lift with and without stall. Use 0.28 if you have no idea.

• drag-factor-stall: The drag of an airfoil in stall is larger than without stall. Without stall c-drag is assumed to be abs(sin(incidence-"airfoil-incidence-no-lift"))*dragcoef1+dragcoef0); With stall this is multiplied by drag-factor

• stall-change-over: For incidence < "incidence-stall" there is no stall. For incidence > ("incidence-stall" + "stall-change-over") there is stall. In the range between these incidences it is interpolated linear.

• pitch-a:

• pitch-b: collective incidence angles, If you start flightgear with --log-level=info, flightgear reports lift and needed power for these incidence angles

• forceatpitch-a:

• poweratpitch-b:

• poweratpitch-0: old tokens, not supported any longer, the result are not exactly the expected lift and power values. Will be removed in one of the next updates directly. Use "real" coefficients instead (see below) and adjust the lift with rotor-correction-factor.

The airfoil of the rotor is described as follows: The way is to define the lift and drag coefficients directly. Without stall the c-lift of the profile is assumed to be sin(incidence-"airfoil-incidence-no-lift")*liftcoef; And in stall: sin(2*(incidence-"airfoil-incidence-no-lift"))*liftcoef*"lift-factor-stall";

Without stall c-drag is assumed to be abs(sin(incidence-"airfoil-incidence-no-lift"))*dragcoef1+dragcoef0); See above, how the coefficients are defined with stall.

The parameters:

• airfoil-lift-coefficient: liftcoef
• airfoil-drag-coefficient0: dragcoef0
• airfoil-drag-coefficient1: dragcoef1

To find the right values, see file <path to fgdata>/README.yasim.rotor.xls.

With this file you can generate graphs of the airfoil coefficients and adjust the parameters to match real airfoils.

• rotor-correction-factor: If you calculate the lift of a heli rotor or even of a propeller, you get a value larger than the real measured one. (Due to vortex effects.) This is considered in the simulation, but with a old theory by Prantl, which is known to give still too large. This is corrected by this token, default: 1
• flapmin: Minimum flapping angle. (Should normally never reached)
• flapmax: Maximum flapping angle. (Should normally never reached)
• flap0: Flapping angle at no rotation, i.e. -5
• dynamic: this changes the reactions speed of the rotor to an input. normally 1 (Maybe there are rotors with a little faster reaction, then use a value a little greater than one. A value greater than one will result in a more inert system. Maybe it's useful for simulating the rotor of the Bell UH1.)
• rellenflaphinge: The relative length from the center of the rotor to the flapping hinge. Can be taken from pictures of the helicopter (i.e. 0 for Bell206, about 0.05 for most rotors) For rotors without flapping hinge (where the blade are twisted instead, i.e. Bo 105, Lynx) use a mean value, maybe 0.2. This value has an extreme result in the behavior of the rotor [F/r]
• sharedflaphinge: determines, if the rotor has one central flapping hinge (="1") for the blades (like the Bell206 or the tail rotor of the Bo 105), default is "0".
• delta3: Some rotors have a delta3 effect, which results in a decreasing of the incidence when the rotor is flapping. A value of 0 (as most helicopters have) means no change in incidence, a value of 1 result in a decreases of one degree per one degree flapping. So delta3 is the proportional factor between flapping and decrease of incidence. I.e. the tail rotor of a Bo105 has a delta3 of 1. In some publications delta3 is described by an angle. The value in YASim is the atan of this angle
• delta: A factor for the damping constant for the flapping. 1 means an analytical result, which is only an approximation. Has a very strong result in the reaction of the rotor system on control inputs. If you know the flapping angle for a given cyclic input you can adjust this by changing this value. Or if you know the maximum roll rate or ...
• translift-maxfactor: Helicopters have "translational lift", which is due to turbulence. In forward flying the rotor gets less turbulence air and produces more lift. The factor is the quotient between lift at high airspeeds to the lift at hover (with same pitch).
• translift-ve: the speed, where the translational lift reaches 1/e of the maximum value. In m/s.
• ground-effect-constant: Near to the ground the rotor produces more torque than in higher altitudes. The ground effect is calculated as factor = 1 + diameter/altitude * "ground-effect-constant"
• number-of-parts:
• number-of-segments: The rotor is simulated in "number-of-parts" different directions. In every direction the rotor is simulated at number-of-segments points. If the value is to small, the rotor will react unrealistic. If it is to high, cpu-power will be wasted. I now use a value of 8 for "number-of-parts" and 8 for number-of-segments for the main rotor and 4 for "number-of-parts" and 5 for "number-of-segments" for the tail rotor. "number-of-parts" must be a multiple of 4 (if not, it is corrected)
• cyclic-factor: The response of a rotor to cyclic input is hard to calculate (its a damped oscillator in resonance, some parameters have very large impact to the cyclic response) With this parameter (default 1) you can adjust the simulator to the real helo.
• downwashfactor: A factor for the downwash of the rotor, default 1.
• balance: The balance of the rotor. 1.0: the rotor is 100% balanced, 0.0: half of the blades are missing. Use a value near one (0.98 ... 0.999) to add some vibration.
• tiltcenterx:
• tiltcentery:
• tiltcenterz: The center for the tilting of the complete rotorhead/ mast. Can be used for simulating of the Osprey or small autogyros.
• mintiltyaw:
• mintiltpitch:
• mintiltroll:
• maxtiltyaw:
• maxtiltpitch:
• maxtiltroll: The limits (in degree) for tilting the rotor head

All rotors can have <control> subelements for the cyclic (CYCLICELE, CYCLICAIL) and collective (COLLECTIVE) input, and can have <control> subelements for tilting the whole rotor head around the y-axis (TILTPITCH), the x-axis (TILTROLL) and the z-axis (TILTYAW). ROTORBALANCE is a factor for the balance.

rotorgear

If you are using one or more rotors you have to define a rotorgear. It connects all the rotors and adds a simple engine. In the future it will be possible to add a YASim-engine.

• max-power-engine: the maximum power of the engine, in kW.
• engine-prop-factor: the engine is working as a pd-regulator. This is the width of the regulation-band, or, in other words, the inverse of the proportional-factor of the regulator. If you set it to 0.02, then up to 98% of the rotor-rpm the engine will produce maximum torque. At 100% the engine will produce no torque. It is planned to use YASim-engines instead of this simple engine.
• engine-accel-limit: The d-factor of the engine is defined as the maximum acceleration rate of the engine in %/s, default is 5%/s.
• max-power-rotor-brake: the maximum power of the rotor brake, in kW at normal rpm (most real rotor brakes would be overheated if used at normal rpm, but this is not simulated now)
• rotorgear-friction: the power loss due to friction in kW at normal RPM
• yasimdragfactor: It is applied for whole aircraft. It is normally calculated as a result of YASim solver for plane. But the plane solver is disabled for rotorcraft.
• yasimliftfactor: the solver is not working with rotor-aircraft. Therefore you have to specify the results yourself. 10 for drag and 140 for lift seem to be good starting values. Although the solver is not invoked for aircraft with at least one rotor, you need to specify the cruise and the approach settings. The approach speed is needed to calculate the gear springs. Use a speed of approx. 50knots. They do not need to match any real value.

The rotorgear needs a <control> subelement for the engine (ROTORGEARENGINEON) and can have further <control> subelements:

• ROTORBRAKE: rotor brake
• ROTORRELTARGET: the target rpm of the engine relative to the "normal" value for the governor. Default is 1.
• ROTORENGINEMAXRELTORQUE: the maximum torque of the engine relative to the torque defined by the enginepower. Default is 1. By setting the rel-target to a large number you get control over the engine by this control. Alternatively you can use these two values for individual start-up sequences (see the s58)

Example

Here's the main rotor definition of the bo105:

xml

<rotor name="main" x="-2.75" y="0.0" z="1.55" nx="0.05" ny="0" nz="1." fx="1" fy="0" fz="0" ccw="1"
  maxcollective="15.8" mincollective="0.2"
  mincyclicele="-4.7" maxcyclicele="10.5"
  mincyclicail="-4.23" maxcyclicail="5.65"
  diameter="9.98" numblades="4" weightperblade="75" relbladecenter="0.5"
  dynamic="1" rpm="442" rellenflaphinge="0.18" delta3="0"
  delta=".125"
  pitch-a="10"
  pitch-b="15"
  flapmin="-15"
  flapmax="15"
  flap0="-5"
  flap0factor="0"
  notorque="0"
  dragfactor="0.30"
  translift-ve="20"
  translift-maxfactor="1.5"
  ground-effect-constant="0.1"
  twist="-8.5"
  taper="1"
  chord="0.27"
  number-of-segments="8"
  number-of-parts="8"
  rel-len-where-incidence-is-measured="0.7"
  rel-len-blade-start="0.076"

  airfoil-lift-coefficient="3.46"
  airfoil-drag-coefficient0="0.0064"
  airfoil-drag-coefficient1="0.20"
  incidence-stall-zero-speed="15"
  incidence-stall-half-sonic-speed="14.5"
  lift-factor-stall="0.18"
  stall-change-over="5.5"
  drag-factor-stall="2.0"
  cyclic-factor="0.8"
  rotor-correction-factor="0.95"
  downwashfactor="1.0"
>

<control-input axis="/controls/flight/aileron-trim" control="CYCLICAIL"/>

<control-input axis="/controls/flight/aileron" control="CYCLICAIL"
                 src0="-1.0" src1="1.0"
                 dst0="-1.0" dst1="1.0"/>

<control-input axis="/controls/flight/elevator-trim" control="CYCLICELE"/>

<control-input axis="/controls/flight/elevator" control="CYCLICELE"
                 src0="-1.0" src1="1.0"
                 dst0="-1.0" dst1="1.0"/>

<control-input axis="/controls/engines/engine[0]/throttle" control="COLLECTIVE"
                 src0="0.0" src1="1.0"
                 dst0="1.0" dst1="-1.0"/>

</rotor>

Engine

Thruster

A very simple "thrust only" engine object. Useful for things like thrust vectoring nozzles. All it does is map its THROTTLE input axis to its output thrust rating. Does not consume fuel, etc...

• thrust: Maximum thrust in pounds
• x,y,z: The point on the airframe where thrust will be applied.
• vx,vy,vz: The direction of the thrust in airframe coordinates. The vector will be normalized automatically, so any non-zero vector will work fine.

Example:

xml

<thruster x="0" y="0" z="0.03" vx="1" vy="0" vz="0" thrust="6.61">
  <control-input axis="/controls/engines/engine[0]/throttle" control="THROTTLE" src0="-1" src1="1" dst0="-1" dst1="1"/>
</thruster>

Jet

A turbojet/fan engine. It accepts a <control> subelement to map a property to its throttle setting, and an <actionpt> subelement to place the action point of the thrust at a different position than the mass of the engine.

• x,y,z: The location of the engine, as a point mass. If no actionpt is specified, this will also be the point of application of thrust.
• mass: The mass of the engine, in pounds.
• thrust: The maximum sea-level thrust, in pounds.
• afterburner: Maximum total thrust with afterburner/reheat, in pounds [defaults to "no additional thrust"].
• rotate: Vector angle of the thrust in degrees about the Y axis [0].
• n1-idle: Idling low pressure core / fan speed [55].
• n1-max: Maximum low pressure core / fan speed [102].
• n2-idle: Idling high pressure core speed [73].
• n2-max: Maximum high pressure core speed [103].
• tsfc: Thrust-specific fuel consumption [0.8]. This should be considerably lower for modern turbofans.
• atsfc: Thrust specific fuel consumption with afterburner on. When set to zero defaults to older behaviour where it is calculated from dry fuel consumption [0].
• egt: Exhaust gas temperature at takeoff in K [1050].
• epr: Engine pressure ratio at takeoff [3.0].
• exhaust-speed: The maximum exhaust speed in knots [~1555].
• spool-time: Time, in seconds, for the engine to respond to 90% of a commanded powersetting.

Propeller

A propeller. This element requires an engine subtag. Currently <piston-engine>, <turbine-engine>, and <electric-engine> are supported.

• x,y,z: The position of the mass (!) of the engine/propeller combination. If the point of force application is different (and it will be) it should be set with an <actionpt> subelement.
• mass: The mass of the engine/propeller, in pounds.
• moment: The moment, in $\text{kg}\cdot\text{m}^2$. This has to be hand calculated and guessed at for now. A more automated system will be forthcoming. Use a negative moment value for counter-rotating ("European" — CCW as seen from behind the prop) propellers. A good guess for this value is the radius of the prop (in meters) squared times the mass (kg) divided by three; that is the moment of a plain "stick" bolted to the prop shaft.
• radius: The radius, in meters, of the propeller.
• cruise-speed: The max efficiency cruise speed of the propeller. Generally not the same as the aircraft's cruise speed.
• cruise-rpm: The RPM of the propeller at max-eff. cruise.
• cruise-power: The power sunk by the prop at cruise, in horsepower.
• cruise-alt: The reference cruise altitude in feet.
• takeoff-power: The takeoff power required by the propeller...
• takeoff-rpm: ...at the given takeoff RPM.
• gear-ratio: The factor by which the engine RPM is multiplied to produce the propeller RPM. Optional (defaults to 1.0).
• contra: When set (contra="1"), this indicates that the propeller is a contra-rotating pair. It will not contribute to the aircraft's net gyroscopic moment, nor will it produce asymmetric torque on the aircraft body. Asymmetric slipstream effects, when implemented, will also be zero when this is set.

YASim assumes a fixed-pitch propeller by default. If your engine is using a constant-speed propeller, you'll also need to provide these attributes:

• min-rpm: The minimum operational RPM for a constant speed propeller. This is the speed to which the prop governor will seek when the blue lever is at a minimum. The coarse-stop attribute limits how far the governor can go into trying to reach this RPM.
• max-rpm: The maximum operational RPM for a constant speed propeller. See above. The fine-stop attribute limits how far the governor can go in trying to reach this RPM.
• fine-stop: The minimum pitch of the propeller (high RPM) as a ratio of ideal cruise pitch. This is set to 0.25 by default — a higher value will result in a lower RPM at low power settings (e.g. idle, taxi, and approach).
• coarse-stop: The maximum pitch of the propeller (low RPM) as a ratio of ideal cruise pitch. This is set to 4.0 by default — a lower value may result in a higher RPM at high power settings.

piston-engine

A piston engine definition. This must be a subelement of an enclosing <propeller> tag.

• eng-power: Maximum BHP of the engine at sea level.
• eng-rpm: The engine RPM at which eng-power is developed.
• displacement: The engine displacement in cubic inches.
• compression: The engine compression ratio.

xml

<piston-engine eng-power="2" eng-rpm="3800" displacement="20">
    <control-input axis="/controls/engines/engine[0]/throttle" control="THROTTLE"/>
    <control-input axis="/controls/engines/engine[0]/starter" control="STARTER"/>
    <control-input axis="/controls/engines/engine[0]/magnetos" control="MAGNETOS"/>
    <control-input axis="/controls/engines/engine[0]/mixture" control="MIXTURE"/>
</piston-engine>

electric-engine

A simplified electric DC engine model. This definition must be a subelement of an enclosing <propeller> tag.

• Kv: Electric engine constant in revolutions per minute per volt (RPM/V).
• voltage: The voltage applied to the motor e.g. Nominal battery voltage in Volts.
• Rm: The engine winding resistance in Ohms.

Example:

xml

<propeller x="0.02" y="0" z="0.03"
           mass="0.05"
           moment="0.0006"
           radius="0.203"
           cruise-speed="26"
           cruise-rpm="7000"
           cruise-power="0.5"
           cruise-alt="2000"
           takeoff-power="0.70"
           takeoff-rpm="9200"
           contra="1">
    <actionpt x="0" y="0" z="0.03"/>
    <electric-engine Kv="750" voltage="15" Rm="0.02">
        <control-input axis="/controls/engines/engine[0]/throttle" control="THROTTLE"/>
    </electric-engine>
</propeller>

Landing gear

gear

Defines a landing gear. Accepts <control> subelements to map properties to steering and braking. Can also be used to simulate floats. Although the coefficients are still called ..fric, it is calculated in fluids as a drag (proportional to the square of the speed). In fluids, gears are not considered to detect crashes (as on ground).

• x,y,z: The location of the fully-extended gear tip.
• compression: The distance in metres along the "up" axis that the gear will compress.
• initial-load: The initial load of the spring in multiples of compression. Defaults to 0. (With this parameter, lower spring-constants will be used for the gear $\rightarrow$ can reduce numerical problems like jitter). Note: the spring-constant is varied from 0% compression to 20% compression to get continuous behavior around 0 compression (could be physically explained by wheel deformation).
• upx/upy/upz: The direction of compression, defaults to vertical (0,0,1) if unspecified. These are used only for direction — the vector need not be normalized, as the length is specified by compression.
• sfric: Static (non-skidding) coefficient of friction. Defaults to 0.8.
• dfric: Dynamic friction. Defaults to 0.7.
• stiction: Stiction to ground. Defaults to 0. stiction="1" ensures the gear isn't sliding unintentionally.
• spring: A dimensionless multiplier for the automatically generated spring constant. Increase to make the gear stiffer, decrease to make it squishier.
• damp: A dimensionless multiplier for the automatically generated damping coefficient. Decrease to make the gear "bouncier", increase to make it "slower". Beware of increasing this too far: very high damping forces can make the numerics unstable. If you can't make the gear stop bouncing with this number, try increasing the compression length instead.
• on-water: If this is set to "0", the gear will be ignored if on water. Defaults to "0".
• on-solid: If this is set to "0", the gear will be ignored if not on water. Defaults to "1".
• speed-planing: Speed threshold for planing mode on water.
• spring-factor-not-planing: At zero speed, the spring factor is multiplied by spring-factor-not-planing. Above speed-planing, this factor is equal to 1. The idea is to use this for floats simulating the transition from swimming to planing. speed-planing defaults to 0, spring-factor-not-planing defaults to 1.
• reduce-friction-by-extension: At full extension, the friction is reduced by this relative value. 0.7 means 30% friction at full extension. If you specify a value greater than one, the friction will be zero before reaching full extension. Defaults to "0".
• ignored-by-solver: With the on-water/on-solid tags, you can have more than one set of gears on an aircraft. If the solver (which automatically generates the spring constants) takes all gears into account, the result will be wrong. Set this tag to "1" for all gears that are not active on runways. Defaults to "0". You cannot exclude all gears in the solving process.

Will define two properties associated with compression of landing gear:

• compression-norm — range from 0 to 1; 0 means gear fully extended, 1 means fully compressed.
• compression-m — vertical distance in metres that the wheel has moved in order to be on top of ground; this will usually be different from the animation distance.

xml

<!-- front gear -->
<gear x="0.0" y="0.0" z="-0.205"
      spring="0.9"
      damp="0.8"
      dfric="0.9"
      sfric="1.1"
      compression="0.051">
    <control-input axis="/controls/flight/rudder" control="STEER" square="true" src0="-1.0" src1="1.0" dst0="-0.3" dst1="0.3"/>
    <control-input axis="/controls/gear/brake-right" control="BRAKE" split="true"/>
    <control-input axis="/controls/gear/brake-parking" control="BRAKE" split="true"/>
</gear>

<!-- two rear gears -->
<gear x="-0.4" y="0.25" z="-0.205"
      spring="0.9"
      damp="0.8"
      dfric="0.9"
      sfric="1.1"
      compression="0.051">
    <control-input axis="/controls/gear/brake-right" control="BRAKE" split="true"/>
    <control-input axis="/controls/gear/brake-parking" control="BRAKE" split="true"/>
</gear>

<gear x="-0.4" y="-0.25" z="-0.205"
      spring="0.9"
      damp="0.8"
      dfric="0.9"
      sfric="1.1"
      compression="0.051">
    <control-input axis="/controls/gear/brake-left" control="BRAKE" split="true"/>
    <control-input axis="/controls/gear/brake-parking" control="BRAKE" split="true"/>
</gear>

Torus-shaped contact surface

One can specify a torus-shaped tyre contact surface using these parameters:

• wheel-x
• wheel-y
• wheel-z
• wheel-radius (default 0)
• tyre-radius (default 0)
• wheel-axle-x
• wheel-axle-y
• wheel-axle-z

The contact point will be the lowest point on a torus with radius tyre-radius wrapped around a wheel with radius wheel-radius centred on point (wheel-x, wheel-y, wheel-z) with orientation defined by wheel-axle. This contact point will depend on the aircraft's orientation relative to the ground.

If not specified, wheel-axle defaults to (0, 1, 0), giving a conventional vertical wheel in line with the aircraft. Other values may allow modelling of, for example, a Bf109's non-vertical undercarriage.

Default values of zero for wheel-radius and tyre-radius give a fixed contact point at (wheel-x, wheel-y, wheel-z).

If an aircraft also specifies an old-style contact point with (x, y, z), it will also work with older FlightGear versions.

Launchbar

Defines a catapult launchbar or strop.

• x,y,z: The location of the mount point of the launch bar or strop on the aircraft.
• length: The length of the launch bar from mount point to tip.
• down-angle: The max angle below the horizontal the launchbar can achieve.
• up-angle: The max angle above the horizontal the launchbar can achieve.
• holdback-{x,y,z}: The location of the holdback mount point on the aircraft.
• holdback-length: The length of the holdback from mount point to tip. Note: holdback up-angle and down-angle are the same as those defined for the launchbar and are not specified in the configuration.

Fuel

tank

A fuel tank. Tanks in the aircraft are identified numerically (starting from zero), in the order they are defined in the file. If the left tank is first, tank[0] will be the left tank.

• x,y,z: The location of the tank.
• capacity: The maximum contents of the tank, in pounds. Not gallons — YASim supports fuels of varying densities.
• jet: A boolean. If present, this causes the fuel density to be treated as Jet-A. Otherwise, gasoline density is used.

Center of Gravity

Ballast

This is a mechanism for modifying the mass distribution of the aircraft. A ballast setting specifies that a particular amount of the empty weight of the aircraft must be placed at a given location. The remaining non-ballast weight will be distributed "intelligently" across the fuselage and wing objects. Note again: this does NOT change the empty weight of the aircraft.

• x,y,z: The location of the ballast.
• mass: How much mass, in pounds, to put there. Note that this value can be negative. (Often used to "lighten" the tail of the aircraft).

xml

<ballast x="-0.24" y="0.0" z="0.33" mass-kg="0.5"/>

Weight

This is an added weight, something not part of the empty weight of the aircraft, like passengers, cargo, or external stores. The actual value of the mass is not specified here; instead, a mapping to a property is used. This allows external code, such as the panel, to control the weight (loading a given cargo configuration from preference files, dropping bombs at runtime, etc.).

• x,y,z: The location of the weight.
• mass-prop: The name of the fgfs property containing the mass, in pounds, of this weight.
• size: The aerodynamic "size", in metres, of the object. This is important for external stores, which will cause drag. For reasonably aerodynamic items like bombs, the size should be roughly the width of the object. The default is zero, which results in no aerodynamic force (internal cargo).
• solve-weight: Subtag of approach and cruise parameters. Used to specify a non-zero setting for a <weight> tag during solution. The default is to assume all weights are zero at the given performance numbers.
• idx: Index of the weight in the file (starting with zero).
• weight: Weight setting in pounds.

xml

<weight x="-0.06471" y="0.225" z="-0.2" mass-prop="/sim/weight[0]/weight-kg"/>

Controls

control-input

This element manages a mapping from fgfs properties (user input) to settable values on the aircraft's objects. Note: the value to be set MUST (!) be valid on the given object type (wings don't have throttle controls, etc.). This is not checked for by the parser, and will cause a runtime crash if misconfigured. Note that multiple axes may be set on the same value; they are summed before setting.

• axis: The name of the double-valued fgfs property "axis" to use as input, such as /controls/flight/aileron.

• control: Which control axis to set on the objects. Available values include:

• THROTTLE — The throttle on a jet or propeller.

• MIXTURE — The mixture on a propeller.

• REHEAT — The afterburner on a jet.

• PROP — The propeller advance.

• BRAKE — The brake on a gear.

• STEER — The steering angle on a gear.

• INCIDENCE — The incidence angle of a wing.

• FLAP0 / FLAP1 — Flap deflections of a wing.

• SLAT — Slat extension of a wing.

• SPOILER — Spoiler extension for a wing.

• CYCLICAIL / CYCLICELE — Cyclic inputs (aileron/elevator) of a rotor.

• COLLECTIVE — Collective input of a rotor.

• ROTORENGINEON — If non-zero, the rotor is rotating.

• WINCHRELSPEED — Relative winch speed.

• ...

• invert: Negate the value of the property before setting on the object.

• split: Applicable to wing control surfaces. Sets the normal value on the left wing, and a negated value on the right wing.

• square: Squares the value before setting. Useful for controls like steering that need a wide range yet high sensitivity around the center.

• src0/src1/dst0/dst1: Defines a linear mapping from source to output value. Input values in the range src0-src1 map linearly to dst0-dst1, with clamping for values outside the range.

control-output

Used to pass the value of a YASim control axis (after all mapping and summing is applied) back to the property tree.

• control: Name of the control axis.
• prop: Property node to receive the value.
• side: Optional, for split controls ("right" or "left").
• min/max: Clamping applied to the output value.

control-speed

Defines maximum slew rates for controls (such as flaps or hydraulics) that cannot respond instantly to pilot input.

• control: Name of the control axis.
• transition-time: Time in seconds to slew through the full input range.

control-setting

Used to define a specific setting for a control axis inside <cruise> or <approach> tags where property input is unavailable (e.g., informing the solver that approach performance assumes full flaps).

• axis: Name of the control input (i.e., a property name).
• value: Value of the control axis.

Winch and Aerotow

hitch

A hitch used for winch launches (gliders), aerotow (gliders and motorized aircraft), or external cargo (helicopters). Aerotowing over multiplayer is supported.

• name: Name of the hitch. Must be aerotow for multiplayer aerotow functionality. Properties are created under /sim/hitches/name.
• x,y,z: Position of the hitch.
• force-is-calculated-by-other: Set to "1" in the tow aircraft for multiplayer aerotowing. Leave at "0" in gliders.

tow

The tow cable used for aerotow or winch. Must be a subelement of an enclosing <hitch> tag.

• length: Unstretched length in metres.
• weight-per-meter: Weight in kg/metre.
• elastic-constant: Lower values give higher elasticity.
• break-force: Breaking force in Newtons.
• mp-auto-connect-period: Interval in seconds to search for a towed multiplayer aircraft.

winch

The winch mechanism parameters. Must be a subelement of an enclosing <hitch> tag.

• max-tow-length: Maximum tow length in metres.
• min-tow-length: Minimum tow length in metres.
• initial-tow-length: Initial length in metres (also defines search radius for multiplayer auto-connect).
• max-winch-speed: Maximum winch speed in m/s.
• power: Power rating in kW.
• max-force: Maximum force in Newtons.

xml

<hitch name="winch" x="0.0" y="0.0" z="0.0">
    <tow length="50" weight-per-meter="0.0035" elastic-constant="40000" break-force="10000"/>
    <!-- 3mm paracord -->
    <winch max-tow-length="1000" min-tow-length="1" initial-tow-length="1000" max-winch-speed="20" power="2" max-force="80"/>
    <control-input axis="/controls/winch/place" control="PLACEWINCH"/>
</hitch>

<hitch name="aerotow" x="0.0" y="0.0" z="0.0" force-is-calculated-by-other="0">
    <tow length="60" weight-per-meter="0.0035" elastic-constant="9000" break-force="100" mp-auto-connect-period="0.0"/>
    <winch max-tow-length="1000" min-tow-length="60" initial-tow-length="60"/>
    <control-input axis="/controls/aerotow/find-aircraft" control="FINDAITOW"/>
</hitch>