YASim: Difference between revisions

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.

The top-level element for the file. It contains only one attribute:  

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

*'''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 ====  

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

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

*'''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 them width you can define cy=2 and (due to the doubled front surface) cx=2.

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.

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

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

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.

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

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

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,vy:''' The direction of the thrust in airframe coordinates. The vector will be normalized automatically, so any non-zero vector will work fine.

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

*'''egt:'''           Exhaust gas temperature at takeoff [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.

A propeller. This element requires an engine subtag. Currently <piston-engine> and <turbine-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 kg-metres^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 metres) 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 metres, 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.

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

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

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

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

=====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 a lower spring-constants will be used for the gear-> can reduce numerical problems (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 a 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.

*'''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 set to "0" the gear will be ignored if not on water. Defaults to "1"

*'''speed-planing:'''

*'''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 in one aircraft, If the solver (who automatically generates the spring constants) would take all gears into account, the result would be wrong. E. G. set this tag to "1" for all gears, which are not active on runways. Defaults to "0". You can not exclude all gears in the solving process.

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

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

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

====Controls====

=====control-input=====

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

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

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

**CYCLICAIL - The "aileron" cyclic input of a rotor  

**CYCLICELE - The "elevator" cyclic input of a rotor  

**COLLECTIVE - The collective input of a rotor

**ROTORENGINEON - If not equal zero the rotor is rotating

**WINCHRELSPEED - The relative winch speed  

**{... and many more, see FGFDM.cpp ...}

*'''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 sensitivity in the center. Obviously only applicable to values that have a range of [-1:1] or [0:1].  

*'''src0/src1/dst0/dst1:''' If present, these defined a linear mapping from the source to the output value. Input values in the range src0-src1 are mapped linearly to dst0-dst1, with clamping for input values that lie outside the range.

=====control-output=====

*'''control:''' Name of the control axis. See above.

*'''prop:''' Property node to receive the value.

*'''side:''' Optional, for split controls. Either "right" or "left"  

*'''min/max:''' Clamping applied to output value.

=====control-speed=====

Some controls (most notably flaps and hydraulics) have maximum slew rates and cannot respond instantly to pilot input. This can be implemented with a control-speed tag, which defines a "transition time" required to slew through the full input range. Note that this tag is semi-deprecated, complicated control input filtering can be done much more robustly from a Nasal script.

*'''control:''' Name of the control axis. See above.

*'''transition-time:''' Time in seconds to slew through input range.

=====control-setting=====

This tag is used to define a particular setting for a control axis inside the <cruise> or <approach> tags, where obviously property input is not available. It can be used, for example, to inform the solver that the approach performance values assume full flaps, etc...

*'''axis:''' Name of the control input (i.e. a property name)

*'''value:''' Value of the control axis.

====Winch and Aerotow====

=====hitch=====

*'''name:''' the name of the hitch. must be aerotow if you want to do aerotow via multiplayer. You will find many properties at /sim/hitches/name. Most of them are directly tied to the internal variables, you can modify them as you like. You can add a listener to the property "broken", e. g. for playing a sound.

*'''x,y,z:''' The position of the hitch

*'''force-is-calculated-by-other:''' if you want to simulate aerotowing over the internet, set this value to "1" in the motor aircraft. Don't specify or set this to zero in gliders. In a LAN the time lag might be small enough to set it on both aircraft to "0". It's intended, that this is done automatically in the future.

=====tow=====

*'''length:''' upstretched length in metres

*'''weight-per-meter:''' in kg/metre

*'''elastic-constant:''' lower values give higher elasticity

*'''break-force:''' in N

*'''mp-auto-connect-period:''' the every x seconds a towed multiplayer aircraft is searched. If found, this tow is connected automatically, parameters are copied from the other aircraft. Should be set only in the motor aircraft, not in the glider

=====winch=====

*'''max-tow-length:''' in m

*'''min-tow-length''': in m

*'''initial-tow-length:''' in m. The initial tow length also defines the length/search radius used for the mp-autoconnect feature

*'''max-winch-speed:''' in m/s

*'''power:''' in kW

*'''max-force:''' in N

===Command Line===

*'''Drag Coefficient:''' The drag coefficient of the aircraft.

*'''Lift Ratio:''' The lift ratio of the aircraft.

*'''Cruise AoA:''' The cruise AoA, from conditions at <[[YASim#cruise|cruise]]> in the xml file.

*'''Tail Incidence:''' The incidence angle of the tail, "solved" by YASim as a way to stabilize the aircraft.

*'''Approach Elevator:''' The approach elevator, from conditions at <[[YASim#approach|approach]]> in the xml file.

*'''CG:''' Center of gravity of the aircraft in coordinates. Unless it's supposed to be offset, it should always have a Y value of 0.