fgdata/Aircraft-yasim/README.yasim

Coordinate system notes: All positions specified are in meters (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.

XML Elements
------------

airplane: The top-level element for the file.  It contains only one
          attribute:
          mass: The empty (no fuel) weight, in pounds.

approach: The approach parameters for the aircraft.  The solver will
          generate an aircraft that matches these settings.  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

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.

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 meters.

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 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.
          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.

hstab:    These defines the horizontal stabilizer of the aircraft.
          Internally, it is just awing objects and therefore work 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.

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.

stall:    A subelement of a wing (or hstab/vstab) 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 viscious
                 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 positition 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.

jet:      A turbojet/fan engine.  Really cheezy right now, so there's
          not much to set.  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.

propeller: A propeller connected to a non-turbocharged piston engine
          The engine model is evolving, this element is likely to change
          radically in the future.
          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 kg-meters.  This has to be
                         hand calculated and guessed at for now.  A
                         more automated system will be forthcoming.
          radius:        The radius, in meters, or 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.
          alt:           The cruise altitude.
          takeoff-power: The takeoff power required by the propeller...
          takeoff-rpm:   ...at the given takeoff RPM.

actionpt: Defines an "action point" for an enclosing jet or propeller
          element.  This is the location where the force from the thruster
          will be applied.
          x,y,z:  The location of force application.

gear:     Defines a landing gear.  Accepts <control> subelements to map
          properties to steering and braking.
          x,y,z:  The location of the fully-extended gear tip.
          compression:  The distance along the Z axis that the gear
                        will compress.  Compression along other
                        vectors is supported internally, but not in
                        the XML parser.  Bug me if you wantthis
                        added.
          sfric:        Static (non-skidding) coefficient of
                        friction.  Defaults to 0.8.
          dfric:        Dynamic friction.  Defaults to 0.7.
          retract-time: The time, in seconds, that the gear takes to
                        fully retract or extend.  Defaults to zero,
                        which indicates a non-retractable gear.
          spring:       A dimensionless multiplier for the automatically
                        generated spring constant.  Increase to make
                        the gear stiffer, decrease to make it
                        squishier.
          damp:         A dimensionless multipler 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 result and make
                        the numerics unstable.  If you can't make the
                        gear stop bouncing with this number, try
                        increasing the compression length instead.

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.  A more elaborate
                    density setting (in pounds per gallon, for
                    example) would be easy to implement.  Bug me.

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.  I find that I often need
                 to "lighten" the tail of the aircraft.

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 propery 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 meters, of the
                      object.  This is important for external stores,
                      which will cause drag.  For reasonably
                      aerodynamic stuff like bombs, the size should be
                      roughly the width of the object.  For other
                      stuff, you're on your own.  The default is zero,
                      which results in no aerodynamic force (internal
                      cargo).

control:  This element, which can appear in two different contexts,
          manages a mapping from fgfs properties (user input) to
          settable values on the aircraft's objects.  Note that the
          value to be set MUST (!) be valid on the given object type.
          This is not checked for by the parser, and will cause a
          runtime crash if you try it.  Wing's don't have throttle
          controls, etc...  Note that multiple axes may be set on the
          same value.  They are summed before setting.

          One serious shortcoming of the current implementation is
          that there is no provision for modifying the values read
          from properties.  There needs to be a way to scale,
          translate and truncate the values.  On its way, I promise.

          axis:  The name of the double-valued fgfs property "axis" to
                 use as input, such as "/controls/aileron".
          output: Which property to set on the objects.  It can have
                  the following values:
                  THROTTLE - The throttle on a jet or propeller.
                  MIXTURE - The mixture on a propeller.
                  REHEAT - The afterburner on a jet (unimpl.).
                  PROP - The propeller advance (unimpl.)
                  BRAKE - The brake on a gear.
                  STEER - The steering angle on a gear.
                  INCIDENCE - The incidence angle of a wing.
                  FLAP0 - The flap0 deflection of a wing.
                  FLAP1 - The flap1 deflection of a wing.
                  SLAT - The slat extension of a wing.
                  SPOILER - The spoiler extension for a wing.
          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
                  lots of sensitiviy in the center.  Obviously only
                  applicable to values that have a range of [-1:1] or
                  [0:1].

          A control element can also appear inside of an <approach> or
          <cruise> element.  Here, it specifies a particular value of an
          axis mapping that should be true under the given
          conditions.  At cruise, the throttle is generally at a high
          setting, the flaps and slats are up During approach
          the flaps and slats are down, etc...

          axis:  As above, the name of the input property.
          value: A floating point number that the property is expected
                 to hold.