Kapitel 4
Takeoff: How to start the program

4.1 Launching the simulator

PIC

Abbildung 4.1: Ready for takeoff – Startup position at Honolulu Intl., PHNL

FlightGear comes complete with an integrated launcher to start FlightGear. On Windows, double-click on the FlightGear Launcher Start Menu item or the icon on the Desktop. Alternatively, on any system, you can run

fgfs --launcher

from the command line. The launcher allows you to select your aircraft, the starting location (you can now even start 10 miles from the runway, in a nice place for an approach, or over a specific navaid!), time of day, enable or disable TerraSync or live weather, and lots of other settings.

When you first open the launcher, you will see a dialog box to set your FG_ROOT variable, normally:

C:\Program Files\FlightGear\data or
C:\Program Files\FlightGear 2020.3.19\data

When you have set that, you will see the screen like in figure 4.2.

PIC

Abbildung 4.2: Summary of the launcher settings – Click on Fly! to start

The launcher defaults to starting a flight with the Cessna 172P at the default airport, which depends on the FlightGear release. Simply press the Fly! button to start the simulator. Alternatively, if you want to change any of your starting settings, select from the buttons on the left.

PIC

Abbildung 4.3: Aircraft Selection – Choose from a wide range of aircraft and download them automatically

You can change your aircraft by navigating to the Aircraft tab on the left of the window. FlightGear comes pre-installed with the Cessna 172P, and a UFO. To fly other aircraft, the easiest way is to add a default FlightGear hangar with hundreds of aircraft. To do this, in the Aircraft tab, click the Browse button and then the Add default hangar. The list will fill up with lots of aircraft. You may download any of the other aircraft listed simply by clicking on the Install button. You can also download aircraft from the official website and private hangars.

PIC

Abbildung 4.4: Starting Position – Choose a starting position on the ground or in the air

Selecting Location allows you to select your starting position – tied down at a parking location, on the runway ready for take-off, on approach on an ILS approach, or relative to a VOR , FIX. By default, the current selected location is displayed. To select a completely different location, click the Back button and enter the name of where within the world you want to be.

FlightGear will automatically download any required scenery (assuming you have it selected in the Settings page).

The Environment page allows you to select the time of day, season and weather modeling. You can choose to use the current real world weather conditions, or select a specific weather scenario such as a high pressure region, or a thunderstorm.

The Settings page allows you to select a variety of simulation settings, such as multiplayer, automatic scenery download and graphics options. Advanced options are available from Show More on the right.

Finally, the Add-ons page allows you to select different hangars of aircraft to download.

Once you are happy with your settings, click on the Fly! button to start the simulator.

4.2 Launching from the command line

Section 4.1 showed how to run FlightGear using its built-in launcher. Alternatively, you can run it from the command line. When doing so, you may pass options such as --fg-root and --fg-scenery, or set the corresponding environment variables named FG_ROOT and FG_SCENERY.

Note that doing such settings is not always necessary (for instance, if you compiled FlightGear yourself and passed -D FG_DATA_DIR:PATH=path to CMake, then your fgfs executable has this directory as its default FG_ROOT setting). However, if you are not using the built-in launcher and either FlightGear can’t find its base package or you want to add directories for custom scenery, then passing options --fg-root or --fg-scenery, or alternatively setting FG_ROOT or FG_SCENERY as environment variables, is likely to be helpful.

How to set environment variables largely depends on the operating system and the shell in use, if any. We’ll get into such platform-specific details after a few general comments on FG_ROOT and FG_SCENERY.

4.2.1 FG_ROOT

The value of the FG_ROOT setting is the path to a directory (folder) where FlightGear looks for its base data files (for instance, XML and Nasal files shared by several aircraft, navigational beacon locations, radio frequencies for contacting airports, shaders for graphical effects, translation files, etc.).

The contents of this directory comes directly from the FGData repository.1 If you have installed FlightGear from a binary distribution on Windows or macOS, the directory name should be data. It can also be called fgdata (typically, after cloning the FGData repository), but other names are possible: for instance, the flightgear-data-base package in Debian ships it as /usr/share/games/flightgear. This directory contains files such as version, defaults.xml and keyboard.xml as well as subdirectories such as Aircraft, Input and Nasal.

In order to run, FlightGear absolutely needs to know where to find this directory. Users of the built-in launcher are prompted to select it from the graphical interface if FlightGear hasn’t found it automatically. Unless the location recorded at compile-time points to a suitable directory, FlightGear command line users need to either set the FG_ROOT environment variable or pass the --fg-root option in order to specify an appropriate location (check that it has the aforementioned files and subdirectories).

If you are a user of the download_and_compile.sh script, the base data files are in install/flightgear/fgdata (relatively to the directory from which you ran the script), but you don’t need to use --fg-root nor to set FG_ROOT: the run_fgfs.sh script created by download_and_compile.sh automatically passes the --fg-root option to fgfs for you with the appropriate value.

In most Unix shell languages, $VAR can be thought of as “the value of variable VAR”. In explanations and documentation related to FlightGear, we often extend this notation a little bit. Typically, $FG_ROOT should be understood as “your FG_ROOT setting, regardless of the way FlightGear obtains it: compile time default, FG_ROOT environment variable or --fg-root option.”

The same kind of sloppy wording is sometimes applied to other settings such as FG_SCENERY to mean “the list of scenery paths FlightGear has been configured to use”, however this can get confusing. Indeed, the list of scenery paths considered by FlightGear is assembled from several things, including the values passed to --fg-scenery options and that of the FG_SCENERY environment variable, if set… value which is obtained via $FG_SCENERY in typical Unix shells!

4.2.2 FG_SCENERY

The scenery shown by FlightGear can be assembled from several places, and the whole is sometimes referred to as “FG_SCENERY”. This is however sloppy wording: FG_SCENERY is actually the name of an environment variable that may be used (but there are several other ways) to point FlightGear to some folders containing scenery. FlightGear can use scenery from folders listed in $FG_SCENERY as well as folders given to the --fg-scenery option, all in the same run.

The most straightforward way to obtain FlightGear scenery if you have a good Internet connection is TerraSync: with this piece of the FlightGear infrastructure, scenery for the relevant area is downloaded as you fly. TerraSync scenery is automatically updated when you fly again to the same place. FlightGear can also use folders containing scenery that isn’t managed by TerraSync; this is how “custom scenery” is used.

For users of the built-in launcher, enabling or disabling TerraSync is done under Downloads in the Settings tab: from there, you can enable or disable automatic scenery download and choose where the resulting files are stored (they can easily take up several gigabytes). Scenery directories not managed by TerraSync can be set in the Add-ons tab under Additional scenery folders.

For people who start FlightGear from the command line, TerraSync can be enabled or disabled with --enable-terrasync and --disable-terrasync. In order to choose where TerraSync stores the resulting files, you can use --download-dir or --terrasync-dir (if both are set, the latter takes precedence).

If you start FlightGear from the command line with the simple command fgfs --enable-terrasync, scenery will be downloaded to the default location:

This may be a good way to start FlightGear for the first time, if for some reason you don’t want to use its built-in launcher. In case you don’t have enough space in that location, simply specify another one using the --download-dir option.

Scenery directories not managed by TerraSync can be added using the --fg-scenery option and the FG_SCENERY environment variable. The value given to --fg-scenery or FG_SCENERY must be a list of directories that will be searched in order, separated by “:” on Unix or macOS and by “;” on Windows. For instance, this value could be used on Unix:

/home/joebloggs/my-fg-scenery:/home/joebloggs/.fgfs/TerraSync

and that one on Windows:

D:\MyScenery;C:\Users\joebloggs\FlightGear\Downloads\TerraSync

If you want to use both TerraSync-managed scenery and custom scenery, it is generally advised to give the TerraSync directory as the last item, as in the above examples. This way, custom scenery can override TerraSync-managed scenery. Actually, unless it is already mentioned in $FG_SCENERY or via --fg-scenery, the TerraSync directory is automatically appended to the list of scenery paths used by FlightGear (and followed by $FG_ROOT/Scenery in case neither FG_SCENERY nor --fg-scenery specify anything).

4.2.3 Launching the simulator under Windows

Open a shell (also known as “command prompt”) and use the cd command to change to the directory containing your fgfs.exe executable. For instance:

C:
cd \Program Files\FlightGear\bin

Then try simply running fgfs. If it complains that it can’t find the “base data files”, you need to either pass the --fg-root option or set the FG_ROOT environment variable:

fgfs " --fg-root=C:\Program Files\FlightGear\data"

(quotes are needed here because of the spaces in the option value) or

SET FG_ROOT="C:\Program Files\FlightGear\data"
fgfs

In case you have custom scenery, you might also want to set FG_SCENERY (cf. section 4.2.2). The usual syntax for invoking the fgfs executable is:

fgfs --option1 --option2

where available options are described in section 4.4. Of course, you can create a batch file with a Windows text editor (like Notepad) using the above lines. For maximum performance, it is recommended that you to minimize (iconize) the text output window while running FlightGear.

4.2.4 Launching the simulator under Unix/Linux

There are several cases to distinguish: if you used the download_and_compile.sh script to compile FlightGear, simply run the generated run_fgfs.sh script as if it were fgfs, giving it any of the options mentioned in section 4.4. In this case, don’t pass --fg-root to run_fgfs.sh: this is already handled inside the script.

We now assume that you have an fgfs executable that wasn’t obtained by running the download_and_compile.sh script. If you have compiled FlightGear yourself and passed -D FG_DATA_DIR:PATH=path to CMake where path tells where your FGData resides, then your fgfs executable has this directory as its default FG_ROOT setting; therefore, you don’t need to pass --fg-root nor to set the FG_ROOT environment variable: you can simply run the fgfs executable and give it any of the options mentioned in section 4.4.

In case the fgfs executable comes from your distribution, things may or may not be as in the previous paragraph. Try simply running fgfs. If it complains that it can’t find the “base data files”, you need to either pass the --fg-root option or set the FG_ROOT environment variable. Using the option is done this way:

fgfs --fg-root=/usr/share/games/flightgear

(replace /usr/share/games/flightgear with the directory containing your FGData files; the above value is only where Debian puts them). As with any shell command, use double or single quotes if the path contains spaces. An alternative to using the --fg-root option is to set the FG_ROOT environment variable. In Bourne-style shells, this can be done like so:

export FG_ROOT=/usr/share/games/flightgear

On the other hand, you would use something like this instead in C-style shells:

setenv FG_ROOT /usr/share/games/flightgear

Then simply run fgfs. In case you have custom scenery, you might also want to use the same technique to set FG_SCENERY (cf. section 4.2.2). Once these details have been sorted out, you can start FlightGear and give it any of the options mentioned in section 4.4:

fgfs --option1 --option2

4.2.5 Launching the simulator under macOS

You can also launch the simulator from the command line on macOS. In order to do so, you may open Terminal.app (located at /Applications/Utilities) and type the following commands:

cd /Applications/FlightGear.app/Contents/MacOS
./fgfs --option1 --option2

See section 4.4 for information on the available command line options. As long as you use a prebuilt binary package, you don’t need to manually specify FG_ROOT.

4.3 fgfsrc configuration files

The FlightGear executable is called fgfs (fgfs.exe on Windows). This program accepts a large number of options which will be listed in section 4.4. One of these options, namely --launcher, has already been presented in section 4.1 and starts the FlightGear built-in launcher. When this option is used, one rarely needs to pass other options manually to fgfs, because most settings can be performed from the built-in launcher.

It is also possible to start FlightGear without going through its built-in launcher, i.e., without using the --launcher option. This is particularly useful when testing things that require one to restart FlightGear many times in the same or similar conditions. There are also external launchers which work this way, calling the fgfs executable with all kinds of options, except --launcher.

The rest of this section goes into some details and is safe to skip if you are starting with FlightGear, especially if you use its built-in launcher.

When FlightGear (or rather, the fgfs executable) is started without the --launcher option, it tries to read options from a well-defined set of configuration files before processing the options passed as arguments to fgfs. These configuration files are fgfsrc in a location described in table 4.1, as well as .fgfsrc and .fgfsrc.⟨hostnameas explained in table 4.2. If you have options that you very often use, you can create one of these files and put the options there, one per line. Then you don’t need to explicitly pass them to fgfs anymore. Such files can be created with any text editor (Notepad, Emacs, vi, etc.). If you don’t know whether to create an fgfsrc or .fgfsrc file, we suggest the former: its expected location is tidier and its name not starting with a dot can make things easier in some situations.

Operating system

Where fgfsrc is looked fora

Windows

%APPDATA%\flightgear.org (typically: C:\Users\username\AppData\Roaming\flightgear.org on Vista or later, otherwise C:\Documents and Settings\username\Application Data\flightgear.org)

macOS

~/Library/Application Support/FlightGear

Unix/Linux

~/.fgfs

a That is, unless FG_HOME is set, in which case fgfsrc is looked for in the corresponding location; however, doing so is not advised unless you have a good reason.

Tabelle 4.1: Location of the fgfsrc configuration file

Operating system Where .fgfsrc and .fgfsrc.⟨hostnameare looked for
Windows %USERPROFILE% (typically: C:\Users\username)
macOS $HOME (typically: /Users/username)
Unix/Linux $HOME (typically: /home/username)
Tabelle 4.2: Location of the .fgfsrc and .fgfsrc.⟨hostnameconfiguration files

As the order of fgfs options can matter, let’s be a bit more explicit about it. If --launcher has been passed, configuration files specified with the --config option are first processed, followed by other options from the command line. Otherwise, options are processed in the following order:

There can be exceptions, but usually, options that are processed later override those processed earlier.

The fgfsrc, .fgfsrc, .fgfsrc.⟨hostnameand non-XML files loaded with --config all obey the same syntax rules: they should have one fgfs option per line. Lines starting with a # character are treated as comments, i.e. they are ignored. Each option found outside a comment line is treated as if it had been passed as an argument to the fgfs executable.

4.4 Command line parameters

Following is a complete list of the numerous command line options available in FlightGear (i.e., options that can be passed to the fgfs executable). For more convenience, options that you always want to use may be specified in a preferences file that is automatically processed when FlightGear is started (see section 4.3).

When using the built-in launcher, the default preferences files (fgfsrc and similar) are not read by FlightGear unless explicitly requested; however, applicable options may be entered in the Additional Settings box of the launcher’s Settings tab.

4.4.1 General Options

4.4.2 Features

4.4.3 Sound

4.4.4 Aircraft

4.4.5 Flight model

4.4.6 Initial Position and Orientation

4.4.7 Environment Options

4.4.8 Rendering Options

4.4.9 HUD Options

4.4.10 Aircraft System Options

4.4.11 Time Options

4.4.12 Network Options

4.4.13 Route/Waypoint Options

4.4.14 IO Options

These options are provided for the advanced user.

More detailed descriptions of the various IO parameters can be found in the README.IO file within the Docs directory of your FlightGear installation.

4.4.15 Debugging options

These options are provided for the advanced user.

4.5 Joystick support

Could you imagine a pilot in his or her Cessna controlling the machine with a keyboard alone? For getting the proper feeling of flight you will need a joystick/yoke plus rudder pedals.

FlightGear has integrated joystick support, which automatically detects any joystick, yoke, or pedals attached. Simply plug in your joystick and start the simulator.

You can see how FlightGear has configured your joystick by selecting File Joystick Configuration from the menu. This dialog shows the name of your joystick, and what each of the buttons and control axes have been set to. You can press a button or move the joystick to see exactly what control it maps to.

If you have a common joystick, there’s every chance that someone has already set up FlightGear specific configuration for it, and you can simply go and fly! If you wish to change the configuration of a particular button/axis, simply edit it using the Joystick Configuration dialog.

If your joystick is more unusual, then FlightGear will by default use a simple joystick configuration for it. To change the configuration, simply use the Joystick Configuration dialog to select what you wish each button or movement to do. The configuration takes effect immediately and will be saved for your next flight.

1https://sourceforge.net/p/flightgear/fgdata/ci/next/tree/