Aircraft-set.xml

From FlightGear wiki
Revision as of 13:51, 1 February 2019 by Stuart (talk | contribs) (Reverted edits by Rudolf (talk) to last revision by Stuart)
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 the main source of information, about other files to load, such as the 3D model and FDM configuration. It also contains meta data that is important when packaging the aircraft before a release of FlightGear, or when searching for aircraft in the UI (for example, the launcher).

Overview

The aircraft-set.xml file is an XML file which contains many recommended pieces.

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

When creating multiple aircraft this way, it's very common to put shared XML data into a -common.xml file which is included by both of the -set.xml files. It's important that your common file does not end in -set.xml, otherwise some systems will erroneously consider the file as another aircraft. Typically the name might be fkdr1-common-sounds.xml or fokker-shared.xml - but anything is fine so long as it doesn't end in -set.xml

Note  When defining multiple versions of an aircraft, it's important to use some additional tags to link the aircraft together correctly - this improves the user experience by telling various places which -set.xml is the most important one. See below for the <variant-of> and <primary-set> tags.

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.

-set.xml Sections

The aircraft-set.xml file is a PropertyList XML file that will configure properties in the property tree when an aircraft is loaded. When you view the property tree via the in-sim inspector, the properties you see are those defined in your -set.xml, combined with all the properties defined at runtime by the FDM, instruments, renderer and so on.

Since the -set.xml can grow to become very large, it's common to break it into several pieces. This is especially important when using multiple -set.xml files to avoid code duplication, but it can be very helpful in all cases to keep the main -set.xml file clear and readable. Splitting the file up is done via the PropertyList include syntax.

Note  Most of these tags are optional.
Note  FGMeta contains a Python script fgmeta/catalog/check_aircraft.py which can validate -set.xml files and report potential problems
<?xml version="1.0" encoding="UTF-8"?>
<PropertyList>
 <sim>

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

Name & Description

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

The name that will be shown in the aircraft selection dialog of FGRun and other GUIs. It's called description but consider it the human-readable name for the aircraft. It's the primary thing users will see of your aircraft in UIs, so try to make it as informative as possible without being too long. Many authors include the manufacturer in the name, but this is not always necessary: e.e there's no need to call an aircraft 'Mikoyan-Gurevich MiG 27 ML (Flogger)'. In this case 'MiG 27ML' or 'Mikoyan MiG-27ML' is likely fine. Nickname such as the NATO reporting name here are good to include in the longer description (see next next section) since this is also searchable in the UI.

 <long-description>The Cessna 172 is the most popular general aviation aircraft in the world, with 
over 40,000 examples built. The aircraft evolved from the earlier Cessna 170, and is available with
a huge range of instruments and engines. This examples features the a Lycoming IO-360 engine
and traditional mechanical flight instruments, typical of a new aircraft from 1986.
</long-description>

A brief description of the aircraft, typically a few sentences or paragraphs. Do not including formatting in this text since it will be re-formatted by the UI. (Line breaks to separate paragraphs are ok). Since this text is also searchable, this is a good place to include nick-names or other information (eg, historical manufacturer names) to aid in discovery.

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

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


Ratings

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

The aircraft rating, using the the criteria outlined in the article Aircraft rating system, which gives a (reasonably) objective rating based on the availability and quality of various aspects of the aircraft.

Authors & Maintainers

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

  <!-- new in FlightGear 2018.3.0 style -->
  <authors>
    <author n="0">
      <name>Wilbur Wirght</name>
      <description>FDM, systems</description>
      <nick>wwright</nick>
    </author>
    <author n="1">
      <name>Orville Wirght</name>
      <description>model and sounds</description>
      <email>orville@gmail.com</email>
    </author>
  </authors>

Previously, aircraft could define a single <author> tag with a string listing the authors of the aircraft. This often ended up containing other information, and for complex aircraft, could become very long and unreadable in some places, such as the splash screen.

For FlightGear 2018.3.0 onwards there is a replacement system, based around a structured list of authors. For each author their name can be supplied, and optionally other data if desired: nickname, email and a description of what they contributed. (The strucutre of this XML deliberately matches that used for add-ons)

Both the old and and new data can co-exist to allow aircraft compatability with older versions of FlightGear.

To distinguish contributions and previous authors from active maintainers, there is a seperate maintainers section which can be provided. The syntax is the same as for the authors, but the contact email is more important. In the future this might potentially be used to contact / notify all maintainers of aircraft. (Nickname and description are not used for maintainers)

 <maintainers>
   <maintainer n="0">
       <name>Wilbur Wirght</name>
       <email>ww@wright-brothers.com</email>
    </maintainer>
 </maintainers >

Variants

When you have multiple -set.xml files in an aircraft directory, one of them should be indicated as the default or primary, and other -set.xmls should be marked as variants of this. This is important so the packaging system knows which -set.xml best describes the whole directory. It's usually quite clear what the main or principle -set.xml should be, but sometimes an arbitrary decision is needed. (For example, with the 777, should the -200 or -300 be the primary aircraft? In practice it doesn't matter)

In the main -set.xml, add the following:

  <primary-set type="bool">true</primary-set>

In each variant -set.xml, add the following:

  <variant-of>....mainAircraftName....</variant-of>

For example if the main aircraft -set.xml is 'dc3-set.xml', and the variants are 'c47-set.xml' and 'dst-set.xml', you would add:

  <variant-of>dc3</variant-of>

in both c47-set.xml and dst-set.xml. This ensures the information from dc3-set.xml will be used when describing the entire package. In this example it's clear the DC-3 should be the primary aircraft because that is the most commonly recognised version - the C-47 and Douglas Sleeper Transport are both useful variants that might exist, but DC-3 is the most generic name / variant.

Tags

The tag system allows systems to categorise aircraft, for example allowing more advanced searches in the future. Tags allow better feedback to the user when interacting with your aircraft - for example if the aircraft is tagged as towable, a glider, or a helicopter, the startup behaviour can be customised.

Most importantly, set the following tags if appropriate:

   * glider
   * helicopter
   * floats
   * skis
   * seaplane
   * airship
   * amphibious
   * vtol

These tags are the most helpful in customising the start-up experience based on the type of aircraft. (Especially, which starting locations are offered / preferred when searching)

<tags>
    <tag n="0">boeing</tag>
    <tag n="1">vtol</tag>
    <tag n="2">glider</tag>
</tags>

Urls

Beginning with FlightGear 2018.3.0, aircraft can list significant URLs, such as their home page, support forum or code repository. Again the format matches that uses for add-ons:

<urls>
  <home-page>http://wiki.flightgear.org/UFO_from_the_%27White_Project%27_of_the_UNESCO</home-page>
  <support>http://forum.flightgear.org</support>
  <wikipedia>https://en.wikipedia.org/wiki/Unidentified_flying_object</wikipedia>
  <code-repository>https://sourceforge.net/p/flightgear/fgdata/ci/next/tree/Aircraft/ufo/</code-repository>
</urls>

The support URL is perhaps the most important, to direct users to a forum or bug-tracker where they can ask questions or report issues with the particular aircraft. Note that while multiple URLs of each type are in theory permitted, at the moment only the first one of each type will be used in the UI. (This may change in the future)

Previews

The preview system allows UI to show a visual preview of the aircraft during startup, on the website, and in the launcher. Several images can be provided, showing the aircraft exterior and interior. These are also used to provide an improved splash-screen experience, replacing the older system described below. Images should be 1024x768 with no text (as that is added dynamically) and minimal post-processing.

<previews>
  <preview>
    <type>exterior</type>
    <splash type="bool">true</splash>
    <path>Previews/exterior-1.png</path>
  </preview>
  <preview>
    <type>exterior</type>
    <splash type="bool">true</splash>
    <path>Previews/exterior-f16a-2.png</path>
  </preview>
  <preview>
    <type>panel</type>
    <splash type="bool">false</splash>
    <path>Previews/cockpit.png</path>
  </preview>
</previews>

Previews are tagged to allow automatic selection for certain use cases. It's recommended to include at least one exterior, daytime shot of the aircraft, and one interior shot fo the main instrument panel from the pilot's viewpoint. Beyond this any image of the aircraft is acceptable. Avoid including logo, badge or text elements in preview images since this gives poor quality results and restricts how the images can be used - different uses of the images will composite their own elements on top.

Preview file paths are relative to the -set.xml file. Permitted types at present are exterior and panel - the type can also be committed. By default all previews are considered for random selection as the splash screen - to prevent a particular preview being used as the splash screen, set the splash tag to false.

Flight-model (FDM)

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

Startup

The startup section contains information used to show the splash screen for your aircraft. The recommend approach is to use the previews system described above, optionally marking some previews as suitable or unsuitable for use as a splash screen. When using the previews system to provide a splash screen, you can optionally provide a logo image. This replaces the default text (containing the aircraft name) with a presumably partially-transaprent overlay, allowing more interesting graphics to be displayed on the splash screen.

  <sim>
    <startup>
      <splash-logo-image>beechcraft-logo.png</splash-logo-image>
    </startup>
  </sim>

When using a logo image, it should be a PNG with an alpha channel enabled, and will be blended over the selected preview image automatically. At present the placement is hard-coded, but this could be extended- if you'd like this added please ask on the developer mailing list.

The legacy splash screen system does not use previews, but instead uses the following syntax:

  <sim>
    <startup>
      <splash-texture n="0"><!-- File path --></splash-texture>
      <splash-texture n="1"><!-- File path --></splash-texture>
    </startup>
  </sim>

Because old splash screens typically included text and logo elements, the splash screen appearance is different in this case, to ensure all text is legible. (Information added by FlightGear such as version and startup progress, is moved to avoid overlapping, and the scaling behaviour is different)

Visual aircraft model

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

Performance and Flight-planning

From FlightGear 2018.3.0 onwards, it's possible to include additional data to improve user feedback and flight-plan creation. Note this information lives under the top-level aircraft tag, and not under sim as all the content above does.

<aircraft>
  <icao>
    <wake-turbulence-category>M</wake-turbulence-category>   <!-- L = light, M = medium, H = heavy, J = jumbo -->
    <type type="string">B738</type>  <!-- eg B738, C172, BE9L -->
    <!-- ICAO equipment string  -->
    <equipment type="string">SDFGY</equipment>
    <!-- ICAO surveillance string  -->
    <surveillance type="string">S</surveillance> <!-- mode-S transponder -->
  </icao>
</aircraft>

This information is useful in pre-filling an ICAO standard flight-plan based on the aircraft and equipment. In the future it may be reported automatically to ATC clients / networks. To find out the officially registered ICAO type string for an aircraft, ICAO provides a lookup service

<aircraft>
  <performance>
    <minimum>
      <takeoff-length-ft type="int">6000</takeoff-length-ft>
      <landing-length-ft type="int">4000</landing-length-ft>
    </minimum>
    <climb>
      <!-- potential for climb data in the future 
      <airspeed-knots type="int">280</airspeed-knots>
      <vertical-speed-fpm type="int">2000</vertical-speed-fpm>
      -->
    </climb>
    <cruise>
      <airspeed-knots type="int">400</airspeed-knots>
      <!--  <mach type="double">0.875</mach> -->
      <altitude-ft type="int">4500</altitude-ft>
      <!-- <flight-level type="int">330</flight-level> -->
    </cruise>
    <descent>
      <!-- potential for descent data in the future 
      <airspeed-knots type="int">330</airspeed-knots>
      <vertical-speed-fpm type="int">-1200</vertical-speed-fpm>
      -->
    </descent>
    <approach>
      <airspeed-knots type="int">120</airspeed-knots>
    </approach>
    <maximum>
      <altitude-ft type="int">21000</altitude-ft> <!-- service ceiling -->
      <mach type="double">0.875</mach>
      <airspeed-knots type="int">180</airspeed-knots> <!-- VNe or similar airframe structural limit -->
    </maximum>
  </performance >
</aircraft>

Performance data is optional, and advisory : it does not influence the system or FDM simulation in any way. Its purpose is to inform flight-planning and user experience, especially to provide reasonable default values when the user selects starting on approach or in the air. The cruise information is valuable in generating a plausible route between two airports (for example, if Victor or Jet airways should be used), and making a crude estimate of the time enroute based on typical cruising speeds.

The minimum runway length information is helpful in preferring certain airfields when searching locations - for example when using the 777 there is little point in considering a 600ft grass strip.

Information on aircraft maximums is valuable in the UI to give feedback when the user requests values which exceed aircraft capabilities: for example starting the C172 at 50000ft altitude or 800kts. (Since we're dealing with a flight-simulation situation, we still permit such uses, but it's beneficial to be able to warn the user they are doing something which will likely not work well)

At present climb and descent information is not included, but future version of FlightGear might support this, to plan realistic climb and descent profiles for the aircraft.

Related content