Aircraft-set.xml

From FlightGear wiki
Revision as of 17:12, 2 September 2017 by Wkitty42 (talk | contribs) (→‎The -set.xml file itself: remove errant syntaxhighlight closing tag)
Jump to navigation Jump to search

The aircraft-set.xml file (or rather name-of-aircraft-set.xml) is the top level aircraft configuration file. The aircraft-set.xml file should be in the aircraft's root directory, for example $FG_ROOT/Aircraft/747-400/747-400-set.xml.

When FlightGear loads an aircraft the aircraft-set.xml file is from where all the other aircraft specific configuration and other files are read in. It also can contain the meta data that is used for example when packaging the aircraft before a release of FlightGear.

Overview

The aircraft-set.xml file is an XML file that contain for example:

FlightGear allows a great deal of flexibility when it comes to how to configure an aircraft.

To help provide a more consistent experience for end users, aircraft developers are encouraged to use Release:Aircraft Selection Criteria as a guide when preparing an aircraft for inclusion in the FGAddon aircraft repository, especially if you are hoping for your aircraft to become part of the default distribution, such as the c172p for example.

The aircraft-set.xml file name

The name-of-aircraft portion of name-of-aircraft-set.xml is the name of the aircraft that is used for example when starting FlightGear from the command line (using the --aircraft=name-of-aircraft option). For example, if the file name is

  fkdr1-set.xml

Then the command line to start with that aircraft is something like:

  fgfs.exe --aircraft=fkdr1

Multiple aircraft-set.xml files

This naming convention gives you the opportunity to create two (or more) aircraft within the aircraft package root directory. For instance one could create two versions of an aircraft using different FDMs, but sharing many or most other features (and .xml files/models), using the following file names:

 fkdr1-yasim-set.xml
 fkdr1-uiuc-set.xml

Not used for loading multiplayer aircraft

The aircraft-set.xml aircraft name is not used when loading models in multiplayer. As only the model and animations are of interest, instead the path to the aircraft model is transmitted with the multiplayer packets (in essence the string in the /sim/model/path property).

There is also a feature that will load an AI aircraft model if it shares the same path, in essence from

$FG_ROOT/AI/Aircraft/Aircraft-name/Models/Model-and-animation-configuration.xml

instead of

$FG_ROOT/Aircraft/Aircraft-name/Models/Model-and-animation-configuration.xml

Note that the AI aircraft model need not be an XML file with a model and animation configuration, but can also be a plain .ac (AC3D) file with a 3D model.

Unfortunately, as this feature have been rather unknown and possibly undocumented for many years, few aircraft developers have provided such a model with their aircraft.

Needless to say, aircraft developers are highly encouraged to provide such a model with the aircraft.

The property tree

1rightarrow.png See Property tree for the main article about this subject.

The property tree contain a tree-like representation of various key-value pair properties that are used for configuration of and communication between different parts of FlightGear.

Most of the properties can be set using various configuration files and can be manipulated while FlightGear is running. Some of them are manipulated by FlightGear itself, some by the FDM, some by aircraft systems and Nasal scripts. Properties can also be manipulated manually when FlightGear is running using the property browser.

The -set.xml file itself

The aircraft-set.xml file is a PropertyList XML file that will configure properties in the property tree when an aircraft is loaded. Properties can also be added as needed.

While the aircraft-set.xml file is very flexible and can be dauntingly complex for some aircraft this description will only deal with the most commonly used tags within the <sim> tags.

Note  Most of these tags are optional.
<?xml version="1.0" encoding="UTF-8"?>
<PropertyList>
 <sim>

XML file header and opening <PropertyList> and <sim> tags

  <description><!-- Short description of the aircraft --></description>

The description that will be shown in the aircraft selection dialog of FGRun and other GUIs.

  <aircraft-version><!-- Version --></aircraft-version>

Version of the aircraft. Often the date of the last change or a version number.

  <rating>
   <FDM type="int"><!-- 1..5 --></FDM>
   <systems type="int"><!-- 1..5 --></systems>
   <cockpit type="int"><!-- 1..5 --></cockpit>
   <model type="int"><!-- 1..5 --></model>
  </rating>
  <!-- or -->
  <status></status>

Either the aircraft rating or development status. The aircraft ratings uses the the criteria outlined in the article Aircraft rating system, that gives a reasonably objective rating based on the availability and quality of various aspects of the aircraft. The aircraft rating system has been available since about FlightGear 2.0. The development status usually is either of Alpha, Beta, Production or Stable, in essence the developments statuses often used in software development.

When using the aircraft rating system, a development status is applied automatically based on the ratings.

  <author><!-- Name of author (development area), Name of author (development area), etc. --></author>

Names of the authors. If multiple people worked on an aircraft, the specific development area for each person is often shown within parenthesis after the name.

  <flight-model><!-- FDM --></flight-model>

The FDM the aircraft is using. Use yasim for YASim and jsb for JSBSim.

  <aero><!-- Truncated file path --></aero>

The filename of the FDM file, without .xml. For instance, if your FDM file is sopwithCamel1F1.xml, the aero section would look like <aero>sopwithCamel1F1</aero>.

The next section is the <startup> section, which can contain two elements:

  <splash-texture><!-- File path --></splash-texture>

Path to an image you would like to show during loading of the aircraft. FlightGear will randomly pick one of the generic splashes in $FG ROOT/Textures/ when this line is not found in the aircraft-set.xml file.

  <splash-title><!-- Title --></splash-title>

A small text to be shown above the splash texture during loading of an aircraft.

Example:

 <startup>
  <splash-texture>images/splash.jpg</splash-texture>
  <splash-title>My Aircraft!</splash-title>
 </startup>


  <model>
   <path><!-- File path --></path>
  </model>

The file path to either a plain .ac (AC3D) 3D model or a model and animation configuration XML file.

This path is also used when loading multiplayer aircraft. For more details, see the #Not used for loading multiplayer aircraft section above.

  <sound>
   <path><!-- File path --></path>
  </sound>

The path to a sound configuration XML file. If for example you find a nice WAV file of the jet engine you're using, you can fix it up with your favorite sound editor so it loops nicely and include that into your model (I've noticed a few models where it can get quite annoying when the loop length is so small you can really notice it) so make it smooth.

  <panel>
   <path><!-- File path --></path>
  </panel>

File path to the 2D panel configuration XML file. We prefer 3D cockpits, which are linked in the model .xml file.

  <autopilot>
   <path><!-- File path --></path>
  </autopilot>

File path to the autopilot configuration XML file. For details, see for example Autopilot configuration reference.

 <checklists include=""/>  <!-- File name -->

Configuration XML file defining a checklist (available since version 3.0).

 <variant-of><!-- Aircraft --></variant-of>

Since 3.6, there is a new <variant-of> tag that can be added. This is used by the integrated Qt5 launcher to easily select a variant of an aircraft. For example, the BAe Sea Harrier FA2 is a variant of the BAe Sea Harrier, and the Cessna 172P - Canvas Demo is a variant of the Cessna 172P. Additionally, this could be used for different startup situations too.

Example from the 777-200ER-set.xml: <variant-of>777-200</variant-of>

 </sim>
<PropertyList>

Closing <sim> and <PropertyList> tags

Related content