Basic Layout of a YASim Flight Model
By Gary "Buckaroo" Neely
A YASim FDM is an XML file made up of elements that define the structure and characteristics of the aircraft. It consists of elements that bracket the flight characteristics, describe the flight surfaces, the fuselage or other non-flight surface bodies, propulsion systems, landing gear, fuel tanks, and a few other features and options.
The following is a suggested structure for a conventional sport aircraft having a single piston engine, a constant-speed propeller, tricycle gear, flaps, and a fuel tank in each wing.
<?xml version="1.0"?>
<airplane mass="..." >
<approach ... >
<control-setting axis="/controls/engines/engine[0]/throttle" value="..."/>
<control-setting axis="/controls/engines/engine[0]/mixture" value="1"/>
<control-setting axis="/controls/engines/engine[0]/propeller-pitch" value="1"/>
<control-setting axis="/controls/gear/gear-down" value="1"/>
<control-setting axis="/controls/flight/flaps" value="1"/>
...
</approach>
<cruise ... >
<control-setting axis="/controls/engines/engine[0]/throttle" value="1"/>
<control-setting axis="/controls/engines/engine[0]/mixture" value="0.65"/>
<control-setting axis="/controls/engines/engine[0]/propeller-pitch" value="1"/>
<control-setting axis="/controls/flight/elevator-trim" value="..."/>
<control-setting axis="/controls/gear/gear-down" value="0"/>
<control-setting axis="/controls/flight/flaps" value="0"/>
...
</cruise>
<cockpit x="..." y="..." z="..." />
<fuselage ax="..." ay="..." az="..." bx="..." by="..." bz="..." width="..." taper="..." midpoint="..." />
<wing ... >
<stall ... />
<flap0 ... />
<flap1 ... />
<control-input axis="/controls/flight/flaps-norm" control="FLAP0"/>
<control-input axis="/controls/flight/aileron" control="FLAP1" split="true"/>
<control-output control="FLAP0" prop="/surface-positions/flap-pos-norm"/>
<control-output control="FLAP1" side="left" prop="/surface-positions/left-aileron-pos-norm"/>
<control-output control="FLAP1" side="right" prop="/surface-positions/right-aileron-pos-norm"/>
<control-speed control="FLAP0" transition-time="..."/>
</wing>
<hstab ... >
<stall ... />
<flap0 ... />
<control-input control="FLAP0" axis="/controls/flight/elevator" invert="true"/>
<control-input control="FLAP0" axis="/controls/flight/elevator-trim" invert="true"/>
<control-output control="FLAP0" prop="/surface-positions/elevator-pos-norm"/>
</hstab>
<vstab ... >
<stall ... />
<flap0 ... />
<control-input axis="/controls/flight/rudder" control="FLAP0" invert="true"/>
<control-input axis="/controls/flight/rudder-trim" control="FLAP0" invert="true"/>
<control-output control="FLAP0" prop="/surface-positions/rudder-pos-norm"/>
</vstab>
<propeller ... >
<actionpt x="..." y="0" z="..."/>
<control-input axis="/controls/engines/engine[0]/propeller-pitch" control="ADVANCE"/>
<piston-engine ... >
<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>
</propeller>
<gear x="..." y="0" z="..." ... >
<control-input axis="/controls/gear/gear-down" control="EXTEND"/>
<control-output control="EXTEND" prop="/gear/gear[0]/position-norm"/>
<control-speed control="EXTEND" transition-time="..."/>
</gear>
<gear x="..." y="..." z="..." ... >
<control-input axis="/controls/gear/brake-left" control="BRAKE"/>
<control-input axis="/controls/gear/brake-parking" control="BRAKE" split="true"/>
<control-input axis="/controls/gear/gear-down" control="EXTEND"/>
<control-output control="EXTEND" prop="/gear/gear[1]/position-norm"/>
<control-speed control="EXTEND" transition-time="..."/>
</gear>
<gear x="..." y="-..." z="..." ... >
<control-input axis="/controls/gear/brake-left" control="BRAKE"/>
<control-input axis="/controls/gear/brake-parking" control="BRAKE" split="true"/>
<control-input axis="/controls/gear/gear-down" control="EXTEND"/>
<control-output control="EXTEND" prop="/gear/gear[1]/position-norm"/>
<control-speed control="EXTEND" transition-time="..."/>
</gear>
<tank x="..." y="..." z="..." capacity="..." />
<tank x="..." y="-..." z="..." capacity="..." />
<ballast x="..." y="..." z="..." mass="..." />
</airplane>
It's not as scary as it might appear. With a little experience, many things are cut-and-paste jobs, changing a few parameters.
The YASim Coordinate System
Before continuing with descriptions of the elements, a word on the YASim coordinate system. Many YASim elements specify an x, y, z position for a component. Within the YASim XML file, the positive x axis is forward, the positive y axis points left, and the positive z axis is up. When positioning elements like fuel tanks, landing gear, or engines along the right wing, their y axis coordinates will be negative. In YASim, all coordinates are in meters. YASim curiously mixes both English and metric units.
The origin of your coordinates can be anywhere. The simulation will rotate the model about its center of gravity in flight, and the CG will always be placed correctly with respect to the origin you define. Some developers place their origin at a guess for the CG location. I use the nose of the aircraft as my origin, because this is the standard historical origin often used by engineers and dating back to early naval drafts. This is helpful when working with engineering plans, as positions are often designated along the station-line or fuselage station line, which is a measurement taken from a point in front of the aircraft. The equivalent for the z axis is the water-line, and for the y axis, the butt-line. Usually engineers will place the origin of the station-line and water-line at a location such that all measurements result in positive numbers. The butt-line is the exception, as it is measured from the axis of symmetry. I follow this standard when laying out my YASim models.
It helps reduce errors if your 3D model uses the same origin. This way you can take the numbers straight from your model and use them in your FDM, with no more trouble than perhaps reversing the sign of the y axis.
In flight, the aircraft's orientation will pivot about its center of gravity, but when rotating an external view about the model, the model will appear to rotate about the model's origin. In most views this will feel unnatural. This is easily remedied by setting an offset to position the view closer to the model's approximate CG. The Flightgear wiki has an article on this: Model View Offsets
The YASim Elements
Let's look at each of the fundamental YASim elements and see what they do. Not all elments are required, and many will be different from the above example, but this will give you an idea how to begin.
Elements take the form "<element-name [list of attributes]>", where an attribute looks like "attribute-name="n", where n is some value. Attributes should be separated by spaces, not commas. Many elements will contain sub-elements. Those that do have a different form: "<element-name ...>[list of sub-elements]</element-name>. You'll quickly get the idea from the examples.
The Airplane Element
The primary element for the FDM is the
<airplane mass="..." > ... </airplane>
This has a single required attribute, mass, which should be the dry, empty weight of the aircraft in pounds.
All other YASim elements are contained within the <airplane> element. The order of elements does not matter. I use the above order in my FDMs, which is a common convention with many other YASim FDMs. Make sure that your FDM ends with the closing </airplane> tag.
Approach and Cruise Elements
Next are the approach and cruise elements.
<approach ... > ... </approach> <cruise ... > ... </cruise>
These two elements bracket the flight envelope of the aircraft. Both are required and are critical to the flight behavior. For details on how to set up and tune these elements, see Approach and Cruise Settings.
The Cockpit Element
Next up is the <cockpit> element.
<cockpit x="..." y="..." z="..." />
This element specifies the pilot's viewpoint for the model. This may be a legacy element. It is parsed but not used within YASim and appears to be optional. Possibly it defines a default eyepoint if no other viewpoint is specified in the aircraft's -set.xml file. I've always defined my viewpoints in a separate views.xml file, so I've never tested to see if this element is used. I typically include it as a quick reference for a base viewpoint.
Fuselage Elements
Fuselage elements define structures that have mass and aerodynamic influence but otherwise don't determine primary flight characteristics. They serve as ground contact points, act as simple surfaces that contribute drag, and affect mass distribution. The structure of a fuselage element will usually look like this:
<fuselage ax="..." ay="..." az="..." bx="..." by="..." bz="..." width="..." midpoint="..." taper="..." />
Most aircraft will have at least one fuselage element representing the actual aircraft fuselage. Additional Fuselage elements can be used to represent engine nacelles, or wheel pants, external fuel tanks, static weapon structures, etc. You can have as many fuselage structures as you need, or none at all. For a detailed description, visit Fuselage Elements.
Flight Surface Elements
Flight surfaces like the wing, horizontal stabilizer, and vertical stabilizer are the main lifting and control surfaces of an aircraft. A flight surface element looks like this:
<wing ... > <stall ... /> <flap0 ... /> <flap1 ... /> ... <control-input .../> ... <control-output .../> ... </wing>
The element name is followed by a number of attributes that describe the geometry of the surface. The stall sub-element describes stall and lift behavior. Optional flap0 and flap 1 sub-elements describe moveable control surfaces such as a flap, rudder, elevator, etc. Control inputs bind a Flightgear property to a flap for manipulation of the moveable surface, and control outputs create properties tht show the current position of a moveable surface.
A "wing" is just one of the available flight surface types. An "hstab" (horizontal stabilizer) is another. YASim requres that the flight model have exactly one wing and one hstab, but other flight surface types allow you to describe vertical stabilizers and additional wings.
You can read more about flight surfaces and their many options here: Flight Surfaces
Propulsion Elements
YASim has a number of ways to propel your aircraft through the virtual skies. The most common are jet engines and piston-driven propellers, followed by turboprop-driven propellers. There is also a simple thruster. A basic propeller-driven unit has this form:
<propeller ...>
<actionpt ... />
<piston-engine ...>
<control-input .../>
...
</piston-engine>
</propeller>
A jet engine definition is a little simpler:
<jet ...> <actionpt ... /> <control-input ... /> ... </jet>
Each consists of a primary element with a set of descriptive attributes, a sub-element that describes where thrust is applied (the action point), and a set of sub-elements describing engine controls. In the case of the propeller, the actual powerplant is a sub-element.
You can have any number of propulsion elements, 1 to 4 being common. The engines will be enumerated in Flightgear property lists by the order in which they are defined in the YASim file. So the first engine defined will be 0, the second will be 1, etc.
Propulsion elements are a broad topic. Piston engines and jet engines are described in much more detail here:
Piston-driven Propeller Engines
Jet Engines
Writing guides for turboprops and thrusters is on my to-do list.
Landing Gear
Each landing gear unit receives its own element in the flight model. A typical gear element looks like this:
<gear x="..." y="..." z="..." ... > <control-input axis="/controls/gear/brake-left" control="BRAKE"/> <control-input axis="/controls/gear/brake-parking" control="BRAKE" split="true"/> <control-input axis="/controls/gear/gear-down" control="EXTEND"/> <control-output control="EXTEND" prop="/gear/gear[1]/position-norm"/> <control-speed control="EXTEND" transition-time="..."/> </gear>
The primary gear element describes the coordinates for the gear's ground contact points at full extension and a set of attributes for other gear parameters. Full extension in this case means the gear's fully extended length, with no compression on the shock absorber. Sub-elements describe the gear's braking controls and characteristics, optional controls for extending the gear in the case of retractable landing gear, and transition time for retraction.
You can have any number of gear elements, 3 being common. Landing gear are enumerated in the property tree by the order in which they are defined in the YASim file. So the first gear will be 0, the second will be 1, etc.
A guide for landing gear is on my to-do list.
Fuel Tanks
Fuel tank elements are simple:
<tank x="..." y="..." z="..." capacity="..." />
The tank has a set of coordinates locating its center of mass, and a capacity expressed in pounds. You can have as many as you require, and each is enumerated according the order in which it is defined. See Weight and Balance for more information on setting up and using fuel tanks.
Ballast
Ballast elements are also simple:
<ballast x="..." y="..." z="..." mass="..." />
Ballast is simply a mass and coordinates for its position. Ballast elements do not add weight, they re-distribute weight. This topic is covered in more detail in Weight and Balance and Inertia Tensors and YASim.
Other Elements
YASim features additional elements for aerotowing, catapult launching, anchoring (useful for flying boats and seaplanes), and helicopter simulation. Anchoring and aerotowing are on my to-do list. Unfortunately I have no experience with YASim rotary wings and so I have no plans to write a guide on the YASim rotor elements.
Documenting Your Flight Model
Documentation of your flight model is important, not only for others who may view your FDM, but for yourself. You may find yourself coming back to a flight model a year after developing it, and wondering "Why did I set this value to 1.5?"
Document your FDM settings in the FDM itself. A comment takes the form:
<!-- My really illuminating comment. -->
Beware of using "--" within your comments. The parser will interpret that as an end to the comment and you will likely get an error in your FDM.
Many settings are not intuitive especially to inexperienced designers. You may have spent a great deal of time and effort researching a behavior and tweaking an attribute for flight results, but if you don't document your rationale no one will know why those values were chosen, and it's very possible some enthusiastic but inexperienced follow-on developer may change your values without understanding them. Lack of proper documentation is probably the greatest flaw of YASim itself. Don't make the same mistake in your FDM.