Aircraft-set.xml: Difference between revisions

Jump to navigation Jump to search

Aircraft-set.xml (view source)

Revision as of 15:52, 2 October 2015

3,662 bytes added ,  2 October 2015
Some more cleanup. Still more to go though
(More comprehensive first section; Moved some content to a section with typical content; Proper heading levels; +rel; Still a lot to do...)
(Some more cleanup. Still more to go though)
Line 1: Line 1:
''See also: [[Aircraft Generation Wizard]] (stalled as of 12/2013)''
''See also: [[Aircraft Generation Wizard]] (stalled as of 12/2013)''


The '''aircraft-set.xml''' file (or rather &lt;name-of-aircraft&gt;-set.xml) is the top level aircraft configuration file.  The aircraft-set.xml file should be in the aircraft's root directory, for example <code>[[$FG_ROOT]]/Aircraft/747-400/747-400-set.xml</code>.
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 <code>[[$FG_ROOT]]/Aircraft/747-400/747-400-set.xml</code>.


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


== Typical content ==
== Overview ==
The aircraft-set.xml file is a [[PropertyList XML files|PropertyList XML file]] that contain for example:
The aircraft-set.xml file is an XML file that contain for example:


* A header with a description and names of the authors
* A header with for example a description and names of the authors
* [[Aircraft rating system|Aircraft ratings]] that can be used to select only the more well developed aircraft (or bad ones if you are looking for aircraft to improve)
* [[Aircraft rating system|Aircraft ratings]] that can be used to select only the more well developed aircraft (or bad ones if you are looking for aircraft to improve)
* [[Howto:Reassign keyboard bindings|Keyboard bindings]]
* [[Howto:Reassign keyboard bindings|Keyboard bindings]]
* Paths to [[Nasal]] modules
* Paths to [[Nasal]] modules
* Paths to configuration files for the [[Flight Dynamics Model|flight dynamics model]], [[Howto:Animate models|3D models and their animations]], [[Autopilot configuration reference|autopilot]], [[Howto:Add sound effects to aircraft|sound]] etc.
* Paths to configuration files for the [[Flight Dynamics Model|flight dynamics model]] (FDMs), [[Howto:Animate models|3D models and their animations]], [[Autopilot configuration reference|autopilot]], [[Howto:Add sound effects to aircraft|sound]] etc.
 
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.
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 -set.xml file gives your aircraft its name ==
== The aircraft-set.xml file name ==
The name of the -set.xml file gives the aircraft its official name withing FlightGear--for instance, the name that is used to select that aircraft on the command line when FlightGear is started, and the name that is used to match an aircraft running on one computer with the corresponding multiplayer aircraft shown on a different computer on the multiplayer network.
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 <code>--aircraft=''name-of-aircraft''</code> option). For example, if the file name is
 
For instance, if the filename is


   fkdr1-set.xml
   fkdr1-set.xml
Line 27: Line 27:
   fgfs.exe --aircraft=fkdr1
   fgfs.exe --aircraft=fkdr1


This naming convention gives you the opportunity to create two (or more) aircraft within one directory--for instance, create versions of your aircraft using two different FDMS, but sharing many or most other features (and .xml files/models):
=== 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-yasim-set.xml
   fkdr1-uiuc-set.xml
   fkdr1-uiuc-set.xml


== The -set.xml file gives your aircraft its properties ==
=== Not used for loading multiplayer aircraft ===
The aircraft-set.xml aircraft name is not used when loading models in [[Howto:Multiplayer|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 <code>/sim/model/path</code> [[Property tree|property]]).
 
There is also a feature that will load an AI aircraft model if it shares the same path, in essence from


Most XML files in FlightGear use the so called [[PropertyList XML File|Property List]] format.
[[$FG_ROOT]]/'''AI'''/Aircraft/''Aircraft-name''/Models/''Model-and-animation-configuration''.xml
Always begin the -set.xml file with:


<PropertyList>
instead of
  <sim>


and close the file with:
$FG_ROOT/Aircraft/''Aircraft-name''/Models/''Model-and-animation-configuration''.xml
 
  </sim>
</PropertyList>


The following tags are to be placed between the <sim> and </sim> tags.
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.


=== <description></description> ===
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.
The text that is to be shown in the aircraft selection dialog of [[FGRun]] and other GUIs.


=== <aircraft-version></aircraft-version> ===
Needless to say, aircraft developers are highly encouraged to provide such a model with the aircraft.
Commonly shows the latest update date.


=== <status></status> ===
== The property tree ==
The status of the development of your plane. This can for example be used in order to get a list of aircraft with a certain minimum development status by passing the --min-status= parameter to the fgfs executable.
{{main article|Property tree}}


See [[Formalizing Aircraft Status]] for guidelines.
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 files|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 <code>&lt;sim&gt;</code> tags.
 
 
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<PropertyList>
<sim>
</syntaxhighlight>
 
XML file header and opening <code>&lt;PropertyList&gt;</code> and <code>&lt;sim&gt;</code> tags
 
<syntaxhighlight lang="xml">
  <description><!-- Short description of the aircraft --></description>
</syntaxhighlight>


=== <author></author> ===
The description that will be shown in the aircraft selection dialog of [[FGRun]] and other GUIs.
Place your name(s) here. If multiple people worked on the same aircraft, you can place the specific development area for each person between ( ).


=== <flight-model></flight-model> ===
<syntaxhighlight lang="xml">
What FDM system is the aircraft using. Set to 'yasim' for [[YASim]] and to 'jsb' for [[JSBSim]].
  <aircraft-version><!-- Version --></aircraft-version>
</syntaxhighlight>


=== <aero></aero> ===
Version of the aircraft. Often the date of the last change.
The filename of the FDM file, without .xml.  


For instance, if your FDM file is sopwithCamel1F1.xml, the aero section would look like:
<syntaxhighlight lang="xml">
  <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>
</syntaxhighlight>


  <aero>sopwithCamel1F1</aero>
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 3.0.  The development status usually is either of ''Alpha'', ''Beta'', ''Production'' or ''Stable'', in essence the developments statuses often used in software development.


You have created this file earlier on at: [[#The .xml file (FDM)]]
When using the aircraft rating system, a development status is applied automatically based on the ratings.


=== <splash-texture></splash-texture> ===
<syntaxhighlight lang="xml">
Place the location of an image you would like to show during loading of the aircraft. FlightGear will randomly pick one of the generic splashes in <tt>[[$FG ROOT]]/Textures/</tt> when this line is not found in the -set.xml file.
  <author><!-- Name of author (development area), Name of author (development area), etc. --></author>
</syntaxhighlight>


=== <splash-title></splash-title> ===
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.
Adds small text (above the splash texture) to the loading screen.


=== <model><path></path></model> ===
<syntaxhighlight lang="xml">
Where to find the model. Could be an .ac file (plain model format) or .xml if you want to have extras like animations etc.
  <flight-model><!-- FDM --></flight-model>
</syntaxhighlight>


=== <sound><path></path></sound> ===
The FDM the aircraft is using.  Use <code>yasim</code> for [[YASim]] and <code>jsb</code> for [[JSBSim]].
The path to your aircraft's sound file, do not include if you don't have one. The pitch and volume of the sound is controlled by the xml file and throttle position. 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.


For additional information, you'll want to check out <tt>[[$FG ROOT]]/Docs/README.xmlsound</tt>
<syntaxhighlight lang="xml">
  <aero><!-- Truncated file path --></aero>
</syntaxhighlight>


=== <panel><path></path></panel> ===
The filename of the FDM file, without <code>.xml</code>.  For instance, if your FDM file is sopwithCamel1F1.xml, the aero section would look like <code><nowiki><aero>sopwithCamel1F1</aero></nowiki></code>.
Where to find the (2D) panel. We prefer 3D cockpits, which are linked in the model .xml file.


=== <autopilot><path></path></autopilot> ===
<syntaxhighlight lang="xml">
Where to find the [[autopilot]] system.
  <splash-texture><!-- File path --></splash-texture>
</syntaxhighlight>
 
Path to an image you would like to show during loading of the aircraft.  FlightGear will randomly pick one of the generic splashes in <code>[[$FG ROOT]]/Textures/</code> when this line is not found in the aircraft-set.xml file.
 
<syntaxhighlight lang="xml">
  <splash-title><!-- Title --></splash-title>
</syntaxhighlight>
 
A small text to be shown above the splash texture during loading of an aircraft.
 
<syntaxhighlight lang="xml">
  <model>
  <path><!-- File path --></path>
  </model>
</syntaxhighlight>
 
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.
 
<syntaxhighlight lang="xml">
  <sound>
  <path><!-- File path --></path>
  </sound>
</syntaxhighlight>
 
The path to a [[Howto:Add sound effects to aircraft|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.
 
<syntaxhighlight lang="xml">
  <panel>
  <path><!-- File path --></path>
  </panel>
</syntaxhighlight>
 
File path to the 2D panel configuration XML file.  We prefer 3D cockpits, which are linked in the model .xml file.
 
<syntaxhighlight lang="xml">
  <autopilot>
  <path><!-- File path --></path>
  </autopilot>
</syntaxhighlight>
 
File path to the autopilot configuration XML file.  For details, see for example [[Autopilot configuration reference]].
 
<syntaxhighlight lang="xml">
</sim>
<PropertyList>
</syntaxhighlight>


More info here: http://wiki.flightgear.org/XML#3._Data
Closing <code>&lt;sim&gt;</code> and <code>&lt;PropertyList&gt;</code> tags


== Checklists ==
== Checklists ==
Line 117: Line 191:


== Related content ==
== Related content ==
* [[Aircraft Generation Wizard]] (stalled as of 12/2013)
* [[Aircraft rating system]]
* [[Aircraft rating system]]
* [[Howto:3D Aircraft Models]]
* [[Howto:Add sound effects to aircraft]]
* [[Howto:Add sound effects to aircraft]]
* [[Howto:Animate models]]
* [[Howto:Animate models]]
Retrieved from "https://wiki.flightgear.org/Special:MobileDiff/87619"

Navigation menu