PropertyList XML files

This page is meant is introduce new FlightGear users to the PropertyList XML file format used in FlightGear, this is basically an XML based file format specifically created for use by the FlightGear Property Tree.

For additional background information, you'll also want to refer to $FG_ROOT/Docs/README.introduction.

Most configuration files in FlightGear are XML-encoded property lists. PropertyList-encoded XML files use a subset of XML to map the property tree to XML space and vice versa. PropertyList-XML files are the main mechanism to populate the FlightGear property tree (or a sub branch of it) from XML files, but also to serialize (save) property tree/branch state to an XML file. XML attributes are mainly used as meta-directives for the property tree.

Not everything that is read from an XML file resides in the main property tree; some subsystems also use XML files for initial configuration information. There are different kinds of data. The property tree is meant to represent the shared state of the program; when a subsystem happens to use an XML file to set up its internal state -- information that is of no use to the rest of the program and that cannot be changed without a reinit. Temporary trees are usually deleted as soon as the subsystem is set up (i.e. they exist for perhaps 0.1 sec). We could just as easily use another format for internal initialization, but since the XML support is already available, it was the easiest route.

FlightGear is getting more sophisticated -- there's more to learn if you want to customize things, but that's only because there's so much more that you can customize.

The config files serve many different purposes; using the XML-based property-list format for all of them helps a lot, since it allows some common structure and reusable code among all the formats. Imagine if we had one file format for preferences, a different one for panels (say, with fixed-length fields), a different one for saving a flight (perhaps a binary format), another one for sound configuration (perhaps an INI file), a different one for top-level aircraft configuration (perhaps CSV), yet another one for configuring 3D models (perhaps embedded data strings in the 3D files themselves), etc. etc.

We have config files for totally different purposes, and the fact that they all use XML is simply a convenience for programmers and customizers. Here are some of the conventions that we've come up with so far, partly ad-hoc (all paths relative to $FG_ROOT):

• preferences.xml - the top-level default preferences
• joysticks.xml - default joystick bindings, included by preferences.xml
• keyboard.xml - default keyboard bindings, included by preferences.xml
• Aircraft/*-set.xml - aircraft-specific settings, overriding the defaults in preferences.xml (and joystick/keyboard.xml)

Basically, these are the main files in the base package that affect FlightGear's main property tree. Other files use the property-file format for convenience to populate various data structures, but they do not touch the main tree and are not accessible through the property browser or through the command-line --prop: option; it's just a coincidence that they also use the property-list format:

• materials.xml - define the materials (textures, colour, lighting) for use in the scenery
• HUDS/**/*.xml - configuration files to define the various heads-up displays
• Aircraft/*/*-sound.xml - configuration files to define sounds played for various aircraft
• Aircraft/*/Panels/*-panel.xml - configuration files to define 2D panels for various aircraft.
• Aircraft/*/Instruments/*.xml - configuration files for individual instruments included by the 2D panels.
• Aircraft/Instruments/*.xml - ditto

We also use some XML-based formats that do not (yet?) follow the property-list conventions, including the following:

• Aircraft/*/*.xml - JSBSim aero model config files
• Aircraft/Aircraft-yasim/*.xml - YASim aero model config files
• Engine/*.xml - JSBSim engine and thruster config files

YASim and JSBSim each uses its own XML format, which is different from the XML format used by the rest of FlightGear. For YASim, see $FG_ROOT/Aircraft-yasim/README.yasim in the base package; for JSBSim, see the documentation at http://jsbsim.sourceforge.net/. UIUC uses a non-XML config-file format.

To work with PropertyList-XML files, you can use various means, such as:

• fgcommands
• Nasal (props.nas, io.nas)
• C++ APIs (see links at the end of the navigation sidebar)

There are several places to look for properties; one is in the aircraft files, another is all Nasal files, and the last place (and often most useful!) is grepping (searching) through the C++ code. To determine how a property works and what it does often requires looking through any code that uses it. This is a part of FlightGear that we could certainly document better .

As for the relationship between XML and the Property Tree, in some cases in FG (most notably preferences.xml and each AIRCRAFT-set.xml file), the <PropertyList> format directly defines properties in FlightGear's global property tree. In other cases, like the animation files given by /sim/model/path, those do not define properties but the <PropertyList> format is used as a matter of convenience so that FG can parse all of its XML files using the same mechanism and to keep the fundamental structure the same. XML has a lot of different dialects, and having only one for FlightGear really makes it easier, especially since it is very intuitive

The root element of each file is always named <PropertyList>. Tags are almost always found in pairs, with the closing tag having a slash prefixing the tag name, i.e </PropertyList>. The exception is the tag representing an aliased property. In this case a slash is prepended to the closing angle bracket.

A minimal example of a complete property list encoded XML file, looks like this:

 <?xml version="1.0" encoding="UTF-8"?>
 <PropertyList>
  
 </PropertyList>

Property typing is optional, all properties are by default string/unspecified and are transparently converted by the property tree:

 <?xml version="1.0" encoding="UTF-8"?>
 <PropertyList>
  <foo type="string">Hello</foo>
  <pi type="float">3.14</pi>
  <boo type="bool">true</boo>
 </PropertyList>

Indexing happens implicitly for identically named properties:

 <?xml version="1.0" encoding="UTF-8"?>
 <PropertyList>
  <foo>Hello</foo> 
  <foo>Hello</foo>
  <foo>Hello</foo>
 </PropertyList>

so that the three foo tags become foo[0], foo[1], foo[2] in the property tree.

You can also use explicit indexing by setting the 'n attribute of each tag:

 <?xml version="1.0" encoding="UTF-8"?>
 <PropertyList>
  <foo n="0">Hello</foo> 
  <foo n="1">Hello</foo>
  <foo n="2">Hello</foo>
 </PropertyList>

To make property settings persistent in between FlightGear sessions, use the userarchive attribute:

 <?xml version="1.0" encoding="UTF-8"?>
 <PropertyList>
  <foo userarchive="y">Hello</foo> 
 </PropertyList>

For further information please refer to $FG_ROOT/Docs/README.introduction and $FG_ROOT/Docs/README.properties.

Also see

• http://flightgear.org/forums/viewtopic.php?f=18&t=19503