Howto:Make an aircraft

From FlightGear wiki
Revision as of 07:05, 4 September 2011 by Flug (talk | contribs)
Jump to navigation Jump to search
This article is a stub. You can help the wiki by expanding it.

There are many things required to develop an aircraft for FlightGear. We encourage new aircraft developers to start their 'career' by modifying and enhancing existing aircraft. It is much easier to do and gives you a giant advantage by the time you create an aircraft completely by yourself.

The content in this article gives a summary of codes and can be found on most planes. So, for examples on how it's used, you can take a look at some random planes.

Additional information is available in a special forum topic.

Before you start

If you are a complete beginner, knowing the processes involved will help out quite a bit. Roughly 4 simplified steps, first creating your 3d model, then the FDM, followed by creating animations and finally to implement systems. Each aircraft in FlightGear has two main development areas:

  1. The Flight Dynamics Model (FDM): This tells the computer how your aircraft reacts to various conditions. The FDM is composed of two main models most people use, either JSBSim or YASim. Or the lesser used model UIUC. Define the dimensions, mass-and-balance data. Tell FlightGear which part of your aircraft and where it may hit the ground. Where the gear is, if and how it travels. How it is propelled and how it flies if you move the controls. A subarea of the FDM are integral systems like the autopilot and fuel systems.
  2. The appearence of the aircraft, which can be split in two areas:
    1. 3-dimensional model and all of its visual aspects: animations (These give visual feedback from your FDM. Move the aileron of your 3D model when the aileron control is moved. Same for the other aero surfaces, the gear. Than go ahead with the instruments, animate the needles, the digital readouts. Define hot spots and pick animations, so you can click in your 3D cockpit.), lighting and textures (images that are put in specific locations on the 3D model).
    2. auditory (sounds).

Rules and guidelines

  • All images in FlightGear should be sized to powers of two (eg. 64*64, 128*256 or 16*1024). Since FlightGear 1.9, images no longer have to be saved in the .rgb format. Right now .png is most common used among FlightGear developers.
  • Please note that we use spaces in our codes, some developers use rather tabs, to make our code easy(er) to read. Every line that starts a new tag, we press the space key once, so you get a kind of stairs. It does not really matter what method you use, as long as you use it consistently throughout all of your files.
  • Filenames and directories are case-sensitive on most OS's. Windows is not case-sensitive, so when you are developing on a Windows machine, you won't notice any problems. On other OS's, there is a difference between 'Boeing' and 'boeing'. Since FlightGear is used on multiple platforms, make sure your code makes correct usage of capitals.

Tools of the Trade

If you realize this is harder than you expect, don't worry. For the first-timer, the FDM(aircraft.xml), aircraft-set.xml, and the engine.xml files are the easiest. Modeling will require considerable time and practice. You want to have the tools for the job, so here are some tools to help:

  • Aeromatic (works only for JSBSim, gives you entire engine file and FDM (aircraft.xml) file.
  • JSBSim Commander (Only JSBSim, helps with the multitude of tags, try this on your aircraft BEFORE you release it and AFTER you are finished with all the xmls)
  • This wiki
  • Flightgear Forum
  • Design plans and specifications of your aircraft, including:
    • Three-View Plan (shows front view, top view, side view)
    • Technical Specifications (from Wikipedia, Boeing, or Airbus)
    • NOTE: Implement the specifications into the xmls
  • A friend, and/or another developer, let's say you only want to do the FDM and XMLs. You'll need another person (a modeller) to model. Don't worry, the <author> tag has enough room. ;)
  • 6 days for xmls + 2 weeks for modeling
  • your patience

Directories and files

The data created during development results in many files, which are stored in several directories per aircraft. Each aircraft has its own directory in the $FG_ROOT/Aircraft/ directory. The first thing to do when you start working on a new aircraft is to make a directory for it. A short version of the aircraft name (eg. harrier), or its serial number (eg. 747-400) is prefered. More directories might be needed further on, but we will create them when we need them. They are explained in this article, but you can skip them if you are working on your first aircraft. For now we create one directory, namely:

  • Models/ all files related to the appearence of the model are saved in this directory.

All paths are relative to $FG ROOT, with the exception of some that are explicit noted.

  • Hint for Developers: You can pre-test all your .xml files without having to load FlightGear by opening them with Internet Explorer or Mozilla Firefox. These web browsers will parse XML documents and let you know if you made a mistake coding them.

The .xml file (FDM)

This file contains the entire (or partial) Flight Dynamics Model of the aircraft. We have three different systems; they all have their up- and downsides.

With limited data available, YASim is generally considered to be the best way to go. When you have acces to real windtunnel data and/or require more flexibility, JSBSim might be a better choice.

The -set.xml file

This is the most important file of a FlightGear aircraft. This is the only file that is read directly by FlightGear. Actually it can be compared with an airport hub (from where flights of a certain airline to all other airports departure and arrive). The -set.xml file leads FlightGear to all files that are needed to simulate the aircraft. The -set.xml file should be stored in the aircraft's root directory (eg. $FG_ROOT/Aircraft/747-400/)

The -set.xml file gives your aircraft its 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.

For instance, if the filename is

  fkdr1-set.xml

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

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

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

The -set.xml file gives your aircraft its properties

Most XML files in FlightGear use the so called Property List format. Always begin the -set.xml file with:

<PropertyList>
 <sim>

and close the file with:

 </sim>
</PropertyList>

The following tags are to be placed between the <sim> and </sim> tags.

<description></description>

The text that is to be shown in the aircraft selection dialog of FGRun and other GUIs.

<aircraft-version></aircraft-version>

Commonly shows the latest update date.

<status></status>

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.

See Formalizing Aircraft Status for guidelines.

<author></author>

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>

What FDM system is the aircraft using. Set to 'yasim' for YASim and to 'jsb' for JSBSim.

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

You have created this file earlier on at: #The .xml file (FDM)

<splash-texture></splash-texture>

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 $FG ROOT/Textures/ when this line is not found in the -set.xml file.

<splash-title></splash-title>

Adds small text (above the splash texture) to the loading screen.

<model><path></path></model>

Where to find the model. Could be an .ac file (plain model format) or .xml if you want to have extras like animations etc.

<sound><path></path></sound>

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 $FG ROOT/Docs/README.xmlsound

<panel><path></path></panel>

Where to find the (2D) panel. We prefer 3D cockpits, which are linked in the model .xml file.

<autopilot><path></path></autopilot>

Where to find the autopilot system.

Engines/ directory

Only required for JSBSim aircraft. In this directory the engine and thruster/propeller files are stored.

Models/ directory

This directory contains all model related files; such as textures, models and animation files (.xml). In the -set.xml file we've set the path to one .xml file. That file should link (indirect) to each other model file (including a possible 3D cockpit) needed for the plane. The whole plane could be modeled into one file, but most developers prefer to split things up. A cockpit for example can be built up by several files, each existing of just one instrument or panel. This way it is easy to (re)move certain parts of the aircraft. You set up your model file like this:

 <PropertyList>
 
 <path>Aircraft.ac</path>
 
 <model>
  <name>Cockpit</name>
  <path>Aircraft/.../Models/cockpit.xml</path>
  <offsets>
   <x-m> -5.25</x-m>
   <y-m>  0.00</y-m>
   <z-m>  1.30</z-m>
  </offsets>
 </model>
 
 <animation>
  <type>rotate</type>
  <object-name>AileronLeft</object-name>
  <property>/controls/flight/aileron</property>
  <factor>-65</factor>
  <center>
   <x-m> 2.09</x-m>
   <y-m>-5.50</y-m>
   <z-m>-1.50</z-m>
  </center>
  <axis>
   <x>1</x>
   <y>0</y>
   <z>0</z>
  </axis>
 </animation>
 
 </PropertyList>

The cockpit.xml file can contain a similair structure, with all the instruments as seperate models. The amount of models is not limited, nor is the amount of animations.

A detailed article about animating and models can be found in Howto: 3D Aircraft Models.

A common subdirectory is the Liveries/ one, which holds the livery files. See Livery over MP for more information about that subject.

Nasal/ directory

All Nasal code specific to the aircraft is placed in this directory, with the exception of some system or instrument specific Nasal. If a certain Nasal script is usefull for all aircraft (eg. weather or multiplayer related) it can be placed in the $FG ROOT/Nasal directory. Nasal scripts that are useable on multiple aircraft (eg. air-air refueling) can be found in the $FG ROOT/Aircraft/Generic directory.

Sounds/ directory

What is an airliner without the sound of its mighty engines, or a glider without the sound of wind blowing around your face? Sounds are quite important to increase the feeling that you are actually into the simulation. In this directory all sound files that are specific for the aircarft are stored. Sounds that can be used on multiple aircraft (eg. the click of a switch or thunder) are available in the $FG ROOT/Sounds directory.

Tutorials/ directory

A helpfull feature in learning how to start the engines of a plane, flying a basic leg etc. is FlightGears tutorial system. It allows you to create a step by step tutorial that guides the user through a certain procedure. It can even indicate what switches should be pressed!

More about the tutorial system can be found at Tutorials.

Comments in XML files

We can place extra information in XML files, that will be ignored by FlightGear. Such as descriptions and explanations of certain XML markups, changelogs etc.

These will be mainly useful to other developers working with your XML code, for example when updating/maintaining your files, or when borrowing XML code from your work.

 <!-- Last update: 09-10-2007 -->

Related content