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 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 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 meters. 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. 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 subelement to indicate stall behavior, control surface subelements (flap0, flap1, spoiler, slat) to indicate what and where the control surfaces are, and 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. 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. 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. 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 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. It accepts a subelement to map a property to its throttle setting, and an 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 additional thrust from the afterburner, in pounds [0]. rotate: Vector angle of the thrust in degrees about the Y axis [0]. n1-idle: Idling rotor speed [55]. n1-max: Maximum rotor speed [102]. n2-idle: Idling compressor speed [73]. n2-max: Maximum compressor 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]. propeller: A propeller. This element requires an engine subtag. Currently and 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 subelement. mass: The mass of the engine/propeller, in pounds. moment: The moment, in kg-meters^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, 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.. max-rpm: The maximum operational RPM for a constant speed propeller. See above. 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 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. turbo-mul: The turbo/super-charger pressure multiplier. Static pressure will be multiplied by this value to get the manifold pressure. wastegate-mp: The maximum manifold pressure. Beyond this, the gate will release to keep the MP below this number. (inHG). turbine-engine: A turbine engine definition. This must be a subelement of an enclosing tag. eng-power: Maximum BHP of the engine at a suitable cruise altitude. eng-rpm: The engine RPM at which eng-power is developed. Note that this is "shaft" RPM as seen by the propeller. Don't use a gear-ratio on the enclosing propeller, or else you'll get confused. :) alt: The altitude at which eng-power is developed. This should be high enough to be lower (!) than the flat-rating power. flat-rating: The maximum allowed power developed by the engine. Most turboprops are flat rated below a certain altitude and temperature range to prevent engine damage. min-n2: N2 (percent) turbine speed at zero throttle. max-n2: N2 (percent) turbine speed at max throttle. bsfc: Specific fuel consumption, in lbs/hr per horsepower. 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 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. 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. 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). solve-weight: Subtag of approach and cruise parameters. Used to specify a non-zero setting for a 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. 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/flight/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. 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 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 or 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. 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. Instead stored results from the c182 will be used. 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. 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 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 rpm: rounds per minute. ccw: determines if the rotor rotates clockwise (="false") or counterclockwise (="true"), (if you look on the top of the normal, so the bo105 has counterclockwise rotor) 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 pitch_a: A collective incidence angle, used for the next token forceatpitch_a: The force, the rotor is producing when the incident angle is equal pitch_a. I.e. hover-pitch and a force equivalent to the weight. (in pounds of force) pitch_b: A collective incidence angle, used for the next token poweratpitch_b: the power the rotor needs at pitch_b. (i.e. at the bo105 the main rotor consumes bout 90% of the engine power, and 9% the tail rotor. In kW. Used for calculation of the torque. poweratpitch_0: the power the rotor needs at zero pitch. In kW. Used for calculation of the torque. notorque: If set to "true" the calculated torque is always zero. Very helpful while adjusting rotor parameters. 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 peed of the rotor to an input. normally 1 (Maybe there are rotors with a little faster reaction, than 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 a extreme result in the behavior of the rotor 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. delta: A factor for the damping constant for the flapping. 1 means a analytical result, which is only a 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 now the maximum roll rate or ... translift: Helicopters have "translational lift", which is due to turbulence and hard to calculate, so this simulation uses a phenomenological ansatz. Use .1 for the start value dragfactor: The drag of the rotating rotor perpendicular to the rotor plane is larger than the drag of the not rotating rotor. Hard to calculate, so it is added phenomenological Any rotor needs a subelement for the engine (ROTORENGINEON) and can have subelements for the cyclic (CYCLICELE, CYCLICAIL) and collective (COLLECTIVE) input. The rotor simulation is very "beta" and not finished yet. So don't spend too much time to adjust a flight behavior to the smallest details now.