FlightGear wiki - User contributions [en]

Honeycomb Input Devices

2026-04-05T09:09:11Z

Johan G: +category: Joysticks and Yokes

This page provides information about the input devices available from ''[https://flyhoneycomb.com Honeycomb Aeronautical]'' and their integration into FlightGear.

== Alpha Lite Flight Controls (Yoke) ==
Classic yoke designed for GA aircrafts like the C172 or PA28. Left side with 4-way hat switch, 2-way rocker switch (e.g. trim switch) and two buttons (e.g. PTT and AP disconnect). Right side has two buttons and a 2-way rocker switche (e.g. rudder trim).

'''Integration'''

to do

== Alpha Flight Controls (Yoke) ==
The Alpha Flight Control is basically the same as the Alpha lite but with additional switches for e.g. battery, alternator, several lights and starter 'key' on the unit. Furthermore, the 2-way rocker switches on each side of the yoke are split

'''Integration'''

Partly done

== Bravo lite Throttle Quadrant ==
Four lever throttle quadrant with trim wheel, parking brake switch, gear lever and gear indication lights.

'''Integration'''

to do

== Bravo Throttle Quadrant ==
Very flexible throttle quadrant with six replaceable levers, gear lever, autopilot control panel, flap switch, annunciator panel and seven configurable switches. Shipped with lever sets for single and dual engine GA aircraft (throttle, mixture, propeller) as well as commercial jets (e.g. Boeing, CRJ).

Separate throttle pack with Airbus style levers is sold separately.

'''Integration'''
{| class="wikitable"
|+
!Feature
!Status
!Comments
|-
|Gear lever
|done
|
|-
|Gear indicator
|done
|
|-
|Trim wheel
|done
|
|-
|Thrust levers
|done
|
|-
|reversers
|wip
|
|-
|TOGA, AT disconnect
|wip
|
|-
|Switches
|wip
|
|-
|AP mode control panel
|needs discussion
|
|-
|Annunciator panel
|partly done, needs discussion
|
|}

== Charlie Rudder Pedals ==
Rudder pedals with L/R break.

'''Integration'''

{{Done}}

== Foxtrott Aviation Stick ==
Joystick / Sidestick with several buttons and switches e.g. for aircraft lights, AP, radio, etc

'''Integration'''

to do

== Sierra TPM Module ==
Throttle, Propeller, Mixture for a GA aircraft like the C172. Also contains a trim wheel, parking brake, flap switch,gear lever and gear indication lights.

'''Integration'''

to do

== see also ==
[[USB-HID]]

[[Category:Joysticks and Yokes]]

Shadows

2026-04-05T09:05:11Z

Johan G: Updating this a bit. Project Rembrandt is no longer maintained and about to be deprecated, and shadows were back in FG 2024.1. But when was scenery object shadows introduced?

'''Shadows''' were available until [[FlightGear 1.0]]. The feature became deprecated with the [[OSG]] based [[FlightGear 1.9.0]]. However, the shift to OSG opened up the possibility for re-implementing shadows and many other new graphical features in future FlightGear versions (such as happened with [[3D Clouds]]).

At some point scenery object shadows was reintroduced, probably when scenery objects like for example vegetation and random buildings became rendered instantiated rather then as separate objects.

With FlightGear 2024.1 ([https://www.flightgear.org/download/releases/2024-1/ link to changelog]) aircraft shadows was reintroduced.

== Shadow mapping ==
Shadow mapping is a technique that use a texture where distance of objects from the light has been recorded. During rendering, the distance to the light of the fragment rendered is compared to the shortest distance of the scene to the light, and if it is higher, the fragment is drawn using only ambient light. Otherwise, it is fully lit.

[[Project Rembrandt]] was a new project that implemented shadow mapping for FlightGear.

Another project which allowed aircraft developers to implement aircraft shadows was the [[ALS technical notes#ALS fuselage shadow effect|Atmospheric Light Scattering (ALS)]] project.

== Related ==
* [[Howto: Add smooth ("Ambient Occlusion") shadows in Blender]]

[[Category:FlightGear feature]]

Nasal unit tests

2026-03-15T10:04:05Z

Johan G: +-minor spelling and grammar corrections; +external links: Some relevant WikiWikiWeb articles

'''Nasal unit tests''' is way to test that Nasal functions returns expected values.

By writing unit tests for functions you are about to write you can check that the functions work as intended by using test cases that compare expected returns and actual returns.

Unit tests will also allow you to check if you introduce bugs when you extend, fix bugs, {{wikipedia|Code refactoring|refactor}}, or otherwise maintain your Nasal code.

They will also later help other check that they don't mess up your code when they continue to maintain it.

== Unit test files ==
The test files are usually placed in the same directory as the Nasal modules that are to be tested, and usually have a one to one relationship with the Nasal modules, that is each module have a test file, and each function have their test function.

The test files usually have the prefix <code>test_</code> and then the same name as the Nasal module to be tested. They are regular Nasal files, but have the file suffix <code>.nut</code> (for Nasal unit test). For example <code>test_math.nut</code> is the test file for <code>math.nas</code>.

=== Optional header comment block ===
Test files often begin with a comment block with a header with a short description of what the file is, followed by a commented line with how to run the test, for example something like this:

<syntaxhighlight lang="Nasal">
#-------------------------------------------------------------------------------
# Test file for multiplayer time synchronization
# File: test_mp_time_sync.nut
# Author: Iam Cardholder
# Created: 2026-03-14
# Licence: GPLv2 or later
#-------------------------------------------------------------------------------

# fgcommand("nasal-test", props.Node.new({"path":"test_mp_time_sync.nut"}));
</syntaxhighlight>

=== Optional setup and tear-down functions ===
Optionally the unit test file can have a <code>setUp()</code> and a <code>tearDown()</code> function. These are useful for example when a module have dependencies to other modules.

Most of the time these functions are used for printing to the console and/or log that the test has started or finished.

<syntaxhighlight lang="Nasal">
# Optional setup function
var setUp = func {
logprint(LOG_INFO, "mp_time_sync tests begin");
};

# Optional tear-down function
var tearDown = func {
logprint(LOG_INFO, "mp_time_sync tests finished");
};
</syntaxhighlight>

== Test functions and test cases ==
{{stub|section=1}}
{{WIP|Parts of the information below may be inaccurate. The author is currently trying to understand how this works. Would be grateful for help.}}
The names of the test functions, like the names of the test files, usually begin with <code>test_</code> and matches the names of the functions to test.

The test functions set up variables etc, and then have one or more test cases using the functions described below:

=== unitTest.assert() ===
{{Nasal doc
| syntax = unitTest.assert(bool[, message])
| text = Asserts that a boolean is true. If false the test fails with an optional message, the file path, line number, and the runtime error "Test assert failed".
| mode =
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=47|t=Source}}
| version = Likely 2024.1
| param1 = bool
| param2 = message
| param1text = A boolean. Usually the return from the function to test. Can be an expression.
| param2text = An optional string with a message to show with the file path and line number.
| example1text =
| example1 =
}}

=== unitTest.fail() ===
{{Nasal doc
| syntax = unitTest.fail([message])
| text = Will fail the test with an optional message, the file path, line number, and the runtime error "Test failed".
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=72|t=Source}}
| version = Likely 2024.1.2
| param1 = message
| param1text = An optional string with a message to show with the file path and line number.
| example1text =
| example1 =
}}

=== unitTest.assert_equal() ===
{{Nasal doc
| syntax = unitTest.assert_equal(a, b[, message])
| text = Compares a and b. If not equal the test fails with an optional message, the file path, line number, and the runtime error "assert_equal failed", or if defined the message.
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=94|t=Source}}
| version = Likely 2024.1.2
| param1 = a
| param2 = b
| param3 = message
| param1text = A value. Usually the expected value to be returned. Can be an expression.
| param2text = A value. Usually the actual value returned from the function to be tested. Can be an expression.
| param3text = An optional string with a message to show with the file path and line number. Will also be the runtime error. Defaults to "assert_equal failed".
| example1text =
| example1 =
}}

=== unitTest.assert_doubles_equal() ===
{{Nasal doc
| syntax = unitTest.assert_doubles_equal(a, b, tolerance[, message])
| text = Compares two doubles. If the difference larger or equal to the tolerance the test fails with an optional message, the file path, line number, and the runtime error "assert_doubles_equal failed", or if defined the message.
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=115|t=Source}}
| version = Likely 2024.1.2
| param1 = a
| param2 = b
| param3 = tolerance
| param4 = message
| param1text = A double. Usually the expected value to be returned. Can be an expression.
| param2text = A double. Usually the actual value returned from the function to be tested. Can be an expression.
| param3text = A double with the tolerance.
| param4text = An optional string with a message to show with the file path and line number. Will also be the runtime error. Defaults to "assert_doubles_equal failed".
| example1text =
| example1 =
}}

== Running the tests ==
The tests are run with the FGCommands:

* <code>fgcommand("nasal-test", props.node.new({"path":"<path to Nasal test file>"}));</code>
* <code>fgcommand("nasal-test-dir", props.node.new({"path":"<path to directory with Nasal test files>"}));</code>

== See also ==
=== Wiki articles ===
* [[Software testing]]
* [[Nasal Unit Testing Framework]] (An older effort.)

=== Source code ===
* {{flightgear source|path=src/Scripting/NasalUnitTesting.hxx}}
* {{flightgear source|path=src/Scripting/NasalUnitTesting.cxx}}

=== Examples ===
* {{fgdata source|path=Nasal/std.nut}}
* {{fgdata source|path=Nasal/string.nut}}
* {{fgdata source|path=Nasal/test_emesary.nut}}

== External links ==
* [https://people.freedesktop.org/~mmohrhard/cppunit/group___assertions.html CppUnit Documentation - Making assertions] - The unit test framework that runs the unit tests.
* {{wikipedia|Test-driven development}}
* [https://wiki.c2.com/?CodeUnitTestFirst CodeUnitTestFirst - WikiWikiWeb]
* [https://wiki.c2.com/?UnitTest UnitTest - WikiWikiWeb]
* [https://wiki.c2.com/?TestDrivenDevelopment TestDrivenDevelopment - WikiWikiWeb]

[[Category:Nasal]]
[[Category:Software testing]]

Nasal unit tests

2026-03-15T03:00:44Z

Johan G: /* See also */ +heading: Wiki articles

'''Nasal unit tests''' is way to test that Nasal functions returns expected values.

By writing unit tests for functions you are about to write you can check that the functions work as intended by using test cases that compare expected returns and actual returns.

Unit tests will also allow you to check if you introduce bugs when you extend, fix bugs, {{wikipedia|Code refactoring|refactor}}, or otherwise maintain your Nasal code.

They will also later help other check that they don't mess up your code when they continue to maintain it.

== Unit test files ==
The test files are usually placed in the same directory as the Nasal modules that are to be tested, and usually have a one to one relationship with the Nasal modules; each module have a test file, and each function have their test function.

The test files usually have the prefix <code>test_</code> and then the same name as the Nasal module to be tested. They are regular Nasal files, but have the file suffix <code>.nut</code> (for Nasal unit test). For example <code>test_math.nut</code> is the test file for <code>math.nas</code>.

=== Optional header comment block ===
Test files often begin with a comment block with a header with a short description of what the file is, followed by a commented line with how to run the test, foe example something like this:

<syntaxhighlight lang="Nasal">
#-------------------------------------------------------------------------------
# Test file for multiplayer time synchronization
# File: test_mp_time_sync.nut
# Author: Iam Cardholder
# Created: 2026-03-14
# Licence: GPLv2 or later
#-------------------------------------------------------------------------------

# fgcommand("nasal-test", props.Node.new({"path":"test_mp_time_sync.nut"}));
</syntaxhighlight>

=== Optional setup and tear-down functions ===
Optionally the unit test file can have a <code>setUp()</code> and a <code>tearDown()</code> function. These are useful for example when a module have dependencies to other modules.

Most of the time these functions are used for printing to the console and/or log that the test has started or finished.

<syntaxhighlight lang="Nasal">
# Optional setup function
var setUp = func {
logprint(LOG_INFO, "mp_time_sync tests begin");
};

# Optional tear-down function
var tearDown = func {
logprint(LOG_INFO, "mp_time_sync tests finished");
};
</syntaxhighlight>

== Test functions and test cases ==
{{stub|section=1}}
{{WIP|Parts of the information below may be inaccurate. The author is currently trying to understand how this works. Would be grateful for help.}}
The names of the test functions, like the names of the test files, usually begin with <code>test_</code> and matches the names of the functions to test.

The test functions set up variables etc, and then have one or more test cases using the functions described below:

=== unitTest.assert() ===
{{Nasal doc
| syntax = unitTest.assert(bool[, message])
| text = Asserts that a boolean is true. If false the test fails with an optional message, the file path, line number, and the runtime error "Test assert failed".
| mode =
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=47|t=Source}}
| version = Likely 2024.1
| param1 = bool
| param2 = message
| param1text = A boolean. Usually the return from the function to test. Can be an expression.
| param2text = An optional string with a message to show with the file path and line number.
| example1text =
| example1 =
}}

=== unitTest.fail() ===
{{Nasal doc
| syntax = unitTest.fail([message])
| text = Will fail the test with an optional message, the file path, line number, and the runtime error "Test failed".
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=72|t=Source}}
| version = Likely 2024.1.2
| param1 = message
| param1text = An optional string with a message to show with the file path and line number.
| example1text =
| example1 =
}}

=== unitTest.assert_equal() ===
{{Nasal doc
| syntax = unitTest.assert_equal(a, b[, message])
| text = Compares a and b. If not equal the test fails with an optional message, the file path, line number, and the runtime error "assert_equal failed", or if defined the message.
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=94|t=Source}}
| version = Likely 2024.1.2
| param1 = a
| param2 = b
| param3 = message
| param1text = A value. Usually the expected value to be returned. Can be an expression.
| param2text = A value. Usually the actual value returned from the function to be tested. Can be an expression.
| param3text = An optional string with a message to show with the file path and line number. Will also be the runtime error. Defaults to "assert_equal failed".
| example1text =
| example1 =
}}

=== unitTest.assert_doubles_equal() ===
{{Nasal doc
| syntax = unitTest.assert_doubles_equal(a, b, tolerance[, message])
| text = Compares two doubles. If the difference larger or equal to the tolerance the test fails with an optional message, the file path, line number, and the runtime error "assert_doubles_equal failed", or if defined the message.
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=115|t=Source}}
| version = Likely 2024.1.2
| param1 = a
| param2 = b
| param3 = tolerance
| param4 = message
| param1text = A double. Usually the expected value to be returned. Can be an expression.
| param2text = A double. Usually the actual value returned from the function to be tested. Can be an expression.
| param3text = A double with the tolerance.
| param4text = An optional string with a message to show with the file path and line number. Will also be the runtime error. Defaults to "assert_doubles_equal failed".
| example1text =
| example1 =
}}

== Running the tests ==
The tests are run with the FGCommands:

* <code>fgcommand("nasal-test", props.node.new({"path":"<path to Nasal test file>"}));</code>
* <code>fgcommand("nasal-test-dir", props.node.new({"path":"<path to directory with Nasal test files>"}));</code>

== See also ==
=== Wiki articles ===
* [[Software testing]]
* [[Nasal Unit Testing Framework]] (An older effort.)

=== Source code ===
* {{flightgear source|path=src/Scripting/NasalUnitTesting.hxx}}
* {{flightgear source|path=src/Scripting/NasalUnitTesting.cxx}}

=== Examples ===
* {{fgdata source|path=Nasal/std.nut}}
* {{fgdata source|path=Nasal/string.nut}}
* {{fgdata source|path=Nasal/test_emesary.nut}}

== External links ==
* [https://people.freedesktop.org/~mmohrhard/cppunit/group___assertions.html CppUnit Documentation - Making assertions] - The unit test framework that runs the unit tests.

[[Category:Nasal]]
[[Category:Software testing]]

Nasal unit tests

2026-03-15T02:55:50Z

Johan G: /* Writing unit test files */ +- Rephrasing; +- Restructuring; - unitTest.equal() which, looking at the code, does not seem to generate an error

'''Nasal unit tests''' is way to test that Nasal functions returns expected values.

By writing unit tests for functions you are about to write you can check that the functions work as intended by using test cases that compare expected returns and actual returns.

Unit tests will also allow you to check if you introduce bugs when you extend, fix bugs, {{wikipedia|Code refactoring|refactor}}, or otherwise maintain your Nasal code.

They will also later help other check that they don't mess up your code when they continue to maintain it.

== Unit test files ==
The test files are usually placed in the same directory as the Nasal modules that are to be tested, and usually have a one to one relationship with the Nasal modules; each module have a test file, and each function have their test function.

The test files usually have the prefix <code>test_</code> and then the same name as the Nasal module to be tested. They are regular Nasal files, but have the file suffix <code>.nut</code> (for Nasal unit test). For example <code>test_math.nut</code> is the test file for <code>math.nas</code>.

=== Optional header comment block ===
Test files often begin with a comment block with a header with a short description of what the file is, followed by a commented line with how to run the test, foe example something like this:

<syntaxhighlight lang="Nasal">
#-------------------------------------------------------------------------------
# Test file for multiplayer time synchronization
# File: test_mp_time_sync.nut
# Author: Iam Cardholder
# Created: 2026-03-14
# Licence: GPLv2 or later
#-------------------------------------------------------------------------------

# fgcommand("nasal-test", props.Node.new({"path":"test_mp_time_sync.nut"}));
</syntaxhighlight>

=== Optional setup and tear-down functions ===
Optionally the unit test file can have a <code>setUp()</code> and a <code>tearDown()</code> function. These are useful for example when a module have dependencies to other modules.

Most of the time these functions are used for printing to the console and/or log that the test has started or finished.

<syntaxhighlight lang="Nasal">
# Optional setup function
var setUp = func {
logprint(LOG_INFO, "mp_time_sync tests begin");
};

# Optional tear-down function
var tearDown = func {
logprint(LOG_INFO, "mp_time_sync tests finished");
};
</syntaxhighlight>

== Test functions and test cases ==
{{stub|section=1}}
{{WIP|Parts of the information below may be inaccurate. The author is currently trying to understand how this works. Would be grateful for help.}}
The names of the test functions, like the names of the test files, usually begin with <code>test_</code> and matches the names of the functions to test.

The test functions set up variables etc, and then have one or more test cases using the functions described below:

=== unitTest.assert() ===
{{Nasal doc
| syntax = unitTest.assert(bool[, message])
| text = Asserts that a boolean is true. If false the test fails with an optional message, the file path, line number, and the runtime error "Test assert failed".
| mode =
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=47|t=Source}}
| version = Likely 2024.1
| param1 = bool
| param2 = message
| param1text = A boolean. Usually the return from the function to test. Can be an expression.
| param2text = An optional string with a message to show with the file path and line number.
| example1text =
| example1 =
}}

=== unitTest.fail() ===
{{Nasal doc
| syntax = unitTest.fail([message])
| text = Will fail the test with an optional message, the file path, line number, and the runtime error "Test failed".
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=72|t=Source}}
| version = Likely 2024.1.2
| param1 = message
| param1text = An optional string with a message to show with the file path and line number.
| example1text =
| example1 =
}}

=== unitTest.assert_equal() ===
{{Nasal doc
| syntax = unitTest.assert_equal(a, b[, message])
| text = Compares a and b. If not equal the test fails with an optional message, the file path, line number, and the runtime error "assert_equal failed", or if defined the message.
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=94|t=Source}}
| version = Likely 2024.1.2
| param1 = a
| param2 = b
| param3 = message
| param1text = A value. Usually the expected value to be returned. Can be an expression.
| param2text = A value. Usually the actual value returned from the function to be tested. Can be an expression.
| param3text = An optional string with a message to show with the file path and line number. Will also be the runtime error. Defaults to "assert_equal failed".
| example1text =
| example1 =
}}

=== unitTest.assert_doubles_equal() ===
{{Nasal doc
| syntax = unitTest.assert_doubles_equal(a, b, tolerance[, message])
| text = Compares two doubles. If the difference larger or equal to the tolerance the test fails with an optional message, the file path, line number, and the runtime error "assert_doubles_equal failed", or if defined the message.
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=115|t=Source}}
| version = Likely 2024.1.2
| param1 = a
| param2 = b
| param3 = tolerance
| param4 = message
| param1text = A double. Usually the expected value to be returned. Can be an expression.
| param2text = A double. Usually the actual value returned from the function to be tested. Can be an expression.
| param3text = A double with the tolerance.
| param4text = An optional string with a message to show with the file path and line number. Will also be the runtime error. Defaults to "assert_doubles_equal failed".
| example1text =
| example1 =
}}

== Running the tests ==
The tests are run with the FGCommands:

* <code>fgcommand("nasal-test", props.node.new({"path":"<path to Nasal test file>"}));</code>
* <code>fgcommand("nasal-test-dir", props.node.new({"path":"<path to directory with Nasal test files>"}));</code>

== See also ==
* [[Software testing]]
* [[Nasal Unit Testing Framework]] (An older effort.)

=== Source code ===
* {{flightgear source|path=src/Scripting/NasalUnitTesting.hxx}}
* {{flightgear source|path=src/Scripting/NasalUnitTesting.cxx}}

=== Examples ===
* {{fgdata source|path=Nasal/std.nut}}
* {{fgdata source|path=Nasal/string.nut}}
* {{fgdata source|path=Nasal/test_emesary.nut}}

== External links ==
* [https://people.freedesktop.org/~mmohrhard/cppunit/group___assertions.html CppUnit Documentation - Making assertions] - The unit test framework that runs the unit tests.

[[Category:Nasal]]
[[Category:Software testing]]

Nasal unit tests

2026-03-15T02:40:27Z

Johan G: /* External links */ fix broken link

'''Nasal unit tests''' is way to test that Nasal functions returns expected values.

By writing unit tests for functions you are about to write you can check that the functions work as intended by using test cases that compare expected returns and actual returns.

Unit tests will also allow you to check if you introduce bugs when you extend, fix bugs, {{wikipedia|Code refactoring|refactor}}, or otherwise maintain your Nasal code.

They will also later help other check that they don't mess up your code when they continue to maintain it.

== Writing unit test files ==
The files with the unit tests, the test files, are regular Nasal files but with the file ending <code>.nut</code> (for Nasal unit test).

The name of the test files usually begin with <code>test_</code> and then usually use the same file name as the module that are to be tested.

The test files are usually placed in the same directory as the Nasal modules that are to be tested.

=== Optional header comment block ===
Test files often begin with a comment block with a header with a short description of what the file is, followed by a commented line with how to run the test, foe example something like this:

<syntaxhighlight lang="Nasal">
#-------------------------------------------------------------------------------
# Test file for multiplayer time synchronization
# File: test_mp_time_sync.nut
# Author: Iam Cardholder
# Created: 2026-03-14
# Licence: GPLv2 or later
#-------------------------------------------------------------------------------

# fgcommand("nasal-test", props.Node.new({"path":"test_mp_time_sync.nut"}));
</syntaxhighlight>

=== Optional setup and tear-down functions ===
Optionally the unit test file can have a <code>setUp()</code> and a <code>tearDown()</code> function. These are useful if for example some other module need to be loaded.

Most of the time these functions are used for printing to the console and/or log that the test has started or finished.

<syntaxhighlight lang="Nasal">
# Optional setup function
var setUp = func {
logprint(LOG_INFO, "mp_time_sync tests begin");
};

# Optional tear-down function
var tearDown = func {
logprint(LOG_INFO, "mp_time_sync tests finished");
};
</syntaxhighlight>

=== Test functions and test cases ===
{{stub|section=1}}
{{WIP|Parts of the information below may be inaccurate. The author is currently trying to understand how this works. Would be grateful for help.}}
The names of the test functions usually matches the names of the functions to test except they, like the name of the test file, begin with <code>test_</code>.

Tests are written as functions with one or more test cases. If needed modules can be loaded, variables can be defined etc. that will then be used for each test case.

You can have as many test cases as needed and each test case can be using using one of four different tests:
* <code>assert</code>
* <code>fail</code>
* <code>assert_equal</code>
* <code>assert_doubles_equal</code>
* <code>equal</code>

=== unitTest.assert() ===
{{Nasal doc
| syntax = unitTest.assert(bool[, message])
| text = Asserts that a boolean is true. If false the test fails with an optional message, the file path, line number, and the runtime error "Test assert failed".
| mode =
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=47|t=Source}}
| version = Likely 2024.1
| param1 = bool
| param2 = message
| param1text = A boolean. Usually the return from the function to test. Can be an expression.
| param2text = An optional string with a message to show with the file path and line number.
| example1text =
| example1 =
}}

=== unitTest.fail() ===
{{Nasal doc
| syntax = unitTest.fail([message])
| text = Will fail the test with an optional message, the file path, line number, and the runtime error "Test failed".
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=72|t=Source}}
| version = Likely 2024.1.2
| param1 = message
| param1text = An optional string with a message to show with the file path and line number.
| example1text =
| example1 =
}}

=== unitTest.assert_equal() ===
{{Nasal doc
| syntax = unitTest.assert_equal(a, b[, message])
| text = Compares a and b. If not equal the test fails with an optional message, the file path, line number, and the runtime error "assert_equal failed", or if defined the message.
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=94|t=Source}}
| version = Likely 2024.1.2
| param1 = a
| param2 = b
| param3 = message
| param1text = A value. Usually the expected value to be returned. Can be an expression.
| param2text = A value. Usually the value returned from the function to be tested. Can be an expression.
| param3text = An optional string with a message to show with the file path and line number. Will also be the runtime error. Defaults to "assert_equal failed".
| example1text =
| example1 =
}}

=== unitTest.assert_doubles_equal() ===
{{Nasal doc
| syntax = unitTest.assert_doubles_equal(a, b, tolerance[, message])
| text = Compares two doubles. If the difference larger or equal to the tolerance the test fails with an optional message, the file path, line number, and the runtime error "assert_doubles_equal failed", or if defined the message.
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=115|t=Source}}
| version = Likely 2024.1.2
| param1 = a
| param2 = b
| param3 = tolerance
| param4 = message
| param1text = A double. Usually the expected value to be returned. Can be an expression.
| param2text = A double. Usually the value returned from the function to be tested. Can be an expression.
| param3text = A double with the tolerance.
| param4text = An optional string with a message to show with the file path and line number. Will also be the runtime error. Defaults to "assert_doubles_equal failed".
| example1text =
| example1 =
}}

=== unitTest.equal() ===
{{Nasal doc
| syntax = unitTest.equal(a, b)
| text = Compares two values.
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=136|t=Source}}
| version = Likely 2024.1.2
| param1 = a
| param2 = b
| param1text = A value. Usually the expected value to be returned. Can be an expression.
| param2text = A value. Usually the value returned from the function to be tested. Can be an expression.
| example1text =
| example1 =
}}

== Running the tests ==
The tests are run with the FGCommands:

* <code>fgcommand("nasal-test", props.node.new({"path":"<path to Nasal test file>"}));</code>
* <code>fgcommand("nasal-test-dir", props.node.new({"path":"<path to directory with Nasal test files>"}));</code>

== See also ==
* [[Software testing]]
* [[Nasal Unit Testing Framework]] (An older effort.)

=== Source code ===
* {{flightgear source|path=src/Scripting/NasalUnitTesting.hxx}}
* {{flightgear source|path=src/Scripting/NasalUnitTesting.cxx}}

=== Examples ===
* {{fgdata source|path=Nasal/std.nut}}
* {{fgdata source|path=Nasal/string.nut}}
* {{fgdata source|path=Nasal/test_emesary.nut}}

== External links ==
* [https://people.freedesktop.org/~mmohrhard/cppunit/group___assertions.html CppUnit Documentation - Making assertions] - The unit test framework that runs the unit tests.

[[Category:Nasal]]
[[Category:Software testing]]

Template:Nasal Navigation

2026-03-15T01:37:24Z

Johan G: +link: Nasal unit tests

<noinclude>{{Informative template|1=
Navigation box for core [[Nasal]] articles.

== Usage ==
Put this at the top of the article:
{{obr}}'''Nasal Navigation'''{{cbr}}

}}

[[Category:Navigation templates]]

</noinclude><includeonly>{{nocat|{{{nocat|}}}|Nasal}}</includeonly>{{forum|30|Nasal Scripting}}

{{Sidebar with collapsible lists
| name = Nasal Navigation
| pretitle = [[File:Nasallogo3.png|link=Nasal]]
| title = [[Nasal|Nasal scripting]]
| expanded = {{{expanded|}}}

| content1 =
* [[What is Nasal]]?
* [[Nasal success stories|Success stories]]
* [[Nasal FAQ]]
* [[Nasal Snippets]]
* [[Howto:Syntax highlighting for Nasal]]

| list2title = Tools and utilities
| list2 = [[Nasal Console|Console]] • [[Interactive Nasal Console|REPL Console]] • [[Nasal Browser|Browser]]

| list3title = Getting started
| list3 =
* [[Nasal Best Practices]]
* [[Nasal for C++ programmers]]
* [[Creating new Nasal scripts]]
* [[Nasal Hello World]]
* [[Howto:Create a new Nasal module]]
* [[Using Nasal functions]]
* [[Nasal Variables]]
* [[Nasal Namespaces]]
* [[Howto:Understand Namespaces and Methods|Namespace and Methods]]
* [[Nasal Namespaces in-depth]]
* [[Nasal Conditionals]]
* [[Nasal Loops]]
* [[Numbers in Nasal]]
* [[Nasal Operators]]
* [[Howto:Use vectors and foreach loops to write shorter code]]
* [[Howto:Start using vectors and hashes in Nasal]]
* [[Nasal library]] ([[Nasal library#Core library functions|core]]/[[Nasal library#Extension functions|extension]] functions)
** [[Nasal library/clipboard|<code>clipboard</code> namespace]]
** [[Nasal library/debug|<code>debug</code> namespace]]
** [[Nasal library/geo|<code>geo</code> namespace]]
** [[Nasal library/io|<code>io</code> namespace]]
** [[Nasal library/math|<code>math</code> namespace]]
** [[Nasal library/os.path|<code>os.path</code> namespace]]
** [[Nasal library/props|<code>props</code> namespace]]
** [[Nasal String Manipulation|<code>string</code> namespace]]
** [[Nasal library/flightplan|flightplan library]]
* [[Nasal Flightplan]]
* [[Object oriented programming in Nasal|OOP Introduction]]
* [[Object Oriented Programming with Nasal]]
* [[Nasal Callbacks Explained]]
* [[Exception handling with Nasal]]
* [[Using listeners and signals with Nasal]]
* [[Developing and debugging Nasal code]]

| list4title = Advanced Tutorials
| list4 =
* [[Caching Nasal function calls]]
* [[Nasal Unit Testing Framework]] (WIP)
* [[Nasal Meta-Programming]]
* [[A GPX flight logger in Nasal]]
* [[Multiplayer scripting in Nasal]]
* [[Howto:Making HTTP Requests from Nasal]]
* [[Howto:Transmit properties over MP]]
* [[Howto:Terrain sampling in Nasal]]
* [[Howto:Create a new system in Nasal]]
* [[Howto:Load a Nasal file at runtime]]
* [[Howto:Control the route manager in Nasal]]
* [[Howto:Get a number of elevation offsets for a number of objects]]
* [[Howto:Nasal in scenery object XML files]]
* [[Howto:Create animation XML files from Nasal]]
* [[Howto:Port I/O from Nasal]]
* [[Howto:Continuation-passing style programming in Nasal]]
* [[Howto:Start worker threads using listeners in Nasal]]
* [[Howto:Developing a DSL interpreter in Nasal]]
* [[Howto:Nasal Metaprogramming]]
* [[Nasal/JavaScript Subset]]
* [[Nasal unit tests]]
}}

{{Nasal Internals}}

Nasal unit tests

2026-03-15T01:24:26Z

Johan G: +fix: Correct Wikipedia link

'''Nasal unit tests''' is way to test that Nasal functions returns expected values.

By writing unit tests for functions you are about to write you can check that the functions work as intended by using test cases that compare expected returns and actual returns.

Unit tests will also allow you to check if you introduce bugs when you extend, fix bugs, {{wikipedia|Code refactoring|refactor}}, or otherwise maintain your Nasal code.

They will also later help other check that they don't mess up your code when they continue to maintain it.

== Writing unit test files ==
The files with the unit tests, the test files, are regular Nasal files but with the file ending <code>.nut</code> (for Nasal unit test).

The name of the test files usually begin with <code>test_</code> and then usually use the same file name as the module that are to be tested.

The test files are usually placed in the same directory as the Nasal modules that are to be tested.

=== Optional header comment block ===
Test files often begin with a comment block with a header with a short description of what the file is, followed by a commented line with how to run the test, foe example something like this:

<syntaxhighlight lang="Nasal">
#-------------------------------------------------------------------------------
# Test file for multiplayer time synchronization
# File: test_mp_time_sync.nut
# Author: Iam Cardholder
# Created: 2026-03-14
# Licence: GPLv2 or later
#-------------------------------------------------------------------------------

# fgcommand("nasal-test", props.Node.new({"path":"test_mp_time_sync.nut"}));
</syntaxhighlight>

=== Optional setup and tear-down functions ===
Optionally the unit test file can have a <code>setUp()</code> and a <code>tearDown()</code> function. These are useful if for example some other module need to be loaded.

Most of the time these functions are used for printing to the console and/or log that the test has started or finished.

<syntaxhighlight lang="Nasal">
# Optional setup function
var setUp = func {
logprint(LOG_INFO, "mp_time_sync tests begin");
};

# Optional tear-down function
var tearDown = func {
logprint(LOG_INFO, "mp_time_sync tests finished");
};
</syntaxhighlight>

=== Test functions and test cases ===
{{stub|section=1}}
{{WIP|Parts of the information below may be inaccurate. The author is currently trying to understand how this works. Would be grateful for help.}}
The names of the test functions usually matches the names of the functions to test except they, like the name of the test file, begin with <code>test_</code>.

Tests are written as functions with one or more test cases. If needed modules can be loaded, variables can be defined etc. that will then be used for each test case.

You can have as many test cases as needed and each test case can be using using one of four different tests:
* <code>assert</code>
* <code>fail</code>
* <code>assert_equal</code>
* <code>assert_doubles_equal</code>
* <code>equal</code>

=== unitTest.assert() ===
{{Nasal doc
| syntax = unitTest.assert(bool[, message])
| text = Asserts that a boolean is true. If false the test fails with an optional message, the file path, line number, and the runtime error "Test assert failed".
| mode =
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=47|t=Source}}
| version = Likely 2024.1
| param1 = bool
| param2 = message
| param1text = A boolean. Usually the return from the function to test. Can be an expression.
| param2text = An optional string with a message to show with the file path and line number.
| example1text =
| example1 =
}}

=== unitTest.fail() ===
{{Nasal doc
| syntax = unitTest.fail([message])
| text = Will fail the test with an optional message, the file path, line number, and the runtime error "Test failed".
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=72|t=Source}}
| version = Likely 2024.1.2
| param1 = message
| param1text = An optional string with a message to show with the file path and line number.
| example1text =
| example1 =
}}

=== unitTest.assert_equal() ===
{{Nasal doc
| syntax = unitTest.assert_equal(a, b[, message])
| text = Compares a and b. If not equal the test fails with an optional message, the file path, line number, and the runtime error "assert_equal failed", or if defined the message.
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=94|t=Source}}
| version = Likely 2024.1.2
| param1 = a
| param2 = b
| param3 = message
| param1text = A value. Usually the expected value to be returned. Can be an expression.
| param2text = A value. Usually the value returned from the function to be tested. Can be an expression.
| param3text = An optional string with a message to show with the file path and line number. Will also be the runtime error. Defaults to "assert_equal failed".
| example1text =
| example1 =
}}

=== unitTest.assert_doubles_equal() ===
{{Nasal doc
| syntax = unitTest.assert_doubles_equal(a, b, tolerance[, message])
| text = Compares two doubles. If the difference larger or equal to the tolerance the test fails with an optional message, the file path, line number, and the runtime error "assert_doubles_equal failed", or if defined the message.
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=115|t=Source}}
| version = Likely 2024.1.2
| param1 = a
| param2 = b
| param3 = tolerance
| param4 = message
| param1text = A double. Usually the expected value to be returned. Can be an expression.
| param2text = A double. Usually the value returned from the function to be tested. Can be an expression.
| param3text = A double with the tolerance.
| param4text = An optional string with a message to show with the file path and line number. Will also be the runtime error. Defaults to "assert_doubles_equal failed".
| example1text =
| example1 =
}}

=== unitTest.equal() ===
{{Nasal doc
| syntax = unitTest.equal(a, b)
| text = Compares two values.
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=136|t=Source}}
| version = Likely 2024.1.2
| param1 = a
| param2 = b
| param1text = A value. Usually the expected value to be returned. Can be an expression.
| param2text = A value. Usually the value returned from the function to be tested. Can be an expression.
| example1text =
| example1 =
}}

== Running the tests ==
The tests are run with the FGCommands:

* <code>fgcommand("nasal-test", props.node.new({"path":"<path to Nasal test file>"}));</code>
* <code>fgcommand("nasal-test-dir", props.node.new({"path":"<path to directory with Nasal test files>"}));</code>

== See also ==
* [[Software testing]]
* [[Nasal Unit Testing Framework]] (An older effort.)

=== Source code ===
* {{flightgear source|path=src/Scripting/NasalUnitTesting.hxx}}
* {{flightgear source|path=src/Scripting/NasalUnitTesting.cxx}}

=== Examples ===
* {{fgdata source|path=Nasal/std.nut}}
* {{fgdata source|path=Nasal/string.nut}}
* {{fgdata source|path=Nasal/test_emesary.nut}}

== External links ==
* [https://people.freedesktop.org/~mmohrhard/cppunit/group___assertions.htm CppUnit Documentation - Making assertions] - The unit test framework that runs the unit tests.

[[Category:Nasal]]
[[Category:Software testing]]

Nasal unit tests

2026-03-15T01:22:50Z

Johan G: +- Rephrasing the first section

'''Nasal unit tests''' is way to test that Nasal functions returns expected values.

By writing unit tests for functions you are about to write you can check that the functions work as intended by using test cases that compare expected returns and actual returns.

Unit tests will also allow you to check if you introduce bugs when you extend, fix bugs, {{wikipedia|refactor}}, or otherwise maintain your Nasal code.

They will also later help other check that they don't mess up your code when they continue to maintain it.

== Writing unit test files ==
The files with the unit tests, the test files, are regular Nasal files but with the file ending <code>.nut</code> (for Nasal unit test).

The name of the test files usually begin with <code>test_</code> and then usually use the same file name as the module that are to be tested.

The test files are usually placed in the same directory as the Nasal modules that are to be tested.

=== Optional header comment block ===
Test files often begin with a comment block with a header with a short description of what the file is, followed by a commented line with how to run the test, foe example something like this:

<syntaxhighlight lang="Nasal">
#-------------------------------------------------------------------------------
# Test file for multiplayer time synchronization
# File: test_mp_time_sync.nut
# Author: Iam Cardholder
# Created: 2026-03-14
# Licence: GPLv2 or later
#-------------------------------------------------------------------------------

# fgcommand("nasal-test", props.Node.new({"path":"test_mp_time_sync.nut"}));
</syntaxhighlight>

=== Optional setup and tear-down functions ===
Optionally the unit test file can have a <code>setUp()</code> and a <code>tearDown()</code> function. These are useful if for example some other module need to be loaded.

Most of the time these functions are used for printing to the console and/or log that the test has started or finished.

<syntaxhighlight lang="Nasal">
# Optional setup function
var setUp = func {
logprint(LOG_INFO, "mp_time_sync tests begin");
};

# Optional tear-down function
var tearDown = func {
logprint(LOG_INFO, "mp_time_sync tests finished");
};
</syntaxhighlight>

=== Test functions and test cases ===
{{stub|section=1}}
{{WIP|Parts of the information below may be inaccurate. The author is currently trying to understand how this works. Would be grateful for help.}}
The names of the test functions usually matches the names of the functions to test except they, like the name of the test file, begin with <code>test_</code>.

Tests are written as functions with one or more test cases. If needed modules can be loaded, variables can be defined etc. that will then be used for each test case.

You can have as many test cases as needed and each test case can be using using one of four different tests:
* <code>assert</code>
* <code>fail</code>
* <code>assert_equal</code>
* <code>assert_doubles_equal</code>
* <code>equal</code>

=== unitTest.assert() ===
{{Nasal doc
| syntax = unitTest.assert(bool[, message])
| text = Asserts that a boolean is true. If false the test fails with an optional message, the file path, line number, and the runtime error "Test assert failed".
| mode =
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=47|t=Source}}
| version = Likely 2024.1
| param1 = bool
| param2 = message
| param1text = A boolean. Usually the return from the function to test. Can be an expression.
| param2text = An optional string with a message to show with the file path and line number.
| example1text =
| example1 =
}}

=== unitTest.fail() ===
{{Nasal doc
| syntax = unitTest.fail([message])
| text = Will fail the test with an optional message, the file path, line number, and the runtime error "Test failed".
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=72|t=Source}}
| version = Likely 2024.1.2
| param1 = message
| param1text = An optional string with a message to show with the file path and line number.
| example1text =
| example1 =
}}

=== unitTest.assert_equal() ===
{{Nasal doc
| syntax = unitTest.assert_equal(a, b[, message])
| text = Compares a and b. If not equal the test fails with an optional message, the file path, line number, and the runtime error "assert_equal failed", or if defined the message.
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=94|t=Source}}
| version = Likely 2024.1.2
| param1 = a
| param2 = b
| param3 = message
| param1text = A value. Usually the expected value to be returned. Can be an expression.
| param2text = A value. Usually the value returned from the function to be tested. Can be an expression.
| param3text = An optional string with a message to show with the file path and line number. Will also be the runtime error. Defaults to "assert_equal failed".
| example1text =
| example1 =
}}

=== unitTest.assert_doubles_equal() ===
{{Nasal doc
| syntax = unitTest.assert_doubles_equal(a, b, tolerance[, message])
| text = Compares two doubles. If the difference larger or equal to the tolerance the test fails with an optional message, the file path, line number, and the runtime error "assert_doubles_equal failed", or if defined the message.
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=115|t=Source}}
| version = Likely 2024.1.2
| param1 = a
| param2 = b
| param3 = tolerance
| param4 = message
| param1text = A double. Usually the expected value to be returned. Can be an expression.
| param2text = A double. Usually the value returned from the function to be tested. Can be an expression.
| param3text = A double with the tolerance.
| param4text = An optional string with a message to show with the file path and line number. Will also be the runtime error. Defaults to "assert_doubles_equal failed".
| example1text =
| example1 =
}}

=== unitTest.equal() ===
{{Nasal doc
| syntax = unitTest.equal(a, b)
| text = Compares two values.
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=136|t=Source}}
| version = Likely 2024.1.2
| param1 = a
| param2 = b
| param1text = A value. Usually the expected value to be returned. Can be an expression.
| param2text = A value. Usually the value returned from the function to be tested. Can be an expression.
| example1text =
| example1 =
}}

== Running the tests ==
The tests are run with the FGCommands:

* <code>fgcommand("nasal-test", props.node.new({"path":"<path to Nasal test file>"}));</code>
* <code>fgcommand("nasal-test-dir", props.node.new({"path":"<path to directory with Nasal test files>"}));</code>

== See also ==
* [[Software testing]]
* [[Nasal Unit Testing Framework]] (An older effort.)

=== Source code ===
* {{flightgear source|path=src/Scripting/NasalUnitTesting.hxx}}
* {{flightgear source|path=src/Scripting/NasalUnitTesting.cxx}}

=== Examples ===
* {{fgdata source|path=Nasal/std.nut}}
* {{fgdata source|path=Nasal/string.nut}}
* {{fgdata source|path=Nasal/test_emesary.nut}}

== External links ==
* [https://people.freedesktop.org/~mmohrhard/cppunit/group___assertions.htm CppUnit Documentation - Making assertions] - The unit test framework that runs the unit tests.

[[Category:Nasal]]
[[Category:Software testing]]

Nasal unit tests

2026-03-14T22:01:24Z

Johan G: /* Writing unit test files */ + Test files are usually placed in the same directory as the Nasal modules

'''Nasal unit tests''' is way to test that Nasal functions returns expected values. Writing unit tests with test cases for functions allow you to run tests that check if you made errors when writing the function or check if you introduced bugs when extending or maintaining the function. I twill also later help other to continue to maintain the Nasal files.

== Writing unit test files ==
The files with the unit tests, the test files, are regular Nasal files but with the file ending <code>.nut</code> (for Nasal unit test).

The name of the test files usually begin with <code>test_</code> and then usually use the same file name as the module that are to be tested.

The test files are usually placed in the same directory as the Nasal modules that are to be tested.

=== Optional header comment block ===
Test files often begin with a comment block with a header with a short description of what the file is, followed by a commented line with how to run the test, foe example something like this:

<syntaxhighlight lang="Nasal">
#-------------------------------------------------------------------------------
# Test file for multiplayer time synchronization
# File: test_mp_time_sync.nut
# Author: Iam Cardholder
# Created: 2026-03-14
# Licence: GPLv2 or later
#-------------------------------------------------------------------------------

# fgcommand("nasal-test", props.Node.new({"path":"test_mp_time_sync.nut"}));
</syntaxhighlight>

=== Optional setup and tear-down functions ===
Optionally the unit test file can have a <code>setUp()</code> and a <code>tearDown()</code> function. These are useful if for example some other module need to be loaded.

Most of the time these functions are used for printing to the console and/or log that the test has started or finished.

<syntaxhighlight lang="Nasal">
# Optional setup function
var setUp = func {
logprint(LOG_INFO, "mp_time_sync tests begin");
};

# Optional tear-down function
var tearDown = func {
logprint(LOG_INFO, "mp_time_sync tests finished");
};
</syntaxhighlight>

=== Test functions and test cases ===
{{stub|section=1}}
{{WIP|Parts of the information below may be inaccurate. The author is currently trying to understand how this works. Would be grateful for help.}}
The names of the test functions usually matches the names of the functions to test except they, like the name of the test file, begin with <code>test_</code>.

Tests are written as functions with one or more test cases. If needed modules can be loaded, variables can be defined etc. that will then be used for each test case.

You can have as many test cases as needed and each test case can be using using one of four different tests:
* <code>assert</code>
* <code>fail</code>
* <code>assert_equal</code>
* <code>assert_doubles_equal</code>
* <code>equal</code>

=== unitTest.assert() ===
{{Nasal doc
| syntax = unitTest.assert(bool[, message])
| text = Asserts that a boolean is true. If false the test fails with an optional message, the file path, line number, and the runtime error "Test assert failed".
| mode =
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=47|t=Source}}
| version = Likely 2024.1
| param1 = bool
| param2 = message
| param1text = A boolean. Usually the return from the function to test. Can be an expression.
| param2text = An optional string with a message to show with the file path and line number.
| example1text =
| example1 =
}}

=== unitTest.fail() ===
{{Nasal doc
| syntax = unitTest.fail([message])
| text = Will fail the test with an optional message, the file path, line number, and the runtime error "Test failed".
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=72|t=Source}}
| version = Likely 2024.1.2
| param1 = message
| param1text = An optional string with a message to show with the file path and line number.
| example1text =
| example1 =
}}

=== unitTest.assert_equal() ===
{{Nasal doc
| syntax = unitTest.assert_equal(a, b[, message])
| text = Compares a and b. If not equal the test fails with an optional message, the file path, line number, and the runtime error "assert_equal failed", or if defined the message.
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=94|t=Source}}
| version = Likely 2024.1.2
| param1 = a
| param2 = b
| param3 = message
| param1text = A value. Usually the expected value to be returned. Can be an expression.
| param2text = A value. Usually the value returned from the function to be tested. Can be an expression.
| param3text = An optional string with a message to show with the file path and line number. Will also be the runtime error. Defaults to "assert_equal failed".
| example1text =
| example1 =
}}

=== unitTest.assert_doubles_equal() ===
{{Nasal doc
| syntax = unitTest.assert_doubles_equal(a, b, tolerance[, message])
| text = Compares two doubles. If the difference larger or equal to the tolerance the test fails with an optional message, the file path, line number, and the runtime error "assert_doubles_equal failed", or if defined the message.
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=115|t=Source}}
| version = Likely 2024.1.2
| param1 = a
| param2 = b
| param3 = tolerance
| param4 = message
| param1text = A double. Usually the expected value to be returned. Can be an expression.
| param2text = A double. Usually the value returned from the function to be tested. Can be an expression.
| param3text = A double with the tolerance.
| param4text = An optional string with a message to show with the file path and line number. Will also be the runtime error. Defaults to "assert_doubles_equal failed".
| example1text =
| example1 =
}}

=== unitTest.equal() ===
{{Nasal doc
| syntax = unitTest.equal(a, b)
| text = Compares two values.
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=136|t=Source}}
| version = Likely 2024.1.2
| param1 = a
| param2 = b
| param1text = A value. Usually the expected value to be returned. Can be an expression.
| param2text = A value. Usually the value returned from the function to be tested. Can be an expression.
| example1text =
| example1 =
}}

== Running the tests ==
The tests are run with the FGCommands:

* <code>fgcommand("nasal-test", props.node.new({"path":"<path to Nasal test file>"}));</code>
* <code>fgcommand("nasal-test-dir", props.node.new({"path":"<path to directory with Nasal test files>"}));</code>

== See also ==
* [[Software testing]]
* [[Nasal Unit Testing Framework]] (An older effort.)

=== Source code ===
* {{flightgear source|path=src/Scripting/NasalUnitTesting.hxx}}
* {{flightgear source|path=src/Scripting/NasalUnitTesting.cxx}}

=== Examples ===
* {{fgdata source|path=Nasal/std.nut}}
* {{fgdata source|path=Nasal/string.nut}}
* {{fgdata source|path=Nasal/test_emesary.nut}}

== External links ==
* [https://people.freedesktop.org/~mmohrhard/cppunit/group___assertions.htm CppUnit Documentation - Making assertions] - The unit test framework that runs the unit tests.

[[Category:Nasal]]
[[Category:Software testing]]

Nasal unit tests

2026-03-14T21:37:09Z

Johan G: /* External links */ +link: Assertions in the CppUnit documentation

'''Nasal unit tests''' is way to test that Nasal functions returns expected values. Writing unit tests with test cases for functions allow you to run tests that check if you made errors when writing the function or check if you introduced bugs when extending or maintaining the function. I twill also later help other to continue to maintain the Nasal files.

== Writing unit test files ==
The Nasal test files are regular Nasal files but with the file ending <code>.nut</code> (for Nasal unit test).

The name of the test files usually begin with <code>test_</code> and then usually use the same file name as the module that are to be tested.

=== Optional header comment block ===
Test files often begin with a comment block with a header with a short description of what the file is, followed by a commented line with how to run the test, foe example something like this:

<syntaxhighlight lang="Nasal">
#-------------------------------------------------------------------------------
# Test file for multiplayer time synchronization
# File: test_mp_time_sync.nut
# Author: Iam Cardholder
# Created: 2026-03-14
# Licence: GPLv2 or later
#-------------------------------------------------------------------------------

# fgcommand("nasal-test", props.Node.new({"path":"test_mp_time_sync.nut"}));
</syntaxhighlight>

=== Optional setup and tear-down functions ===
Optionally the unit test file can have a <code>setUp()</code> and a <code>tearDown()</code> function. These are useful if for example some other module need to be loaded.

Most of the time these functions are used for printing to the console and/or log that the test has started or finished.

<syntaxhighlight lang="Nasal">
# Optional setup function
var setUp = func {
logprint(LOG_INFO, "mp_time_sync tests begin");
};

# Optional tear-down function
var tearDown = func {
logprint(LOG_INFO, "mp_time_sync tests finished");
};
</syntaxhighlight>

=== Test functions and test cases ===
{{stub|section=1}}
{{WIP|Parts of the information below may be inaccurate. The author is currently trying to understand how this works. Would be grateful for help.}}
The names of the test functions usually matches the names of the functions to test except they, like the name of the test file, begin with <code>test_</code>.

Tests are written as functions with one or more test cases. If needed modules can be loaded, variables can be defined etc. that will then be used for each test case.

You can have as many test cases as needed and each test case can be using using one of four different tests:
* <code>assert</code>
* <code>fail</code>
* <code>assert_equal</code>
* <code>assert_doubles_equal</code>
* <code>equal</code>

=== unitTest.assert() ===
{{Nasal doc
| syntax = unitTest.assert(bool[, message])
| text = Asserts that a boolean is true. If false the test fails with an optional message, the file path, line number, and the runtime error "Test assert failed".
| mode =
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=47|t=Source}}
| version = Likely 2024.1
| param1 = bool
| param2 = message
| param1text = A boolean. Usually the return from the function to test. Can be an expression.
| param2text = An optional string with a message to show with the file path and line number.
| example1text =
| example1 =
}}

=== unitTest.fail() ===
{{Nasal doc
| syntax = unitTest.fail([message])
| text = Will fail the test with an optional message, the file path, line number, and the runtime error "Test failed".
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=72|t=Source}}
| version = Likely 2024.1.2
| param1 = message
| param1text = An optional string with a message to show with the file path and line number.
| example1text =
| example1 =
}}

=== unitTest.assert_equal() ===
{{Nasal doc
| syntax = unitTest.assert_equal(a, b[, message])
| text = Compares a and b. If not equal the test fails with an optional message, the file path, line number, and the runtime error "assert_equal failed", or if defined the message.
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=94|t=Source}}
| version = Likely 2024.1.2
| param1 = a
| param2 = b
| param3 = message
| param1text = A value. Usually the expected value to be returned. Can be an expression.
| param2text = A value. Usually the value returned from the function to be tested. Can be an expression.
| param3text = An optional string with a message to show with the file path and line number. Will also be the runtime error. Defaults to "assert_equal failed".
| example1text =
| example1 =
}}

=== unitTest.assert_doubles_equal() ===
{{Nasal doc
| syntax = unitTest.assert_doubles_equal(a, b, tolerance[, message])
| text = Compares two doubles. If the difference larger or equal to the tolerance the test fails with an optional message, the file path, line number, and the runtime error "assert_doubles_equal failed", or if defined the message.
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=115|t=Source}}
| version = Likely 2024.1.2
| param1 = a
| param2 = b
| param3 = tolerance
| param4 = message
| param1text = A double. Usually the expected value to be returned. Can be an expression.
| param2text = A double. Usually the value returned from the function to be tested. Can be an expression.
| param3text = A double with the tolerance.
| param4text = An optional string with a message to show with the file path and line number. Will also be the runtime error. Defaults to "assert_doubles_equal failed".
| example1text =
| example1 =
}}

=== unitTest.equal() ===
{{Nasal doc
| syntax = unitTest.equal(a, b)
| text = Compares two values.
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=136|t=Source}}
| version = Likely 2024.1.2
| param1 = a
| param2 = b
| param1text = A value. Usually the expected value to be returned. Can be an expression.
| param2text = A value. Usually the value returned from the function to be tested. Can be an expression.
| example1text =
| example1 =
}}

== Running the tests ==
The tests are run with the FGCommands:

* <code>fgcommand("nasal-test", props.node.new({"path":"<path to Nasal test file>"}));</code>
* <code>fgcommand("nasal-test-dir", props.node.new({"path":"<path to directory with Nasal test files>"}));</code>

== See also ==
* [[Software testing]]
* [[Nasal Unit Testing Framework]] (An older effort.)

=== Source code ===
* {{flightgear source|path=src/Scripting/NasalUnitTesting.hxx}}
* {{flightgear source|path=src/Scripting/NasalUnitTesting.cxx}}

=== Examples ===
* {{fgdata source|path=Nasal/std.nut}}
* {{fgdata source|path=Nasal/string.nut}}
* {{fgdata source|path=Nasal/test_emesary.nut}}

== External links ==
* [https://people.freedesktop.org/~mmohrhard/cppunit/group___assertions.htm CppUnit Documentation - Making assertions] - The unit test framework that runs the unit tests.

[[Category:Nasal]]
[[Category:Software testing]]

Nasal unit tests

2026-03-14T21:32:48Z

Johan G: /* unitTest.assert() */ fix: Remove double parameter in Template:Nasal doc

'''Nasal unit tests''' is way to test that Nasal functions returns expected values. Writing unit tests with test cases for functions allow you to run tests that check if you made errors when writing the function or check if you introduced bugs when extending or maintaining the function. I twill also later help other to continue to maintain the Nasal files.

== Writing unit test files ==
The Nasal test files are regular Nasal files but with the file ending <code>.nut</code> (for Nasal unit test).

The name of the test files usually begin with <code>test_</code> and then usually use the same file name as the module that are to be tested.

=== Optional header comment block ===
Test files often begin with a comment block with a header with a short description of what the file is, followed by a commented line with how to run the test, foe example something like this:

<syntaxhighlight lang="Nasal">
#-------------------------------------------------------------------------------
# Test file for multiplayer time synchronization
# File: test_mp_time_sync.nut
# Author: Iam Cardholder
# Created: 2026-03-14
# Licence: GPLv2 or later
#-------------------------------------------------------------------------------

# fgcommand("nasal-test", props.Node.new({"path":"test_mp_time_sync.nut"}));
</syntaxhighlight>

=== Optional setup and tear-down functions ===
Optionally the unit test file can have a <code>setUp()</code> and a <code>tearDown()</code> function. These are useful if for example some other module need to be loaded.

Most of the time these functions are used for printing to the console and/or log that the test has started or finished.

<syntaxhighlight lang="Nasal">
# Optional setup function
var setUp = func {
logprint(LOG_INFO, "mp_time_sync tests begin");
};

# Optional tear-down function
var tearDown = func {
logprint(LOG_INFO, "mp_time_sync tests finished");
};
</syntaxhighlight>

=== Test functions and test cases ===
{{stub|section=1}}
{{WIP|Parts of the information below may be inaccurate. The author is currently trying to understand how this works. Would be grateful for help.}}
The names of the test functions usually matches the names of the functions to test except they, like the name of the test file, begin with <code>test_</code>.

Tests are written as functions with one or more test cases. If needed modules can be loaded, variables can be defined etc. that will then be used for each test case.

You can have as many test cases as needed and each test case can be using using one of four different tests:
* <code>assert</code>
* <code>fail</code>
* <code>assert_equal</code>
* <code>assert_doubles_equal</code>
* <code>equal</code>

=== unitTest.assert() ===
{{Nasal doc
| syntax = unitTest.assert(bool[, message])
| text = Asserts that a boolean is true. If false the test fails with an optional message, the file path, line number, and the runtime error "Test assert failed".
| mode =
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=47|t=Source}}
| version = Likely 2024.1
| param1 = bool
| param2 = message
| param1text = A boolean. Usually the return from the function to test. Can be an expression.
| param2text = An optional string with a message to show with the file path and line number.
| example1text =
| example1 =
}}

=== unitTest.fail() ===
{{Nasal doc
| syntax = unitTest.fail([message])
| text = Will fail the test with an optional message, the file path, line number, and the runtime error "Test failed".
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=72|t=Source}}
| version = Likely 2024.1.2
| param1 = message
| param1text = An optional string with a message to show with the file path and line number.
| example1text =
| example1 =
}}

=== unitTest.assert_equal() ===
{{Nasal doc
| syntax = unitTest.assert_equal(a, b[, message])
| text = Compares a and b. If not equal the test fails with an optional message, the file path, line number, and the runtime error "assert_equal failed", or if defined the message.
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=94|t=Source}}
| version = Likely 2024.1.2
| param1 = a
| param2 = b
| param3 = message
| param1text = A value. Usually the expected value to be returned. Can be an expression.
| param2text = A value. Usually the value returned from the function to be tested. Can be an expression.
| param3text = An optional string with a message to show with the file path and line number. Will also be the runtime error. Defaults to "assert_equal failed".
| example1text =
| example1 =
}}

=== unitTest.assert_doubles_equal() ===
{{Nasal doc
| syntax = unitTest.assert_doubles_equal(a, b, tolerance[, message])
| text = Compares two doubles. If the difference larger or equal to the tolerance the test fails with an optional message, the file path, line number, and the runtime error "assert_doubles_equal failed", or if defined the message.
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=115|t=Source}}
| version = Likely 2024.1.2
| param1 = a
| param2 = b
| param3 = tolerance
| param4 = message
| param1text = A double. Usually the expected value to be returned. Can be an expression.
| param2text = A double. Usually the value returned from the function to be tested. Can be an expression.
| param3text = A double with the tolerance.
| param4text = An optional string with a message to show with the file path and line number. Will also be the runtime error. Defaults to "assert_doubles_equal failed".
| example1text =
| example1 =
}}

=== unitTest.equal() ===
{{Nasal doc
| syntax = unitTest.equal(a, b)
| text = Compares two values.
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=136|t=Source}}
| version = Likely 2024.1.2
| param1 = a
| param2 = b
| param1text = A value. Usually the expected value to be returned. Can be an expression.
| param2text = A value. Usually the value returned from the function to be tested. Can be an expression.
| example1text =
| example1 =
}}

== Running the tests ==
The tests are run with the FGCommands:

* <code>fgcommand("nasal-test", props.node.new({"path":"<path to Nasal test file>"}));</code>
* <code>fgcommand("nasal-test-dir", props.node.new({"path":"<path to directory with Nasal test files>"}));</code>

== See also ==
* [[Software testing]]
* [[Nasal Unit Testing Framework]] (An older effort.)

=== Source code ===
* {{flightgear source|path=src/Scripting/NasalUnitTesting.hxx}}
* {{flightgear source|path=src/Scripting/NasalUnitTesting.cxx}}

=== Examples ===
* {{fgdata source|path=Nasal/std.nut}}
* {{fgdata source|path=Nasal/string.nut}}
* {{fgdata source|path=Nasal/test_emesary.nut}}

[[Category:Nasal]]
[[Category:Software testing]]

Nasal unit tests

2026-03-14T21:29:48Z

Johan G: /* Test functions and test cases */ +template:WIP; + New section describing what seems to be the syntax, comparing flightgear/src/Scripting/NasalUnitTesting.cxx with the assertions described in the CppUnit Cookbook. Have yet to test. Would be grateful for any help.

'''Nasal unit tests''' is way to test that Nasal functions returns expected values. Writing unit tests with test cases for functions allow you to run tests that check if you made errors when writing the function or check if you introduced bugs when extending or maintaining the function. I twill also later help other to continue to maintain the Nasal files.

== Writing unit test files ==
The Nasal test files are regular Nasal files but with the file ending <code>.nut</code> (for Nasal unit test).

The name of the test files usually begin with <code>test_</code> and then usually use the same file name as the module that are to be tested.

=== Optional header comment block ===
Test files often begin with a comment block with a header with a short description of what the file is, followed by a commented line with how to run the test, foe example something like this:

<syntaxhighlight lang="Nasal">
#-------------------------------------------------------------------------------
# Test file for multiplayer time synchronization
# File: test_mp_time_sync.nut
# Author: Iam Cardholder
# Created: 2026-03-14
# Licence: GPLv2 or later
#-------------------------------------------------------------------------------

# fgcommand("nasal-test", props.Node.new({"path":"test_mp_time_sync.nut"}));
</syntaxhighlight>

=== Optional setup and tear-down functions ===
Optionally the unit test file can have a <code>setUp()</code> and a <code>tearDown()</code> function. These are useful if for example some other module need to be loaded.

Most of the time these functions are used for printing to the console and/or log that the test has started or finished.

<syntaxhighlight lang="Nasal">
# Optional setup function
var setUp = func {
logprint(LOG_INFO, "mp_time_sync tests begin");
};

# Optional tear-down function
var tearDown = func {
logprint(LOG_INFO, "mp_time_sync tests finished");
};
</syntaxhighlight>

=== Test functions and test cases ===
{{stub|section=1}}
{{WIP|Parts of the information below may be inaccurate. The author is currently trying to understand how this works. Would be grateful for help.}}
The names of the test functions usually matches the names of the functions to test except they, like the name of the test file, begin with <code>test_</code>.

Tests are written as functions with one or more test cases. If needed modules can be loaded, variables can be defined etc. that will then be used for each test case.

You can have as many test cases as needed and each test case can be using using one of four different tests:
* <code>assert</code>
* <code>fail</code>
* <code>assert_equal</code>
* <code>assert_doubles_equal</code>
* <code>equal</code>

=== unitTest.assert() ===
{{Nasal doc
| syntax = unitTest.assert(bool[, message])
| text = Asserts that a boolean is true. If false the test fails with an optional message, the file path, line number, and the runtime error "Test assert failed".
| mode =
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=47|t=Source}}
| version = Likely 2024.1
| param1 = bool
| param2 = message
| param1text = A boolean. Usually the return from the function to test. Can be an expression.
| param2text = An optional string with a message to show with the file path and line number.
| example1 =
| example1text =
| example1 =
}}

=== unitTest.fail() ===
{{Nasal doc
| syntax = unitTest.fail([message])
| text = Will fail the test with an optional message, the file path, line number, and the runtime error "Test failed".
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=72|t=Source}}
| version = Likely 2024.1.2
| param1 = message
| param1text = An optional string with a message to show with the file path and line number.
| example1text =
| example1 =
}}

=== unitTest.assert_equal() ===
{{Nasal doc
| syntax = unitTest.assert_equal(a, b[, message])
| text = Compares a and b. If not equal the test fails with an optional message, the file path, line number, and the runtime error "assert_equal failed", or if defined the message.
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=94|t=Source}}
| version = Likely 2024.1.2
| param1 = a
| param2 = b
| param3 = message
| param1text = A value. Usually the expected value to be returned. Can be an expression.
| param2text = A value. Usually the value returned from the function to be tested. Can be an expression.
| param3text = An optional string with a message to show with the file path and line number. Will also be the runtime error. Defaults to "assert_equal failed".
| example1text =
| example1 =
}}

=== unitTest.assert_doubles_equal() ===
{{Nasal doc
| syntax = unitTest.assert_doubles_equal(a, b, tolerance[, message])
| text = Compares two doubles. If the difference larger or equal to the tolerance the test fails with an optional message, the file path, line number, and the runtime error "assert_doubles_equal failed", or if defined the message.
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=115|t=Source}}
| version = Likely 2024.1.2
| param1 = a
| param2 = b
| param3 = tolerance
| param4 = message
| param1text = A double. Usually the expected value to be returned. Can be an expression.
| param2text = A double. Usually the value returned from the function to be tested. Can be an expression.
| param3text = A double with the tolerance.
| param4text = An optional string with a message to show with the file path and line number. Will also be the runtime error. Defaults to "assert_doubles_equal failed".
| example1text =
| example1 =
}}

=== unitTest.equal() ===
{{Nasal doc
| syntax = unitTest.equal(a, b)
| text = Compares two values.
| source = {{flightgear file|p=src/Scripting/NasalUnitTesting.cxx|l=136|t=Source}}
| version = Likely 2024.1.2
| param1 = a
| param2 = b
| param1text = A value. Usually the expected value to be returned. Can be an expression.
| param2text = A value. Usually the value returned from the function to be tested. Can be an expression.
| example1text =
| example1 =
}}

== Running the tests ==
The tests are run with the FGCommands:

* <code>fgcommand("nasal-test", props.node.new({"path":"<path to Nasal test file>"}));</code>
* <code>fgcommand("nasal-test-dir", props.node.new({"path":"<path to directory with Nasal test files>"}));</code>

== See also ==
* [[Software testing]]
* [[Nasal Unit Testing Framework]] (An older effort.)

=== Source code ===
* {{flightgear source|path=src/Scripting/NasalUnitTesting.hxx}}
* {{flightgear source|path=src/Scripting/NasalUnitTesting.cxx}}

=== Examples ===
* {{fgdata source|path=Nasal/std.nut}}
* {{fgdata source|path=Nasal/string.nut}}
* {{fgdata source|path=Nasal/test_emesary.nut}}

[[Category:Nasal]]
[[Category:Software testing]]

FlightGear wiki:Village pump

2026-03-14T12:36:45Z

Johan G: /* Nasal unit test assertion documentation */ New section. Is there any other documentation than the source code and Nasal unit test files?

__NEWSECTIONLINK__
{{Archives|[[/Archive 2012|2012]]|[[/Archive 2013|2013]]|[[/Archive 2014|2014]]|[[/Archive 2015|2015]]|[[/Archive 2016|2016]]|[[/Archive 2017|2017]]|[[/Archive 2018|2018]]|[[/Archive 2019|2019]]|[[/Archive 2020|2020]]|[[/Archive 2021|2021]]|[[/Archive 2022|2022]]}}
{{shortcut|FGW:VP}}

Welcome to the '''Village Pump'''. This page is used to discuss the technical issues, operations and guidelines of the [[FlightGear wiki]].

Please <span class="plainlinks">[{{fullurl:{{FULLPAGENAME}}|action=edit&section=new}} add new topics]</span> to the '''bottom''' of this page.

Old discussions should be moved to a [[FlightGear wiki:Village pump/Archive YEAR]]. These discussions can then be moved to a relevant talk page if appropriate.

__TOC__

== MediaWiki updated to 1.39.6 ==

We have updated MediaWiki to its latest LTS version 1.39.6 today. Although we've tested the update, chances are that we've missed certain scenarios or features. Please report any issues that you may encounter.

[[User:Gijs|Gijs]] ([[User talk:Gijs|talk]]) 09:31, 30 January 2024 (UTC)

== Embedded YouTube videos broken ==

It seems that the [[mw:Extension:EmbedVideo|EmbedVideo extension]] was removed at some point. Consequently, pages such as [[Howto:Creating FlightGear Promo Videos]] are broken. At present, the best replacements seems to be [[mw:Extension:EmbedVideo_(fork)|a fork]] and [[mw:Extension:YouTube|Extension:YouTube]].

—'''''[[User:Red Leader|<span style="color:red">Red Leader</span>]]''''' ([[User talk:Red Leader|talk]], [[Special:Contributions/Red Leader|contribs]]) 19:21, 30 January 2024 (UTC)

: Hi,
: Thanks for the report. It was introduced by today's update, but should be fixed now.
: [[User:Gijs|Gijs]] ([[User talk:Gijs|talk]]) 21:21, 30 January 2024 (UTC)

:: Confirmed, thanks. And I’d completely forgotten about {{[[Template:Wikipedia|wikipedia]]}}. 😅
:: '''''[[User:Red Leader|<span style="color:red">Red Leader</span>]]''''' ([[User talk:Red Leader|talk]], [[Special:Contributions/Red Leader|contribs]]) 21:57, 30 January 2024 (UTC)

== Forum registration problem ==

Hello,
I would like to register on the forum, but I tried several times without success. I sent an email to the administrator some time ago, but it seems to have been lost. I don't know what to do, is there somebody here who could help? Please tell me if you need additional information.
Thanks very much in advance. [[User:Kestrel|Kestrel]] ([[User talk:Kestrel|talk]]) 13:14, 25 March 2024 (UTC)

: Hi,
: That's unfortunate! You can find my email address at https://forum.flightgear.org/contact.php Please try again if you've done that before, I'll actively monitor the address for any incoming messages, and let me know if you don't get a reply.
: [[User:Gijs|Gijs]] ([[User talk:Gijs|talk]]) 15:01, 25 March 2024 (UTC) (forum admin)

== Sidebar link for "Build server" is broken ==

Hello,

Just wanted to bring to someones attention that the URL for "Build server" currently 404s. Not sure if this resource still exists or if its URL has changed.

Cheers!
-Joshua

: Hi Joshua,
: The URL is still correct, but the build server is temporarily down due to a server failure. It's being worked on, so should be back up "soon".
: [[User:Gijs|Gijs]] ([[User talk:Gijs|talk]]) 12:29, 3 September 2024 (UTC)

== FlightGear Wikipedia article image needs correctly sourced Flightgear wiki screenshot ==
https://en.wikipedia.org/wiki/FlightGear

The image used for the Flightgear Wikipedia article appears to have been deleted, because it was sourced from the following Flightgear-wiki screenshot page:

[[:File:Bo 105 over Sint Marteen.png]]

which referred to an imgur link instead of the following thread, which gives a CC license based on a google search of the file name:

https://forum.flightgear.org/viewtopic.php?f=88&t=32163&start=0

Discussion on Wikipedia:

https://en.wikipedia.org/wiki/Wikipedia:Files_for_discussion/2024_December_7#File:FlightGear_Flight_Sim_Bo_105_over_Sint_Marteen.png

> ''Subsequent comments should be made on the appropriate discussion page (such as the file's talk page or in a [https://en.wikipedia.org/wiki/Wikipedia:Deletion_review deletion review]).''

The person who uploaded it, or someone from the wiki, should ideally fix the FlightGear wiki page, and do a deletion review for the Wikipedia file. The file may have been used in multiple pages since screenshots are uncommon on Wikipedia due to proprietary apps. Feel free to remove this comment once it's taken care of. Good luck

== Issues with three templates ==

Hi,

The [[Template:Fgmeta_commit|fgmeta commit]] template appears to be broken. It used to work in the first ''Note'' [[Scripted_Compilation_on_Linux_Debian/Ubuntu#For_the_curious:_the_SSH_way|here]] (see the URL).

Also, I tried to use [[Template:Repo_link#Site:_Generic]] to create a link to the [https://gitlab.kitware.com/cmake/cmake.git CMake repo], but didn't manage: IIRC, the link text was empty.

Finally, [[Template:Fgmeta_source]] doesn't seem to to what the doc. says for ''simplepath'': with
<pre><nowiki>{{fgmeta source
| path = download_and_compile.sh
| simplepath = 1
}}</nowiki></pre>

the link text starts with a slash, so I used
<pre><nowiki>{{fgmeta source
| path = download_and_compile.sh
| text = download_and_compile.sh
}}</nowiki></pre>
which is of course more redundant.

Thanks for considering! :-)

[[User:Rominet|Rominet]] ([[User talk:Rominet|talk]])

: Good catch. I need to look into that one. I may not have coded the commit part of GitLab into the master {{tl|repo_link}} template.

: [[User:Bugman|Bugman]] ([[User talk:Bugman|talk]]) 15:41, 13 March 2025 (UTC)

:: All fixed. It was quite simple - the {{tl|fgmeta_source}} template was missing the <code>proj</code> parameter. I've also fixed {{tl|fgmeta_clone}}.

:: [[User:Bugman|Bugman]] ([[User talk:Bugman|talk]]) 15:53, 13 March 2025 (UTC)

::: Thanks for the reply and fixes, Bugman! (And sorry for the delay, I didn't see any notification...) I see the first item is indeed addressed. Regarding the second item, well, I see no place where I'd really want to use this now on the d&c page, so didn't test it. As for the third one, I still get <code>/download_and_compile.sh</code> in the Preview when I try the above {{tl|fgmeta_source}} snippet with <code>simplepath = 1</code>.

::: I looked at {{tl|fgmeta_clone}} too; it looks nice but seems to default to the <code>git://</code> protocol. Would it be possible to make it default to using <code>https://</code>? Thanks again. :-)

::: [[User:Rominet|Rominet]] ([[User talk:Rominet|talk]])

:::: Not a problem. For the <code>simplepath</code> parameter, that is the designed behaviour in the {{tl|repo link}} template. In most cases our repositories have complex directory structures and the desired output is the absolute file path, removing the protocol and URL parts of the path. Do you wish to simply have the file name there? No one had asked for that before, so I never added an option for that. In the case of the source repositories, you often want to remove the first part of the absolute path so that for example in SimGear, {{simgear source|path=simgear/scene/util/QuadTreeBuilder.hxx|simplepath=1}} (<nowiki>{{simgear source|path=simgear/scene/util/QuadTreeBuilder.hxx|simplepath=1}}</nowiki>) would be shown as {{simgear source|path=simgear/scene/util/QuadTreeBuilder.hxx|text=scene/util/QuadTreeBuilder.hxx}} (<nowiki>{{simgear source|path=simgear/scene/util/QuadTreeBuilder.hxx|text=scene/util/QuadTreeBuilder.hxx}}</nowiki>. This is not scriptable in MediaWiki so I left it all for the text parameter.

:::: For the protocol, I have now added the <code>protocol</code> parameter. E.g. <nowiki>{{fgmeta clone | protocol = https}}</nowiki>. That will give <code>{{fgmeta clone | protocol = https}}</code> (as of today generated as <code><nowiki>git clone https://gitlab.com/flightgear/fgmeta.git</nowiki></code>).

:::: [[User:Bugman|Bugman]] ([[User talk:Bugman|talk]]) 08:51, 24 March 2025 (UTC)

::::: Thanks Bugman, I've updated the [[Scripted_Compilation_on_Linux_Debian/Ubuntu|download_and_compile.sh page]] to use <code><nowiki>{{fgmeta clone | protocol = https}}</nowiki></code> as you proposed; it works great. For the link to download_and_compile.sh, I can continue to use <code><nowiki>{{fgmeta source | path = download_and_compile.sh | text = download_and_compile.sh}}</nowiki></code>, no problem.

::::: As far as I'm concerned, everything is resolved here, so this thread/section can be deleted if someone wants to “clean up”.

::::: ''Other subject:'' the only remaining thing is that I didn't receive any notification, neither for your replies here nor for the January changes by [[User:Jebba|Jebba]] to the [[Scripted_Compilation_on_Linux_Debian/Ubuntu|download_and_compile.sh page]] that is on my watchlist. I used to receive email notifications for these things years ago, haven't changed my preferences regarding this and don't see any setting that would explain why I don't receive these notifications anymore. Maybe email sending by the wiki software is not quite well configured according to current standards (SPF, DKIM, DMARC)?

::::: [[User:Rominet|Rominet]] ([[User talk:Rominet|talk]])

== Improve the 'simgear clone', 'flightgear clone' and 'fgdata clone' templates ==

Hi,

In order to improve [[Fedora_Packages_and_Compiling]], it would be nice to have the <code><nowiki>{{simgear clone}}</nowiki></code>, <code><nowiki>{{flightgear clone}}</nowiki></code> and <code><nowiki>{{fgdata clone}}</nowiki></code> templates on par with <code><nowiki>{{fgmeta clone}}</nowiki></code> (support for the <code>protocol</code> parameter, etc.). I tried

<nowiki>{{simgear clone | protocol = https | opt = --single-branch --branch release/2024.1 | post = simgear}}</nowiki>

but it doesn't seem to work, as the preview shows this:

<nowiki>git clone --single-branch --branch release/2024.1 git://gitlab.com simgear</nowiki>

(ditto with <code>flightear clone</code> and <code>fgdata clone</code>). Thanks in advance :-)

[[User:Rominet|Rominet]] ([[User talk:Rominet|talk]])

: I needed a while to work out the best strategy for these changes. I've now gone through all of the {{tl|repo link}} cloning subtemplates listed on {{tl|repo link/doc related}} and added the <code>project</code> parameter to the templates and the optional <code>protocol</code> parameter. These changes were required as the <code>gl</code> section of the {{tl|repo_link}} template is constructed differently to the <code>sf</code> section. I've also updated the git cloning documentation {{tl|repo link/doc git clone}}. I hope this covers everything you need.

: [[User:Bugman|Bugman]] ([[User talk:Bugman|talk]]) 07:48, 1 April 2025 (UTC)

:: Thanks a lot, Bugman, this works great! Your changes allowed me to perform [https://wiki.flightgear.org/w/index.php?title=Fedora_Packages_and_Compiling&type=revision&diff=141687&oldid=141513 this edit] in [[Fedora_Packages_and_Compiling]]. The only remaining <code>git clone</code> command written in full on that page is for FG's fork of OpenSceneGraph at GitLab. I understand that choosing a proper name for an applicable <code><nowiki>{{... clone}}</nowiki></code> template probably requires some careful thinking... ;-)

:: [[User:Rominet|Rominet]] ([[User talk:Rominet|talk]])

== Default text in Template:Repo link ==

Hi,

The default ''text'' in {{tl|Repo link}} gives somewhat pleasant link texts such as
flightgear/flightgear/src/Scripting/NasalSys.cxx
when the ''site'' is <code>sourceforge</code>, however the result looks like a bug for other sites (though I understand this may be as intended). To be clear, the URLs are correct but the default link texts look weird because they start with the unqualified site name rather than the fully-qualified domain name. For instance,
{{obr}}fgmeta source{{cbr}}
yields [https://gitlab.com/flightgear/fgmeta gitlab/flightgear/fgmeta/next] rather than [https://gitlab.com/flightgear/fgmeta gitlab.com/flightgear/fgmeta/next]. I suggest to replace <code>gitlab</code> with <code>gitlab.com</code> in the default text (where the HTML comment says “Site advertising”) and do the same for <code>github</code>.

Note: the Gitorious web site doesn't exist anymore, maybe that should be removed from the template?

Thanks for considering; I can do the replacement if you wish.

[[User:Rominet|Rominet]] ([[User talk:Rominet|talk]]) 10:38, 12 November 2025 (UTC)

: Sounds sensible, so please go ahead!
: Regarding Gitorious, it may be nice to link to an archived version of the repos, such as https://archive.softwareheritage.org/browse/origin/directory/?origin_url=https://gitorious.org/flightgear/fgdata.git&visit_type=git Altough this only makes sense for repos or branches that are not part of our current GitLab...
: [[User:Gijs|Gijs]] ([[User talk:Gijs|talk]]) 13:58, 12 November 2025 (UTC)

:: [https://wiki.flightgear.org/w/index.php?title=Template:Repo_link&action=history Done], thanks Gijs!
::

:: One should be careful using this, though, because the resulting link ''texts'' may be non-existing URLs (after prepending the protocol) despite looking like valid ones, as shown by the first example in [[User:Rominet/Sandbox#FGMeta-Python repo templates]]!

:: So, to avoid people getting trapped by this, maybe the default link text should start with something like <code>[GitLab]/...</code> rather than the <code>gitlab.com/...</code> I just put (to make it clear that such link texts are not supposed to be “Internet addresses”).
:: [[User:Rominet|Rominet]] ([[User talk:Rominet|talk]]) 16:20, 12 November 2025 (UTC)

::: This is now implemented. For instance, <code>{{obr}}fgmeta-python source {{!}} path = pyproject.toml {{!}} tag = 1.0.0b1 {{cbr}}</code> results in {{fgmeta-python source | path = pyproject.toml | tag = 1.0.0b1 }}. This also holds for GitHub and GitoriousIsNowClosed. SourceForge has no such prefix for now (it initially didn't, and editing its part of {{tl|Repo link}} requires a bit more temerity than what I have at the moment :-)).
::: [[User:Rominet|Rominet]] ([[User talk:Rominet|talk]]) 09:15, 14 November 2025 (UTC)

: That's a good idea. Note for Gitorious - I added this because there are a number of historical documents/pages that refer to developments that occurred on Gitorious which were not migrated to SourceForge. I originally made the Gitorious links work by pointing to the archive by the Internet Archive (see [[Gitorious]]). However that archive has been offline for a few years now. The Internet Archive are storing all the data so it may return one day.

: [[User:Bugman|Bugman]] ([[User talk:Bugman|talk]]) 22:06, 13 November 2025 (UTC)

== Beware of shortened Git commit IDs ==

While fixing broken links due to the {{tl|foo commit}} templates not specifying <code>proj=flightgear</code> (this was implicit with <code>site=sf</code> but isn't with <code>site=gl</code>), I found that URLs at GitLab don't accept the same shortened Git commit IDs as those at SourceForge:
https://sourceforge.net/p/flightgear/fgdata/ci/807062 - OK
https://gitlab.com/flightgear/fgdata/-/commit/807062 - NOK
https://gitlab.com/flightgear/fgdata/-/commit/807062d - OK
https://gitlab.com/flightgear/fgdata/-/commit/807062d0b6f858885547f27325e829c2bf42a12b - OK

As a consequence, there are probably a lot of broken links in the wiki due to shortened commit IDs. Better always use the long ones...

{{Note|Commit ID 807062 in FGData is not ambiguous at the time of this writing.}}
[[User:Rominet|Rominet]] ([[User talk:Rominet|talk]]) 15:45, 3 December 2025 (UTC)

: I have modified {{tl|Simgear_commit}}, {{tl|Flightgear_commit}}, {{tl|Fgdata_commit}}, etc. (12 templates!) to show a commit ID truncated to 7 characters in the automatically generated link text, so there is no excuse for not using the full commit IDs anymore when using these templates (see the result [[Howto:Building_FlightGear_without_HiDPI_support#Commits|here]] for instance). Thanks to [[User:Gijs|Gijs]] for installing [https://en.wikipedia.org/wiki/Module:Ustring Module:Ustring] which made this possible!

: Note that manually provided ''text'' arguments are not truncated.
: {{tip|In case you feel like replacing shortened commit IDs with full ones in {{tl|foo commit}} template calls, the full commit IDs can be found like so:
cd /path/to/repository
git rev-parse ''shortened-id1'' ''shortened-id2'' ...
}}

: [[User:Rominet|Rominet]] ([[User talk:Rominet|talk]]) 18:05, 25 December 2025 (UTC)

== Nasal unit test assertion documentation ==
I just started an article about [[Nasal unit tests]] but could need some help improving the section about the tests.

The only documentation I find is the {{flightgear source|path=src/Scripting/NasalUnitTesting.cxx|text=C++ source code}} and the existing test files (<code>test_*.nut</code>) in {{fgdata source|path=Nasal|text=fgdata/Nasal}} (side note: it took me several days to figure out where the <code>nasal-test</code> FGCommand was implemented).

—[[User:Johan G|Johan G]] ([[User_talk:Johan_G|Talk]] | [[Special:Contributions/Johan_G|contribs]]) 12:36, 14 March 2026 (UTC)

Nasal unit tests

2026-03-14T12:26:18Z

Johan G: + first section: Slightly clearer phrasing.

Nasal Unit Testing Framework

2026-03-14T12:22:50Z

Johan G: +template: Historical

{{historical|date = 14 March 2026}}
{{for|the Nasal unit testing implemented 2020|Nasal unit tests}}
{{infobox subsystem
|image =
|name =Nasal Unit Testing Framework
|started= 02/2014 (stalled)
|description = Unit Testing support for Nasal
|status = RFC
|maintainers = F-JYL, dbelcham, Hooray, Philosopher
|developers = dbelcham, F-JYL (since 02/2014),
}}

{{Template:Nasal Navigation}}

== Status 06/2013 ==
We do not currently have any established unit testing framework for Nasal. For the time being, this whole discussion is just about coming up with the requirements and a possible design.
The intent is to explore the idea of being able to run isolated unit tests against Nasal scripts. The idea was being able to do something like this:

See also {{flightgear commit|d7a680}}.

=== Concept ===
<syntaxhighlight lang="bash">
standalone-nasal.exe ATR72-FMC-tests.nas
</syntaxhighlight>

and see output like this:
<syntaxhighlight>
When_calculating_deflection_that_is_greater_than_the_provided_maximum
the_provided_maximum_should_be_returned (failed: expected 180 was 99)

When_calculating_deflection_from_33_degrees_to_90_degrees
the_result_should_be_67_degrees (failed: expected 67 was 66)
</syntaxhighlight>

=== The standalone Nasal interpreter ===
Based on what I read about the current stand-alone interpreter this should be fairly easy to do. That should now be possible, the nasal-standalone branch builds successfully for Windows (make sure to have boost available for building cppbind):

Here's the Nasal standalone interpreter as part of SimGear: {{gitorious source|proj=fg|repo=hoorays-simgear|branch=topics/nasal-standalone|view=shortlog}}
Just check out the branch named "nasal-bin".

To build it:
<syntaxhighlight lang="bash">
cd $SG_SRC
mkdir BUILD
cd BUILD
cmake ../ -DENABLE_TESTS=ON -DSIMGEAR_HEADLESS=ON -DENABLE_SOUND=OFF -DENABLE_LIBSVN=OFF
make
</syntaxhighlight>

Basically

* create and use a separate build folder, separate from the source tree
* configure the build via -DENABLE_TESTS=ON -DSIMGEAR_HEADLESS=ON -DENABLE_SOUND=OFF -DENABLE_LIBSVN=OFF
* build
* report back

Note that there's no need to actually install anything (make install), because we are just using the SimGear library to build a standalone nasal-bin binary, nothing else.

Let us know if there are still any windows-specific build errors so that we can fix the config file. It should give you a "nasal-bin.exe" in $SG_BUILD/simgear/nasal/ that runs just Nasal scripts, no FG APIs whatsoever - you '''need''' to pass a valid Nasal script when running the file.

You should be able to "make test" to run a bunch of standard Nasal tests from the original Nasal repository, which are to be found in $SG_SRC/nasal/tests: {{gitorious source|proj=fg|repo=hoorays-simgear|view=tree|branch=topics/nasal-standalone|path=simgear/nasal/tests}}

Meanwhile, the build actually works for Windows using the MingW compiler - providing a nasal-bin.exe, which I cannot test currently because I don't have a Windows VM available: http://www.speedyshare.com/MbBTA/download/nasal-bin.exe{{dead link}}

To run it, open a shell (START/EXECUTE cmd/command) and go to the folder of the binary, add a simple Nasal script and run "nasal-bin script.nas", i.e. use one of the scripts in: {{gitorious source|proj=fg|repo=hoorays-simgear|view=tree|branch=topics/nasal-standalone|path=simgear/nasal/tests}}

=== Roadmap ===
* get the stand-alone interpreter compiling and running against both windows and Linux (currently there are a bunch of libraries used that aren't available on Windows) {{done}}
* build a set of Nasal scripts that provide stubs for native fg calls (getprop/setprop/etc) {{Not done}}
* build out testing script with the ability to verify values and report failures to the console {{Not done}}
* send a patch upstream, so that a standalone Nasal interpreter is included in each upcoming release {{Not done}}

Once we have those three things we would be able to write and execute tests independent of FG and still have them be meaningful. The key thing to remember is that this would be only for isolated unit tests. For integration tests (verifying that different systems, whether 2 different scripts/methods/application, work together correctly) we would need to think about a different approach.

It should be doable to teach the nasal-bin.exe to check $FG_ROOT, and use that if available to load a semi-plausible FG environment (API-wise) - using some fancy meta-programming tricks, most of the default APIs could probably be wrapped, without too much manual work involved. Philosopher could be truly instrumental here, because he really has a deep understanding of some of the more esoteric tricks that can be done in Nasal space, referring to advanced uses of compile(), bind(), call(), closure() and caller() - which make meta-programming a fantastic experience. Basically, familiarity with this handful of APIs, can save tons of time: http://plausible.org/nasal/

There's quite a lot of stuff possible in Nasal, that nobody ever used in FG - Philosopher has started writing a bunch of tutorials, for example see: [[Nasal Meta-Programming]]

And you can take a look at some of the scripts in the standalone branch, which support fancy constructs like dependency resolution using import("foo"); but also completely sandboxed/wrapped environments: {{gitorious source|proj=fg|repo=hoorays-simgear|view=tree|branch=topics/nasal-standalone|path=simgear/nasal/tests}}

These are regression tests developed by the Nasal developer himself, so not true unit testing - but only regression tests for the interpreter itself.

=== Contributing ===
If possible, new code should be contributed to the maintainers, ideally even a branch of FG_ROOT, because that will make it easier to directly integrate such a unit testing system with all the code we got in $FG_ROOT/Nasal.

== Problem ==
One of the things that is most frustrating and time consuming when working with Nasal scripts is the brute force and manual nature of testing the scripts. A simple misspelling in a custom script can take 5-10, or more, minutes to fix from the point of finding it (shut down FG, change script, startup FG and get back to a point in the sim where the code will execute). I realize that Nasal is tightly coupled to FG at this point and that most scripts won't run without access to the property tree. That doesn't mean that it can't be done though (mocks, fakes, stubs, etc).

Most scripts in FlightGear use a plethora of APIs and FG-specific modules, so FG has become a runtime dependency (APIs, data structures like the property tree, and "live" state),

== Test/Fail Passes ==
Just because a language is dynamic doesn't mean that the code-test-fail/pass feedback loop has to be a long one. Just look at dynamic language communities like Ruby and you'll see that automated testing (both behavioral and state), in combination with continuous integration, is used to try to move those failures from application run-time to test suite run-time. Dynamic language communities do this with a lot of success (both in tightening the feedback loop and improving quality).

== Wrapping dependencies ==
FGs loading of scripts is stopping us from being able to change-reload right in app. What I was thinking is to remove the app (FG in this case) from the equation completely. For a lot of systems scripts the only interaction that they have with FG is through the property tree. Between these interactions the nasal systems scripts being developed for most aircraft are simply state based; they read some values, do some calculations and set some values. If we know the inputs (method parameters and getprop calls), we know the outputs (method return values and setprop calls).
What I do in other languages is to replace the call to those "external dependencies" (in this case getprop and setprop) with known implementation. So a call to getprop("/orientation/yaw-deg") in a specific test scenario would be configured to always return "33.5". My understanding of the inner workings of Nasal are limited, but I would think that one should be able to override get/setprop due to the dynamic nature of the language. That said, I can't find any definitions for those in the nasal-standalone codebase.

If someone could point me to where the get/setprop stuff is then I'd be a step closer to exploring my theory of having standalone Nasal running against developer defined property tree values as a mechanism for automated testing.

Wrapping APIs is simple to do in Nasal, too - without even requiring C/C++ changes, a standalone testbed could be scripted in Nasal like this:
<syntaxhighlight lang="nasal">

var tree = {};

var isalpha = func(n) n >= `a` and n <= `z` or n >= `A` and n <= `Z`;
var isdigit = func(n) n >= `0` and n <= `9`;

var sanitize = func(p) {
if (!p) die();
if (p[0] == `/`) p = substr(p, 1, nil);
parts = split("/", p);
for (var i=0; i<size(parts); i+=1) {
if (parts[i] == "") {
if (i == size(parts)-1)
parts = parts[:i-1];
else parts = parts[:i-1] ~ parts[i+1:];
i-=1;
} else {
for (var j=0; j<size(parts[i]); j+=1) {
if (parts[i][j] == `[`) break;
if (parts[i][j] != `-` and !isalpha(parts[i][j]) and
parts[i][j] != `_` and !isdigit(parts[i][j]) and
parts[i][j] != `.`) die("bad character in name "~parts[i]~" at index "~j~".");
}
if (j == size(parts[i]))
parts[i] ~= "[0]";
elsif (parts[i][-1] != `]`) die("bad index specifier in string "~parts[i]~".")
}
}
var p = "/";
foreach (var part; parts)
p ~= part;
return p;
}

# wrappers for the FG setprop/getprop APIs:
var setprop = func(p, value) tree[ sanitize(p) ] = value;
var getprop = func(p) return tree[ sanitize(p) ];

# some tests:

var path = ["/foo/bar", "/foo[0]/bar[0]","/foo[0]/bar[0]/", "/foo/bar[0]","/foo[0]/bar/","/foo[0]/bar/"];
var value = "MyUniqueValue";
setprop(path[0], value);
foreach(var p; path)
if (getprop(p) != value) die("sanitize() implementation is broken");
print("sanitize() looks good!\n");

# init your tree:
setprop("/orientation/yaw-deg", 33.5);
print("yaw-deg is:", getprop("/orientation/yaw-deg") );
</syntaxhighlight>

Basically, you can override ANYTHING in Nasal - even library/extension functions - see above, you don't even need to look at the Nasal C code.

We would need to use custom script-specific wrappers, instead of the main FG/Nasal APIs and modules - so that your Nasal code *never* uses the APIs directly, that way you can easily have different implementations - i.e.
<syntaxhighlight lang="nasal">
var debug_profile = {};
var runtime_profile = {};
var current_profile = nil;

runtime_profile.systime = systime;
debug_profile.systime = my_systime;

# set the API profile:
current_profile = runtime_profile;

# And then only ever make calls through active_profile.systime():

print( current_profile.systime() );

# or simply override the global symbols during initialization:
var systime = current_profile.systime;
print( systime() );

</syntaxhighlight>

== Test Suites ==

I'd rather not have to launch FG to run my tests. Ideally I'd like to be able to build up a suite of tests that I can run in an automated fashion to ensure that all are still operating as expected at any time. In my close to ideal world I would want to be able to execute the automate tests (and exercise the scripts as a result) dozens of times per hour. Launching FG and manually triggering this from the console would limit me to a few times per hour. Add in more complicate scripts which require extensive state in the property tree to test specific scenarios and I might be lucky to manually execute these tests a couple of times an hour. Manually launching the tests would also probably mean that I'd have to remember to configure and run each and every scenario...something I would never remember to do. Each time I forgot I'd possibly be introducing issues into my code.

The rigour around this isn't for everyone, but it is how I derive the most confidence that I'm delivering the highest quality code possible. This all came to light because of a defect in the ATR the Omega95 and I have built (mostly him) that could have easily been found if we had had some automate scenario tests written.

I'm working with the ATR's FMC. The time and difficulty with it is that if I want to change and retest any of the different segments in the flight plan (especially the SID and STAR) I need to be able to reset my self to a specific position and property tree state. If I'm testing the transition from waypoint 1->2 in the SID then I need to start pre waypoint 1 which means on the ground, starting up, keying in the flight plan, etc. Worse is the transition from the flight plan to the first STAR waypoint. If I could write automated tests for all of these scenarios plus dozens of others I can think of then my development-testing feedback loop would tighten immensely.

I had the idea, which you implemented above, of just overriding the get/setprop un the scripts. I guess taking that Sudafed might pay off in more ways than one.
Ultimately what I'd like to have is an implementation of something like the jUnit/xUnit/nUnit testing frameworks. Tonight's goal will be to hack out a rough implementation that allows for isolation of the property tree.

== Integration & Adoption ==
Unit testing support in Nasal would certainly be beneficial - but it would need to be added to FG at a library-level, i.e. in $FG_ROOT/Nasal, so that people have to use it, and have an advantage when using it - sort of like the RoR example you mentioned previously.

I could see that being useful for many things, even outside aircraft development - but thinking in th most generic terms, we need to find a compromise that will not just work for specialists who have a decade of unit testing experience, but also our average aircraft developers.

Scripting-wise, I think we really only got a handful of people here who regularly write Nasal code and who would also see the merits and potentially adopt the system.

People would only be likely to actually use that if they have a corresponding developers background, so it would need to be designed right into the framework and touch lots of places in $FG_ROOT and $FG_AIRCRAFT - I only see a handful of aircraft developers here who would go that route and actually have the mental capacity, and developer mentality to see the merits here.

Probably,a handful of people would be able to use it, but if it's well documented, and if it actually supports features not provided otherwise, it could gain traction - so it would need to be more compelling than the current workflow obviously.

A unit testing framework is definitely going to be useful for $FG_ROOT as a whole, not just aircraft/instrument developers. Obviously, one of the first steps will be documenting the whole thing with tutorials, so that people can start adopting it.

[[Category:Software testing]]

Nasal unit tests

2026-03-14T12:17:51Z

Johan G: +- Move the stub template to the section about test functions and test cases. I can't find any other documentation than the C++ source code at the moment.

'''Nasal unit tests''' is way to test that Nasal functions returns expected values. Writing unit tests for functions allow you to run tests that check if you made errors when writing the function or check if you introduced bugs when extending or maintaining the function.

== Writing unit test files ==
The Nasal test files are regular Nasal files but with the file ending <code>.nut</code> (for Nasal unit test).

The name of the test files usually begin with <code>test_</code> and then usually use the same file name as the module that are to be tested.

=== Optional header comment block ===
Test files often begin with a comment block with a header with a short description of what the file is, followed by a commented line with how to run the test, foe example something like this:

<syntaxhighlight lang="Nasal">
#-------------------------------------------------------------------------------
# Test file for multiplayer time synchronization
# File: test_mp_time_sync.nut
# Author: Iam Cardholder
# Created: 2026-03-14
# Licence: GPLv2 or later
#-------------------------------------------------------------------------------

# fgcommand("nasal-test", props.Node.new({"path":"test_mp_time_sync.nut"}));
</syntaxhighlight>

=== Optional setup and tear-down functions ===
Optionally the unit test file can have a <code>setUp()</code> and a <code>tearDown()</code> function. These are useful if for example some other module need to be loaded.

Most of the time these functions are used for printing to the console and/or log that the test has started or finished.

<syntaxhighlight lang="Nasal">
# Optional setup function
var setUp = func {
logprint(LOG_INFO, "mp_time_sync tests begin");
};

# Optional tear-down function
var tearDown = func {
logprint(LOG_INFO, "mp_time_sync tests finished");
};
</syntaxhighlight>

=== Test functions and test cases ===
{{stub|section=1}}
The names of the test functions usually matches the names of the functions to test except they, like the name of the test file, begin with <code>test_</code>.

Tests are written as functions with one or more test cases. If needed modules can be loaded, variables can be defined etc. that will then be used for each test case.

You can have as many test cases as needed and each test case can be using using one of four different tests:
* <code>unitTest.assert()</code>
* <code>unitTest.fail()</code>
* <code>unitTest.assert_equal()</code>
* <code>unitTest.assert_doubles_equal()</code>
* <code>unitTest.equal()</code>

== Running the tests ==
The tests are run with the FGCommands:

* <code>fgcommand("nasal-test", props.node.new({"path":"<path to Nasal test file>"}));</code>
* <code>fgcommand("nasal-test-dir", props.node.new({"path":"<path to directory with Nasal test files>"}));</code>

== See also ==
* [[Software testing]]
* [[Nasal Unit Testing Framework]] (An older effort.)

=== Source code ===
* {{flightgear source|path=src/Scripting/NasalUnitTesting.hxx}}
* {{flightgear source|path=src/Scripting/NasalUnitTesting.cxx}}

=== Examples ===
* {{fgdata source|path=Nasal/std.nut}}
* {{fgdata source|path=Nasal/string.nut}}
* {{fgdata source|path=Nasal/test_emesary.nut}}

[[Category:Nasal]]
[[Category:Software testing]]

User:Johan G/Things I have done

2026-03-14T12:14:13Z

Johan G: /* New pages */ + Nasal unit tests

These are ''some'' of the '''things I have done''' on the wiki.

''For a complete list see [[Special:Contributions/Johan_G]].''

== New pages ==
* [[Howto:Add blackout and redout settings]]
* [[Howto:Add multi-key commands to an aircraft]]
* [[Aerial refueling improvement ideas and resources]]
* [[Aircraft interception]]
* [[Blacklist add-on]]
* [[Dassault Mirage F1]]
* [[FlightGear wiki:FlightGear screenshot categories]]
* [[Flightplan XML formats]]
* [[Hand camera HK 101B add-on]]
* [[Head tracking]]
* [[Help:Tables]]
* [[Log time-stamper add-on]]
* [[Nasal unit tests]]
* [[Pilotage and dead reckoning]]
* [[Pilot List]]
* [[TerraMaster]]
* [[Time in FlightGear]]

== Larger edits ==
* Replaced the text in [[Howto: Edit a livery]] ([http://wiki.flightgear.org/index.php?title=Howto:_Edit_a_livery&oldid=36141 original text]) with my own draft ([http://wiki.flightgear.org/index.php?title=User:Johan_G/Howto:_Edit_a_livery&oldid=39121 Final draft]).
* [[Help:Templates]] – Rewritten it more or less completely ([http://wiki.flightgear.org/index.php?title=Help%3ATemplates&diff=64365&oldid=44878 diff])
* [[Help:Formatting]] – Complete rewrite of the former [http://wiki.flightgear.org/index.php?title=Help:Tutorial&oldid=42573 Help:Tutorial]
* [[Help:Your first article]] – Complete rewrite of [http://wiki.flightgear.org/index.php?title=Help:Your_first_article&oldid=64321 Help:Your first article]

== Templates ==
* A lot of template documentation
* Unification of the template documentation style (manually editing all existing template documentation!)
* {{tl|Welcome to the wiki}}
* {{tl|alds}} – For use on the [[Airliner Development Status]] page
* {{tl|due date}} – When you want to show one text before and another one after a certain date.
* {{tl|issue}} – For referencing bug tracker issues (be that bugs or feature requests).
* {{tl|key press}} – For illustrating key presses and combinations.
* {{tl|LangSwitch}} – For showing different texts depending on the language of a page.
* {{tl|rule of thumb}} – For rules of thumb, like 2 kt is about 1 m/s.
* {{tl|wikipedia}} – For links to Wikipedia.
* {{tl|yes}}, {{tl|partial}}, {{tl|no}} and {{tl|n/a}} – For use in various tables.
* Split up [http://wiki.flightgear.org/index.php?title=Template:Issue_Tracker&oldid=83057 <nowiki>{{Issue Tracker}}</nowiki>] into {{tl|register to sf}}, {{tl|create ticket}} and {{tl|tickets}}.
* {{tl|fg screenshot cat}} – To lessen the typing when adding descriptions to FlightGear screenshot categories.
* {{tl|screenshot cat}} - To add to pages about subjects there are a screenshot category for.
* {{tl|readme file}} – To link to readme files in [[$FG_DATA]]/Docs.
* {{tl|fgaddon revision}}, {{tl|fgdata commit}}, {{tl|simgear commit}} and {{tl|flightgear commit}} – For links to revision/commit summaries on the repositories.

== Uploaded images ==
* [[Special:ListFiles/Johan_G]]

[[Category:User pages]]

Software testing

2026-03-14T12:12:20Z

Johan G: +category: Software testing

{{Note|There’s already the test_suite in {{fg src file|path=test_suite}} using [[Cppunit effort|CppUnit]], thanks to some hard work by [[User:Bugman|Edward]]. We need more tests written for it; submissions are welcome. (Pick an area of interest)<ref>https://sourceforge.net/p/flightgear/mailman/message/36972720/</ref>}}

{{See also|Cppunit effort}}

FlightGear developers use various testing tools. This includes automated testing via unit tests in [[SimGear]] and a full test suite with multiple test categories in the [[FlightGear Git|flightgear repository]], as well as manual in-sim testing. Writing tests is one of the best ways to jump into FlightGear development.

One improving area is unit testing: certain areas and features (e.g., carrier start) now 'can't break.' As we add testing in additional areas (e.g., Multi-player, AI, protocols, and replay are all possible), we increase the baseline quality and have a clearer idea when we make incompatible changes. (The idea is that we capture the 'supported API' in the tests: when an aircraft deviates from that, we can decide to add another test case, fix the aircraft, etc). Of course, there are some pretty significant areas where Automated Testing Is Hard (TM).<ref>https://sourceforge.net/p/flightgear/mailman/message/37078825/</ref>

== SimGear ==

Unit testing for the [[SimGear]] sources uses the CMake CTest unit testing infrastructure. Several tests use the BOOST unit testing infrastructure tied to the build system using CTest; however, the FlightGear developers are shifting towards eliminating BOOST, so CPPUnit and CTest tests are preferred.

=== Building and running the SimGear tests ===
<syntaxhighlight lang="bash">
$ make
$ ctest
</syntaxhighlight>

== FlightGear ==

Testing of the [[FlightGear Git|flightgear sources]] is via a comprehensive test suite implemented using [https://www.freedesktop.org/wiki/Software/cppunit/ CppUnit], a port of the famous JUnit framework.

=== Building the test suite ===

You must build FlightGear from the source using cmake to run the tests. See [[Building FlightGear]] for details.

Once you have your cmake build environment, do the following:
# Change to your FlightGear build* directory
# Enable building the tests by setting a cmake variable: <code>cmake -DBUILD_TESTING=ON .</code>
# Ensure the <code>[[$FG ROOT|$FG_ROOT]]</code> environment variable points to fgdata e.g. <code>$FG_INSTALL_DIR/share/fgdata</code>
# Build the test suite: <code>make test_suite</code>

Building the test suite will also run a test because you will typically want to write a test and then immediately compile and run it.

* ls in this directory should include CMakeCache.txt, cmake_install, and others. You do not want to run cmake in the flightgear sources directory, which includes files such as AUTHORS, COPYING, INSTALL, etc.

On a Windows MSVC-based build environment, after generating files with cmake, run the following code:
# cmake --build . --config RelWithDebInfo --target test_suite/test_suite

=== Running the test suite ===

To run the test suite, simply run <code>./test_suite/fgfs_test_suite</code>

Executing fgfs_test_suite will run the entire test suite and print a Synopsis of results, as shown below.

Synopsis
========

System/functional tests ....................................... [ OK ]
Unit tests .................................................... [ OK ]
Simgear unit tests ............................................ [ OK ]
FGData tests .................................................. [ OK ]
Synopsis ...................................................... [ OK ]

You can also run individual test cases. Run <code>./test_suite/fgfs_test_suite -h</code> to see the various options

For example, fgfs_test_suite --log-level=alert -d -u GPSTests will run the GPS unit tests while displaying the output.

=== Why write unit tests? ===

A well-tested piece of software will have a much lower bug count/load. An extensive test suite with "'unit tests,'" system/functional tests, GUI tests, installer tests, and other categories of tests can significantly help in this regard.

The benefits of not just chasing clear "wins" are great: An excellent learning experience for new developers; the ability to catch latent, unreported bugs; making it easier to refactor current code by creating a safety net; making it easier for current developers to accept new contributions (when accompanied with passing tests); helping other test writers by contributing to the standard test suite infrastructure; and being able to check for memory leaks or other issues via Valgrind easily.<ref>https://sourceforge.net/p/flightgear/mailman/message/36977686/</ref>

If you are a new developer, jump in and write any test! It does not need to catch a bug. Do whatever you wish! Just dive into this shallow end, and you'll see that the water is not cold.

You are writing a test as a safety net. You write the test to pass, make your changes, and then make sure that the test still passes. Then, you push both the test and core changes.<ref>https://sourceforge.net/p/flightgear/mailman/message/36977465/</ref>

It'd be better to work in a specific area of interest to you and submit merge requests. When reviewed, that would usually trigger some C++ feedback, but we aren't looking for perfection here. The feedback you receive during the open and public review process increases our overall pool of knowledge of what best practice looks like, even if a given commit is less than perfect.

Having 10 or 20 people actively contributing correct and reasonable code is more important than three people contributing perfect, micro-optimised C++. <ref>https://sourceforge.net/p/flightgear/mailman/message/36951247/</ref>

=== Benefits of unit testing ===
There are lots of benefits to writing tests that pass.

Benefits include :

* Learning! New developers can learn a ton from writing several passing tests in the area they are interested in. This is one of the quickest ways to learn about a pre-existing and mature code base. You have zero worries about breaking things.

* Latent bug uncovering. One will probably fail every ten tests you write, expecting them to pass. Tests may uncover unexpected behavior that a developer can improve.

* Refactoring. If we had 10,000 passing tests (assuming universal test coverage), large-scale refactoring of the entire code base would be quick and reliable. It would enable refactoring on a scale currently unimaginable. I cannot emphasize enough how much of a benefit this would be.

* Developer turnover. Again, if we had 10,000 passing tests (assuming universal test coverage), it would encourage new developers, giving them confidence that their changes will not cause problems. It is a safety net. It also would provide existing developers peace of mind when a new developer works in one of the dark parts of FlightGear that no current developer understands (there are plenty of those).

* Test suite infrastructure. The more passing tests written, the better the test suite infrastructure will become. We can already do a lot, but adding more passing tests will help other test writers.

* Memory checking. Running a single test through Valgrind is fantastic. Running FlightGear through Valgrind is close to impossible. One can write tests that pass but are useful under Valgrind to catch memory leaks!

* Code quality and standards. If a test compiles on all OSes without warning, it passes, and Valgrind gives you an ok, it is good enough. You don't need to be a C++ expert to dive into this shallow end of the pool.

=== Bootstrapping completely new tests ===
To start diving straight into the test suite code, firstly copy what has been done in this commit: {{repo link
| site = sf
| user = edauvergne
| repo = flightgear
| commit = 8474df
| view = commit
}}

Just modify all names for a JSBSim test (or any other test fixture you
want to code). You should then be able to compile and check that your
new test dummy () test passes as expected. You can then slowly build up
from this basic infrastructure as you learn the fgfs internals, c++,
and git skills required for implementing your test on your fork's new
development branch :)

For a step by step description of how to add new tests
see: [[Software Testing/Adding CPPUnit Tests]]

For a detailed explanation of everything in the flightgear/test_suite folder, top to bottom level,
see: [[Software Testing/Flightgear Test Suite Details]]

===Headless testing===
{{Main article|FlightGear Headless}}

For an FDM+systems test, we should run FG without a renderer (which is what the test_suite does) to benchmark the pure C++ performance of whatever system we care about (FDM or whatever). But a few hours playing with 'perf' on Linux or Instruments on macOS will show you that OSG + the GL drivers use 80% of our CPU time, and hence Amdhal's law will always get you.<ref>https://sourceforge.net/p/flightgear/mailman/message/36977666/</ref>

===Graphics testing===
{{See also|FlightGear Benchmark}}

Create test-case scenes where you can quickly measure differences and compare via screenshots. The brain/eye/memory are terrible at this stuff, setup something you can load from the command line via a script to test old/new versions, if possible. <ref>https://sourceforge.net/p/flightgear/mailman/message/36959002/</ref>

For example, a test would use several rc files (.[[fgfsrc]] variants, with different renderers and threading modes, including static values for:
*c172p at some parking in a detailed airport
*camera set with a specific direction and field of view
*AW with specific METARs around (if not possible, BW with specific METAR)
*fixed rendering settings ( <ref>https://sourceforge.net/p/flightgear/mailman/message/36975122/</ref>

We can load a [[Instant Replay|replay tape]] on startup. Since the FDM and User interface are unavailable, replays are suitable for testing rendering and performance.

But essentially, small amounts of shell script + Nasal hacking, can implement any of these methods, and any of them would be welcome additions. The unit-test framework is excellent for lower-level tests run by developers (i.e., 'Does the API call produce the right results in the system?'), but a smoke test that regular users can run would be ideal.

A rendering performance would likely do the following:

*Select some particular rendering settings (clouds, draw distance, etc)
*Run a saved fgtape recording
* Record the mean/min/max FPS during this and save it in some text file/copy to the clipboard

So yes, if anyone wants to work on the above, the code is all there. Please jump in and start hacking. I don't think it needs any more from the core code, but as always, please ask if it does.<ref>https://sourceforge.net/p/flightgear/mailman/message/36975213/</ref>

For example, when describing a /rendering/ test (to establish FPS), the advantage of a replay tape is that the actual position (and, therefore, the rendered scene) will be 100% consistent across different computers.

Keep in mind that the CPU use of the FDM+systems is typically < 10% of our total CPU use, even when running OSG single-threaded, so for a rendering performance test, whether the FD is run or not is probably noise compared to other things that do run (Nasal, Canvas for example)

Also, the Multi-monitor setup is an area that could use additional unit testing. <ref>https://sourceforge.net/p/flightgear/mailman/message/36904782/</ref>

==Fgdata==
===Nasal scripting (comments)===
{{WIP}}

The now builtin CppUnit framework can solve all the issues
identified in the old [[Nasal Unit Testing Framework]] wiki article and the discussions it points to
and provide the full framework required.<ref>https://sourceforge.net/p/flightgear/mailman/message/36990615/</ref>

We have some very simple tests running now for the route manager, which relies on Nasal. We're skipping a few of the bigger Nasal modules (local weather, jetways) and have a few lingering issues in some other modules, but the basic concept is working.

An exciting further step, which you might wish to discuss with Edward, is writing test checks *in* Nasal since this could be quite a fast way to test some areas of the code. There are several ways that could work, and I don't know if Edward has always planned something around this, so I won't preempt that conversation.
<ref>https://sourceforge.net/p/flightgear/mailman/message/36764781/</ref>

we have route-manager tests which validate route_manager.nas is working correctly, and we have Canavs tests ({{fg src file|path=test_suite/simgear_tests/canvas|}}) which poke the Nasal API. <ref>https://sourceforge.net/p/flightgear/mailman/message/36991200/</ref>

We need more FGData testing via the test suite.

James has suggested adding CppUnit assertions to Nasal so others can write tests in pure Nasal. James would make these changes in C++.
In addition, some C++ code in a test would scan a directory for files matching a pattern, e.g., test_XYZ.nas, and run each of those automatically.

The idea for testing Nasal would be that you write a small CppUnit
interface in C++ in $FG_SRC/test_suite/*_tests/ (the FGData Nasal
testing would be in a fgdata_tests/ directory). This would register
each test which points to the script in
$FG_SRC/test_suite/shared_data/nasal/, and the setUp() and tearDown()
functions would use helper functions in the fgtest namespace to start
and stop Nasal. The Nasal scripts could then call the CppUnit
assertion macros wrapped up as Nasal functions for communicating
failures and errors to the test suite. <ref>https://sourceforge.net/p/flightgear/mailman/message/36991150/</ref>

Scanning for scripts is a great idea. Then, developers (core and content) could write tests using pure Nasal.

However, all scripts found and executed will be seen as a single test within the test suite. So maybe we should have a $FG_SRC/test_suite/nasal_staging/ directory for the initial development of such auto-scanned scripts. But then we have someone shift them into $FG_SRC/test_suite/system_tests/, $FG_SRC/test_suite/unit_tests/, or $FG_SRC/test_suite/fgdata_tests/ later on? That would give better diagnostics and would avoid long-term clutter.<ref>https://sourceforge.net/p/flightgear/mailman/message/36991198/</ref>

*First, we should probably hard code tests into the C++ framework. For this, the CppUnit assertion macros will have to be wrapped up as Nasal functions.
*Implement the scanning code as we need some CMake magic (probably using file(COPY, ...)).
*Finally, we must determine if and how to improve the Nnasaldebugging output.

the code could go into a subdirectory in $FG_SRC/test_suite/fgdata_tests/, and the Nasal script in $FG_SRC/test_suite/shared_data/nasal/.

==References==
{{Appendix}}

[[Category:Core development]]
[[Category:Software testing]]

Software Testing/Flightgear Test Suite Details

2026-03-14T12:11:28Z

Johan G: +category: Software testing

= Definitions =

==Test Case==
A single assertion about one or two variable values that is testable.
==Test Fixture==
In CppUnit, a group of tests is called a TestFixture. A TestFixture provides a common environment for multiple test cases.
==App Component==
Major parts of the application, usually corresponding to folders in flightgear/src or simgear/simgear
==Test Category==
The type of testing: unit, system and simgear (library) tests
==Test Suite==
All the tests and everything needed to support them

= Top Level flightgear/test_suite folder =

Take a look at the '''flightgear/test_suite''' folder in a file browser preferably one that allows you to see the folders on multiple levels such as a code editor like VsCode. Start in the top level of flightgear's repo sources look for a directory named '''test_suite'''. Note that test_suite is not part of '''flightgear/src'''.

'''flightgear/test_suite''' contains two kinds of testing resources.

* '''Programs and data used in tests'''
* '''Groups of CPPUnit tests'''

==Programs and data used in test modules==

* individual files directly under test_suite
* test_data folder
* FGTestApi folder
* Groups of CPPUnit tests

==Test Categories==

* fgdata_tests - placeholder
* gui_tests - placeholder
* simgear_tests
* system_tests
* unit_tests

Each of the last three test_suite/*_tests folders contain sub-folders covering some part of Flightgear's code. They may roughly correspond to the folders under flightgear/src, but that is not a requirement. Some areas may be covered in more than one *_tests folder. FDM for example in unit_tests and system_tests.

== Folder Levels ==

Note at this point that the maximum Folder depth is 3:

# flightgear/test_suite Folder.
# Test-category folders ex: unit_tests, system_tests, simgear_tests
# App Component folders ex: FDM, Network, canvas. These roughly correspond to specific flightgear/src folders,

Expand the '''unit_tests''' test category folder
Expand the '''Network''' app component folder

CPPUNIT test fixtures are implemented in test_*.cxx and test_*.hhx files int the Component category folders.

== CMakeLists.txt, testSuite.cxx and TestSuite.cxx files ==

CMakeLists.txt files exist at every level
TestSuite.cxx files are in each application component folders (bottom level)
testSuite.cxx is only at the top level

# '''test_suite/CMakeLists.txt''' & test_suite/testSuite.cxx
# '''test_suite/[test-category]/CMakeLists.txt'''
# '''test_suite/[test-category]/[app-component]/CMakeLists.txt''' and '''Test_suite.cxx'''

More to follow {{WIP}}

[[Category:Software testing]]

Nasal Unit Testing Framework

2026-03-14T12:10:34Z

Johan G: +hatnote: For the Nasal unit testing implemented 2020, see Nasal unit tests; +category: Software testing

{{for|the Nasal unit testing implemented 2020|Nasal unit tests}}
{{infobox subsystem
|image =
|name =Nasal Unit Testing Framework
|started= 02/2014 (stalled)
|description = Unit Testing support for Nasal
|status = RFC
|maintainers = F-JYL, dbelcham, Hooray, Philosopher
|developers = dbelcham, F-JYL (since 02/2014),
}}

{{Template:Nasal Navigation}}

== Status 06/2013 ==
We do not currently have any established unit testing framework for Nasal. For the time being, this whole discussion is just about coming up with the requirements and a possible design.
The intent is to explore the idea of being able to run isolated unit tests against Nasal scripts. The idea was being able to do something like this:

See also {{flightgear commit|d7a680}}.

=== Concept ===
<syntaxhighlight lang="bash">
standalone-nasal.exe ATR72-FMC-tests.nas
</syntaxhighlight>

and see output like this:
<syntaxhighlight>
When_calculating_deflection_that_is_greater_than_the_provided_maximum
the_provided_maximum_should_be_returned (failed: expected 180 was 99)

When_calculating_deflection_from_33_degrees_to_90_degrees
the_result_should_be_67_degrees (failed: expected 67 was 66)
</syntaxhighlight>

=== The standalone Nasal interpreter ===
Based on what I read about the current stand-alone interpreter this should be fairly easy to do. That should now be possible, the nasal-standalone branch builds successfully for Windows (make sure to have boost available for building cppbind):

Here's the Nasal standalone interpreter as part of SimGear: {{gitorious source|proj=fg|repo=hoorays-simgear|branch=topics/nasal-standalone|view=shortlog}}
Just check out the branch named "nasal-bin".

To build it:
<syntaxhighlight lang="bash">
cd $SG_SRC
mkdir BUILD
cd BUILD
cmake ../ -DENABLE_TESTS=ON -DSIMGEAR_HEADLESS=ON -DENABLE_SOUND=OFF -DENABLE_LIBSVN=OFF
make
</syntaxhighlight>

Basically

* create and use a separate build folder, separate from the source tree
* configure the build via -DENABLE_TESTS=ON -DSIMGEAR_HEADLESS=ON -DENABLE_SOUND=OFF -DENABLE_LIBSVN=OFF
* build
* report back

Note that there's no need to actually install anything (make install), because we are just using the SimGear library to build a standalone nasal-bin binary, nothing else.

Let us know if there are still any windows-specific build errors so that we can fix the config file. It should give you a "nasal-bin.exe" in $SG_BUILD/simgear/nasal/ that runs just Nasal scripts, no FG APIs whatsoever - you '''need''' to pass a valid Nasal script when running the file.

You should be able to "make test" to run a bunch of standard Nasal tests from the original Nasal repository, which are to be found in $SG_SRC/nasal/tests: {{gitorious source|proj=fg|repo=hoorays-simgear|view=tree|branch=topics/nasal-standalone|path=simgear/nasal/tests}}

Meanwhile, the build actually works for Windows using the MingW compiler - providing a nasal-bin.exe, which I cannot test currently because I don't have a Windows VM available: http://www.speedyshare.com/MbBTA/download/nasal-bin.exe{{dead link}}

To run it, open a shell (START/EXECUTE cmd/command) and go to the folder of the binary, add a simple Nasal script and run "nasal-bin script.nas", i.e. use one of the scripts in: {{gitorious source|proj=fg|repo=hoorays-simgear|view=tree|branch=topics/nasal-standalone|path=simgear/nasal/tests}}

=== Roadmap ===
* get the stand-alone interpreter compiling and running against both windows and Linux (currently there are a bunch of libraries used that aren't available on Windows) {{done}}
* build a set of Nasal scripts that provide stubs for native fg calls (getprop/setprop/etc) {{Not done}}
* build out testing script with the ability to verify values and report failures to the console {{Not done}}
* send a patch upstream, so that a standalone Nasal interpreter is included in each upcoming release {{Not done}}

Once we have those three things we would be able to write and execute tests independent of FG and still have them be meaningful. The key thing to remember is that this would be only for isolated unit tests. For integration tests (verifying that different systems, whether 2 different scripts/methods/application, work together correctly) we would need to think about a different approach.

It should be doable to teach the nasal-bin.exe to check $FG_ROOT, and use that if available to load a semi-plausible FG environment (API-wise) - using some fancy meta-programming tricks, most of the default APIs could probably be wrapped, without too much manual work involved. Philosopher could be truly instrumental here, because he really has a deep understanding of some of the more esoteric tricks that can be done in Nasal space, referring to advanced uses of compile(), bind(), call(), closure() and caller() - which make meta-programming a fantastic experience. Basically, familiarity with this handful of APIs, can save tons of time: http://plausible.org/nasal/

There's quite a lot of stuff possible in Nasal, that nobody ever used in FG - Philosopher has started writing a bunch of tutorials, for example see: [[Nasal Meta-Programming]]

And you can take a look at some of the scripts in the standalone branch, which support fancy constructs like dependency resolution using import("foo"); but also completely sandboxed/wrapped environments: {{gitorious source|proj=fg|repo=hoorays-simgear|view=tree|branch=topics/nasal-standalone|path=simgear/nasal/tests}}

These are regression tests developed by the Nasal developer himself, so not true unit testing - but only regression tests for the interpreter itself.

=== Contributing ===
If possible, new code should be contributed to the maintainers, ideally even a branch of FG_ROOT, because that will make it easier to directly integrate such a unit testing system with all the code we got in $FG_ROOT/Nasal.

== Problem ==
One of the things that is most frustrating and time consuming when working with Nasal scripts is the brute force and manual nature of testing the scripts. A simple misspelling in a custom script can take 5-10, or more, minutes to fix from the point of finding it (shut down FG, change script, startup FG and get back to a point in the sim where the code will execute). I realize that Nasal is tightly coupled to FG at this point and that most scripts won't run without access to the property tree. That doesn't mean that it can't be done though (mocks, fakes, stubs, etc).

Most scripts in FlightGear use a plethora of APIs and FG-specific modules, so FG has become a runtime dependency (APIs, data structures like the property tree, and "live" state),

== Test/Fail Passes ==
Just because a language is dynamic doesn't mean that the code-test-fail/pass feedback loop has to be a long one. Just look at dynamic language communities like Ruby and you'll see that automated testing (both behavioral and state), in combination with continuous integration, is used to try to move those failures from application run-time to test suite run-time. Dynamic language communities do this with a lot of success (both in tightening the feedback loop and improving quality).

== Wrapping dependencies ==
FGs loading of scripts is stopping us from being able to change-reload right in app. What I was thinking is to remove the app (FG in this case) from the equation completely. For a lot of systems scripts the only interaction that they have with FG is through the property tree. Between these interactions the nasal systems scripts being developed for most aircraft are simply state based; they read some values, do some calculations and set some values. If we know the inputs (method parameters and getprop calls), we know the outputs (method return values and setprop calls).
What I do in other languages is to replace the call to those "external dependencies" (in this case getprop and setprop) with known implementation. So a call to getprop("/orientation/yaw-deg") in a specific test scenario would be configured to always return "33.5". My understanding of the inner workings of Nasal are limited, but I would think that one should be able to override get/setprop due to the dynamic nature of the language. That said, I can't find any definitions for those in the nasal-standalone codebase.

If someone could point me to where the get/setprop stuff is then I'd be a step closer to exploring my theory of having standalone Nasal running against developer defined property tree values as a mechanism for automated testing.

Wrapping APIs is simple to do in Nasal, too - without even requiring C/C++ changes, a standalone testbed could be scripted in Nasal like this:
<syntaxhighlight lang="nasal">

var tree = {};

var isalpha = func(n) n >= `a` and n <= `z` or n >= `A` and n <= `Z`;
var isdigit = func(n) n >= `0` and n <= `9`;

var sanitize = func(p) {
if (!p) die();
if (p[0] == `/`) p = substr(p, 1, nil);
parts = split("/", p);
for (var i=0; i<size(parts); i+=1) {
if (parts[i] == "") {
if (i == size(parts)-1)
parts = parts[:i-1];
else parts = parts[:i-1] ~ parts[i+1:];
i-=1;
} else {
for (var j=0; j<size(parts[i]); j+=1) {
if (parts[i][j] == `[`) break;
if (parts[i][j] != `-` and !isalpha(parts[i][j]) and
parts[i][j] != `_` and !isdigit(parts[i][j]) and
parts[i][j] != `.`) die("bad character in name "~parts[i]~" at index "~j~".");
}
if (j == size(parts[i]))
parts[i] ~= "[0]";
elsif (parts[i][-1] != `]`) die("bad index specifier in string "~parts[i]~".")
}
}
var p = "/";
foreach (var part; parts)
p ~= part;
return p;
}

# wrappers for the FG setprop/getprop APIs:
var setprop = func(p, value) tree[ sanitize(p) ] = value;
var getprop = func(p) return tree[ sanitize(p) ];

# some tests:

var path = ["/foo/bar", "/foo[0]/bar[0]","/foo[0]/bar[0]/", "/foo/bar[0]","/foo[0]/bar/","/foo[0]/bar/"];
var value = "MyUniqueValue";
setprop(path[0], value);
foreach(var p; path)
if (getprop(p) != value) die("sanitize() implementation is broken");
print("sanitize() looks good!\n");

# init your tree:
setprop("/orientation/yaw-deg", 33.5);
print("yaw-deg is:", getprop("/orientation/yaw-deg") );
</syntaxhighlight>

Basically, you can override ANYTHING in Nasal - even library/extension functions - see above, you don't even need to look at the Nasal C code.

We would need to use custom script-specific wrappers, instead of the main FG/Nasal APIs and modules - so that your Nasal code *never* uses the APIs directly, that way you can easily have different implementations - i.e.
<syntaxhighlight lang="nasal">
var debug_profile = {};
var runtime_profile = {};
var current_profile = nil;

runtime_profile.systime = systime;
debug_profile.systime = my_systime;

# set the API profile:
current_profile = runtime_profile;

# And then only ever make calls through active_profile.systime():

print( current_profile.systime() );

# or simply override the global symbols during initialization:
var systime = current_profile.systime;
print( systime() );

</syntaxhighlight>

== Test Suites ==

I'd rather not have to launch FG to run my tests. Ideally I'd like to be able to build up a suite of tests that I can run in an automated fashion to ensure that all are still operating as expected at any time. In my close to ideal world I would want to be able to execute the automate tests (and exercise the scripts as a result) dozens of times per hour. Launching FG and manually triggering this from the console would limit me to a few times per hour. Add in more complicate scripts which require extensive state in the property tree to test specific scenarios and I might be lucky to manually execute these tests a couple of times an hour. Manually launching the tests would also probably mean that I'd have to remember to configure and run each and every scenario...something I would never remember to do. Each time I forgot I'd possibly be introducing issues into my code.

The rigour around this isn't for everyone, but it is how I derive the most confidence that I'm delivering the highest quality code possible. This all came to light because of a defect in the ATR the Omega95 and I have built (mostly him) that could have easily been found if we had had some automate scenario tests written.

I'm working with the ATR's FMC. The time and difficulty with it is that if I want to change and retest any of the different segments in the flight plan (especially the SID and STAR) I need to be able to reset my self to a specific position and property tree state. If I'm testing the transition from waypoint 1->2 in the SID then I need to start pre waypoint 1 which means on the ground, starting up, keying in the flight plan, etc. Worse is the transition from the flight plan to the first STAR waypoint. If I could write automated tests for all of these scenarios plus dozens of others I can think of then my development-testing feedback loop would tighten immensely.

I had the idea, which you implemented above, of just overriding the get/setprop un the scripts. I guess taking that Sudafed might pay off in more ways than one.
Ultimately what I'd like to have is an implementation of something like the jUnit/xUnit/nUnit testing frameworks. Tonight's goal will be to hack out a rough implementation that allows for isolation of the property tree.

== Integration & Adoption ==
Unit testing support in Nasal would certainly be beneficial - but it would need to be added to FG at a library-level, i.e. in $FG_ROOT/Nasal, so that people have to use it, and have an advantage when using it - sort of like the RoR example you mentioned previously.

I could see that being useful for many things, even outside aircraft development - but thinking in th most generic terms, we need to find a compromise that will not just work for specialists who have a decade of unit testing experience, but also our average aircraft developers.

Scripting-wise, I think we really only got a handful of people here who regularly write Nasal code and who would also see the merits and potentially adopt the system.

People would only be likely to actually use that if they have a corresponding developers background, so it would need to be designed right into the framework and touch lots of places in $FG_ROOT and $FG_AIRCRAFT - I only see a handful of aircraft developers here who would go that route and actually have the mental capacity, and developer mentality to see the merits here.

Probably,a handful of people would be able to use it, but if it's well documented, and if it actually supports features not provided otherwise, it could gain traction - so it would need to be more compelling than the current workflow obviously.

A unit testing framework is definitely going to be useful for $FG_ROOT as a whole, not just aircraft/instrument developers. Obviously, one of the first steps will be documenting the whole thing with tutorials, so that people can start adopting it.

[[Category:Software testing]]

Nasal unit tests

2026-03-14T12:02:16Z

Johan G: Created page with "{{stub}} '''Nasal unit tests''' is way to test that Nasal functions returns expected values. Writing unit tests for functions allow you to run tests that check if you made errors when writing the function or check if you introduced bugs when extending or maintaining the function. == Writing unit test files == The Nasal test files are regular Nasal files but with the file ending <code>.nut</code> (for Nasal unit test). The name of the test files usually begin with <code..."

{{stub}}
'''Nasal unit tests''' is way to test that Nasal functions returns expected values. Writing unit tests for functions allow you to run tests that check if you made errors when writing the function or check if you introduced bugs when extending or maintaining the function.

== Writing unit test files ==
The Nasal test files are regular Nasal files but with the file ending <code>.nut</code> (for Nasal unit test).

The name of the test files usually begin with <code>test_</code> and then usually use the same file name as the module that are to be tested.

=== Optional header comment block ===
Test files often begin with a comment block with a header with a short description of what the file is, followed by a commented line with how to run the test, foe example something like this:

<syntaxhighlight lang="Nasal">
#-------------------------------------------------------------------------------
# Test file for multiplayer time synchronization
# File: test_mp_time_sync.nut
# Author: Iam Cardholder
# Created: 2026-03-14
# Licence: GPLv2 or later
#-------------------------------------------------------------------------------

# fgcommand("nasal-test", props.Node.new({"path":"test_mp_time_sync.nut"}));
</syntaxhighlight>

=== Optional setup and tear-down functions ===
Optionally the unit test file can have a <code>setUp()</code> and a <code>tearDown()</code> function. These are useful if for example some other module need to be loaded.

Most of the time these functions are used for printing to the console and/or log that the test has started or finished.

<syntaxhighlight lang="Nasal">
# Optional setup function
var setUp = func {
logprint(LOG_INFO, "mp_time_sync tests begin");
};

# Optional tear-down function
var tearDown = func {
logprint(LOG_INFO, "mp_time_sync tests finished");
};
</syntaxhighlight>

=== Test functions and test cases ===
The names of the test functions usually matches the names of the functions to test except they, like the name of the test file, begin with <code>test_</code>.

Tests are written as functions with one or more test cases. If needed modules can be loaded, variables can be defined etc. that will then be used for each test case.

You can have as many test cases as needed and each test case can be using using one of four different tests:
* <code>unitTest.assert()</code>
* <code>unitTest.fail()</code>
* <code>unitTest.assert_equal()</code>
* <code>unitTest.assert_doubles_equal()</code>
* <code>unitTest.equal()</code>

== Running the tests ==
The tests are run with the FGCommands:

* <code>fgcommand("nasal-test", props.node.new({"path":"<path to Nasal test file>"}));</code>
* <code>fgcommand("nasal-test-dir", props.node.new({"path":"<path to directory with Nasal test files>"}));</code>

== See also ==
* [[Software testing]]
* [[Nasal Unit Testing Framework]] (An older effort.)

=== Source code ===
* {{flightgear source|path=src/Scripting/NasalUnitTesting.hxx}}
* {{flightgear source|path=src/Scripting/NasalUnitTesting.cxx}}

=== Examples ===
* {{fgdata source|path=Nasal/std.nut}}
* {{fgdata source|path=Nasal/string.nut}}
* {{fgdata source|path=Nasal/test_emesary.nut}}

[[Category:Nasal]]
[[Category:Software testing]]

Category:Software testing

2026-03-14T09:59:28Z

Johan G: More specific header.

{{en|Category with articles related to [[software testing]].}}

[[Category:Core development]]
[[Category:Nasal]]

Category:Software testing

2026-03-14T09:56:11Z

Johan G: Created page with "{{en|Articles related to software testing.}} Category:Core development Category:Nasal"

{{en|Articles related to [[software testing]].}}

[[Category:Core development]]
[[Category:Nasal]]

Howto:Add procedures to the route manager

2026-03-08T16:06:52Z

Johan G: /* Waypoints */ Table cleanup

{{Stub}}
{{Autoflight Navigation}}

A free way to get more SID and STAR procedures for the FlightGear Route Planner.<ref>{{cite web
| url = https://forum.flightgear.org/viewtopic.php?p=313123#p313123
| title = <nowiki> routeplanner stir sid </nowiki>
| author = <nowiki> Sarith </nowiki>
| date = Jun 24th, 2017
| added = Jun 24th, 2017
| script_version = 0.40
}}</ref>

Make some procedures yourself. Charts are easy to find and a quick search will find you the syntax. This is what FlightGear is all about; doing it yourself and sharing it to others. A quick search would also find existing packages.<ref>{{cite web
| url = https://forum.flightgear.org/viewtopic.php?p=313128#p313128
| title = <nowiki> Re: routeplanner stir sid </nowiki>
| author = <nowiki> Parnikkapore </nowiki>
| date = Jun 24th, 2017
| added = Jun 24th, 2017
| script_version = 0.40
}}</ref>

== Installing procedure files ==
=== Manually ===
SID and STAR procedures are found in the <code>procedures.xml</code> file for an airport. There is at most one procedures file per airport and it is located in the root of the airport directory:

<code>[[$FG_SCENERY]]/Airports/I/C/A/ICAO.procedures.xml</code>

With the ICAO code of your airport replacing <code>ICAO</code>.<ref>{{cite web
| url = https://forum.flightgear.org/viewtopic.php?p=313362#p313362
| title = <nowiki> Re: routeplanner stir sid </nowiki>
| author = <nowiki> Parnikkapore </nowiki>
| date = Jun 28th, 2017
| added = Jun 28th, 2017
| script_version = 0.40
}}</ref>

For example, to import SID or STAR procedures for Phuket International Airport (VTSP), you name the file <code>VTSP.procedures.xml</code> and put it in the directory

<code>[[$FG_SCENERY]]/Airports/V/T/S/</code>

In there you will likely find for example <code>VTSP.twr.xml</code>, but not an existing <code>VTSP.procedures.xml</code> file.

Replace <code>VTSP</code> in the directory and <code>procedures.xml</code> file name with your airport code.<ref>{{cite web
| url = https://forum.flightgear.org/viewtopic.php?p=313409#p313409
| title = <nowiki> Re: routeplanner stir sid </nowiki>
| author = <nowiki> Parnikkapore </nowiki>
| date = Jun 29th, 2017
| added = Jun 29th, 2017
| script_version = 0.40
}}</ref>

=== Bash script for organizing files ===
ZirconiumX wrote a bash script for putting the XML files into the the right directories in the scenery.<ref>{{cite web
| url = https://forum.flightgear.org/viewtopic.php?p=280561#p280561
| title = <nowiki> Re: Non-Navigraph SID/STAR xml files </nowiki>
| author = <nowiki> ZirconiumX </nowiki>
| date = Mar 26th, 2016
| added = Mar 26th, 2016
| script_version = 0.40
}}</ref>

<syntaxhighlight lang="bash">
for file in $(ls *.xml)
do
# First, rename all the files to the correct convention
mv "$file" "${file%.xml}.procedures.xml"

# Then move it to the correct place
icao=${file%.xml}
icao1=$(echo $icao | cut -c 1)
icao2=$(echo $icao | cut -c 2)
icao3=$(echo $icao | cut -c 3)
mkdir -p $icao1/$icao2/$icao3
mv "${icao}.procedures.xml" "$icao1/$icao2/$icao3/${icao}.procedures.xml"
done
</syntaxhighlight>

=== Navigraph procedures for linux users ===

* Create a directory to install procedures, let's say navigraph
* Download the bash script and make it executable
* Download the IFMS data from navigraph down load page [https://navigraph.com/downloads navigraph downloads] (paid subscription)
* Expand the data
* Create an Airports directory
* Start the navigraph.sh script with the directories as parameters : ie ./navigraph.sh navdata_native_2511 Airports

Bash script inspired from the one from ZirconiumX<syntaxhighlight lang="bash">
#!/usr/bin/bash
#
# Organize navigraph procedures
#
#
if (( $# < 2 ))
then
printf "%b" "Error. Not enough arguments.\n" >&2
printf "%b" "usage: navigraph.sh fromdirectory todirectory\n" >&2
printf "use directories without trailing slash" >&2
exit 1
fi

fromDir=$1
toDir=$2

for file in $(ls $fromDir/*.xml)
do
filename=${file##*/}
name=${filename%.*} # delete everything after last dot
upcase=${name^^} # uppercase everything

target="$upcase.procedures.xml"
# Then move it to the correct place
icao=${name^^}
icao1=$(echo $icao | cut -c 1)
icao2=$(echo $icao | cut -c 2)
icao3=$(echo $icao | cut -c 3)

dirToCreate=$toDir/$icao1/$icao2/$icao3
echo "creating dir $dirToCreate"
mkdir -p $dirToCreate
echo "copy $fromDir/$filename to $toDir/$icao1/$icao2/$icao3/$target"
cp $fromDir/$filename $toDir/$icao1/$icao2/$icao3/$target
done
</syntaxhighlight>Now you can start flightgear using this directory as a scenery source <blockquote>...

-- fg-scenery=/home/user/fg/Navigraph

...</blockquote>

== File structure ==
In the explanation below, the name like "ProceduresDB" is the tag - so it's actually <code><ProceduresDB></code> in the XML file.
The subsequent parameters, like "build" are attributes - so it's actually <code><ProceduresDB build=""></code> in the XML file.

<pre>
ProceduresDB [build] (one of these per file)
|
Airport [ICAOcode] (one of these per file)
|
Sid [Name, Runways (comma separated - example: "08L,08R")] (many of these per Airport)
|
Sid_Waypoint [ID (unique sequential integer)] (many of these per Sid)
|
Name
Type
Latitude
Longitude
Speed
Altitude
AltitudeCons
AltitudeRestriction (one of "above" or "below" or "at")
Hdg_Crs (optional. example value = "1")
Hdg_Crs_value (optional. heading degrees)
Sp_Turn (optional. example value = "Auto")
...
Sid_Transition [Name] (just one of these per Sid)
|
SidTr_Waypoint [ID] (many of these per Sid_Transition)

Star [Name] (many of these per Airport)
|
Star_Waypoint [ID] (many of these per Star)
...
Star_Transition [Name] (just one of these per Star)
|
StarTr_Waypoint [ID] (many of these per Star_Transition)

Approach [Name] (e.g., ILS08L - uses IL, if appropriate, and the runway name by convention)
|
App_Waypoint [ID]
App_Transition [Name] (just one of these per Approach)
|
AppTr_Waypoint [ID] (many of these per App_Transition)
</pre>

== Waypoints ==
As of FlightGear 2024.1.4, the following types of waypoints are supported<ref>{{flightgear source|path=src/Navaids/LevelDXML.cxx}}</ref>,

{| class="wikitable"
! Waypoint type !! Description !! Required Waypoint Tags
|-
| Normal || Waypoint for proceeding directly to the next one, after a flyby or a flyover, as set by <code>Flytype</code>. || <code>Name</code>, <code>Latitude</code>, <code>Longitude</code>
|-
| Runway || Same as a for a normal waypoint, except with added integrity check to confirm that the runway exists in the airport. || <code>Name</code>, <code>Latitude</code>, <code>Longitude</code>
|-
| Hold || Enter a holding. || <code>Name</code>, <code>Latitude</code>, <code>Longitude</code>, <code>Hld_Turn</code>, <code>Hld_Time_or_Dist</code>, <code>Hld_td_value</code>, <code>Hld_rad_value</code>
|-
| Vectors || Expect vectors by ATC. || <code>Airport</code> (supertag)
|-
| VorRadialIntc / Intc (both are the same) || Fly <code>Hdg_Crs_value</code> until a VOR radial is intercepted, then fly radial to next waypoint. || <code>Name</code>, <code>Latitude</code>, <code>Longitude</code>, <code>Hdg_Crs_value</code>, <code>RadialtoIntercept</code>
|-
| DmeIntc || Fly <code>Hdg_Crs_value</code> until <code>DMEtoIntercept</code> away from required DME, then fly an arc until the next waypoint. || <code>Name</code>, <code>Latitude</code>, <code>Longitude</code>, <code>Hdg_Crs_value</code>, <code>DMEtoIntercept</code>
|-
| ConstHdgtoAlt || Fly <code>Hdg_Crs_value</code> until Altitude is reached, then proceed to next waypoint. || <code>Name</code>, <code>Hdg_Crs_value</code>, <code>Altitude</code>
|-
| PBD || || <code>Name</code>, <code>Latitude</code>, <code>Longitude</code>, <code>Hdg_Crs_value</code>, <code>DMEtoIntercept</code>
|}

== Sample procedures.xml files ==
Here are some links to example XML files which follows the format specified above:
* {{github source
| proj = jojo2357
| repo = flightgear-star-sid-manager
| path = 2020.4/Airports/K/A/T/KATL.procedures.xml
}}<ref>{{cite web
| url = https://forum.flightgear.org/viewtopic.php?p=313583#p313583
| title = <nowiki> Re: routeplanner stir sid </nowiki>
| author = <nowiki> eric </nowiki>
| date = Jul 2nd, 2017
| added = Jul 2nd, 2017
| script_version = 0.40
}}</ref>
* {{github source
| proj = terrasync
| repo = main
| path = Airports/L/F/R/LFRB.procedures.xml
}}

== Sources for procedure files ==
=== Installing free community procedures ===
The FAA provides the [https://www.faa.gov/air_traffic/flight_info/aeronav/digital_products/cifp/ CIFP] which provides procedure data for airports under the purview of the FAA, namely the US.

There is a free project on {{github source
| user = jojo2357
| repo = flightgear-star-sid-manager
| text = GitHub
}} that aims to take FAA data and format it into the Level-D required by FlightGear. For instructions on how to install, see {{github source
| user = jojo2357
| repo = flightgear-star-sid-manager
| path = README.MD#installation
| text = this section
}} of the README.

This project uses GitHub Actions in order to automatically update the procedures at the start of a new AIRAC cycle.

=== Commercial sources ===
A process to import SID/STARs from Navigraph Level D (obtaining this data requires paid subscription to Navigraph) was described on the forum.

Quoting here for reference:{{cite web
| url=https://forum.flightgear.org/viewtopic.php?f=11&t=37975&start=15#p416078
| title = <nowiki> Re: How to get SIDs and STARs in Airbus A320 mcdu </nowiki>
| author = <nowiki> mpotra </nowiki>
| quote = :
# Download Level-D navdata from Navigraph (On the Downloads -> Manual Download page)
# This is ZIP file with a Windows Installer executable inside. If you're on Windows already, run the installer, select a version (Prepar3D/PD3) and then skip to step 4.
# The executable is a Inno Setup executable. In Linux you can extract the contents with `innoextractor -e leveld_2311.exe` for example, which will output a "code$AppName" directory.
# In the extracted directory you'll find a "navdata" folder containing XML files with procedures for all airports for the AIRAC cycle with filenames as "<ICAO>.xml".
# You can either rename in bulk or single file from "<ICAO>.xml" to "<ICAO>.procedures.xml" for desired airports.
# Create a new directory somewhere (anywhere you want) say "AIRAC/2311", and inside it create the "Airports" directory. (camel-case formatted - "airports" with small letter A didn't work for me)
# Inside this "Airports" directory, create new subdirectories for each airport you want to bring in, using the [I]/[C]/[A] format. For example, if you want to add Vienna airport LOWW, create the subdirectories "Airports/L/O/W" - do not create the fourth subdirectory [W] (it won't work)
# Copy the renamed file from step 5 into this last subdirectory. For example, copy "LOWW.procedures.xml" into "AIRAC/2311/Airports/L/O/W" directory, resulting in "AIRAC/2311/Airports/L/O/W/LOWW.procedures.xml". Example 2: for Budapest airport copy "LHBP.procedures.xml" into "AIRAC/2311/Airports/L/H/B", resulting in "AIRAC/2311/Airports/L/H/B/LHBP.procedures.xml"
# In FlightGear, add the "AIRAC/2311" directory to your sceneries paths.
# Reload FlightGear and enjoy SID/STARs in your MCDU
}}

== References ==
{{Appendix}}

== Related content ==
=== Wiki articles ===
* [[Route manager]]
* [[Flightplan XML formats]]

=== Mailing list threads ===
* [https://sourceforge.net/p/flightgear/mailman/flightgear-devel/thread/222DD5B1-B7F1-421B-84AE-A60353203085@flightgear.org/ <nowiki>[Flightgear-devel<nowiki>]</nowiki> Procedures SID/STAR/Approach]

=== Source code ===
* {{flightgear source|path=src/Navaids/LevelDXML.hxx}}
* {{flightgear source|path=src/Navaids/LevelDXML.cxx}}

FlightGear Newsletter

2026-03-08T15:22:05Z

Johan G: /* Archive */ Updating table to show newsletters for January and February 2026.

[[File:magagazine.png|right]]

The '''FlightGear Newsletter''' is intended to provide a collection of the latest developments from the worldwide [[FlightGear]] community. With so much development ongoing, it's almost impossible for anyone to keep up. The newsletter was started in July 2009, and is presented on a monthly basis. It is a collaborative effort that is created, edited and distributed via the [[FlightGear Wiki]], and all FlightGear users, contributors and developers are invited to contribute.

=== Archive ===
<div class="noresize">
{| class="prettytable"
! align="left" | 2026
! align="left" | 2025
! align="left" | 2024
! align="left" | 2023
! align="left" | 2022
! align="left" | 2021
! align="left" | 2020
! align="left" | 2019
! align="left" | 2018
! align="left" | 2017
! align="left" | 2016
! align="left" | 2015
! align="left" | 2014
! align="left" | 2013
! align="left" | 2012
! align="left" | 2011
! align="left" | 2010
! align="left" | 2009
|-
| valign="top" |
* [[FlightGear Newsletter January 2026|January]]
* [[FlightGear Newsletter February 2026|February]]
| valign="top" |
* [[FlightGear Newsletter January 2025|January]]
* [[FlightGear Newsletter February 2025|February]]
* [[FlightGear Newsletter March 2025|March]]
* [[FlightGear Newsletter April 2025|April]]
* [[FlightGear Newsletter May 2025|May]]
* [[FlightGear Newsletter June 2025|June]]
* [[FlightGear Newsletter July 2025|July]]
* [[FlightGear Newsletter August 2025|August]]
* [[FlightGear Newsletter September 2025|September]]
* [[FlightGear Newsletter October 2025|October]]
* [[FlightGear Newsletter November 2025|November]]
* [[FlightGear Newsletter December 2025|December]]
| valign="top" |
* [[FlightGear Newsletter January 2024|January]]
* [[FlightGear Newsletter February 2024|February]]
* [[FlightGear Newsletter March 2024|March]]
* [[FlightGear Newsletter April 2024|April]]
* [[FlightGear Newsletter May 2024|May]]
* [[FlightGear Newsletter June 2024|June]]
* [[FlightGear Newsletter July 2024|July]]
* [[FlightGear Newsletter August 2024|August]]
* [[FlightGear Newsletter September 2024|September]]
* [[FlightGear Newsletter October 2024|October]]
* [[FlightGear Newsletter November 2024|November]]
* [[FlightGear Newsletter December 2024|December]]
| valign="top" |
* [[FlightGear Newsletter January 2023|January]]
* [[FlightGear Newsletter February 2023|February]]
* [[FlightGear Newsletter March 2023|March]]
* [[FlightGear Newsletter April 2023|April]]
* [[FlightGear Newsletter May 2023|May]]
* [[FlightGear Newsletter June 2023|June]]
* [[FlightGear Newsletter July 2023|July]]
* [[FlightGear Newsletter August 2023|August]]
* [[FlightGear Newsletter September 2023|September]]
* [[FlightGear Newsletter October 2023|October]]
* [[FlightGear Newsletter November 2023|November]]
* [[FlightGear Newsletter December 2023|December]]
| valign="top" |
* [[FlightGear Newsletter January 2022|January]]
* [[FlightGear Newsletter February 2022|February]]
* [[FlightGear Newsletter March 2022|March]]
* [[FlightGear Newsletter April 2022|April]]
* [[FlightGear Newsletter May 2022|May]]
* June
* [[FlightGear Newsletter July 2022|July]]
* [[FlightGear Newsletter August 2022|August]]
* [[FlightGear Newsletter September 2022|September]]
* [[FlightGear Newsletter November 2022|November]]
* [[FlightGear Newsletter December 2022|December]]
| valign="top" |
* [[FlightGear Newsletter January 2021|January]]
* [[FlightGear Newsletter February 2021|February]]
* [[FlightGear Newsletter March 2021|March]]
* [[FlightGear Newsletter April 2021|April]]
* [[FlightGear Newsletter May 2021|May]]
* [[FlightGear Newsletter June 2021|June]]
* [[FlightGear Newsletter July 2021|July]]
* [[FlightGear Newsletter August 2021|August]]
* [[FlightGear Newsletter September 2021|September]]
* [[FlightGear Newsletter October 2021|October]]
* [[FlightGear Newsletter November 2021|November]]
* [[FlightGear Newsletter December 2021|December]]
| valign="top" |
* [[FlightGear Newsletter January 2020|January]]
* [[FlightGear Newsletter February 2020|February]]
* [[FlightGear Newsletter March 2020|March]]
* [[FlightGear Newsletter April 2020|April]]
* [[FlightGear Newsletter May 2020|May]]
* [[FlightGear Newsletter June 2020|June]]
* [[FlightGear Newsletter July 2020|July]]
* [[FlightGear Newsletter August 2020|August]]
* [[FlightGear Newsletter September 2020|September]]
* [[FlightGear Newsletter October 2020|October]]
* [[FlightGear Newsletter November 2020|November]]
* [[FlightGear Newsletter December 2020|December]]
| valign="top" |
* [[FlightGear Newsletter January 2019|January]]
* [[FlightGear Newsletter February 2019|February]]
* [[FlightGear Newsletter March 2019|March]]
* [[FlightGear Newsletter April 2019|April]]
* [[FlightGear Newsletter May 2019|May]]
* [[FlightGear Newsletter June 2019|June]]
* [[FlightGear Newsletter July 2019|July]]
* [[FlightGear Newsletter August 2019|August]]
* [[FlightGear Newsletter September 2019|September]]
* [[FlightGear Newsletter October 2019|October]]
* [[FlightGear Newsletter November 2019|November]]
| valign="top" |
* [[FlightGear Newsletter January 2018|January]]
* [[FlightGear Newsletter February 2018|February]]
* [[FlightGear Newsletter March 2018|March]]
* [[FlightGear Newsletter April 2018|April]]
* [[FlightGear Newsletter May 2018|May]]
* [[FlightGear Newsletter June 2018|June]]
* [[FlightGear Newsletter July 2018|July]]
* [[FlightGear Newsletter August 2018|August]]
* [[FlightGear Newsletter September 2018|September]]
* [[FlightGear Newsletter October 2018|October]]
* [[FlightGear Newsletter November 2018|November]]
* [[FlightGear Newsletter December 2018|December]]
| valign="top" |
* [[FlightGear Newsletter January 2017|January]]
* [[FlightGear Newsletter February 2017|February]]
* [[FlightGear Newsletter March 2017|March]]
* [[FlightGear Newsletter April 2017|April]]
* [[FlightGear Newsletter May 2017|May]]
* [[FlightGear Newsletter June 2017|June]]
* [[FlightGear Newsletter July 2017|July]]
* [[FlightGear Newsletter August 2017|August]]
* [[FlightGear Newsletter September 2017|September]]
* [[FlightGear Newsletter October 2017|October]]
* [[FlightGear Newsletter November 2017|November]]
* [[FlightGear Newsletter December 2017|December]]
| valign="top" |
* [[FlightGear Newsletter January 2016|January]]
* [[FlightGear Newsletter February 2016|February]]
* [[FlightGear Newsletter March 2016|March]]
* [[FlightGear Newsletter April 2016|April]]
* [[FlightGear Newsletter May 2016|May]]
* [[FlightGear Newsletter June 2016|June]]
* [[FlightGear Newsletter July 2016|July]]
* [[FlightGear Newsletter August 2016|August]]
* [[FlightGear Newsletter September 2016|September]]
* [[FlightGear Newsletter October 2016|October]]
* [[FlightGear Newsletter November 2016|November]]
* [[FlightGear Newsletter December 2016|December]]
| valign="top" |
* [[FlightGear Newsletter January 2015|January]]
* [[FlightGear Newsletter February 2015|February]]
* [[FlightGear Newsletter March 2015|March]]
* [[FlightGear Newsletter April 2015|April]]
* [[FlightGear Newsletter May 2015|May]]
* [[FlightGear Newsletter June 2015|June]]
* [[FlightGear Newsletter July 2015|July]]
* [[FlightGear Newsletter August 2015|August]]
* [[FlightGear Newsletter September 2015|September]]
* [[FlightGear Newsletter October 2015|October]]
* [[FlightGear Newsletter November 2015|November]]
* [[FlightGear Newsletter December 2015|December]]
| valign="top" |
* [[FlightGear Newsletter January 2014|January]]
* [[FlightGear Newsletter February 2014|February]]
* [[FlightGear Newsletter March 2014|March]]
* [[FlightGear Newsletter April 2014|April]]
* [[FlightGear Newsletter May 2014|May]]
* [[FlightGear Newsletter June 2014|June]]
* [[FlightGear Newsletter July 2014|July]]
* [[FlightGear Newsletter August 2014|August]]
* [[FlightGear Newsletter September 2014|September]]
* [[FlightGear Newsletter October 2014|October]]
* [[FlightGear Newsletter November 2014|November]]
* [[FlightGear Newsletter December 2014|December]]
| valign="top" |
* [[FlightGear Newsletter January 2013|January]]
* [[FlightGear Newsletter February 2013|February]]
* [[FlightGear Newsletter March 2013|March]]
* [[FlightGear Newsletter April 2013|April]]
* [[FlightGear Newsletter May 2013|May]]
* [[FlightGear Newsletter June 2013|June]]
* [[FlightGear Newsletter July 2013|July]]
* [[FlightGear Newsletter August 2013|August]]
* [[FlightGear Newsletter September 2013|September]]
* [[FlightGear Newsletter October 2013|October]]
* [[FlightGear Newsletter November 2013|November]]
* [[FlightGear Newsletter December 2013|December]]
| valign="top" |
* [[FlightGear Newsletter January 2012|January]]
* [[FlightGear Newsletter February 2012|February]]
* [[FlightGear Newsletter March 2012|March]]
* [[FlightGear Newsletter April 2012|April]]
* [[FlightGear Newsletter May 2012|May]]
* [[FlightGear Newsletter June 2012|June]]
* [[FlightGear Newsletter July 2012|July]]
* [[FlightGear Newsletter August 2012|August]]
* [[FlightGear Newsletter September 2012|September]]
* [[FlightGear Newsletter October 2012|October]]
* [[FlightGear Newsletter November 2012|November]]
* [[FlightGear Newsletter December 2012|December]]
| valign="top" |
* [[FlightGear Newsletter January 2011|January]]
* [[FlightGear Newsletter February 2011|February]]
* [[FlightGear Newsletter March 2011|March]]
* [[FlightGear Newsletter April 2011|April]]
* [[FlightGear Newsletter May 2011|May]]
* [[FlightGear Newsletter June 2011|June]]
* [[FlightGear Newsletter July 2011|July]]
* [[FlightGear Newsletter August 2011|August]]
* [[FlightGear Newsletter September 2011|September]]
* [[FlightGear Newsletter October 2011|October]]
* [[FlightGear Newsletter November 2011|November]]
* [[FlightGear Newsletter December 2011|December]]
| valign="top" |
* [[FlightGear Newsletter January 2010|January]]
* [[FlightGear Newsletter February 2010|February]]
* [[FlightGear Newsletter March 2010|March]]
* [[FlightGear Newsletter April 2010|April]]
* [[FlightGear Newsletter May 2010|May]]
* [[FlightGear Newsletter June 2010|June]]
* [[FlightGear Newsletter July 2010|July]]
* [[FlightGear Newsletter August 2010|August]]
* [[FlightGear Newsletter September 2010|September]]
* [[FlightGear Newsletter October 2010|October]]
* [[FlightGear Newsletter November 2010|November]]
* [[FlightGear Newsletter December 2010|December]]
| valign="top" |
* [[FlightGear Newsletter July 2009|July]]
* [[FlightGear Newsletter August 2009|August]]
* [[FlightGear Newsletter September 2009|September]]
* [[FlightGear Newsletter October 2009|October]]
* [[FlightGear Newsletter November 2009|November]]
* [[FlightGear Newsletter December 2009|December]]
|}
</div>

Some newsletter editions have been translated in other languages:
* [[File:De.gif|16px|link=:De:FlightGear Newsletter]] [[:De:FlightGear Newsletter|Deutsch]]
* [[File:Es.gif|16px|link=:Es:FlightGear Newsletter]] [[:Es:FlightGear Newsletter|Español]]
* [[File:Fr.gif|16px|link=:Fr:FlightGear Newsletter]] [[:Fr:FlightGear Newsletter|Français]]

=== You are invited to contribute! ===
We would like to emphasize that the monthly newsletter can not live without the contributions of FlightGear users and developers. The FlightGear Newsletter is a community-driven newsletter, which means that it is created and edited by people like ''you''. You don't need to be a long-time FlightGear user (or even a developer) to contribute to the newsletter.

In fact, helping write the monthly FlightGear newsletter is an excellent way for getting started contributing to the FlightGear community very quickly and very easily.

Even if you don't have to add anything yourself, just reviewing and improving additions by others is also highly appreciated, as are efforts to help translate newsletters or add screen shots (e.g. taken from the forum or mailing lists) to the newsletter. Screen shots can be uploaded at [[Special:Upload]].

Everyone with a wiki account (free to [[Special:UserLogin|register]]) can edit the newsletter and every contribution is welcome. So if you know about any FlightGear related projects such as for example updated scenery or aircraft, please do feel invited to add such news to the newsletter.

A simple template providing a basic structure for each upcoming newsletter can be taken from [[Talk:Next newsletter]]. This template can be copied/pasted into each new newsletter to help users getting started providing contents.

The draft for the upcoming newsletter can always be found at [[Next newsletter]].

If English is not your native language, please don't be concerned about contributing to the newsletter, you can always easily ask fellow FlightGear users to review or proof-read your changes. Also, one of the easiest ways to get started is simply copying/pasting text from forum or mailing list discussions, such as announcements (e.g., new aircraft, new scenery, etc.).

Another neat option to get started is adding links to FlightGear-related YouTube videos. For this, we have a dedicated section in each newsletter: "[[FlightGear Newsletter {{#time: F Y | last month }}#FlightGear on YouTube|FlightGear on YouTube]]."

If you want to embed a video, please see {{mediawiki|Extension:EmbedVideo#Usage}}

If you are looking for other ways to get involved, please see [[Volunteer]].

[[Category:FlightGear Newsletter| ]]
[[Category:Community|Newsletter]]
[[Category:Lists|Newsletter]]

[[de:FlightGear Newsletter]]
[[es:FlightGear Newsletter]]
[[fr:FlightGear Newsletter]]

Category:World Scenery 3.0

2026-01-25T07:47:39Z

Johan G: +cat Scenery enhancement

Articles relating to WS 3.0

[[Category:Scenery enhancement]]

Timed Loops

2025-10-12T12:51:03Z

Johan G: Spelling fix

{{Infobox Software|title=Timed Loops Add-on|developedby=FGUK|initialrelease=2017|writtenin=Nasal|type=Add-on|license=[[GNU General Public License]] v2}}

'''Timed Loops''', also known as '''Mach Loop Challenge''' by FGUK is an add-on with timed courses challenges trough the valleys of the Mach Loop in Wales, Great Britain.

== The Mach Loop ==
The ''Mach Loop''<ref>{{wikipedia |Mach Loop}}</ref> (also known as the ''Machynlleth Loop'') is a part of the United Kingdom Low Flying System and lies within Low Flying Area 7 (LFA7), which covers most of Wales.

The system of valleys lies 13 km (8 mi) east of Barmouth between the towns of Dolgellau to the north and Machynlleth to the south

== The Mach Loop Challenge ==
This challenge is based on that in the BAE Typhoon training simulator. There are a series of Gates the pilot must pass through to complete the challenge. As with most peacetime military flying operations flight operations are limited to subsonic.

Your course time will be printed on screen as you exit the course providing that no gates are missed and that the speed limit was not exceeded.

There are 5 versions of the challenge available in this add-on.

# '''Mach loop – Unlimited''' – As above, but with no max speed limit.
# '''Heli Race''' – Helicopter version of the loop
# '''Moli Loop''' – An extended course in the same area. Speed restrictions of < M1.0 applies.
# '''Long loop''' – Mach loop extending into Moli loop.
# '''Unlimited mach loop''' - Version of the loop with no speed restrictions.

The scenarios should now be available from your AI/Scenarios menu in sim.

The scenarios are closest to Llanbedr Airfield (EGOD), where it is useful to start on runway 05. If you prefer you could start at RAF Valley (EGOV) and fly south to EGOD to pick up the loop.

== Videos ==
An example of the challenge can be seen in these videos:

* F-14 in 144.0s : https://www.youtube.com/embed/jIdnQfwU1W4
* Vulcan B2 https://www.youtube.com/embed/XK0Y1sfijLY

== References ==
<references/>

== Related content ==
=== Forum topics ===
* {{forum link |t=23670 |title=FlightNight 9/8/14 Mach loop challenge}}
* {{forum link |t=39519 |title=Mach Loop Challenge markers showing as aircraft not hexagons}}

=== Source code ===
* {{fgaddon source |path=Addons/TimedLoops}}

[[Category:FlightGear addons]]

Timed Loops

2025-10-12T12:48:46Z

Johan G: Minor cleanup; +headings; +related: Some forum topics, source; Note: A screenshot or two would be nice

{{Infobox Software|title=Timed Loops Add-on|developedby=FGUK|initialrelease=2017|writtenin=Nasal|type=Add-on|license=[[GNU General Public License]] v2}}

'''Timed Loops''', also known as '''Mach Loop Challenge''' by FGUK is an aad-on with a timed course challenge trough the valleys of the Mach Loop in Wales, Great Britain.

== The Mach Loop ==
The ''Mach Loop''<ref>{{wikipedia |Mach Loop}}</ref> (also known as the ''Machynlleth Loop'') is a part of the United Kingdom Low Flying System and lies within Low Flying Area 7 (LFA7), which covers most of Wales.

The system of valleys lies 13 km (8 mi) east of Barmouth between the towns of Dolgellau to the north and Machynlleth to the south

== The Mach Loop Challenge ==
This challenge is based on that in the BAE Typhoon training simulator. There are a series of Gates the pilot must pass through to complete the challenge. As with most peacetime military flying operations flight operations are limited to subsonic.

Your course time will be printed on screen as you exit the course providing that no gates are missed and that the speed limit was not exceeded.

There are 5 versions of the challenge available in this add-on.

# '''Mach loop – Unlimited''' – As above, but with no max speed limit.
# '''Heli Race''' – Helicopter version of the loop
# '''Moli Loop''' – An extended course in the same area. Speed restrictions of < M1.0 applies.
# '''Long loop''' – Mach loop extending into Moli loop.
# '''Unlimited mach loop''' - Version of the loop with no speed restrictions.

The scenarios should now be available from your AI/Scenarios menu in sim.

The scenarios are closest to Llanbedr Airfield (EGOD), where it is useful to start on runway 05. If you prefer you could start at RAF Valley (EGOV) and fly south to EGOD to pick up the loop.

== Videos ==
An example of the challenge can be seen in these videos:

* F-14 in 144.0s : https://www.youtube.com/embed/jIdnQfwU1W4
* Vulcan B2 https://www.youtube.com/embed/XK0Y1sfijLY

== References ==
<references/>

== Related content ==
=== Forum topics ===
* {{forum link |t=23670 |title=FlightNight 9/8/14 Mach loop challenge}}
* {{forum link |t=39519 |title=Mach Loop Challenge markers showing as aircraft not hexagons}}

=== Source code ===
* {{fgaddon source |path=Addons/TimedLoops}}

[[Category:FlightGear addons]]

Aircraft failure system

2025-10-04T23:58:10Z

Johan G: + Mention that this article relates to FlightGear version 3.0 or older; +related: Link to forum topic

: ''For FlightGear version 3.1 or newer see [[A Failure Management Framework for FlightGear]].''

Want an engine or instrument to fail mid-flight? Flightgear has such a system, but not every aircraft supports it fully.
The failure system is disabled by default, the system can be accessed in Flightgear in the Equipment menu.

== Flying with failures ==
=== Using the Failure System ===
Should you for example wish to fail an instrument, you can open the Instrument failure panel as seen below.

[[File:Instrument Failures.png|The instrument failure panel]]

A checked field means that the instrument has not failed. To fail it, simply uncheck it, and click apply. If the aircraft suports it, it will fail immidiatly.

For each instrument, there is also a MTBF ([http://en.wikipedia.org/wiki/Mean_time_between_failures Mean time between failures]), where you can specify the how often an instrument should fail. MTBF is in seconds.

To make the instrument work again, simply open the panel, check it, and click apply.

Systems works in the same way as instruments, but some components have a MCBF (Mean cyclus between failures) field, instead of a MTBF. A cycle is each time the system is changed into the other direction. E.g. for flaps each time it is moved in or out, opposite of last movement counts for a cycle:

[[File:System Failures.png|The system failure panel]]

=== Using the Random Failure Manager ===
The random failure manager is a convenient way to enter the same MTBF/MCBF for all systems/instruments.

[[File:Random Failures.png|The random failure panel]]

If you want a red message on the screen to tell when it fails, the click the checkbox for that.

== Adapting an aircraft to fail ==
Some things will work pretty much out of the box. For example engine and control surfaces. Some control surfaces like elevons, spoilers and instruments like CDU you have to either find a matchable serviceable property and make the object depend on it or make your own.

Serviceable properties are found various places.

Examples:

<code>/instrumentation/airspeed-indicator/serviceable

/gear/serviceable

/systems/vacuum/serviceable

/controls/flight/elevator/serviceable</code>

They are either true or false.

Some things depend on more serviceables, for example airspeed indicator can fail on its own, or the electrical system can fail on which it depend.

For some systems/instruments, when it becomes unserviceable, some properties will also become read-only. For example the rudder will get 'stuck'. Some elements of Flightgear give some Alerts in the console, when the try to change a property and cannot. For example JSBSim will output an error when trying to change the rudder position after it failed, when you try to yaw the plane. Most of these messages can be ignored.

=== Making a custom failure ===
At the moment the panels for failure cannot be extended with custom elements, but you can write in NASAL your own code on when/how to fail a system.

Make a serviceable property where you have other properties for that system. And then write some script/xml to make the system depend on that property.

Examples of what you could make a custom failure for:

Brakes, CDU, instrumentation light, HUD, Canopy, doors, cabin pressure system, autopilot, radar etc.

=== Extending the random failure manager ===
With Nasal the random failure manager can be extended with additional failures, but until Flightgear 3.4 they will not show up in the GUI panels.

Notice the failure system has been changed for Flightgear 3.2, even though the GUI has not changed yet (scheduled for Flightgear 3.4). The [[A_Failure_Management_Framework_for_FlightGear|new system]] will allow components to fail at various levels instead of only 0% or 100% failed. It is also more flexible and easier to extend and modify.

==== Flightgear 3.0 example (Do not use for 3.2) ====

Example of adding Canvas HUD, Canopy and Instrumentation lights to the list of systems that might fail:

<syntaxhighlight lang="nasal"># random failure code:

var fail = { SERVICEABLE : 1, JAM : 2, ENGINE: 3};
var type = { MTBF : 1, MCBF: 2 };
var failure_root = "/sim/failure-manager";
#HUD
var prop = "/instrumentation/head-up-display";
failures.breakHash[prop] = {
type: type.MTBF, failure: fail.SERVICEABLE, desc: "Head up display"};
var o = failures.breakHash[prop];
var t = "/mtbf";
props.globals.initNode(failure_root ~ prop ~ t, 0);
props.globals.initNode(prop ~ "/serviceable", 1, "BOOL");
# Instrument light:
prop = "/instrumentation/instrumentation-light";
failures.breakHash[prop] = {
type: type.MTBF, failure: fail.SERVICEABLE, desc: "Instrumentation light"};
props.globals.initNode(failure_root ~ prop ~ t, 0);
props.globals.initNode(prop ~ "/serviceable", 1, "BOOL");
# Canopy:
prop = "/fdm/jsbsim/fcs/canopy";
failures.breakHash[prop] = {
type: type.MTBF, failure: fail.SERVICEABLE, desc: "Canopy"};
props.globals.initNode(failure_root ~ prop ~ t, 0);
props.globals.initNode(prop ~ "/serviceable", 1, "BOOL");
# Set all MTBF to 24 hours:
setprop("/sim/failure-manager/display-on-screen", 1);
setprop("/sim/failure-manager/global-mcbf-0", 0);
setprop("/sim/failure-manager/global-mcbf-500", 1);
setprop("/sim/failure-manager/global-mcbf", 500);
setprop("/sim/failure-manager/global-mtbf-0", 0);
setprop("/sim/failure-manager/global-mtbf-86400", 1);
setprop("/sim/failure-manager/global-mtbf", 86400);
failures.setAllMCBF(500);
failures.setAllMTBF(86400);</syntaxhighlight>

For example for canopy it will make a property called:

/fdm/jsbsim/fcs/canopy/serviceable

In the above code its MTBF is set to 24 hours, but this can be changed in the Random Failure panel.

== Related content ==
=== Forum topics ===
* {{forum link |t=21855 |title=How does serviceable and failures work?}}

=== Source code ===
For FlightGear v 3.0 or older (according to {{forum link |p=227190 |title=this}}).

* $FGDATA/Nasal/failures.nas for more info.

[[Category:Aircraft enhancement]]

Input device

2025-03-17T12:22:24Z

Johan G: /* Forum topics */ + [HOWTO] Use more than 32 buttons on Windows via HID

Could you imagine a pilot in his or her [[:Category:Cessna|Cessna]] controlling the machine with a keyboard alone? For getting the proper feeling of flight you will need a '''joystick/yoke''' plus [[rudder]] pedals, right?

FlightGear has integrated joystick support, which automatically detects any joystick, yoke, or pedals attached. Just try it! If this does work for you, lean back and be happy! You can see what FlightGear has detected your joystick as in the Help > Joystick Configuration dialog from the [[menu]].

Unfortunately, for the above mentioned versatility, chances are your joystick does not work out of the box. This article explains you how to make FlightGear recognise your device

== Joystick or yoke? ==
{| cellpadding="4" cellspacing="0" align="right" style="clear:right; background:#fafafa; font-size: 85%; border: 1px solid #CCCCCC;"
|-
| [[File:CH Products Fighterstick USB.jpg|x199px|CH Products Fighterstick USB]]
| [[File:Saitek Pro Flight Cessna Yoke front.jpg|300px|Saitek Pro Flight Cessna Yoke]]
|-
| CH Products Fighterstick USB
| Saitek Pro Flight Cessna Yoke
|}
The two most common control devices on aircraft are the joystick (left picture) and yoke (right picture). Joysticks can be found on military fighters, helicopters and Airbus [[airliner]]s, while yokes are used on almost all other fixed wing aircraft, including Boeing airliners.

Joysticks are generally a lot cheaper, starting at $10. Yokes start at $100. When you are new to flightsimming, buying a cheap (ca. $20) joystick might be a good way to find out if it's something for you.

The following table should help you decide which one is best suited for you:
{| class="wikitable"
!
! Joystick
! Yoke
|-
! style="text-align:left;" | Price
| $10+
| $100+
|-
! style="text-align:left;" | General aviation
| {{no}}
| {{yes}}
|-
! style="text-align:left;" | Gliders
| {{yes}}
| {{no}}
|-
! style="text-align:left;" | Helicopter
| {{yes}}
| {{no}}
|-
! style="text-align:left;" | Fighters
| {{yes}}
| {{no}}
|-
! style="text-align:left;" | Most airliners including Boeing
| {{no}}
| {{yes}}
|-
! style="text-align:left;" | Airbus
| {{yes}}
| {{no}}
|}

It should be noted that any type of input device (be it a joystick, a yoke or even a gamepad) will work with '''all''' aircraft in FlightGear and that the table above only suggests which ones are more suited to specific types of aircraft given how they are flown in real life.

Some reviews of flight simulation hardware can be found in [[:Category:Hardware reviews]].

== Built-in joystick support ==
In order for joystick auto-detection to work, a joystick bindings xml file must exist for each joystick. This file describes what axes and buttons are to be used to control which functions in FlightGear. The associations between functions and axes or buttons are called "bindings".

FlightGear includes a large number of such bindings files for a variety of manufacturers. Chances are high that your joystick will be recognised straight away, so let's try that first. You can confirm whether it was recognised by looking in the <tt>File > Joystick Configuration</tt> dialog. "Used for" should contain a name/description of your joystick. It will contain "default" when FlightGear did not recognise your joystick.

Most of the time when your joystick is not recognised, it is because of a missing name definition in the respective bindings file. Because FlightGear is used on all kind of operating systems, names vary a lot. You can find the files under <tt>[[$FG_ROOT]]/Input/Joysticks/</tt> (despite the name, yokes and pedals are also found here!). For example, if you have a CH Products joystick, look in the folder <tt>[[$FG_ROOT]]/Input/Joysticks/CH</tt> for a file that might work for your joystick. When such a file exists, do the following:
# Launch FlightGear with the joystick connected.
# Look under File > Joystick Configuration and check the name behind "Joystick #0:".
# Open your joystick's bindings file in a XML editor and add the following code to the file, below the already-present <code><name></code> tags.
# <syntaxhighlight lang="xml"><name>The EXACT name you found under step 2; including spaces, capitals etc.</name></syntaxhighlight>
# Please report this name [http://forum.flightgear.org/viewforum.php?f=24 at our forum], so it can be added to the official file (and next releases).

Please note that the latest config files are always to be found at {{fgdata file|Input/Joysticks}}. This link may contain additional binding files that were not included in the latest stable release.

If there is no file for your joystick, you will have to create such a file. We will discuss that in [[Joystick#Writing or editing joystick binding xml files|a later section]], by cutting and pasting bindings from the examples that are included with FlightGear.

=== Multiple devices on Windows ===
In case you have two USB devices (for instance a yoke plus pedals) to a Windows computer, there may be cases, where the same driver name is reported twice. In this case, you can get at least the yoke to work by assigning it number 0 (out of 0 and 1), by adding a line to <tt>[[$FG_ROOT]]/joystick.xml</tt> like:
<syntaxhighlight lang="xml"><js n="0" include="Input/Joysticks/Saitek/ST290-Pro.xml"/></syntaxhighlight>
if you also have pedals (or another joystick), just add more lines, similar to:
<syntaxhighlight lang="xml"><js n="1" include="Input/Joysticks/Saitek/Pro-Flight-Rudder-Pedals.xml"/></syntaxhighlight>

To make sure that the first input device is indeed the yoke, rotate the yoke ([[aileron]] control) and observe the Help > Joystick Configuration dialog. If the aileron value does not change, you have to make the yoke the preferred device first. For doing so, enter the Windows "Control panel", open "Game controllers" and select the "Advanced" button. Here you can select the yoke as the "Preferred" device. Afterwards you can check that assignment by restarting FlightGear. The yoke should now control the aileron.

== Adding support for your joystick ==
=== Verifying your joystick is working ===
==== Linux ====
Reboot your system and immediately enter on the [[command line]]

<syntaxhighlight lang="bash">
dmesg | grep Joystick
</syntaxhighlight>

which pipes the boot message to grep which then prints every line in the boot message that contains the string “Joystick”. When you do this with a Saitek joystick attached, you will see a line similar to this one:

<syntaxhighlight>
input0: USB HID v1.00 Joystick [SAITEK CYBORG 3D USB] on usb2:3.0
</syntaxhighlight>

This line tells us that a joystick has identified itself as SAITEK CYBORG 3D USB to the operating system. It does not tell us that the joystick driver sees your joystick. You can verify that the joystick driver sees the joystick by entering:

<syntaxhighlight>
js_demo
</syntaxhighlight>

If your joystick is not recognized by the driver, you may have to manually load the joystick device module with the command:

<syntaxhighlight>
modprobe joydev
</syntaxhighlight>

==== Windows ====
Go to <tt>Start > Control Panel > Game Controller</tt> and see whether the dialog displays (and responses) on your joystick.

=== Confirming that the driver recognizes your joystick ===
FlightGear ships with a utility called js_demo. It will report the number of joysticks attached to a system, their respective "names" and their capabilities. Under Linux, you can run js_demo from the folder /FlightGear/bin as follows:

<syntaxhighlight lang="bash">
$ cd /usr/local/FlightGear/bin
$ js_demo
</syntaxhighlight>

Under Windows, open a command shell (<tt>Start > All Programs > Accessories > Command Prompt</tt>), go to the FlightGear binary folder and start the program as follows (given FlightGear is installed under <tt>C:/Program Files/Flightgear</tt>)

<syntaxhighlight lang="dos">
C:
cd /Program Files/FlightGear/bin/win32
js_demo.exe
</syntaxhighlight>



On our system, the first few lines of output are (stop the program with C if it is quickly scrolling past your window!) as follows:

<syntaxhighlight>
Joystick test program.
Joystick 0: “CH PRODUCTS CH FLIGHT SIM YOKE USB ”
Joystick 1: “CH PRODUCTS CH PRO PEDALS USB”
Joystick 2 not detected
Joystick 3 not detected
Joystick 4 not detected
Joystick 5 not detected
Joystick 6 not detected
Joystick 7 not detected
+——————–JS.0———————-+——————–JS.1———————-+
| Btns Ax:0 Ax:1 Ax:2 Ax:3 Ax:4 Ax:5 Ax:6 | Btns Ax:0 Ax:1 Ax:2 |
+———————————————-+———————————————-+
| 0000 +0.0 +0.0 +1.0 -1.0 -1.0 +0.0 +0.0 . | 0000 -1.0 -1.0 -1.0 . . . . . |
</syntaxhighlight>

First note that js demo reports which number is assigned to each joystick recognized by the driver. Also, note that the “name” each joystick reports is also included between quotes. We will need the names for each bindings file when we begin writing the binding xml files for each joystick.

=== Identifying the numbering of axes and buttons ===
Axis and button numbers can be identified using js demo as follows. By observing the output of js demo while working your joystick axes and buttons you can determine what axis and button numbers are assigned to each joystick axis and button. It should be noted that numbering generally starts with zero.

The buttons are handled internally as a binary number in which bit 0 (the least significant bit) represents button 0, bit 1 represents button 1, etc., but this number is displayed on the screen in hexadecimal notation, so:

* 0001 ⇒ button 0 pressed
* 0002 ⇒ button 1 pressed
* 0004 ⇒ button 2 pressed
* 0008 ⇒ button 3 pressed
* 0010 ⇒ button 4 pressed
* 0020 ⇒ button 5 pressed
* 0040 ⇒ button 6 pressed
* ... etcp to ...
* 8000 ⇒ button 15 pressed
* ... and ...
* 0014 ⇒ buttons 2 and 4 pressed simultaneously
* ... etc.

For Linux users, there is another option for identifying the “name” and the numbers assigned to each axis and button. Most Linux distributions include a very handy program, “jstest”. With a CH Product Yoke plugged into the system, the following output lines are displayed by jstest:

<syntaxhighlight lang="bash">
jstest /dev/js3
Joystick (CH PRODUCTS CH FLIGHT SIM YOKE USB ) has 7 axes and 12 buttons. Driver version is 2.1.0
Testing…(interrupt to exit)
Axes: 0: 0 1: 0 2: 0 3: 0 4: 0 5: 0 6: 0 Buttons: 0:off 1:off 2:off 3:on 4:off 5:off 6:off 7:off 8:off 9:off 10:off 11:off
</syntaxhighlight>

Note the “name” between parentheses. This is the name the system associates with your joystick.

When you move any control, the numbers change after the axis number corresponding to that moving control and when you depress any button, the “off” after the button number corresponding to the button pressed changes to “on”. In this way, you can quickly write down the axes numbers and button numbers for each function without messing with binary.

In most modern repositories, there is a graphical version of this program, called "jstest-gtk", where you are given a list of attached devices to choose from, and then get a graphical representation of all axes and buttons.

=== Calibration ===
For many/most joysticks this step might not be necessary. If either, the centre position of the joystick does not yield near-zero values for relevant axes, or if the maximum value for an axis cannot be reached, or is reached too early, you need to calibrate the joystick. (Note that some calibration problems can be fixed with the flighgear joystick configuration files, but not all, e.g. if the maximum value is reached too early)

==== Linux ====
The program "jscal" (install from repositories if not already available on your system) provides a calibration routine for joysticks. You need to know or find out the device name of your joystick (usually /dev/js0 or /dev/input/js0 - instead of 0 a different number might need to be used, look at output of js_demo to figure out which). For example to calibrate the joystick with device name /dev/input/js0, execute
<syntaxhighlight lang="bash">jscal -c /dev/input/js0
</syntaxhighlight>
and follow instructions.
The calibration is retained until the joystick is unplugged, or the computer rebooted. In order to save it for future use, execute
<syntaxhighlight lang="bash">jscal -p /dev/input/js0
</syntaxhighlight>
which will print the command that needs to be entered to restore the calibration, for example
<syntaxhighlight lang="bash">jscal -s 6,1,0,8171,8171,65936,65374,1,0,8166,8166,65928,65494,1,0,128,128,4194176,4227201,1,0,128,128,4194176,4227201,1,0,0,0,536854528,536854528,1,0,0,0,536854528,536854528 /dev/input/js0
</syntaxhighlight>
Copy the command you obtained into your startup script in order to restore calibration automatically.

Recent versions of jscal have this simplified, you can store and restore your calibration settings.
After calibration store the settings:
<syntaxhighlight lang="bash">jscal-store /dev/input/js0
</syntaxhighlight>

Then in your startup script recall the settings for the given device:
<syntaxhighlight lang="bash">jscal-restore /dev/input/js0
</syntaxhighlight>

However if you have multiple controllers connected, they might be renumbered on pluging/repluging. Best way to insure you get the correct calibration is to create a custom '''udev''' rule-set that you put into /etc/udev/rules.d/00-joystick.rules, similar to the following example:
<syntaxhighlight lang="bash">
#joystick rules to make the names persistent and reload the stored calibration profile
ACTION!="add|change", GOTO="joystick_end"
SUBSYSTEM!="input", GOTO="joystick_end"

KERNEL=="js*", ATTRS{idProduct}=="a02f", ATTRS{idVendor}=="12bd", SYMLINK+="input/joystick" RUN+="/etc/udev/scripts/joycal.sh"
KERNEL=="js*", ATTRS{name}=="Logitech Logitech Racing Wheel", SYMLINK+="input/logiwheel" RUN+="/etc/udev/scripts/wheelcal.sh"

LABEL="joystick_end"
</syntaxhighlight>

Then the scripts called would be as follows:
*/etc/udev/scripts/joycal.sh:
<syntaxhighlight lang="bash">
#!/bin/sh
jscal-restore /dev/input/joystick
</syntaxhighlight>
*/etc/udev/scripts/wheelcal.sh
<syntaxhighlight lang="bash">
#!/bin/sh
jscal-restore /dev/input/logiwheel
</syntaxhighlight>

Now each time you plug/replug your joysticks/controllers they will get the persistent device names, and will get the correct calibration profile restored.

The calibration is even more comfortable using the program "jstest-gtk", also available from most repositories. Starting this you are given a list of all attached joysticks with their device names. Pick the one you wish to inspect or calibrate and click 'Properties', then calibrate. This calibration tool offers the possibility to fine-tune the calibration by editing the numbers. The program manipulates the same internals as jscal so you can use jscal to save the calibration information for later use, as before.

=== Writing or editing joystick binding xml files ===
At this point, you have confirmed that the operating system and the joystick driver both recognize your joystick(s). You also know of several ways to identify the joystick “name” your joystick reports to the driver and operating system. You will need a written list of what control functions you wish to have assigned to which axis and button and the corresponding numbers.

Make the following table from what you learned from js demo or jstest above (pencil and paper is fine). Here we assume there are 5 axes including 2 axes associated with the hat.

{| class="prettytable"
! align="center" bgcolor="#EFEFEF" | Axis
! align="center" bgcolor="#EFEFEF" | Button
|-
|elevator = 0
|view cycle = 0
|-
|rudder = 1
|all brakes = 1
|-
|aileron = 2
|up trim = 2
|-
|throttle = 3
|down trim = 3
|-
|leftright hat = 4
|extend flaps = 4
|-
|foreaft hat = 5
|retract flaps = 5
|-
|
|decrease RPM = 6
|-
|
|increase RPM = 7
|}

We will assume that our hypothetical joystick supplies the “name” QUICK STICK 3D USB to the system and driver. With all the examples included with FlightGear, the easiest way to get a so far unsupported joystick to be auto detected, is to edit an existing binding xml file. Look at the xml files in the sub-folders of '''/FlightGear/Input/Joysticks/'''. After evaluating several of the xml binding files supplied with FlightGear, we decide to edit the file <tt>[[$FG_ROOT]]/Input/Joysticks/Saitek/Cyborg-Gold-3d-USB.xml</tt>.

This file has all the axes functions above assigned to axes and all the button functions above assigned to buttons. This makes our editing almost trivial.

Before we begin to edit, we need to choose a name for our bindings xml file, create the folder for the QS joysticks, and copy the original xml file into this directory with this name.

<syntaxhighlight lang="bash">
$ cd /usr/local/FlightGear/Input/Joysticks
$ mkdir QS
$ cd QS
$ cp /usr/local/FlightGear/Input/Joysticks/Saitek/
Cyborg-Gold-3d-USB.xml QuickStick.xml
</syntaxhighlight>

Here, we obviously have supposed a Linux/UNIX system with FlightGear being installed under '''/usr/local/FlightGear'''. For a similar procedure under Windows with FlightGear being installed under C:/Program Files/FlightGear, open a command shell and type

<syntaxhighlight lang="dos">
C:
cd /Program Files/FlightGear/Input/Joysticks
mkdir QS
cd QS
copy /Program Files/FlightGear/Input/Joysticks/Saitek/
Cyborg-Gold-3d-USB.xml QuickStick.xml
</syntaxhighlight>

Next, open QuickStick.xml with your favorite editor. Before we forget to change the joystick name, search for the line containing <name>. You should find the line

<syntaxhighlight lang="xml"><name>SAITEK CYBORG 3D USB</name></syntaxhighlight>

and change it to

<syntaxhighlight lang="xml"><name>QUICK STICK 3D USB</name></syntaxhighlight>

This line illustrates a key feature of xml statements. They begin with a <tag> and end with a </tag>.

You can now compare your table to the comment table at the top of your file copy. Note that the comments tell us that the Saitek elevator was assigned to axis 1. Search for the string

<syntaxhighlight lang="xml"><axis n="1"></syntaxhighlight>

and change this to

<syntaxhighlight lang="xml"><axis n="0"></syntaxhighlight>

Next, note that the Saitek rudder was assigned to axis 2. Search for the string

<syntaxhighlight lang="xml"><axis n="2"></syntaxhighlight>

and change this to

<syntaxhighlight lang="xml"><axis n="1"></syntaxhighlight>

Continue comparing your table with the comment table for the Saitek and changing the axis numbers and button numbers accordingly. Since QUICKSTICK USB and the Saitek have the same number of axes but different number of buttons, you must delete the buttons left over. Just remember to double check that you have a closing tag for each opening tag or you will get an error using the file.

Finally, be good to yourself (and others when you submit your new binding file to a FlightGear developers or users archive!), take the time to change the comment table in the edited file to match your changed axis and button assignments. The new comments should match the table you made from the js demo output. Save your edits.

Several users have reported that the numbers of axes and buttons assigned to functions may be different with the same joystick under Windows and Linux. The above procedure should allow one to easily change a binding xml file created for a different operating system for use by their operating system.

You can tell how FlightGear has interpretted your joystick setup by selecting <tt>Help > Joystick Configuration</tt> from the menu.

== Joystick support via .fgfsrc entries ==
Fortunately, there is a tool available now, which takes most of the burden from the average user who, maybe, is not that experienced with XML, the language which these files are written in.

For configuring your joystick using this approach, open a command shell (command prompt under windows, to be found under Start|All programs|Accessories). Change to the directory <tt>[[$FG_ROOT]]/bin</tt> via e.g. (modify to your path)

<syntaxhighlight lang="dos">cd C:/Program Files/FlightGear/bin</syntaxhighlight>

and invoke the tool fgjs via

<syntaxhighlight lang="bash">./fgjs --fg-root=$FG_ROOT</syntaxhighlight>

on a UNIX/Linux machine, or via

<syntaxhighlight lang="dos">fgjs --fg-root=$FG_ROOT</syntaxhighlight>

on a Windows machine. The program will tell you which joysticks, if any, were detected. Now follow the commands given on screen, i.eṁove the axis and press the buttons as required. Be careful, a minor touch already “counts” as a movement. Check the reports on screen. If you feel something went wrong, just re-start the program.

After you are done with all the axis and switches, the directory above will hold a file called fgfsrc.js. If the FlightGear base directory FlightGear does not already contain an options file .fgfsrc (under UNIX)/system.fgfsrc (under Windows) mentioned above, just copy

'''fgfsrc.js''' into '''.fgfsrc''' (UNIX)/'''system.fgfsrc''' (Windows)

and place it into the directory FlightGear base directory FlightGear. In case you already wrote an options file, just open it as well as fgfsrc.js with an editor and copy the entries from fgfsrc.js into .fgfsrc/system.fgfsrc. One hint: The output of fgjs is UNIX formatted. As a result, Windows Editor may not display it the proper way. I suggest getting an editor being able to handle UNIX files as well, for example [https://notepad-plus-plus.org/ Notepad++]. 

The the axis/button assignment of fgjs should, at least, get the axis assignments right, its output may need some tweaking. There may be axes moving the opposite way they should, the dead zones may be too small etc. For instance, I had to change

<syntaxhighlight>
--prop:/input/joysticks/js[1]/axis[1]/binding/factor=-1.0
</syntaxhighlight>

into

<syntaxhighlight>
--prop:/input/joysticks/js[1]/axis[1]/binding/factor=1.0
</syntaxhighlight>

(USB CH Flightsim Yoke under Windows XP). Thus, here is a short introduction into the assignments of joystick properties.

Basically, all axes settings are specified via lines having the following structure:

<syntaxhighlight>
--prop:/input/joysticks/js[n]/axis[m]/binding/command=property-scale
--prop:/input/joysticks/js[n]/axis[m]/binding/property=/controls/steering option
--prop:/input/joysticks/js[n]/axis[m]/binding/dead-band=db
--prop:/input/joysticks/js[n]/axis[m]/binding/offset=os
--prop:/input/joysticks/js[n]/axis[m]/binding/factor=fa
</syntaxhighlight>

where

{| class="prettytable"
! align="center" bgcolor="#EFEFEF" |
! align="center" bgcolor="#EFEFEF" |
|-
|n
|number of device (usually starting with 0)
|-
|m
|number of axis (usually starting with 0)
|-
|steering option
|elevator, aileron, rudder, throttle, mixture, pitch
|-
|dead-band
|range, within which signals are discarded; useful to avoid jittering for minor yoke movements
|-
|offset
|specifies, if device not centered in its neutral position
|-
|factor
|controls sensitivity of that axis; defaults to +1, with a value of -1 reversing the behavior
|}

You should be able to at least get your joystick working along these lines. Concerning all the finer points, for instance, getting the joystick buttons working, John Check has written a very useful README being included in the base package to be found under '''FlightGear/Docs/Readme/Joystick.html'''. In case of any trouble with your input device, it is highly recommended to have a look into this document.

== More about programming joystick XML files ==
=== General tips ===
* When testing a new xml file it is best to start FlightGear via a command window (rather than the GUI interface). Any error messages will then be displayed in the terminal. Error messages will give both a message and a line number, helping you pinpoint any errors.
* Errors can be detected on initial startup or at runtime. Both types of errors will be displayed in the terminal.
* One of the most common errors is including a character that makes XML choke. Such characters include<br>& < --<br>These characters will cause problems even if simply included in comments or within scripts.
* If your scripts contain any of these characters, you have to enclose the scripts in <script><![CDATA[...]]></script>. Alternatively, you can 'escape' the characters, ie "<" becomes "&lt;".
* You can reload your edited joystick file without restarting FlightGear by selecting "Debug" > "Reload Input" from the main simulator window.
* You can find many examples of different ways to program joysticks simply by examining the joystick xml files that are packaged with FlightGear. See the directory FlightGear/data/input/joysticks
* Many advanced functions can be programmed using the Nasal scripting language. These scripts are enclosed in <script></script> tags in the XML file. Helpful:
** A guide to the [[Nasal scripting language]] in FlightGear
** [[Nasal FAQ]]
** [[Howto: Write simple scripts in Nasal]]
* You can explore the internal property tree to see many variables that can be altered using joystick buttons or axes (File/Browse Internal Properties)
* You can test bits of Nasal code and do some other useful things using the Nasal Console (Debug/Nasal Console).
* All Nasal code shares a common namespace, so it's possible to set a variable in one nasal binding, and to read it in another.

=== Useful hints for scripts ===
Some particularly useful ideas for programming scripts within joystick XML files:
* getprop and setprop can be used for getting & setting properties from the internal properties tree:
<syntaxhighlight lang="nasal">
var brake = !getprop("/controls/gear/brake-parking");
setprop("/controls/gear/brake-parking", brake);
</syntaxhighlight>
* You can also make your own values on the property tree:
<syntaxhighlight lang="nasal">
setprop("/input/joysticks/js[0]/myjoystick-modifier", 1);
var mod = getprop("/input/joysticks/js[0]/myjoystick-modifier");
</syntaxhighlight>
* You can print to terminal using the print function. This is very useful for debugging.
<syntaxhighlight lang="nasal">
print("Just", " a ", "test");
</syntaxhighlight>
* You can display info in FlightGear via a popup. This is useful for giving the user feedback about changes that may not be obvious via the panel. It can also be useful for debugging. Example:

<syntaxhighlight lang="nasal">
gui.popupTip("Parking Brake ON");
</syntaxhighlight>

Arguments for gui.popupTip must be strings, so if you want to display other types of variables they should be formatted with something like sprintf:

<syntaxhighlight lang="nasal">
gui.popupTip(sprintf("Elevator trim: %d", 100 * getprop("/controls/flight/elevator-trim")));
</syntaxhighlight>

Or

<syntaxhighlight lang="nasal">
thv = getprop("/controls/engines/engine[0]/mixture");
gui.popupTip("Thrust vector " ~ int(thv * 120 - 20));
</syntaxhighlight>

* You can just start using variables, ie,
<syntaxhighlight lang="nasal">
x = 10;
</syntaxhighlight>

But [http://wiki.flightgear.org/index.php/Nasal_scripting_language#Variables for various reasons] it is generally better to declare variables with the "var" statement:
<syntaxhighlight lang="nasal">
var x = 10;
</syntaxhighlight>

Note that "var" creates variables that are local in scope, but since all bindings for a joystick share the same scope, it will be seen across each script in the joystick file.

* You can include a section of script that runs on startup to initialize variables, create functions, etc. Example:
<syntaxhighlight lang="xml">
<PropertyList>
<name type="string">My joystick name</name>
<name type="string">My joystick name #2</name>
<nasal>
<script>
#initialize variables
f1 = f2 = 0;
left_brake = right_brake = 0;
# create a function to be used with all buttons
getmod = func { getprop("/input/joysticks/js[0]/t-flight-hotas-x-modifier" ) }
</script>
</nasal>
</syntaxhighlight>

* Sample code for firing weapons with the joystick is found on the [[Gun Effects]] page.

== Multiple mice on Linux ==

On Linux, it is possible to make specific mice control specific Flightgear properties instead of the default flight controls.

You will need to know the Linux name and ID for the mouse. This can be done by running the command <code>xinput --list</code> which lists all connected input devices. (Extra information about a specific device can be found with <code>xinput --list-props <id></code> or <code>xinput --list-props <name></code>.)

Then create a file in <code>fgdata/Input/Event/</code>. The leafname doesn't matter, but for example it could be called <code>fgdata/Input/Event/MouseExtra.xml</code>. The contents of this file determine the properties that the mouse will control. For example:

<pre>
<PropertyList>
<name>Logitech Logitech USB Optical Mouse</name>
<debug-events type="bool">false</debug-events>
<grab type="bool">true</grab>
<event>
<desc>Y-Axis</desc>
<name>rel-y-translate</name>
<binding>
<command>property-adjust</command>
<property>/controls/flight/elevator</property>
<factor type="double">-.002</factor>
<min type="double">-1.0</min>
<max type="double">1.0</max>
<wrap type="bool">false</wrap>
</binding>
</event>
<event>
<desc>X-Axis</desc>
<name>rel-x-translate</name>
<binding>
<command>property-adjust</command>
<property>/controls/flight/aileron</property>
<factor type="double">.002</factor>
<min type="double">-1.0</min>
<max type="double">1.0</max>
<wrap type="bool">false</wrap>
</binding>
</event>
</PropertyList>
</pre>

(Change <code><name>Logitech Logitech USB Optical Mouse</name></code> to match your mouse.)

It can be useful to tell X to ignore the mouse so that it doesn't affect the main X pointer. This can be done with: <code>xinput --set-prop <id> "Device Enabled" 0</code>. Normal X handling of the mouse can be restored with <code>xinput --set-prop <id> "Device Enabled" 1</code>. (One can also use the name of the mouse instead of <code><id></code>.)

On Devuan Linux, one can use a udev rule to ensure that the mouse can be read and written by flightgear (usually they are only accessible to root):
* Create a file <code>/etc/udev/rules.d/90-fgmouseextra.rules</code> containing a single line <code>KERNEL=="hidraw*", SUBSYSTEM=="hidraw", MODE="0666"</code>.
* Reboot or run <code>udevadm control --reload-rules</code>.
[Note that i know almost nothing about udev, and it's entirely possible that this represents a huge security flaw, so use with caution.]

[The information above is based on the forum thread https://forum.flightgear.org/viewtopic.php?t=32750 and Torsten Dreyer's original email https://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg23171.html.]

== Related content ==
=== Wiki articles ===
* [[Bindings]]
* [[Force feedback]]
* [[Head tracking]]
* [[Joystick xml library]]
* [[Troubleshooting input devices]]
* [[Writing Joystick Code: Part 1]]
* [[Writing Joystick Code: Part 2]]
* [[Writing Joystick Code: Part 3]]
* [[Writing Joystick Code: Part 4]]

=== Forum topics ===
* {{forum link|f=24|title=Hardware}}
* {{forum link|t=43132|title=<nowiki>[</nowiki>HOWTO<nowiki>]</nowiki> Use more than 32 buttons on Windows via HID}}

== External links ==
* [http://www.flightgear.org/Docs/getstart/getstartch3.html#x8-360003.6 The FlightGear Manual]
* [http://sourceforge.net/projects/hapticsforfg/ Force Feedback]

[[Category:Hardware]]
[[Category:Joysticks and Yokes]]

[[de:Joystick]]
[[es:Joystick]]

Aircraft properties reference

2025-03-03T09:31:23Z

Johan G: /* The serviceable and operable properties */ New section, based on <https://forum.flightgear.org/viewtopic.php?p=198298#p198298> and <flightgear/src/Instrumentation/AbstractInstrument.cxx>

{{PropertyTree}}

This is a generic '''aircraft properties reference'''. There are many properties that are very common in aircraft, and many of them are present even in a very simple aircraft. However, a complete description that matches all the properties is very unlikely to be written, as aircraft can be very different from each other.

{{TOC limit|2}}

== What are properties? ==
{{main article|Property tree}}
=== The property tree ===
Most parts of FlightGear communicate with each other through key-value pair properties in the [[property tree]]. The properties represent both the input from the pilot, the values determining the position and velocity of the aircraft, the values used for animating the aircraft, and pretty much anything else.

While many properties will be common between most aircraft, many properties will also be different between aircraft. This becomes obvious if one consider the many different configurations (aircraft/helicopter/car, control surface and landing gear layout, number and locations of engines, etc) and propulsions systems (types of engines, types of fuels etc.) an aircraft can have. There are also different flight dynamic models (FDMs) that have different needs. In addition many properties will by necessity be aircraft specific, though developers should make a conscious effort to have properties map to more common ones if that is possible.

=== Where are the properties defined? ===
There are a couple ways that the properties are set, but a fair amount of them just "appear" without being documented anywhere. There are several places to look for properties. One is in the aircraft files, starting from the aircraft specific [[aircraft-set.xml]] file, another is the [[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

== The serviceable and operable properties ==
Many systems, instruments, etc. have either or both of the properties <code>serviceable</code> and <code>operable</code>.

The <code>serviceable</code> property is <code>true</code> when something is functional and have not failed. Setting it to false would make it fail.

The <code>operable</code> property is set to <code>true</code> when something both is serviceable and have power. Unfortunately it is a tied property and you can not assign a [[Nasal library#setlistener()|Nasal listener]] to it.

== Annunciators ==
The /instrumentation/annunciators section shall provide a central place for

* aircrafts to write annunciator status data
* 3D aircraft models and external devices (like joysticks, yokes, throttle quadrants or custom made cockpit hardware) to read such data and drive status lights etc.

Some of the props are automatically calculated by property rules in <code>$FGDATA/Aircraft/Generic/generic-annunciators.xml</code> (available since FG 2024.1) other properties have to be calculated by the actual aircraft.

The aircraft.nas module provides aircraft.light which allows easy implementation of blinking lights. Such lights have a bool property 'state' which tells if the light is on or off.<pre>
/instrumentation/annunciators/doors
/instrumentation/annunciators/master-caution/state # aircraft.light
/instrumentation/annunciators/master-warning/state # aircraft.light

/instrumentation/annunciators/autoflight/ap/enabled
/instrumentation/annunciators/autoflight/ap/mode/alt
/instrumentation/annunciators/autoflight/ap/mode/apr
/instrumentation/annunciators/autoflight/ap/mode/hdg
/instrumentation/annunciators/autoflight/ap/mode/ias
/instrumentation/annunciators/autoflight/ap/mode/nav
/instrumentation/annunciators/autoflight/ap/mode/rev
/instrumentation/annunciators/autoflight/ap/mode/vs
/instrumentation/annunciators/autoflight/flightdirector/enabled

/instrumentation/annunciators/engines/
/instrumentation/annunciators/engines/apu/enabled
/instrumentation/annunciators/engines/apu/fire
# summary props, 'sum' of all engines
/instrumentation/annunciators/engines/fire
/instrumentation/annunciators/engines/oil-pressure-low
/instrumentation/annunciators/engines/starter

# for <gear-name> in {nose, left, right}
/instrumentation/annunciators/gear/<gear-name>/down
/instrumentation/annunciators/gear/<gear-name>/in-transition
/instrumentation/annunciators/gear/<gear-name>/unsafe
/instrumentation/annunciators/gear/<gear-name>/up
# gear summary
/instrumentation/annunciators/gear/down
/instrumentation/annunciators/gear/in-transition
/instrumentation/annunciators/gear/unsafe
/instrumentation/annunciators/gear/up
/instrumentation/annunciators/gear/parking-brake

/instrumentation/annunciators/systems/anti-ice/enabled
/instrumentation/annunciators/systems/fuel/aux-pump
/instrumentation/annunciators/systems/fuel/pressure-low
/instrumentation/annunciators/systems/fuel/system[]/pressure-low
/instrumentation/annunciators/systems/hyd/pressure-low
/instrumentation/annunciators/systems/hyd/system[]/pressure-low
/instrumentation/annunciators/systems/vacuum

</pre>

== Consumables ==
:''See also [[#Fuel]]
<pre>
/consumables/fuel/tank[%d]/level-lb
/consumables/fuel/tank[%d]/level-lbs
/consumables/fuel/tank[%d]/level-gal_us
/consumables/fuel/tank[%d]/capacity-gal_us
/consumables/fuel/tank[%d]/density-ppg
/consumables/fuel/total-fuel-lbs
/consumables/fuel/total-gal_us
</pre>

== Controls ==
These properties are meant to represent the various cockpit controls (levers, switches, etc.) Consider these the pilot input.

=== Recommended usage ===

* Animation of control elements (levers, switches, etc) themself in the 3D model of the cockpit
* As input to aircraft system simulation, e.g. hydraulics or electrical systems

Avoid refering to control props directly for animating parts of the 3D model if there is an aircraft system (electric, hydraulic, ...) involved.

Better use XML property rules (e.g. logic or filter) that calculate the component state from /controls/foo as well as "power available", "component is serviceable" etc.

=== Anti-ice ===
These properties control the various anti-ice properties that may be present in an aircraft.

<pre>
/controls/anti-ice/wing-heat
/controls/anti-ice/pitot-heat
/controls/anti-ice/wiper
/controls/anti-ice/window-heat
/controls/anti-ice/engine[%d]/carb-heat
/controls/anti-ice/engine[%d]/inlet-heat
</pre>
TODO - section notes

=== APU ===
These properties control any auxiliary power unit, in essence a small turbine engine driving generators, hydraulic pumps etc. before and after the aircraft's engines are up an running.

<pre>
/controls/APU/off-start-run
/controls/APU/fire-switch
</pre>
TODO - section notes

=== Armament ===
TODO - explain of section
<pre>
/controls/armament/master-arm
/controls/armament/station-select
/controls/armament/release-all
/controls/armament/station[%d]/stick-size
/controls/armament/station[%d]/release-stick
/controls/armament/station[%d]/release-all
/controls/armament/station[%d]/jettison-all
</pre>
TODO - section notes

=== Autoflight ===
These properties control the autopilot on certain airplanes. For [[IT Autoflight]] based systems, see [[IT Autoflight#Interface_Reference|here]].

TODO - explain of section
<pre>
/controls/autoflight/autopilot[%d]/engage
/controls/autoflight/autothrottle-arm
/controls/autoflight/autothrottle-engage
/controls/autoflight/heading-select
/controls/autoflight/altitude-select
/controls/autoflight/bank-angle-select
/controls/autoflight/vertical-speed-select
/controls/autoflight/speed-select
/controls/autoflight/mach-select
/controls/autoflight/vertical-mode
/controls/autoflight/lateral-mode
</pre>
TODO - section notes

=== Electric ===
TODO - explain of section
<pre>
/controls/electric/battery-switch
/controls/electric/external-power
/controls/electric/APU-generator
/controls/electric/engine[%d]/generator
/controls/electric/engine[%d]/bus-tie
</pre>
TODO - section notes

=== Engines ===
Engines are numbered engine[0] for a single engine to engine[0] to engine[3] for a 747 for example. (The model allows for up to 12 engines rumour has it ;-)

<pre>
/controls/engines/throttle_idle
/controls/engines/engine[%d]/throttle
/controls/engines/engine[%d]/starter
/controls/engines/engine[%d]/fuel-pump
/controls/engines/engine[%d]/fire-switch
/controls/engines/engine[%d]/fire-bottle-discharge
/controls/engines/engine[%d]/cutoff
/controls/engines/engine[%d]/mixture
/controls/engines/engine[%d]/propeller-pitch
/controls/engines/engine[%d]/magnetos
/controls/engines/engine[%d]/boost
/controls/engines/engine[%d]/WEP
/controls/engines/engine[%d]/cowl-flaps-norm
/controls/engines/engine[%d]/feather
/controls/engines/engine[%d]/ignition
/controls/engines/engine[%d]/augmentation
/controls/engines/engine[%d]/afterburner
/controls/engines/engine[%d]/reverser
/controls/engines/engine[%d]/water-injection
/controls/engines/engine[%d]/condition
</pre>
TODO - section notes

=== Flight controls ===
These properties control the flight controls surfaces, though often through a mechanical, analog or digital flight control system (FCS) that may or may not be modeled.

<pre>
/controls/flight/aileron
/controls/flight/aileron-trim
/controls/flight/elevator
/controls/flight/elevator-trim
/controls/flight/rudder
/controls/flight/rudder-trim
/controls/flight/flaps
/controls/flight/slats
/controls/flight/BLC // Boundary Layer Control
/controls/flight/spoilers
/controls/flight/speedbrake
/controls/flight/wing-sweep
/controls/flight/wing-fold
/controls/flight/drag-chute
</pre>

The positions of the controls are usually put in <code>/surface-positions/</code> at the discretion of the aircraft designer. These usually drive the animations of the control surfaces. They are either normalized (like <code>/surface-positions/elevator-pos-norm</code>) or in degrees, and sometimes the aileron is split left/right.

=== Fuel ===
TODO - explain of section
<pre>
/controls/fuel/dump-valve
/controls/fuel/tank[%d]/fuel_selector
/controls/fuel/tank[%d]/to_engine
/controls/fuel/tank[%d]/to_tank
/controls/fuel/tank[%d]/boost-pump[%d]
</pre>
TODO - section notes

=== Gear ===
TODO - explain of section
<pre>
/controls/gear/brake-left
/controls/gear/brake-right
/controls/gear/brake-parking
/controls/gear/steering // Used if rudder is not sufficient for control of steering
/controls/gear/gear-down
/controls/gear/antiskid // Deprecated?
/controls/gear/tailhook
/controls/gear/tailwheel-lock
/controls/gear/wheel[%d]/alternate-extension
</pre>
TODO - section notes

=== Hydraulics ===
TODO - explain of section
<pre>
/controls/hydraulic/system[%d]/engine-pump
/controls/hydraulic/system[%d]/electric-pump
</pre>
TODO - section notes

=== Lights ===
TODO - explain of section
<pre>
/controls/lighting/landing-lights
/controls/lighting/turn-off-lights
/controls/lighting/formation-lights
/controls/lighting/taxi-light
/controls/lighting/logo-lights
/controls/lighting/nav-lights
/controls/lighting/beacon
/controls/lighting/strobe
/controls/lighting/panel-norm
/controls/lighting/instruments-norm
/controls/lighting/dome-norm
</pre>
TODO - section notes

=== Pneumatic ===
TODO - explain of section
<pre>
/controls/pneumatic/APU-bleed
/controls/pneumatic/engine[%d]/bleed
</pre>
TODO - section notes

=== Pressurization ===
TODO - explain of section
<pre>
/controls/pressurization/mode
/controls/pressurization/dump
/controls/pressurization/outflow-valve
/controls/pressurization/pack[%d]/pack-on
</pre>
TODO - section notes

=== Seat ===
TODO - explain of section
<pre>
/controls/seat/vertical-adjust
/controls/seat/fore-aft-adjust
/controls/seat/cmd_selector_valve
/controls/seat/eject[%d]/initiate
/controls/seat/eject[%d]/status
</pre>
TODO - section notes

== Engines ==
Status of engines. See also: /controls/engines/
=== Common ===
<pre>
/engines/engine[%d]/fuel-flow-gph
/engines/engine[%d]/fuel-flow_pph
/engines/engine[%d]/thrust_lb
/engines/engine[%d]/running
/engines/engine[%d]/starter
/engines/engine[%d]/cranking
/engines/engine[%d]/fire
</pre>

=== Turbine ===
<pre>
/engines/engine[%d]/n1
/engines/engine[%d]/n2
/engines/engine[%d]/epr
/engines/engine[%d]/augmentation
/engines/engine[%d]/water-injection
/engines/engine[%d]/ignition
/engines/engine[%d]/nozzle-pos-norm
/engines/engine[%d]/inlet-pos-norm
/engines/engine[%d]/reversed
/engines/engine[%d]/cutoff
</pre>

=== Piston ===
<pre>
/engines/engine[%d]/mp-osi
/engines/engine[%d]/egt-degf
/engines/engine[%d]/oil-temperature-degf
/engines/engine[%d]/oil-pressure-psi
/engines/engine[%d]/cht-degf
/engines/engine[%d]/rpm
</pre>

=== Propeller ===
<pre>
/engines/engine[%d]/rpm
/engines/engine[%d]/pitch
/engines/engine[%d]/torque
</pre>
TODO - section notes

== Flight Dynamics Model ==
=== Position ===
This will return the current position of the aircraft within FlightGear. This is also the stuff that is transmitted in [[Howto:Multiplayer|multiplayer]].

<pre>
/position/
/position/altitiude-ft ()
/position/altitude-agl-ft (22.46983965)
/position/altitude-ft (28.24368289)
/position/ground-elev-ft (-0.43513529)
/position/ground-elev-m (-0.1326292364)
/position/latitude-deg (37.61371436)
/position/latitude-string (37*36 49.4N)
/position/longitude-deg (-122.3576508)
/position/longitude-string (-122*21 27.5W)
/position/sea-level-radius-ft (20899648.76)
</pre>

=== Orientation ===
TODO - explain of section
<pre>
/orientation/roll-deg
/orientation/pitch-deg
/orientation/heading-deg

/orientation/roll-rate-degps
/orientation/pitch-rate-degps
/orientation/yaw-rate-degps

/orientation/side-slip-rad
/orientation/side-slip-deg
/orientation/alpha-deg
</pre>
TODO - section notes

=== Velocities ===
TODO - explain of section
<pre>
/velocities/airspeed-kt
/velocities/mach
/velocities/speed-north-fps
/velocities/speed-east-fps
/velocities/speed-down-fps

/velocities/uBody-fps
/velocities/vBody-fps
/velocities/wBody-fps

/velocities/vertical-speed-fps
/velocities/glideslope
</pre>
TODO - section notes

=== Acceleration ===
TODO - explain of section
<pre>
/accelerations/nlf

/accelerations/ned/north-accel-fps_sec
/accelerations/ned/east-accel-fps_sec
/accelerations/ned/down-accel-fps_sec

/accelerations/pilot/x-accel-fps_sec
/accelerations/pilot/y-accel-fps_sec
/accelerations/pilot/z-accel-fps_sec
</pre>
TODO - section notes

== Gear ==
<pre>
/gear/serviceable
/gear/gear[%d]/cast-angle-deg // The angle of the wheel where 0 is pointing straight forward
/gear/gear[%d]/compression-m
/gear/gear[%d]/compression-norm
/gear/gear[%d]/ground-friction-factor
/gear/gear[%d]/ground-is-solid
/gear/gear[%d]/has-brake
/gear/gear[%d]/rollspeed-ms // Speed of the wheel's rotation in meters per second
/gear/gear[%d]/wow // Weight-on-wheel
/gear/gear[%d]/xoffset-in
/gear/gear[%d]/yoffset-in
/gear/gear[%d]/zoffset-in
</pre>

== Instrumentation ==
<pre>
/instrumentation/adf[%d]/
/instrumentation/airspeed-indicator/
/instrumentation/altimeter/
/instrumentation/annunciator/
/instrumentation/attitude-indicator/
/instrumentation/clock/
/instrumentation/comm[%d]/
/instrumentation/dme/
/instrumentation/efis/
/instrumentation/encoder/
/instrumentation/flightdirector/
/instrumentation/gps/
/instrumentation/gps-annunciator/
/instrumentation/heading-indicator/
/instrumentation/heading-indicator-fg/
/instrumentation/magnetic-compass/
/instrumentation/marker-beacon/
/instrumentation/nav[%d]/
/instrumentation/radar/
/instrumentation/slip-skid-ball/
/instrumentation/tacan[%d]/
/instrumentation/transponder/
/instrumentation/turn-indicator/
/instrumentation/vertical-speed-indicator/
/instrumentation/wxradar/
</pre>

=== Instrumentation ADF ===
<pre>
/instrumentation/adf[%d]/adf-btn
/instrumentation/adf[%d]/bro-btn
/instrumentation/adf[%d]/display-mode
/instrumentation/adf[%d]/enroute-timer/running
/instrumentation/adf[%d]/enroute-timer/start-time
/instrumentation/adf[%d]/enroute-timer/time
/instrumentation/adf[%d]/error-deg
/instrumentation/adf[%d]/flight-timer/running
/instrumentation/adf[%d]/flight-timer/start-time
/instrumentation/adf[%d]/flight-timer/time
/instrumentation/adf[%d]/flt-btn
/instrumentation/adf[%d]/frequencies/dial-1-khz
/instrumentation/adf[%d]/frequencies/dial-100-khz
/instrumentation/adf[%d]/frequencies/selected-khz
/instrumentation/adf[%d]/frequencies/standby-khz
/instrumentation/adf[%d]/frq-btn
/instrumentation/adf[%d]/ident
/instrumentation/adf[[%d]/ident-audible
/instrumentation/adf[%d]/in-range
/instrumentation/adf[%d]/indicated-bearing-deg
/instrumentation/adf[%d]/mode
/instrumentation/adf[%d]/model
/instrumentation/adf[%d]/operable
/instrumentation/adf[%d]/power-btn
/instrumentation/adf[%d]/right-display
/instrumentation/adf[%d]/rotation-deg
/instrumentation/adf[%d]/serviceable
/instrumentation/adf[%d]/set-btn
/instrumentation/adf[%d]/volume
/instrumentation/adf[%d]/volume-norm
</pre>

=== Instrumentation comm radio ===
See [[Aircraft_properties_reference/Instrumentation/COMM]]

=== Instrumentation NAV radio ===

<pre>
/instrumentation/nav[%d]/audio-btn
/instrumentation/nav[%d]/back-course-btn
/instrumentation/nav[%d]/cdi/serviceable
/instrumentation/nav[%d]/crosstrack-error-m
/instrumentation/nav[%d]/crosstrack-heading-error-deg
/instrumentation/nav[%d]/data-is-valid
/instrumentation/nav[%d]/dme-in-range
/instrumentation/nav[%d]/filtered-cdiNAV0-deflection
/instrumentation/nav[%d]/filtered-gsNAV0-deflection
/instrumentation/nav[%d]/frequencies/dial-khz
/instrumentation/nav[%d]/frequencies/dial-mhz
/instrumentation/nav[%d]/frequencies/is-localizer-frequency
/instrumentation/nav[%d]/frequencies/selected-mhz
/instrumentation/nav[%d]/frequencies/selected-mhz-fmt
/instrumentation/nav[%d]/frequencies/standby-mhz
/instrumentation/nav[%d]/frequencies/standby-mhz-fmt
/instrumentation/nav[%d]/from-flag
/instrumentation/nav[%d]/frq-swap-btn
/instrumentation/nav[%d]/gs/serviceable
/instrumentation/nav[%d]/gs-direct-deg
/instrumentation/nav[%d]/gs-distance
/instrumentation/nav[%d]/gs-in-range
/instrumentation/nav[%d]/gs-needle-deflection
/instrumentation/nav[%d]/gs-needle-deflection-deg
/instrumentation/nav[%d]/gs-needle-deflection-norm
/instrumentation/nav[%d]/gs-rate-of-climb
/instrumentation/nav[%d]/gs-rate-of-climb-fpm
/instrumentation/nav[%d]/has-gs
/instrumentation/nav[%d]/heading-deg
/instrumentation/nav[%d]/heading-needle-deflection
/instrumentation/nav[%d]/heading-needle-deflection-norm
/instrumentation/nav[%d]/ident
/instrumentation/nav[%d]/ident-audible
/instrumentation/nav[%d]/in-range
/instrumentation/nav[%d]/nav-distance
/instrumentation/nav[%d]/nav-id
/instrumentation/nav[%d]/nav-id_asc1
/instrumentation/nav[%d]/nav-id_asc2
/instrumentation/nav[%d]/nav-id_asc3
/instrumentation/nav[%d]/nav-id_asc4
/instrumentation/nav[%d]/nav-loc
/instrumentation/nav[%d]/operable
/instrumentation/nav[%d]/power-btn
/instrumentation/nav[%d]/radials/actual-deg
/instrumentation/nav[%d]/radials/reciprocal-radial-deg
/instrumentation/nav[%d]/radials/selected-deg
/instrumentation/nav[%d]/radials/target-auto-hdg-deg
/instrumentation/nav[%d]/radials/arget-radial-deg
/instrumentation/nav[%d]/serviceable
/instrumentation/nav[%d]/signal-quality-norm
/instrumentation/nav[%d]/slaved-to-gps
/instrumentation/nav[%d]/time-to-intercept-sec
/instrumentation/nav[%d]/to-flag
/instrumentation/nav[%d]/to-from/serviceable
/instrumentation/nav[%d]/volume
</pre>

=== Instrumentation Tacan ===

<pre>
/instrumentation/tacan[%d]/display/channel
/instrumentation/tacan[%d]/display/x-shift
/instrumentation/tacan[%d]/display/y-shift
/instrumentation/tacan[%d]/frequencies/selected-channel
/instrumentation/tacan[%d]/frequencies/selected-channel[1]
/instrumentation/tacan[%d]/frequencies/selected-channel[2]
/instrumentation/tacan[%d]/frequencies/selected-channel[3]
/instrumentation/tacan[%d]/frequencies/selected-channel[4]
/instrumentation/tacan[%d]/frequencies/selected-mhz
/instrumentation/tacan[%d]/ident
/instrumentation/tacan[%d]/in-range
/instrumentation/tacan[%d]/indicated-bearing-true-deg
/instrumentation/tacan[%d]/indicated-distance-nm
/instrumentation/tacan[%d]/indicated-ground-speed-kt
/instrumentation/tacan[%d]/indicated-time-min
/instrumentation/tacan[%d]/name
/instrumentation/tacan[%d]/serviceable
/instrumentation/tacan[%d]/switch-position
</pre>

== Rotors (YASim only) ==
<pre>
/rotors/gear/torque-sound-filtered // Unused?
/rotors/gear/total-torque
/rotors/{name}/balance
/rotors/{name}/blade[%d]/flap-deg
/rotors/{name}/blade[%d]/incidence-deg
/rotors/{name}/blade[%d]/position-deg // Position relative to model
/rotors/{name}/bladesvisible // Used for animations
/rotors/{name}/cone%d-deg //e.g. cone-deg or cone2-deg
/rotors/{name}/roll-deg
/rotors/{name}/rpm
/rotors/{name}/stall
/rotors/{name}/stall-filtered
/rotors/{name}/tilt
/rotors/{name}/torque
/rotors/{name}/yaw-deg
</pre>

For how to animate rotors using these properties, see [[Howto:Animate helicopters]].

== Related content ==
=== Wiki articles ===
* [[Aircraft-set.xml]]
* [[Multiplayer protocol]]
* [[Property browser]]
* [[PropertyList XML files]]
* [[Property tree]]

=== Readme files ===
* {{readme file|properties}}

=== Source code ===
==== Consumables ====
* {{flightgear file|src/FDM/TankProperties.hxx}}
* {{flightgear file|src/FDM/TankProperties.cxx}}

==== Controls ====
* {{flightgear file|src/Aircraft/controls.hxx}}
* {{flightgear file|src/Aircraft/controls.cxx}}

==== Flight Dynamics Model ====
* {{flightgear file|src/FDM/flightProperties.hxx}}
* {{flightgear file|src/FDM/flightProperties.cxx}}

==== Instrumentation ====
* {{flightgear file|src/Instrumentation}}

[[Category:Property Tree]]
[[Category:Aircraft enhancement]]

Blacklist add-on

2025-02-26T11:35:40Z

Johan G: Clarifications about multiplayer damage.

{{warning|Aircraft using the Emesary multiplayer damage system '''will take damage''' from ignored pilots when both have multiplayer damage enabled..}}
{{infobox addon
| name = Blacklist
| started = 13 November 2024
| desc =
| contributors = {{usr|Johan G}}, pinto, Warty
| status = mature
| coderepo = https://gitlab.com/JohanG/blacklist
}}

The '''Blacklist''' add-on will every few seconds automatically ignore pilots that are listed either in a text file with callsigns or a text file with multiplayer models.

This can be useful for example if there often are trolls using the same callsigns, or if there are heavy models, or models breaking things.

== Installation ==
For installation instructions, see [[Addon#Installing and using an addon]].

== Blacklist files ==
{{note|The files must end with an empty line. Otherwise the last callsign or model in the list will not be ignored.}}

The files with callsigns and models to ignore are:
* <code>[[$FG_HOME]]/Export/Addons/org.flightgear.addons.blacklist/callsign-blacklist.txt</code>
* <code>[[$FG_HOME]]/Export/Addons/org.flightgear.addons.blacklist/model-blacklist.txt</code>

The callsigns and multiplayer models should be as listed in the [[Pilot List]] dialog.

When starting FlightGear with the add-on installed the files will be created it they do not exist.

If you edit them during a FlightGear session you can reload them using ''Main Menu'' > ''Blacklist'' > ''Reload or create blacklists''.

== Known issues ==
=== Taking multiplayer damage ===
{{tip| Do not feed the trolls. Ignore the trolls.}}

The Emesary multiplayer damage system used in some aircraft do not take into account if an aircraft is ignored or not. If both of you have multiplayer damage enabled your aircraft will take damage, even though you can not see the other aircraft.

There are basically two ways around this:
* Do not fly with multiplayer damage always on, or at least not if you are not interested in fighting trolls.
* Change to a private multiplayer server (and do not communicate the change over multiplayer chat or some other way the troll could see or hear).

== History ==
The blacklist add-on is based on a Nasal module by {{usr|PINTO|pinto}}, which in turn was based on a snippet by {{usr|Warty}} in a FlightGear forum topic, most likely {{forum link|text=this one|p=274977}}.

Pinto had sometimes talked about making an add-on of the Nasal module, but after a couple of years I did this one.

== Related content ==
=== Forum topics ===
* {{forum link|text=Blacklist add-on|t=43066}}
* {{forum link|text=Trolls|p=274977}} Warty's snippet.

[[Category:Multiplayer]]

Blacklist add-on

2025-02-26T11:23:48Z

Johan G: +links: Forum topic and Warty's snippet; +cat: Multiplayer

{{warning|Aircraft using the Emesary multiplayer damage system '''will take damage''' from ignored pilots.}}
{{infobox addon
| name = Blacklist
| started = 13 November 2024
| desc =
| contributors = {{usr|Johan G}}, pinto, Warty
| status = mature
| coderepo = https://gitlab.com/JohanG/blacklist
}}

The '''Blacklist''' add-on will every few seconds automatically ignore pilots that are listed either in a text file with callsigns or a text file with multiplayer models.

This can be useful for example if there often are trolls using the same callsigns, or if there are heavy models, or models breaking things.

== Installation ==
For installation instructions, see [[Addon#Installing and using an addon]].

== Blacklist files ==
{{note|The files must end with an empty line. Otherwise the last callsign or model in the list will not be ignored.}}

The files with callsigns and models to ignore are:
* <code>[[$FG_HOME]]/Export/Addons/org.flightgear.addons.blacklist/callsign-blacklist.txt</code>
* <code>[[$FG_HOME]]/Export/Addons/org.flightgear.addons.blacklist/model-blacklist.txt</code>

The callsigns and multiplayer models should be as listed in the [[Pilot List]] dialog.

When starting FlightGear with the add-on installed the files will be created it they do not exist.

If you edit them during a FlightGear session you can reload them using ''Main Menu'' > ''Blacklist'' > ''Reload or create blacklists''.

== Known issues ==
=== Taking multiplayer damage ===
{{tip| Do not feed the trolls. Ignore the trolls.}}

The Emesary multiplayer damage system used in some aircraft do not take into account if an aircraft is ignored or not. My understanding is that this is an anti-cheat feature.

There are basically two ways around this:
* Do not fly with multiplayer damage always on, or at least not if you are not interested in fighting trolls.
* Change to a private multiplayer server (and do not communicate the change over multiplayer chat or some other way the troll could see or hear).

== History ==
The blacklist add-on is based on a Nasal module by {{usr|PINTO|pinto}}, which in turn was based on a snippet by {{usr|Warty}} in a FlightGear forum topic, most likely {{forum link|text=this one|p=274977}}.

Pinto had sometimes talked about making an add-on of the Nasal module, but after a couple of years I did this one.

== Related content ==
=== Forum topics ===
* {{forum link|text=Blacklist add-on|t=43066}}
* {{forum link|text=Trolls|p=274977}} Warty's snippet.

[[Category:Multiplayer]]

Blacklist add-on

2025-02-26T10:58:42Z

Johan G: /* History */ + Links to the user pages of the earlier authors

Blacklist add-on

2025-02-26T10:47:36Z

Johan G: +- The blacklists have been renamed in the latest commit

{{warning|Aircraft using the Emesary multiplayer damage system '''will take damage''' from ignored pilots.}}
{{infobox addon
| name = Blacklist
| started = 13 November 2024
| desc =
| contributors = {{usr|Johan G}}, pinto, Warty
| status = mature
| coderepo = https://gitlab.com/JohanG/blacklist
}}

The '''Blacklist''' add-on will every few seconds automatically ignore pilots that are listed either in a text file with callsigns or a text file with multiplayer models.

This can be useful for example if there often are trolls using the same callsigns, or if there are heavy models, or models breaking things.

== Installation ==
For installation instructions, see [[Addon#Installing and using an addon]].

== Blacklist files ==
{{note|The files must end with an empty line. Otherwise the last callsign or model in the list will not be ignored.}}

The files with callsigns and models to ignore are:
* <code>[[$FG_HOME]]/Export/Addons/org.flightgear.addons.blacklist/callsign-blacklist.txt</code>
* <code>[[$FG_HOME]]/Export/Addons/org.flightgear.addons.blacklist/model-blacklist.txt</code>

The callsigns and multiplayer models should be as listed in the [[Pilot List]] dialog.

When starting FlightGear with the add-on installed the files will be created it they do not exist.

If you edit them during a FlightGear session you can reload them using ''Main Menu'' > ''Blacklist'' > ''Reload or create blacklists''.

== Known issues ==
=== Taking multiplayer damage ===
{{tip| Do not feed the trolls. Ignore the trolls.}}

The Emesary multiplayer damage system used in some aircraft do not take into account if an aircraft is ignored or not. My understanding is that this is an anti-cheat feature.

There are basically two ways around this:
* Do not fly with multiplayer damage always on, or at least not if you are not interested in fighting trolls.
* Change to a private multiplayer server (and do not communicate the change over multiplayer chat or some other way the troll could see or hear).

== History ==
The blacklist add-on is based on a Nasal module by pinto, which in turn was based on a snippet by Warty in a FlightGear forum topic, most likely {{forum link|text=this one|p=274977}}.

Pinto had sometimes talked about making an add-on of the Nasal module, but after a couple of years I did this one.

Blacklist add-on

2025-02-26T10:01:36Z

Johan G: /* Known issues */ New section

{{warning|Aircraft using the Emesary multiplayer damage system '''will take damage''' from ignored pilots.}}
{{infobox addon
| name = Blacklist
| started = 13 November 2024
| desc =
| contributors = {{usr|Johan G}}, pinto, Warty
| status = mature
| coderepo = https://gitlab.com/JohanG/blacklist
}}

The '''Blacklist''' add-on will every few seconds automatically ignore pilots that are listed either in a text file with callsigns or a text file with multiplayer models.

This can be useful for example if there often are trolls using the same callsigns, or if there are heavy models, or models breaking things.

== Installation ==
For installation instructions, see [[Addon#Installing and using an addon]].

== Files ==
{{note|The files must end with an empty line. Otherwise the last callsign or model in the list will not be ignored.}}

The files with callsigns and models to ignore are:
* <code>[[$FG_HOME]]/Export/Addons/org.flightgear.addons.blacklist/callsigns-to-ignore.txt</code>
* <code>[[$FG_HOME]]/Export/Addons/org.flightgear.addons.blacklist/models-to-ignore.txt</code>

The callsigns and multiplayer models should be as listed in the [[Pilot List]] dialog.

When starting FlightGear with the add-on installed the files will be created it they do not exist.

If you edit them during a FlightGear session you can reload them using ''Main Menu'' > ''Blacklist'' > ''Reload or create blacklists''.

== Known issues ==
=== Taking multiplayer damage ===
{{tip| Do not feed the trolls. Ignore the trolls.}}

The Emesary multiplayer damage system used in some aircraft do not take into account if an aircraft is ignored or not. My understanding is that this is an anti-cheat feature.

There are basically two ways around this:
* Do not fly with multiplayer damage always on, or at least not if you are not interested in fighting trolls.
* Change to a private multiplayer server (and do not communicate the change over multiplayer chat or some other way the troll could see or hear).

== History ==
The blacklist add-on is based on a Nasal module by pinto, which in turn was based on a snippet by Warty in a FlightGear forum topic, most likely {{forum link|text=this one|p=274977}}.

Pinto had sometimes talked about making an add-on of the Nasal module, but after a couple of years I did this one.

Addon

2025-02-26T09:44:27Z

Johan G: /* List of Addons */ + Blacklist add-on; alphasort

[[File:Fgaddonslogo202x89.png|right]]
To make it easier to create '''addons''' there is since FlightGear 2017.3 a new way to create addons. In essence FlightGear will load an overlay XML into the property tree and start a well known Nasal function.<ref>{{cite web
|url = https://forum.flightgear.org/viewtopic.php?p=314620#p314620
|title = <nowiki> Re: New Feature: Addon - "API" </nowiki>
|author = <nowiki> Torsten </nowiki>
|date = Jul 19th, 2017
|added = Jul 19th, 2017
|script_version = 0.40
}}</ref>

We now have a simple way to add addons to FlightGear without the need to mess around with <code>FGData/Nasal</code> or <code>FGHome/Nasal</code> directories.<ref name="Forum_announcement">{{cite web
|url = https://forum.flightgear.org/viewtopic.php?p=314563#p314563
|title = <nowiki> New Feature: Addon - "API" </nowiki>
|author = <nowiki> Torsten </nowiki>
|date = Jul 18th, 2017
}}</ref>

{{TOC limit|3}}

== Installing and using an addon ==
Download and copy the addon to a directory on your computer.

If you use the launcher, select the Add-ons page from the icon bar on the left, then find the section Add-on Module folders and click the Add(+) button. Select the folder where you put the addon. Once the addon is shown in the list, make sure its check box is selected.

Use the command line switch <code>--addon=/path/to/some/addon</code>.<ref name="Forum_announcement"/>

== Creating an addon ==
There is a very simple Skeleton addon available in FGAddon to be used as a template.<ref name="Forum_announcement"/> See {{fgaddon source|path=Addons/Skeleton}}.

A leading slash (<code>/</code>) in this section indicates the base directory of the directory structure of the addon.

=== Minimum configuration ===
An addon may be installed in a directory anywhere on your hard disk and need at least two files:

* <code>/addon-config.xml</code> - A standard [[PropertyList XML files|PropertyList XML file]] to be used to populate or modify the [[property tree]]. (Same as to be used in <code>--config=foo.xml</code>)
* <code>/addon-main.nas</code> - The Nasal hook for the logic. This file needs a function called <code>main()</code> which will be called from the global addon initializer (<code>addons.nas</code>)

=== Additional common files ===
* <code>/addon-metadata.xml</code> - A PropertyList XML file with metadata about the addon it.
* <code>/addon-menubar-items.xml</code> - A PropertyList XML file describing menus to be added to the FlightGear menu bar.
* <code>/gui/dialogs/<my-foobar-dialog>.xml</code> - PropertyList XML files to create custom dialogs.

=== Good to know ===
The new addon mechanism lets you add a <code>addon-config.xml</code> to override the settings in <code>defaults.xml</code> and other files.

That will allow an addon to
* Override key bindings (as in the spoken ATC addon)
* Add or override autopilots and property rules
* Introduce XML state machines

Unless your really want to add/change/remove those at runtime, this should cater for most use cases.<ref>{{cite web
|url = https://forum.flightgear.org/viewtopic.php?p=314902#p314902
|title = <nowiki> Re: Spoken </nowiki>
|author = <nowiki> Torsten </nowiki>
|date = Jul 23rd, 2017
|added = Jul 23rd, 2017
|script_version = 0.40
}}</ref>

We have some instructions how to use SVN [[FGAddon|in our wiki]]. It covers mostly aircraft development but the workflow is pretty much the same for addons.<ref>{{cite web
|url = https://forum.flightgear.org/viewtopic.php?p=314647#p314647
|title = <nowiki> Re: Spoken ATC </nowiki>
|author = <nowiki> Torsten </nowiki>
|date = Jul 19th, 2017
|added = Jul 19th, 2017
|script_version = 0.40
}}</ref>

=== Sound Support ===
Sound support is available using fgcommand's.

See [[Nasal FAQ]] "play-audio-sample"

https://sourceforge.net/p/flightgear/flightgear/ci/5acf2e26d085b7553b2387b9753e9253e8b4bff4

[[Hackathon Proposal:Addon specific Sound Queues]]

== Addon initialization ==
On initialization fgfs takes care of:
* Through {{flightgear source|path=src/Main/options.cxx|text=<code>options.cxx</code>}}:<ref name="Forum_announcement"/>
** Creating a property under <code>/addons/addon[n]/path=/path/to/some/addon</code>
** Loading <code>/path/to/some/addon/addon-config.xml</code> into the property tree (same as <code>--config=/path/to/some/addon/addon-config.xml</code>)
** Adding <code>/path/to/some/addon</code> to the list of allowed directories (same as <code>--fg-aircraft=/path/to/some/addon</code>)
* Through {{fgdata source|path=Nasal/addons.nas|text=<code>addons.nas</code>}}:
** Loading <code>/foo/bar/baz/addon-main.nas</code> into namespace <code>__addon[ADDON_ID]__</code>
** Calling <code>main(addonGhost)</code> from <code>/foo/bar/baz/addon-main.nas</code>.

== Aircraft specific config (addon-hints) ==
Some addons need per-aircraft configuration. While addons should strive to be self-contained (ie. the addon should contain means to
detect different aircraft and apply config from whithin the addon) there is also the possibility for the addon to read so called "addon-hints".

For this, a special property tree exists: <code>/sim/addon-hints/<addon>/...</code>
The tree is expected to be populated from the aircraft.xml file. The addon can then read the properties from a common place regardless of loaded aircraft.

<syntaxhighlight lang="xml">
<sim>
<addon-hints>
<my-addon>
...
</my-addon>
</addon-hints>
</sim>
</syntaxhighlight>

== APIs ==
{{hatnote|For more details about these APIs, see the readme file, {{readme file|add-ons}}.}}
=== C++ API ===
There is a C++ API on FlightGear's side that handle some on the addon related tasks manly through the <code>AddonManager()</code>, <code>Addon()</code> and <code>AddonVersion()</code> classes.

=== Nasal API ===
The Nasal add-on API lives in the 'addons' namespace and can for example do queries to <code>AddonManager()</code> and read data from <code>addons.Addon</code> objects. It can for example compare addon versions if there is dependencies.

See: {{Repo link|site=gitlab|proj=flightgear|repo=fgdata|branch=next|path=Nasal/addons.nas}}

== Background ==
{{See also|Howto:Creating a simple modding framework}}

ATC chatter was removed in 2015, see fgdata commit: [https://sourceforge.net/p/flightgear/fgdata/ci/81607f734e13add9be02816ddaec305d05bc4e47/ 81607f734e13add9be02816ddaec305d05bc4e47]

And the devel list messages referenced in the commit log.
the other relevant commit is this: b60736ba7add2a7cd39af3d8a974d5be3ea46e8b
It would not be very difficult to restore this functionality, or even generalize/improve it significantly (which was the scope of the original discussion on the devel list)<ref>{{cite web
|url = https://forum.flightgear.org/viewtopic.php?p=288388#p288388
|title = <nowiki> Re: Whatever happened to radom radio </nowiki>
|author = <nowiki> Hooray </nowiki>
|date = Jun 11th, 2016
|added = Jun 11th, 2016
|script_version = 0.40
}}</ref>

The restored functionality could be distributed as a tarball that is extracted into $FG_ROOT - alternatively, into $FG_HOME, because Nasal files there are treated as overlays, which basically means that you can install user-specific extensions there without having to tamper with $FG_ROOT, it would only take very minor changes to turn the chatter feature into a corresponding "addon" - not unlike fgcamera ...<ref>{{cite web
|url = https://forum.flightgear.org/viewtopic.php?p=288392#p288392
|title = <nowiki> Re: Whatever happened to radom radio </nowiki>
|author = <nowiki> Hooray </nowiki>
|date = Jun 11th, 2016
|added = Jun 11th, 2016
|script_version = 0.40
}}</ref>

We should absolutely stop telling anyone to edit preferences.xml in FG_ROOT; any documentation or advice which says to should be changes ASAP. <ref>{{cite web
|url = https://forum.flightgear.org/viewtopic.php?p=192632#p192632
|title = <nowiki> Re: NavCache:init failed:Sqlite error:Sqlite API abuse </nowiki>
|author = <nowiki> zakalawe </nowiki>
|date = Oct 26th, 2013
|added = Oct 26th, 2013
|script_version = 0.40
}}</ref>

As of 12/2017, the addon API is in the process of being significantly updated <ref>https://sourceforge.net/p/flightgear/mailman/message/36146017/</ref> <ref>https://sourceforge.net/p/flightgear/mailman/message/36150159/</ref> <ref>https://sourceforge.net/p/flightgear/mailman/message/36150444/</ref>

== List of Addons ==
You can find the official repository at {{fgaddon source|path=Addons}}

* [https://github.com/slawekmikula/flightgear-addon-hudheli Additional Heli HUD's] - ([https://github.com/slawekmikula/flightgear-addon-hudheli/blob/master/doc/manual.md manual]) - encapsulation of HeliHUD package as an addon
* [https://github.com/PlayeRom/flightgear-addon-aerotow-everywhere Aerotow Everywhere] AI towing aircraft for gliders at every airport.<ref>{{cite web
|url = https://forum.flightgear.org/viewtopic.php?t=40742
|title = <nowiki> Re: Aerotow Everywhere </nowiki>
|author = <nowiki> Roman Ludwicki (PlayeRom) </nowiki>
|date = Aug 14th, 2022
|added = Aug 14th, 2022
|script_version = 0.40
}}</ref>
* [https://github.com/SP-NTX/AnotherGUI AnotherGUI] - An add-on that adds a new GUI style.
* ATC Chatter (ported by Torsten) {{progressbar|100}}
* [[Blacklist add-on]] - Automatically ignore pilots with certain callsigns or multiplayer models.
* [[Cargo Towing Addon]] <ref>{{cite web
|url = https://forum.flightgear.org/viewtopic.php?t=36824
|title = <nowiki> Re: Cargo Towing Addon </nowiki>
|author = <nowiki> Wayne Bragg (wlbragg) </nowiki>
|date =
|added =
|script_version = 0.40
}}</ref>
* cockpit-view (work in progress by wkitty42)<ref>{{cite web
|url = https://forum.flightgear.org/viewtopic.php?p=316498#p316498
|title = <nowiki> Re: </nowiki>
|author = <nowiki> wkitty42 </nowiki>
|date = Aug 13th, 2017
|added = Aug 13th, 2017
|script_version = 0.40
}}</ref>
* [[Earthview#Customization]] - High resolution customization
* [[FaceTrackNoIR]] (ported by HHS)<ref>{{cite web
|url = https://sourceforge.net/p/flightgear/mailman/message/36454826/
|title = <nowiki> Re: </nowiki>
|author = <nowiki> Unknown, HHS</nowiki>
|date = Nov 1th, 2018
}}</ref> - An addon to interface this [[Head tracking|head tracker]] with FlightGear
* [https://forum.flightgear.org/viewtopic.php?f=5&t=24792 Fencemaker] (Eases creating Fence-like scenery objects. Originally by VaLeo, converted to an addon by sfr) - ([https://www.mediafire.com/file/cf0la63v9g352md/fencemaker_addon.zip/file download])<ref>{{cite web
|url = https://forum.flightgear.org/viewtopic.php?f=5&t=24792&start=45#p390066
|title = <nowiki> Re: </nowiki>
|author = <nowiki> Stefan Frank </nowiki>
|maintainer = <nowiki> Stefan Frank </nowiki>
|date = Aug 8th, 2021
}}</ref>
* [https://github.com/PlayeRom/flightgear-addon-fgcamera FGCamera] - ([https://github.com/PlayeRom/flightgear-addon-fgcamera/blob/master/Docs/manual.md manual]) - [[FGCamera | Wiki Page]]
* [[FGPlot]]
* [[Ground Services]] (ported by ThomasS)<ref>{{cite web
|url = https://forum.flightgear.org/viewtopic.php?p=316400#p316400
|title = <nowiki> Re: </nowiki>
|author = <nowiki> ThomasS </nowiki>
|date = Aug 12th, 2017
|added = Aug 12th, 2017
|script_version = 0.40
}}</ref>
* {{fgaddon source|path=Addons/Headtracker/|text=Headtracker addon}} Helps integrate FaceTrackNoIR and opentrack with FlightGear.
* [[HighAirTrader]] An in-sim mini game in which you transport goods to different airports.
* [https://github.com/tdammers/fg-hoppie-acars Hoppie ACARS client] - connect to [http://www.hoppie.nl/acars Hoppie's ACARS], used on VATSIM and other networks.
* [https://sourceforge.net/p/flightgear/fgaddon/HEAD/tree/trunk/Addons/Illuminator/ Illuminator] - configure lights attached to 3D models (e.g. taxi light, landing light or a light attached to a scenery model like a light pole) at runtime.
* [https://github.com/slawekmikula/flightgear-addon-protocolkml KML Exporter (Google Earth)] - ([https://github.com/slawekmikula/flightgear-addon-protocolkml/blob/master/doc/manual.md manual])
* [[Landing Rate addon]] [https://forum.flightgear.org/viewtopic.php?f=6&t=33101&p=327787#p327787]
* [https://github.com/slawekmikula/flightgear-addon-linuxtrack LinuxTrack Head Tracker integration] - ([https://github.com/slawekmikula/flightgear-addon-linuxtrack/blob/master/doc/manual.md manual])
* [https://github.com/slawekmikula/flightgear-addon-littlenavmap LittleNavMap integration] - ([https://github.com/slawekmikula/flightgear-addon-littlenavmap/blob/master/doc/manual.md manual])
* [https://github.com/PlayeRom/flightgear-addon-logbook Logbook] all your flights to CSV file.<ref>{{cite web
|url = https://forum.flightgear.org/viewtopic.php?t=41070
|title = <nowiki> Re: Logbook Add-on </nowiki>
|author = <nowiki> Roman Ludwicki (PlayeRom) </nowiki>
|date = Dec 11th, 2022
|added = Dec 11th, 2022
|script_version = 0.40
}}</ref>
* [[Log time-stamper add-on]] - Will print simulated UTC time, real local time, and/or real UTC time time-stamps at configurable intervals to the console and log.
* [https://gitlab.com/mdanil/flightgear-hax mdanilov hax!]: landing evaluation and aircraft development tools, TerraSync toggler
* [[Model Cockpit View]]
* [https://github.com/SP-NTX/MPChatImprovments MPChatImprovments] Multi-key commands for Multiplayer, new features for chat,...
* [https://github.com/hbeni/fgfs-noGroundDamage noGroundDamage] - Addon to temporarily disable damage after landing and for ground operations for the c172/c182
* [[Oscilloscope addon]] - Allows displaying a property of Nasal function over time
* [[PAR instrument]] - Precision Approach Radar and Ground Controlled Approach
* [[Red Griffin ATC]] - Speaking Air Traffic Controller<ref>{{cite web
|url = https://forum.flightgear.org/viewtopic.php?f=6&t=36755
|title = <nowiki> Re: </nowiki>
|author = <nowiki> RedGriffin </nowiki>
|date = Jan 6th, 2020
|added = Jan 6th, 2020
|script_version = 1.0.0 RC2
}}</ref>
* [https://github.com/tdammers/fg-simbrief-addon SimBrief import] - Import flightplans, weights, fuel, and winds alof, from SimBrief.
* [[Spoken ATC]] (ported by Torsten)<ref>{{cite web
|url = https://forum.flightgear.org/viewtopic.php?p=314095#p314095
|title = <nowiki> Re: </nowiki>
|author = <nowiki> Torsten </nowiki>
|date = Jul 10th, 2017
|added = Jul 10th, 2017
|script_version = 0.40
}}</ref>
* [[Spoken GCA]] - An offline ground controlled approach (GCA) addon
* [https://gitlab.com/mdanil/flightgear-mickey Tiny HUD for mouse flying in FlightGear] - Visual feedback for mouse flying, to make up for mouse's lack of self-centering
* [https://github.com/slawekmikula/flightgear-addon-vfrflight VFRFlight integration] - ([https://github.com/slawekmikula/flightgear-addon-vfrflight/blob/master/doc/manual.md manual])
* [https://github.com/slawekmikula/flightgear-addon-vfrnavigator VFR Flying Helper] - ([https://github.com/slawekmikula/flightgear-addon-vfrnavigator/blob/master/doc/usage.md manual])
* [[YASim Development Tools]] (by jsb)

== Experimental Addons ==

Addons which are in the development stage/unfinished but can be used as a quick view of addon functionality
* [https://github.com/slawekmikula/flightgear-addon-missions FlightGear Missions addon] - Add-on for missions/adventures code

== Ideas ==
=== Hooking into features using legacy OpenGL code ===
{{See also|Unifying the 2D rendering backend via canvas}}
In 09/2018, James suggested that legacy features using raw OpenGL calls (e.g. HUD/2D panels) could be easily replaced via scripted Canvas/Nasal solutions at the mere cost of providing a mechanism to hook into the legacy code implementing these features (namely, the HUD/instrumentation subsystems) <ref>https://sourceforge.net/p/flightgear/mailman/message/36399261/</ref> <ref>https://sourceforge.net/p/flightgear/mailman/message/36399261/</ref>

=== Catalog & Package Manager support ===
if this works with more complex, pre-existing addons such as [[Bombable]], where the file layout is a replica of the old FGData layout, these types of mature addons might be better as SourceForge FlightGear sub-projects rather than being copied into FGAddon. Maybe the config file and nasal script could be used to automate the installation process ?<ref>{{cite web
|url = https://sourceforge.net/p/flightgear/mailman/message/35953179/
|title = <nowiki> Re: [Flightgear-devel] Simple API for creating FlightGear
addons/plugins </nowiki>
|author = <nowiki> Edward d'Auvergne </nowiki>
|date = Jul 19th, 2017
|added = Jul 19th, 2017
|script_version = 0.40
}}</ref>
The [[Bombable]] addon is one of the most popular addons out there, and a large number of aircraft in FGAddon have bombable support, so it is worth not forgetting about. Especially if the addon system one day becomes automated through a [[Catalog metadata|catalog.xml type system]]<ref>{{cite web
|url = https://sourceforge.net/p/flightgear/mailman/message/35953650/
|title = <nowiki> Re: [Flightgear-devel] Simple API for creating FlightGear
addons/plugins </nowiki>
|author = <nowiki> Edward d'Auvergne </nowiki>
|date = Jul 19th, 2017
|added = Jul 19th, 2017
|script_version = 0.40
}}</ref>

== References ==
{{Appendix}}

== Related content ==
=== Wiki articles ===
* [[FG Add-on FAQ]]
* [[Modules.nas]]
* [[FlightGear configuration via XML]]
* [[FlightGear configuration via XML#preferences.xml]]
* [[Nasal]]
* [[Property tree]]
* [[Properties persistent between sessions]]
* [[PropertyList XML File]]

=== Forum topics ===
* {{forum link|t=32561|title=New Feature: Addon - "API"}}

=== Readme files ===
* {{readme file|add-ons}}
* {{readme file|gui}} - Details on how to add menus and custom dialogs.

=== Source code ===
==== FGAddon ====
* {{fgaddon source|path=Addons/Skeleton}} - Skeleton addon to be used as a template.

==== FGData ====
* {{fgdata source|path=Nasal/addons.nas}}

==== FlightGear ====
* {{flightgear source|path=src/Main/options.cxx}}
* {{flightgear source|path=src/Add-ons/}}

[[Category:FlightGear addons| ]]

User:Johan G/Things I have done

2025-02-26T09:39:16Z

Johan G: /* New pages */ + Blacklist add-on

These are ''some'' of the '''things I have done''' on the wiki.

''For a complete list see [[Special:Contributions/Johan_G]].''

== New pages ==
* [[Howto:Add blackout and redout settings]]
* [[Howto:Add multi-key commands to an aircraft]]
* [[Aerial refueling improvement ideas and resources]]
* [[Aircraft interception]]
* [[Blacklist add-on]]
* [[Dassault Mirage F1]]
* [[FlightGear wiki:FlightGear screenshot categories]]
* [[Flightplan XML formats]]
* [[Hand camera HK 101B add-on]]
* [[Head tracking]]
* [[Help:Tables]]
* [[Log time-stamper add-on]]
* [[Pilotage and dead reckoning]]
* [[Pilot List]]
* [[TerraMaster]]
* [[Time in FlightGear]]

== Larger edits ==
* Replaced the text in [[Howto: Edit a livery]] ([http://wiki.flightgear.org/index.php?title=Howto:_Edit_a_livery&oldid=36141 original text]) with my own draft ([http://wiki.flightgear.org/index.php?title=User:Johan_G/Howto:_Edit_a_livery&oldid=39121 Final draft]).
* [[Help:Templates]] – Rewritten it more or less completely ([http://wiki.flightgear.org/index.php?title=Help%3ATemplates&diff=64365&oldid=44878 diff])
* [[Help:Formatting]] – Complete rewrite of the former [http://wiki.flightgear.org/index.php?title=Help:Tutorial&oldid=42573 Help:Tutorial]
* [[Help:Your first article]] – Complete rewrite of [http://wiki.flightgear.org/index.php?title=Help:Your_first_article&oldid=64321 Help:Your first article]

== Templates ==
* A lot of template documentation
* Unification of the template documentation style (manually editing all existing template documentation!)
* {{tl|Welcome to the wiki}}
* {{tl|alds}} – For use on the [[Airliner Development Status]] page
* {{tl|due date}} – When you want to show one text before and another one after a certain date.
* {{tl|issue}} – For referencing bug tracker issues (be that bugs or feature requests).
* {{tl|key press}} – For illustrating key presses and combinations.
* {{tl|LangSwitch}} – For showing different texts depending on the language of a page.
* {{tl|rule of thumb}} – For rules of thumb, like 2 kt is about 1 m/s.
* {{tl|wikipedia}} – For links to Wikipedia.
* {{tl|yes}}, {{tl|partial}}, {{tl|no}} and {{tl|n/a}} – For use in various tables.
* Split up [http://wiki.flightgear.org/index.php?title=Template:Issue_Tracker&oldid=83057 <nowiki>{{Issue Tracker}}</nowiki>] into {{tl|register to sf}}, {{tl|create ticket}} and {{tl|tickets}}.
* {{tl|fg screenshot cat}} – To lessen the typing when adding descriptions to FlightGear screenshot categories.
* {{tl|screenshot cat}} - To add to pages about subjects there are a screenshot category for.
* {{tl|readme file}} – To link to readme files in [[$FG_DATA]]/Docs.
* {{tl|fgaddon revision}}, {{tl|fgdata commit}}, {{tl|simgear commit}} and {{tl|flightgear commit}} – For links to revision/commit summaries on the repositories.

== Uploaded images ==
* [[Special:ListFiles/Johan_G]]

[[Category:User pages]]

Blacklist add-on

2025-02-26T09:39:00Z

Johan G: Created page with "{{warning|Aircraft using the Emesary multiplayer damage system '''will take damage''' from ignored pilots.}} {{infobox addon | name = Blacklist | started = 13 November 2024 | desc = | contributors = {{usr|Johan G}}, pinto, Warty | status = mature | coderepo = https://gitlab.com/JohanG/blacklist }} The '''Blacklist''' add-on will every few seconds automatically ignore pilots that are listed either in a text file with callsigns or a text fi..."

TerraMaster

2025-01-04T08:21:56Z

Johan G: +cat: Putting back Category:Scenery software, as it seems relevant and might help people find the article

{{Infobox Software
|title = TerraMaster
|logo =
|image = TerraMaster r32 - Global view.png
|developedby = reeed, portree kid
|initialrelease = July 18, 2011
|latestrelease = January 3, 2025 (v3.02)
|writtenin = Java
|os =
|platform = Cross-platform
|developmentstatus =
|type = Scenery manager
|license = [[GNU GPL]] v2
|website = https://portree-kid.github.io/terramaster/
}}

'''TerraMaster''' is a graphical [[scenery]] manager that gives you a quick overview of your scenery and makes it easier to maintain that scenery. TerraMaster is a cross platform stand alone application written in Java that synchronises [[TerraSync]] scenery tiles you select with the [[FlightGear Scenery Database]]. You can delete scenery tiles if the TerraSync scenery directory takes too much space, and you can also search for airports.

== Overview ==
=== Map ===
When TerraMaster starts it will show a map of the Earth. The map can be zoomed and one or more 1x1 degree tiles can be selected before they are synced or deleted. All the airports within a tile can be shown, and airports can be searched for and be shown.

=== Icons ===
The top row contains a status field, two groups of icon buttons, a search field and a sync progress bar. The icons will be grayed out when they can not be used. For more detailed directions, see the section [[#Using|Using]] below. From left to right:
* ''Status field''. Shows the name of the tile that was last selected.

* ''Sync icon''. Syncs the tiles currently selected.
* ''Clock icon''. Syncs old tiles.
* ''Flight icon''. Opens a dialog to help selecting a route.
* ''Trash can icon''. Deletes the currently selected tiles.
* ''Eye icon''. Shows all airports in the first selected tile of the currently selected tiles.
* ''Stop button''. Currently does not work.

* ''Empty paper''. Hides all shown airports.
* ''Globe icon''. Zooms out to the global view.
* ''Gear icon''. Opens a dialogue to select the location of the TerraSync scenery directory.

* ''Search field''. Used to search for airports.

* ''Sync progress bar''. Only visible during syncing.

=== Tile border colours ===
The tiles are colour coded to represent the state of the tiles:

* '''Green''' tiles have both terrain and objects.
* '''Amber/Yellow''' tiles has terrain but no objects. (And are possibly unsyncable - see "Bug", below.)
* '''Red''' tiles are currently selected for synchronisation.
* '''Blue''' tiles are currently being synchronised.

The blue tiles that are being synced will change colour to green or amber/yellow as they are synced. Tiles that get no border after they have been synced don't contain terrain or objects and are usually located in open seas.

== Using ==
[[File:TerraMaster r32 - Mouse hint.png|thumb|Tile information pop-up when holding the mouse pointer over a tile.]]
[[File:TerraMaster r32 - Airports in selected tile.png|thumb|Showing all airports in a selected tile using the "eye" button.]]
[[File:TerraMaster r32 - Searching for an airport.png|thumb|Searching for an airport.]]

=== Zooming and panning ===
TerraMaster with the global view. Left-clicking will zoom you in on an area.

'''Zoom''' using the scroll wheel.

'''Pan''' around by dragging the map while pressing the right mouse button.

Get '''back to global view''' by clicking the "globe" icon.

=== Showing tile information ===
To get some information about a downloaded tile, hold the mouse pointer over it.

A pop-up box will show the name of that tile, if there are terrain and objects in it and what airports it contains. This only works if a tile has been synced, either with Terrasync or TerraMaster.

=== Syncing tiles ===
To '''select just one tile''' left-click it. The scenery for download is available in 1x1 degree tiles.

To '''select more tiles''' press the Ctrl key while left-clicking or left-dragging over the wanted tiles. If you accidentally selected a tile to many, '''deselect tiles''' using it Ctrl+left-click. You can also deselect several tiles using Ctrl+left-click and dragging.

'''Start the update and/or download''' clicking the "sync" icon. The tiles will be downloaded starting from the first tile you selected and proceed in order of distance from it. If you are downloading tiles for a long flight you should then begin by selecting a tile close to the departure airport.

=== Syncing old tiles ===

'''Start the update and/or download''' clicking the 2nd "sync" icon. All previously downloaded tiles that are older than the age given in the settings, will be downloaded.

=== Deleting tiles ===
You can delete files from the TerraSync scenery by selecting the tiles you want to delete and click the "trash can" icon.

=== Showing all airports in a tile ===
To show all airports in a tile, select it and click on the "eye" icon. To hide the airports again, click the "empty paper" icon.

=== Searching for an airport ===
You can search for airports using the search field and pressing enter. The airports location an ICAO code will be shown in white on the map. If you don't see it, zoom out. ICAO airport codes works best, but sometimes the airport's name also work. To hide the airports again, click the "empty paper" icon.

Be warned that the search function is rather slow as it uses a web query to mpmap.flightgear.org and that it also doesn't tell if there was no airports found.

== Video tutorial ==
Here is a short video tutorial:
{{#ev:youtube|YxWV4wk_dHw}}

== Tips ==
* '''Before [[multiplayer]] events''' it might be an idea to sync the related tiles, even more so if you know that someone has crated new buildings etc. and got them into the [[FlightGear Scenery Database|scenery database]].
* If you have very little hard drive space left you can delete tiles you rarely or never fly within.
* Starting TerraMaster in a console window will let you see the sync process, which can be useful if the sync stalls for unknown reasons.
* If you already have a synchronisation running and want to add more tiles to be synced, just mark more tiles as above with Ctrl + leftclick and drag to mark more tiles and press the sync button again.

== Installing ==
Before installing, make sure you have Java 6 or higher, as it is needed. NB: On Ubuntu 22.04 (Jammy) OpenJDK 8+ works.

# Download the newest version of TerraMaster from the [https://github.com/Portree-Kid/terramaster/releases releases page].
# Create a shortcut or script that runs <code>java -jar terramaster.jar</code>
# When running TerraMaster the first time, click the "gear" icon and select the folder where your TerraSync scenery is located. On some machines you might have to manually edit the property file to have it pointing to the TerraSync directory.
# Done!

== External link ==
* {{forum link|title=TerraMaster: a new scenery manager|t=12050}}

[[Category:Scenery software]]

Log time-stamper add-on

2024-08-20T09:31:31Z

Johan G: +- "with some issues" → "with some known issues"

{{infobox addon
| name = Log time-stamper add-on
| started = 6 August 2024
| desc =
| contributors = {{usr|Johan G}}
| status = Under development
| coderepo = https://gitlab.com/JohanG/log-time-stamper
}}

The '''log time-stamper add-on''' will print time-stamps to the console and log, which can be useful when comparing timings of events with other resources.

== Features ==
FlightGear v. 2020.3.18 prints times-stamps each on line of the console output and log, but only with elapsed time of the FlightGear session.

This add-on prints timestamps to the console at configurable intervals. As of early August 2024 it can print:
* Simulated UTC time
* Real local time
* Real UTC time (with some known issues)

Additionally the add-on prints changes in
* Simulation rate, how fast the simulation is running.
* Time warp, if the time of day is running at at a different speed than the simulation rate.
* If FlightGear is paused or unpaused.
* If the Time Setter add-on by Colin<ref>See https://gitlab.com/colingeniet/flightgear-time-offset for his add-on.</ref> is enabled or disabled. It synchronizes the simulated time with real time, optionally with a number of hours offset.

Timestamps are printed in ISO 8601 / RFC 3339 format, in essence <code>YYYY-MM-DD"T"HH:MM:SS("Z"|("+"|"-")hh:mm:ss)</code>.

== Exposed properties ==
There are some properties exposed that control the behavior of the add-on. These can be configured through the <code>addon-config.xml</code> file, or through properties in <code>/addons/by-id/org.flightgear.addons.log-time-stamper/config/</code>.

{| class="wikitable"
! Property !! Type !! Default !! Use
|-
| <code>print-sim-utc-time</code>
| bool
| True
| Simulated UTC time-stamps will be printed if true.
|-
| <code>print-real-local-time</code>
| bool
| True
| Real local time-stamps will be printed if true.
|-
| <code>print-real-utc-time</code>
| bool
| True
| Real UTC time-stamps will be printed if true (with some known issues).
|-
| <code>time-stamp-interval-sec</code>
| int
| 60
| Interval in seconds between time-stamps.
|}

== Known issues ==
=== Real UTC time time-stamps ===
As of early August 2024 the real UTC time time-stamps ignores day rollovers, in essence if the offset and time makes it so that the UTC time would be on another day than the local real time day.

This means that days, months and years can be off by one.

=== The Time Setter add-on ===
The Time Setter add-on must be loaded before the time-stamper add-on for the time-stamper add-on to be able to print status changes of the Time Setter add-on.

This is due that to register a listener to the the relevant property, <code>/sim/time/time-setter/enable</code>, that property must exist. That property get initialized when the Time Setter add-on is loaded.

== Notes ==
<references/>

== Related content ==
=== Wiki articles ===
* [[Time]]

=== Forum topic ===
* {{forum link |title=Log time-stamper add-on |t=42533}}

=== Source code ===
* {{gitlab url |user=JohanG |repo=log-time-stamper}}

Log time-stamper add-on

2024-08-20T09:28:41Z

Johan G: /* Exposed properties */ Listing the properties with some more data in a table instead of as bullet points

{{infobox addon
| name = Log time-stamper add-on
| started = 6 August 2024
| desc =
| contributors = {{usr|Johan G}}
| status = Under development
| coderepo = https://gitlab.com/JohanG/log-time-stamper
}}

The '''log time-stamper add-on''' will print time-stamps to the console and log, which can be useful when comparing timings of events with other resources.

== Features ==
FlightGear v. 2020.3.18 prints times-stamps each on line of the console output and log, but only with elapsed time of the FlightGear session.

This add-on prints timestamps to the console at configurable intervals. As of early August 2024 it can print:
* Simulated UTC time
* Real local time
* Real UTC time (with some issues)

Additionally the add-on prints changes in
* Simulation rate, how fast the simulation is running.
* Time warp, if the time of day is running at at a different speed than the simulation rate.
* If FlightGear is paused or unpaused.
* If the Time Setter add-on by Colin<ref>See https://gitlab.com/colingeniet/flightgear-time-offset for his add-on.</ref> is enabled or disabled. It synchronizes the simulated time with real time, optionally with a number of hours offset.

Timestamps are printed in ISO 8601 / RFC 3339 format, in essence <code>YYYY-MM-DD"T"HH:MM:SS("Z"|("+"|"-")hh:mm:ss)</code>.

== Exposed properties ==
There are some properties exposed that control the behavior of the add-on. These can be configured through the <code>addon-config.xml</code> file, or through properties in <code>/addons/by-id/org.flightgear.addons.log-time-stamper/config/</code>.

{| class="wikitable"
! Property !! Type !! Default !! Use
|-
| <code>print-sim-utc-time</code>
| bool
| True
| Simulated UTC time-stamps will be printed if true.
|-
| <code>print-real-local-time</code>
| bool
| True
| Real local time-stamps will be printed if true.
|-
| <code>print-real-utc-time</code>
| bool
| True
| Real UTC time-stamps will be printed if true (though with some issues).
|-
| <code>time-stamp-interval-sec</code>
| int
| 60
| Interval in seconds between time-stamps.
|}

== Known issues ==
=== Real UTC time time-stamps ===
As of early August 2024 the real UTC time time-stamps ignores day rollovers, in essence if the offset and time makes it so that the UTC time would be on another day than the local real time day.

This means that days, months and years can be off by one.

=== The Time Setter add-on ===
The Time Setter add-on must be loaded before the time-stamper add-on for the time-stamper add-on to be able to print status changes of the Time Setter add-on.

This is due that to register a listener to the the relevant property, <code>/sim/time/time-setter/enable</code>, that property must exist. That property get initialized when the Time Setter add-on is loaded.

== Notes ==
<references/>

== Related content ==
=== Wiki articles ===
* [[Time]]

=== Forum topic ===
* {{forum link |title=Log time-stamper add-on |t=42533}}

=== Source code ===
* {{gitlab url |user=JohanG |repo=log-time-stamper}}

Log time-stamper add-on

2024-08-20T09:03:52Z

Johan G: /* Exposed properties */ Spelling

{{infobox addon
| name = Log time-stamper add-on
| started = 6 August 2024
| desc =
| contributors = {{usr|Johan G}}
| status = Under development
| coderepo = https://gitlab.com/JohanG/log-time-stamper
}}

The '''log time-stamper add-on''' will print time-stamps to the console and log, which can be useful when comparing timings of events with other resources.

== Features ==
FlightGear v. 2020.3.18 prints times-stamps each on line of the console output and log, but only with elapsed time of the FlightGear session.

This add-on prints timestamps to the console at configurable intervals. As of early August 2024 it can print:
* Simulated UTC time
* Real local time
* Real UTC time (with some issues)

Additionally the add-on prints changes in
* Simulation rate, how fast the simulation is running.
* Time warp, if the time of day is running at at a different speed than the simulation rate.
* If FlightGear is paused or unpaused.
* If the Time Setter add-on by Colin<ref>See https://gitlab.com/colingeniet/flightgear-time-offset for his add-on.</ref> is enabled or disabled. It synchronizes the simulated time with real time, optionally with a number of hours offset.

Timestamps are printed in ISO 8601 / RFC 3339 format, in essence <code>YYYY-MM-DD"T"HH:MM:SS("Z"|("+"|"-")hh:mm:ss)</code>.

== Exposed properties ==
There are some exposed properties that can be configured through the <code>addon-config.xml</code> file or through the property tree.

These properties controls:
* The time-stamp interval
* If you want either of these time-stamps
** Simulated UTC time
** Real local time
** Real UTC time (though with some issues)

== Known issues ==
=== Real UTC time time-stamps ===
As of early August 2024 the real UTC time time-stamps ignores day rollovers, in essence if the offset and time makes it so that the UTC time would be on another day than the local real time day.

This means that days, months and years can be off by one.

=== The Time Setter add-on ===
The Time Setter add-on must be loaded before the time-stamper add-on for the time-stamper add-on to be able to print status changes of the Time Setter add-on.

This is due that to register a listener to the the relevant property, <code>/sim/time/time-setter/enable</code>, that property must exist. That property get initialized when the Time Setter add-on is loaded.

== Notes ==
<references/>

== Related content ==
=== Wiki articles ===
* [[Time]]

=== Forum topic ===
* {{forum link |title=Log time-stamper add-on |t=42533}}

=== Source code ===
* {{gitlab url |user=JohanG |repo=log-time-stamper}}

Log time-stamper add-on

2024-08-20T08:59:51Z

Johan G: /* Features */ Listing time stamps as bullet points instead

{{infobox addon
| name = Log time-stamper add-on
| started = 6 August 2024
| desc =
| contributors = {{usr|Johan G}}
| status = Under development
| coderepo = https://gitlab.com/JohanG/log-time-stamper
}}

The '''log time-stamper add-on''' will print time-stamps to the console and log, which can be useful when comparing timings of events with other resources.

== Features ==
FlightGear v. 2020.3.18 prints times-stamps each on line of the console output and log, but only with elapsed time of the FlightGear session.

This add-on prints timestamps to the console at configurable intervals. As of early August 2024 it can print:
* Simulated UTC time
* Real local time
* Real UTC time (with some issues)

Additionally the add-on prints changes in
* Simulation rate, how fast the simulation is running.
* Time warp, if the time of day is running at at a different speed than the simulation rate.
* If FlightGear is paused or unpaused.
* If the Time Setter add-on by Colin<ref>See https://gitlab.com/colingeniet/flightgear-time-offset for his add-on.</ref> is enabled or disabled. It synchronizes the simulated time with real time, optionally with a number of hours offset.

Timestamps are printed in ISO 8601 / RFC 3339 format, in essence <code>YYYY-MM-DD"T"HH:MM:SS("Z"|("+"|"-")hh:mm:ss)</code>.

== Exposed properties ==
There are some exposed properties than can be configured through the <code>addon-config.xml</code> file or through the property tree.

These properties controls:
* The time-stamp interval
* If you want either of these time-stamps
** Simulated UTC time
** Real local time
** Real UTC time (though with some issues)

== Known issues ==
=== Real UTC time time-stamps ===
As of early August 2024 the real UTC time time-stamps ignores day rollovers, in essence if the offset and time makes it so that the UTC time would be on another day than the local real time day.

This means that days, months and years can be off by one.

=== The Time Setter add-on ===
The Time Setter add-on must be loaded before the time-stamper add-on for the time-stamper add-on to be able to print status changes of the Time Setter add-on.

This is due that to register a listener to the the relevant property, <code>/sim/time/time-setter/enable</code>, that property must exist. That property get initialized when the Time Setter add-on is loaded.

== Notes ==
<references/>

== Related content ==
=== Wiki articles ===
* [[Time]]

=== Forum topic ===
* {{forum link |title=Log time-stamper add-on |t=42533}}

=== Source code ===
* {{gitlab url |user=JohanG |repo=log-time-stamper}}

Time

2024-08-20T08:51:03Z

Johan G: /* Wiki articles */ + Log time-stamper add-on

[[File:PropertyBrowser-showing-sim-time.png|right|thumb|The [[property browser]] showing the <code>/sim/time/</code> subtree]]
[[File:Pui-time-dialog.png|right|thumb|The ''Time Settings'' dialog]]
[[File:Time.png|thumb|New Time dialog in FlightGear]]
[[File:Time-dialog-via-pui2canvas.png|thumb|approximation of the FlightGear [[Time in FlightGear|Time]] dialog via [[Howto:Processing legacy PUI dialogs using Canvas|pui2canvas]] parser]]

The '''time in FlightGear''' and the properties affecting it are represented internally as properties in the <code>/sim/time/</code> property subtree. The time can be manipulated using ''simulation rate''/''speed-up'', to increase or decrease the speed of the simulation, and ''time warp''/''warp delta'', to speed up or reverse local and UTC time.

The terminology used in FlightGear is a bit inconsistent even within the GUI. For the one used in this article, see [[#Terms used in this article]].

== Key bindings ==
{| class="wikitable"
! colspan="2" | Keys !! Binding !! Remarks
|-
| {{key press|A}} || {{key press|Shift|A}} || Increase / decrease simulation rate
| Affects <code>/sim/speed-up</code>
|-
| {{key press|W}} || {{key press|Shift|W}} || Increase / decrease the warp offset
| Affects <code>/sim/time/warp</code>
|-
| {{key press|T}} || {{key press|Shift|T}} || Increase / decrease time warp in steps
| Affects <code>/sim/time/warp-delta</code>
|}

== Simulation rate vs. time warp ==
Simulation rate and time warp manipulates the speed of the simulation and time in FlightGear. The simulation rate affects how much faster or slower the FDM appears to run and the time warp affects how fast local and UTC time changes. Neither simulation rate or time warp will affect for example the airspeed of the aircraft.

=== Simulation rate ===
When the simulation is sped up and slowed down, the integer factor <code>/sim/speed-up</code> will increase and decrease. The aircraft will appear to fly <code>/sim/speed-up</code> times faster over the terrain. When running FlightGear at normal simulation rate <code>/sim/speed-up</code> is one.

This will only affect the speed of the simulation, not the local and UTC time.

=== FDM rate ===
{{FGCquote
|1= The FDM runs at 120 Hertz and with a fixed time step. However, we play one small trick to make that happen. We take the time that has elapsed since the last frame, compute how many whole iterations of the FDM will fit in that time slice (at 1/120th of a second per iteration.) Then we invoke the FDM that many times with a time step of 1/120th of a second. Finally we save out the remainder and add that into the next time slice. This can produce a small amount of temporal jitter between the graphics and the fdm if the graphics frame rates are not a diviser of 120. In the best case scenario, you've locked your graphics frame rate to 60 hz so the FDM runs exactly 2 iterations every time it is invoked and there is no temporal jitter at all, ever. One thing to keep in mind is that handing a different size time slice to the FDM every frame (and sometimes that time slice could be 1 second or more?) can lead to instabilities in the math. So our approach is intended to avoid that potential problem. As far as the FDM is concerned, it *is* running asyncronously, at a fixed time step. But, we are playing a little trick on the FDM (it doesn't care) in order to handle the unfortunate possibility of non-fixed and highly variable frame rates on PC hardware running consumer grade operating systems.
|2= {{cite web
| url = http://sourceforge.net/p/flightgear/mailman/message/15645370/
| title = <nowiki>Re: [Flightgear-devel] FlightGear/Plib periodic stutter notes</nowiki>
| author = <nowiki>Curtis Olson</nowiki>
| date = Oct 24th, 2007
| added = Oct 24th, 2007
| script_version = 0.25
}}
}}

{{FGCquote
|1= the autopilot in FG should be running at a fixed framrate (/sim/model-h) these days. That is, fixed in simulated time, which is all that should matter. (As an aside our time management is still pretty messy and lots of things that ought to use simulated time seems to be using real time instead - try increasing the simulation rate and see how many virtual things that do not speed up...)
|2= {{cite web
| url = http://sourceforge.net/p/flightgear/mailman/message/28195667/
| title = <nowiki>Re: [Flightgear-devel] autopilot frame rate</nowiki>
| author = <nowiki>Anders Gidenstam</nowiki>
| date = Oct 7th, 2011
| added = Oct 7th, 2011
| script_version = 0.25
}}
}}

=== Time warp ===
When time of day is sped up or reversed using time warp, <code>/sim/time/warp-delta</code> seconds are added or subtracted to <code>/sim/time/warp</code> each second. In essence, the former is not a factor and the latter is an offset. When running FlightGear at normal time warp <code>/sim/time/warp-delta</code> is zero, and when running in real time, <code>/sim/time/warp</code> is also zero.

This will only affect the local and UTC time, not the speed of the simulation. The aircraft will fly just as fast over the terrain, but the sun and clock hands will speed up or reverse.

{{FGCquote
|1= /sim/speed-up is now included in dt, unless you use ‘real dt’ - which is only for user-interface and other things that should work while paused? (I have a long-standing task to make view direction animation use real-dt so you can look around at normal rate while paused or using sim/speed-up)
|2= {{cite web
| url = http://sourceforge.net/p/flightgear/mailman/message/34883671/
| title = <nowiki>Re: [Flightgear-devel] Time speedup</nowiki>
| author = <nowiki>James Turner</nowiki>
| date = Feb 25th, 2016
| added = Feb 25th, 2016
| script_version = 0.25
}}
}}

{{FGCquote
|1= Note the /sim/time/warp value may not be completely accurate, but should be close enough for what it’s used for (time of day), but to cumulative rounding as that is updated each frame. But the actual dt values should be completely accurate.
|2= {{cite web
| url = http://sourceforge.net/p/flightgear/mailman/message/34883671/
| title = <nowiki>Re: [Flightgear-devel] Time speedup</nowiki>
| author = <nowiki>James Turner</nowiki>
| date = Feb 25th, 2016
| added = Feb 25th, 2016
| script_version = 0.25
}}
}}

=== Warp vs. speedup ===
{{FGCquote
|1= I find two separate concepts exposed in two different properties: sim/time/warp & sim/time/speed-up. The difference is also made in the user interface, where you can set time warping and speed-up independently. Apparently, speed-up affects the aircraft only (physics & instrumentation), and warp affects the environment only (ephemeris, for example). This effectively establishes two independent timelines inside and outside the aircraft, so there is no single value for "elapsed simulated time", i.e. it depends whether we are talking in or out the plane!
|2= {{cite web
| url = http://sourceforge.net/p/flightgear/mailman/message/31578793/
| title = <nowiki>[Flightgear-devel] Time warping</nowiki>
| author = <nowiki>Anton Gomez Alvedro</nowiki>
| date = Oct 30th, 2013
| added = Oct 30th, 2013
| script_version = 0.25
}}
}}

{{FGCquote
|1= speed-up is primarily related to the rate the FDM sees; instruments and autopilot also see the increase since I moved them to run in lock-step with the FDM (to avoid AP instability when using speed-ups which otherwise break the PID parameters). Speed-up is used to speed-up or slow-down how fast the simulation engine is running the local aircraft, in effect, but anything written in Nasal would need to handle it explicitly. We probably *could* factor sim/speed-up into simDt, but this would need to be done with great care since there's probably code using it which does not expect to see a speed-up. None of the above cares about 'wall clock times' or 'dates', only about dt intervals. - warp is about how fast we're updating our simulate 'time+date of the world'. Hence it affects things that refer to time of day such as ephemeris. The goal, I guess, was interactive adjustment of the calendar time to fly in the evening/morning, and indeed that's what the dialog suggests. Warp is really a warp-rate and a warp-offset - the offset is exactly the delta from system clock time to simulated world time, and we adjust it by the warp-rate each frame/update.
|2= {{cite web
| url = http://sourceforge.net/p/flightgear/mailman/message/31578949/
| title = <nowiki>Re: [Flightgear-devel] Time warping</nowiki>
| author = <nowiki>James Turner</nowiki>
| date = Oct 30th, 2013
| added = Oct 30th, 2013
| script_version = 0.25
}}
}}

=== Framerate throttling ===
{{FGCquote
|1= There is also a frame rate throttling option, but it's pretty buried /sim/frame-rate-throttle-h Also consider setting your "sync to vblank" option in your video hardware. That can help limit FlightGear to run at your display's refresh rate.
|2= {{cite web
| url = http://sourceforge.net/p/flightgear/mailman/message/28197283/
| title = <nowiki>Re: [Flightgear-devel] autopilot frame rate</nowiki>
| author = <nowiki>Curtis Olson</nowiki>
| date = Oct 7th, 2011
| added = Oct 7th, 2011
| script_version = 0.25
}}
}}

{{FGCquote
|1= If you sync to the vblank signal in FlightGear (and have enough cpu/graphics hp) you can run at a very solid 60h (or whatever rate your display refreshes at.) If you don't quite have that amount of hp consistently for all situations, there is a throttle-hz property you can set to force a slower update rate (maybe 30 or 20 fps ... ideally you want an even divider into your display update rate.) If consistent frame rates are your goal, there are ways to achieve that. However, because of the variability of systems and personal preferences, we don't turn a lot of this on by default.
|2= {{cite web
| url = http://sourceforge.net/p/flightgear/mailman/message/23257288/
| title = <nowiki>Re: [Flightgear-devel] Multithreading support</nowiki>
| author = <nowiki>Curtis Olson</nowiki>
| date = Aug 5th, 2009
| added = Aug 5th, 2009
| script_version = 0.25
}}
}}

=== News ===
{{FGCquote
|1= First the good news : I have managed to generalise the existing ‘speed up’ function (accessed via a/A keys) to work for many more parts of the simulator than before. (This is the feature which allows time to run faster or slower than normal) This should make flying with speed up on autopilot more reliable, and solves my specific use-case of the testing the AI traffic code easier, since I can speed up how fast the AI aircraft move and update. This also allowed various special cases in the instruments and Nasal to be removed. For those who care about details, the ‘dt’ value passed to subsystems is now scaled by the speed-up factor. This is consistent with the existing behaviour when paused (dt = 0, no sim time is passing). If you are working code which needs the ‘real’ dt, typically because you want to animate something while the sim is paused, the ‘real dt’ is available as it always way. However, any such code in this category would already have been incorrect when froen / paused, so I’m not too worried about such cases. Now the question: as well as sim/speed-up, we have the /sim/time/warp property which defines the offset in seconds from system time to simulator time. This is how we implement the various time of day options, and with Richard’s change, adjusting the date as well.
|2= {{cite web
| url = http://sourceforge.net/p/flightgear/mailman/message/34745068/
| title = <nowiki>[Flightgear-devel] Speed-up vs time-warp</nowiki>
| author = <nowiki>James Turner</nowiki>
| date = Jan 6th, 2016
| added = Jan 6th, 2016
| script_version = 0.23
}}
}}

== Precision ==
As of October 2015 there is only one floating point property, <code>/sim/time/elapsed-sec</code>, which tells how long FlightGear has been running. This property is not affected by simulation rate or time warp. Most of the other properties are integers, thus only able to show full seconds.

=== Getting sub-second local and UTC time ===
{{note|Yet to be tested}}

Sometimes you could want sub-second precision time that is affected by time warp. This could for example be if you want a cockpit clock to have a sweeping second hand or if you are logging test data in smaller intervals than one second while wanting those times to correlate to other data.

As clock hands often only use elapsed seconds to animate the hands, the following example will produce two such properties.

One way to get sub-second precision UTC and local time could be by declaring two floating point properties and a property rule in the [[aircraft-set.xml]] file for example like below. Using property rules will update the values at frame rate, while using autopilot functions would update them at FDM rate.

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

<sim>

<time>

<utc-sec type="double">0</local-sec>
<local-sec type="double">0</local-sec>
<time>

<systems>

<property-rule n="100"> 
<name>Sub-second precision UTC and local time</name>
<path>Systems/precision-time.xml</path>
</property-rule>

</systems>
</sim>

<PropertyList>
</syntaxhighlight>

Add property rules/autopilot filters adding <code>/sim/time/elapsed-sec</code>, <code>/sim/time/warp</code> and <code>/sim/time/offset-local</code> like below:

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

<filter>
<name type="string">Sub-second precision UTC time</name>
<type>gain</type>
<gain>1</gain>
<input>
<expression>
<sum>
<property>/sim/time/elapsed-sec</property> 
<property>/sim/time/warp</property> 
</sum>
</expression>
</input>
<output>/sim/time/utc-sec</output>
</filter>

<filter>
<name type="string">Sub-second precision local time</name>
<type>gain</type>
<gain>1</gain>
<input>
<expression>
<sum>
<property>/sim/time/utc-sec</property> 
<property>/sim/time/local-offset</property> 
</sum>
</expression>
</input>
<output>/sim/time/local-sec</output>
</filter>

<PropertyList>
</syntaxhighlight>

== Terms used in this article ==
The terms used in the source code, keyboard binding descriptions and ''Time Settings'' dialog labels are a bit inconsistent. Therefore, in this article these terms (mostly from the ''Time Settings'' dialog) will be used:

; clock time
: The local system time as represented by the <code>/sim/time/real/</code> property subtree.
; local time
: The in-sim local time as represented by <code>/sim/time/gmt</code> + the offset represented by <code>/sim/time/local-offset</code>.
; real time
: When running FlightGear with zero warp, so that local time is equal to clock time, and zero time warp so that local time is at the same speed as clock time.
; simulation rate
: Simulation rate speed-up factor as represented by <code>/sim/speed-up</code>. This is not related to the FDM rate, the speed at which the flight dynamics model is run.
; time warp
: Local and UTC time change rate as represented by <code>/sim/time/warp-delta</code>.
; UTC time
: The in-sim UTC time as represented by <code>/sim/time/gmt</code> and the <code>/sim/time/utc</code> property subtree. In essence the time shown on many cockpit clocks.
; warp
: The offset between local time and clock time as represented by <code>/sim/time/warp</code>.

== Nasal scripting ==
* {{func link|maketimer()}}
* {{func link|settimer()}}
* FDM coupled

== Ongoing Developments ==
=== Date selector ===
{{Note|See also {{Merge-request|project=fgdata|id=42}}}}
{{FGCquote
|1= sad that it is pretty difficult to set another date while in-simulator (via property menu), so I took the time selector and changed it a bit to have a date selector.
|2= {{cite web
| url = http://forum.flightgear.org/viewtopic.php?p=269399#p269399
| title = <nowiki>Date selector</nowiki>
| author = <nowiki>D-ECHO</nowiki>
| date = Dec 20th, 2015
| added = Dec 20th, 2015
| script_version = 0.23
}}
}}
{{FGCquote
|1= What do you all think about adding a date control to the Time Settings dialog in the Environment menu (and then maybe rename it to "Time and Date Settings")? Currently the only way to set the date while in sim is via the property editor using "/sim/time/gmt". This would as useful as having time controls to play with the amount of daylight since the date influences the position and maximal height of the sun, particularly in very northern or southern places. Personally, I think it would be great to give users the chance to set it in sim without fussing with the debug tools, just like we currently do with time.
|2= {{cite web
| url = http://sourceforge.net/p/flightgear/mailman/message/34735814/
| title = <nowiki>[Flightgear-devel] Time settings dialog</nowiki>
| author = <nowiki>Gilberto Agostinho</nowiki>
| date = Jan 3rd, 2016
| added = Jan 3rd, 2016
| script_version = 0.23
}}
}}

{{FGCquote
|1= I ran into a problem: the property that needs to be altered to change the year, month and day, as well as time, is "/sim/time/gmt", and its value is a single string. Unfortunately my knowledge of XML as well as of the capabilities of our dialogs isn't very fancy (I just did some simple things for the c172p so far), and I really don't know how could I create several buttons to change the date parameters individually and then have them concatenated into a single string in the format required by the mentioned property... If we had a single property for each parameter this would be easy peasy, but I am kind of stuck right now.
|2= {{cite web
| url = http://sourceforge.net/p/flightgear/mailman/message/34736360/
| title = <nowiki>Re: [Flightgear-devel] Time settings dialog</nowiki>
| author = <nowiki>Gilberto Agostinho</nowiki>
| date = Jan 3rd, 2016
| added = Jan 3rd, 2016
| script_version = 0.23
}}
}}

{{FGCquote
|1= I've just added some text input boxes to the dialog for year,month,day to the dialog https://sourceforge.net/u/r-harrison/fgdata/ci/3e667c0b443a06d167d63c9447b6d8442f6aca57/ Merge request created. https://sourceforge.net/p/flightgear/fgdata/merge-requests/39/ (Not quite sure why it says 0 commits on the request - maybe I was a bit quick creating the merge request as possibly it hadn't finished pushing). I can redo the merge request if needed. Also added a checkbox for the warp easing as I'm always having to do this with the property tree.
|2= {{cite web
| url = http://sourceforge.net/p/flightgear/mailman/message/34737165/
| title = <nowiki>Re: [Flightgear-devel] Time settings dialog</nowiki>
| author = <nowiki>Richard Harrison</nowiki>
| date = Jan 4th, 2016
| added = Jan 4th, 2016
| script_version = 0.23
}}
}}

{{FGCquote
|1= I've been working on the time dialog. At first it was a quick fix just to add date entry, but it's grown from that. This is what it is currently: http://i.imgur.com/QDuyDLD.png I wasn't sure about sliders on year,month,date at first, but the sliders actually work really effectively - which surprised me. IMHO this approach works better than the dropdown calendar that we've all seen before. The day of month is limited to the maximum number of days for the currently selected month and it takes leap years into account. I prefer to run with easing turned off which is another reason I added a checkbox for easing. I rather suspect I'm not alone in this view. The time slider partially removes the need for the warping. It's also neat adjusting the date with the sliders and seeing the effect changes can be found here: https://sourceforge.net/u/r-harrison/fgdata/ci/435b81bf2464b4c64b6e69ec966406ea45fea797/tree/gui/dialogs/timeofday.xml I've limited the range for the year from 1971 to 2037 (i.e. within completely safe 32bit time_t range).
|2= {{cite web
| url = http://sourceforge.net/p/flightgear/mailman/message/34747721/
| title = <nowiki>Re: [Flightgear-devel] Speed-up vs time-warp</nowiki>
| author = <nowiki>Richard Harrison</nowiki>
| date = Jan 7th, 2016
| added = Jan 7th, 2016
| script_version = 0.23
}}
}}

{{FGCquote
|1= [we] are debating his proposed changes to the time dialog: https://sourceforge.net/p/flightgear/fgdata/merge-requests/42/ I’m fine with functionality (mostly) but don’t like his choice of widgets, although as ever he is constrained by what PUI does and doesn’t offer. Can some other people, ideally with UX experience, review and comment? I don’t want to make a unilateral decision since I’m aware I’m usually at one extreme end of the ‘less is more’ Johnny Ive school of interface design :D As ever I would ask people reviewing to apply the UI learnability measure of ‘if I’d never seen this screen before or used FlightGear for more than five minutes, would the choices and controls in this dialog make sense to me? If not, what could be added / changed so they do?'
|2= {{cite web
| url = http://sourceforge.net/p/flightgear/mailman/message/34747748/
| title = <nowiki>[Flightgear-devel] Additional perspectives needed on time dialog</nowiki>
| author = <nowiki>James Turner</nowiki>
| date = Jan 7th, 2016
| added = Jan 7th, 2016
| script_version = 0.23
}}
}}

== Related content ==
=== Wiki articles ===
* [[Autopilot configuration reference]]
* [[Log time-stamper add-on]]
* [[Property browser]]
* [[Property tree]]

=== Forum topics ===
* [http://forum.flightgear.org/viewtopic.php?f=25&t=20756 Link Simulation Rate and Time Warp together?]

=== Issues ===
* {{Ticket|421}}

=== Source files ===
* {{fgdata file|keyboard.xml}}
* {{fgdata file|Nasal/controls.nas}}
* {{fgdata file|Timezone/}}

* {{simgear file|simgear/timing/}}

* {{flightgear file|src/Time/}}

[[Category:FlightGear]]

Log time-stamper add-on

2024-08-20T08:50:18Z

Johan G: /* Wiki articles */ + Time

{{infobox addon
| name = Log time-stamper add-on
| started = 6 August 2024
| desc =
| contributors = {{usr|Johan G}}
| status = Under development
| coderepo = https://gitlab.com/JohanG/log-time-stamper
}}

The '''log time-stamper add-on''' will print time-stamps to the console and log, which can be useful when comparing timings of events with other resources.

== Features ==
FlightGear v. 2020.3.18 prints times-stamps each on line of the console output and log, but only with elapsed time of the FlightGear session.

This add-on prints timestamps to the console at configurable intervals. As of early August 2024 it can print the simulated UTC time, real local time, and, with some issues, real UTC time.

Additionally the add-on prints changes in
* Simulation rate, how fast the simulation is running.
* Time warp, if the time of day is running at at a different speed than the simulation rate.
* If FlightGear is paused or unpaused.
* If the Time Setter add-on by Colin<ref>See https://gitlab.com/colingeniet/flightgear-time-offset for his add-on.</ref> is enabled or disabled. It synchronizes the simulated time with real time, optionally with a number of hours offset.

Timestamps are printed in ISO 8601 / RFC 3339 format, in essence <code>YYYY-MM-DD"T"HH:MM:SS("Z"|("+"|"-")hh:mm:ss)</code>.

== Exposed properties ==
There are some exposed properties than can be configured through the <code>addon-config.xml</code> file or through the property tree.

These properties controls:
* The time-stamp interval
* If you want either of these time-stamps
** Simulated UTC time
** Real local time
** Real UTC time (though with some issues)

== Known issues ==
=== Real UTC time time-stamps ===
As of early August 2024 the real UTC time time-stamps ignores day rollovers, in essence if the offset and time makes it so that the UTC time would be on another day than the local real time day.

This means that days, months and years can be off by one.

=== The Time Setter add-on ===
The Time Setter add-on must be loaded before the time-stamper add-on for the time-stamper add-on to be able to print status changes of the Time Setter add-on.

This is due that to register a listener to the the relevant property, <code>/sim/time/time-setter/enable</code>, that property must exist. That property get initialized when the Time Setter add-on is loaded.

== Notes ==
<references/>

== Related content ==
=== Wiki articles ===
* [[Time]]

=== Forum topic ===
* {{forum link |title=Log time-stamper add-on |t=42533}}

=== Source code ===
* {{gitlab url |user=JohanG |repo=log-time-stamper}}

Instant Replay

2024-08-19T15:39:29Z

Johan G: /* Saving and replaying saved replay tapes */ New section

[[File:FG-instant-replay-new.png|thumb|500px|The instant replay dialog.]]
'''Instant Replay''' allows you to view for example your last landing from different views and perspectives afterwards.

Additionally the instant replay feature allows saving and replaying past flights.

== Usage ==
FlightGear maintains an in-memory recording of the current session. To avoid running our of memory, only the last minute or so is recorded in full detail, and older data is gradually pruned.

The in-memory recording can be saved to a file.

=== Starting and controlling replay of normal recording ===
* Press '''Ctrl-r''' or select '''Instant Replay''' from the '''View''' menu to start the replay. Replay starts immediately.
* Press '''p''' or click '''pause''' to pause/resume the replay.
* Use the '''left/right''' arrow keys, or the '''<<''', '''>>''' buttons to skip. You can also use the mouse and drag the time slider.
* Use the '''up/down''' arrow keys, or the '''+''', '''-''' buttons to change replay speed. You can replay at slow-motion, real-time or fast-forward speed.
* Enable the '''Loop''' checkbox to continuously repeat the playback. When you configure a duration (in seconds) then only the last few seconds are continuously replayed.

=== Stopping replay ===
* Press '''Escape''' or the '''End Replay''' button to stop replay and return to the position prior to starting replay.
* Alternatively, click the '''My Controls!''' button to take over control at any point. With this feature you can use the replay system to go back in time, regain control and then continue the flight from a past position. This is useful to train particular flight phases, such as flying the same approach again and again, maybe using different weather/wind conditions.

=== Saving and loading replay tapes ===
Though ''Main Menu'' > ''File'' > ''Save Flight Recorder Tape'' and ''Load Flight Recorder Tape'' you can save and load flight recorder tapes.

When saving the tapes you can add a description of the flight.

== Record/replay on next ==
[[File:Flight-recorder-control.png|thumb|The extended Flight Recorder Control dialog on next.]]
There are various additions to record/replay on next:

* Extended '''File/Flight Recorder Control''' dialogue.
* Periodic generation of a recovery snapshot, allowing resumption after a flightgear crash.
* Continuous recording system:
** Continuous recording to file without any loss of detail.
** Optionally record/replay extra information:
*** Multiplayer aircraft.
*** Main window size.
*** Main window position.
*** Main window view.
* Aircraft override:
** When loading a Continuous recording at startup, we override the aircraft and starting airport to match what is in the recording.
* Replay of Continuous recordings from URL:
** Extends the '''--load-tape command-line''' option, for example: '''--load-tape=<nowiki>http://foo.com/bar.fgtape</nowiki>'''

=== Details ===
* A recovery snapshot is actually a single-frame continuous recording, and will be called '''<aircraft-type>-recovery.fgtape'''.
** Load on the command line with '''--load-tape=<aircraft-type>-recovery'''.
** Then do '''Ctrl-R''' to see the replay dialogue.
** And click on '''My Controls'''.
** Notes:
*** Some aircraft do not support '''My Controls'''.
*** Loading a recovery file from within Flightgear via the '''Flight Recorder Control''' dialogue is usually not useful because the recovery file will have been overwritten by the current Flightgear session.
* Continuous recording to file uncompressed is e.g. 100MB for an hour's recording near EDDF.
* Support for compression of Continuous recordings was pushed to next on 2021-7-31 ({{flightgear commit|7d414886e00e}}).
* Replay of Continuous recordings from URL:
** Downloads to local file in the background while replaying.
** Reuses local file if present, appending to it in the background if it was a partial download.
** Local file is in directory specified by property '''/sim/replay/tape-directory'''.

For details on recording file formats, see: {{flightgear file|docs-mini/README-recordings.md}}

== FG 2.6.0 and later ==
{{Note|
{{FGCquote
|the "my controls" button is currently intentionally disabled for JSBSim and for YASim helicopters. Only works with YASim aircraft so far.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/30084554/
|title=<nowiki>Re: [Flightgear-devel] flight recorder / replay system</nowiki>
|author=<nowiki>ThorstenB</nowiki>
|date=<nowiki>2012-11-11</nowiki>
}}
}}
}}
[[File:FG-instant-replay-new.png|thumb|500px|The instant replay dialog.]]
FG 2.6.0 introduced a new replay system which can be adapted to individual aircraft and provides better recordings/playbacks. It also introduces a new GUI as well as a dedicated file format for serializing flights to disk: [[Fgtape]].

{{FGCquote
|the flight recorder tapes are only 1 or 2 hours max... at one time i wanted to do one for a cross-country flight but when i saved it i only got the last hour or two
|{{cite web |url=https://sourceforge.net/p/flightgear/mailman/message/34868768/
|title=<nowiki>[Flightgear-devel] memory leaks - long term testing - pre-2016.2.0</nowiki>
|author=<nowiki>Unknown</nowiki>
|date=<nowiki>2016-02-20</nowiki>
}}
}}

== FG 2.4.0 and earlier ==
[[File:FG-instant-replay.gif|thumb|220px|The instant replay dialog for FG2.4.0 and earlier.]]
For FG 2.4.0 and earlier, a simple dialog box is presented with a couple of options (duration of replay and view type).
* A value of 0 for duration will replay the entire flight. The default value is 90 seconds (similar to MSFS). If you want something different, just type the number of seconds desired in the text box.
* The view option is a drop-down box with three options corresponding to Cockpit, Chase and Tower views. No matter what this is initially set to, the view type can be changed as normal with v/V and ctrl-v to cycle forwards or backwards through all the available views or return to default Cockpit view.

To return to normal flight, press 'p' twice (pause/unpause). This returns you to the point where you selected Instant Replay. You cannot back up 30 seconds or so and try that landing again. Also, it is currently not possible to save the replay buffer to a file to load and replay a flight later on.

'''Note:''' only data directly related to your aircraft is saved and played back, AI objects, multiplayer aircraft or any random features will not be replayed.

{{FGCquote
|The replay system uses three buffer levels: short term memory records 60 <br/>
seconds at full frame rate, mid term buffer records another 10 minutes <br/>
at 2fps, and the long term buffer holds 1 hour at 1/5fps. As I stated <br/>
earlier, I'm not changing the buffering scheme itself. However, the <br/>
buffer durations and rates are exposed by properties now. So, if you had <br/>
enough memory, you could increase the buffer sizes or change their rates.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28045468/
|title=<nowiki>Re: [Flightgear-devel] flight recorder / replay system</nowiki>
|author=<nowiki>ThorstenB</nowiki>
|date=<nowiki>2011-09-05</nowiki>
}}
}}

{{FGCquote
|1= You should be able to extend the recording limit by changing the /sim/reply/duration property (e.g. by clicking on View -> Instant Replay and changing the duration in the textbox next to the "Loop" checkbox).
|2= {{cite web
| url = http://sourceforge.net/p/flightgear/mailman/message/34868828/
| title = <nowiki>Re: [Flightgear-devel] flight recorder time limit</nowiki>
| author = <nowiki>Alessandro Menti</nowiki>
| date = Feb 20th, 2016
| added = Feb 20th, 2016
| script_version = 0.25
}}
}}

== Feature requests ==
{{FGCquote
|1= If the F/R data was written to disk immediately, so it doesn't have to take up valueable RAM, would make it possible to record nearly indefinitely (depending on disk space). And delete this data like a tmp-file on shutdown, if it isn't stored somewhere else...
|2= {{cite web
| url = http://sourceforge.net/p/flightgear/mailman/message/34868775/
| title = <nowiki>[Flightgear-devel] flight recorder time limit</nowiki>
| author = <nowiki>chris</nowiki>
| date = Feb 20th, 2016
| added = Feb 20th, 2016
| script_version = 0.25
}}
}}
{{FGCquote
|1= This should be quite doable, the FlightRecorder code is quite self-contained. Also it uses thining of the history buckets so actually I think for multi-hour data, maybe it just needs a coarser (maybe one sample per 5 seconds?) bucket of larger sie. If you want to look at the code I’m happy provide guidance on enhancing it.
|2= {{cite web
| url = http://sourceforge.net/p/flightgear/mailman/message/34869713/
| title = <nowiki>Re: [Flightgear-devel] flight recorder time limit</nowiki>
| author = <nowiki>James Turner</nowiki>
| date = Feb 21st, 2016
| added = Feb 21st, 2016
| script_version = 0.25
}}
}}

[Something similar to this is on next - see above.]

== Related content ==
=== Wiki articles ===
* [[Howto:Record, analyze and replay multiplayer flights with network tools]]
* [[Redesigning the Replay System]]

=== Forum topics ===
* {{forum link|p=373973|title=Re: How to start an A320 on approach with engines running?}} - Starting FlightGear with the <code>--load-tape</code> option, for example for approach training.

=== Readme file ===
* {{flightgear source |path=docs-mini/README-recordings.md}} (Description of Normal and Continuous recordings, up to date as of 2021-10-10.)
* {{readme file|flightrecorder}} (Detailed description of Normal recordings, last modified 2013-06-20.)

=== Source code ===
* {{fgdata source|path=Aircraft/Generic/flightrecorder/}} - Generic flight recorder configuration files.

* {{flightgear source|path=src/Aircraft/replay.hxx}}
* {{flightgear source|path=src/Aircraft/replay.cxx}}

[[Category:FlightGear feature]]
[[Category:Menubar]]

Instant Replay

2024-08-19T15:34:21Z

Johan G: Some well needed cleanup

[[File:FG-instant-replay-new.png|thumb|500px|The instant replay dialog.]]
'''Instant Replay''' allows you to view for example your last landing from different views and perspectives afterwards.

Additionally the instant replay feature allows saving and replaying past flights.

== Usage ==
FlightGear maintains an in-memory recording of the current session. To avoid running our of memory, only the last minute or so is recorded in full detail, and older data is gradually pruned.

The in-memory recording can be saved to a file.

=== Starting and controlling replay of normal recording ===
* Press '''Ctrl-r''' or select '''Instant Replay''' from the '''View''' menu to start the replay. Replay starts immediately.
* Press '''p''' or click '''pause''' to pause/resume the replay.
* Use the '''left/right''' arrow keys, or the '''<<''', '''>>''' buttons to skip. You can also use the mouse and drag the time slider.
* Use the '''up/down''' arrow keys, or the '''+''', '''-''' buttons to change replay speed. You can replay at slow-motion, real-time or fast-forward speed.
* Enable the '''Loop''' checkbox to continuously repeat the playback. When you configure a duration (in seconds) then only the last few seconds are continuously replayed.

=== Stopping replay ===
* Press '''Escape''' or the '''End Replay''' button to stop replay and return to the position prior to starting replay.
* Alternatively, click the '''My Controls!''' button to take over control at any point. With this feature you can use the replay system to go back in time, regain control and then continue the flight from a past position. This is useful to train particular flight phases, such as flying the same approach again and again, maybe using different weather/wind conditions.

== Record/replay on next ==
[[File:Flight-recorder-control.png|thumb|The extended Flight Recorder Control dialog on next.]]
There are various additions to record/replay on next:

* Extended '''File/Flight Recorder Control''' dialogue.
* Periodic generation of a recovery snapshot, allowing resumption after a flightgear crash.
* Continuous recording system:
** Continuous recording to file without any loss of detail.
** Optionally record/replay extra information:
*** Multiplayer aircraft.
*** Main window size.
*** Main window position.
*** Main window view.
* Aircraft override:
** When loading a Continuous recording at startup, we override the aircraft and starting airport to match what is in the recording.
* Replay of Continuous recordings from URL:
** Extends the '''--load-tape command-line''' option, for example: '''--load-tape=<nowiki>http://foo.com/bar.fgtape</nowiki>'''

=== Details ===
* A recovery snapshot is actually a single-frame continuous recording, and will be called '''<aircraft-type>-recovery.fgtape'''.
** Load on the command line with '''--load-tape=<aircraft-type>-recovery'''.
** Then do '''Ctrl-R''' to see the replay dialogue.
** And click on '''My Controls'''.
** Notes:
*** Some aircraft do not support '''My Controls'''.
*** Loading a recovery file from within Flightgear via the '''Flight Recorder Control''' dialogue is usually not useful because the recovery file will have been overwritten by the current Flightgear session.
* Continuous recording to file uncompressed is e.g. 100MB for an hour's recording near EDDF.
* Support for compression of Continuous recordings was pushed to next on 2021-7-31 ({{flightgear commit|7d414886e00e}}).
* Replay of Continuous recordings from URL:
** Downloads to local file in the background while replaying.
** Reuses local file if present, appending to it in the background if it was a partial download.
** Local file is in directory specified by property '''/sim/replay/tape-directory'''.

For details on recording file formats, see: {{flightgear file|docs-mini/README-recordings.md}}

== FG 2.6.0 and later ==
{{Note|
{{FGCquote
|the "my controls" button is currently intentionally disabled for JSBSim and for YASim helicopters. Only works with YASim aircraft so far.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/30084554/
|title=<nowiki>Re: [Flightgear-devel] flight recorder / replay system</nowiki>
|author=<nowiki>ThorstenB</nowiki>
|date=<nowiki>2012-11-11</nowiki>
}}
}}
}}
[[File:FG-instant-replay-new.png|thumb|500px|The instant replay dialog.]]
FG 2.6.0 introduced a new replay system which can be adapted to individual aircraft and provides better recordings/playbacks. It also introduces a new GUI as well as a dedicated file format for serializing flights to disk: [[Fgtape]].

{{FGCquote
|the flight recorder tapes are only 1 or 2 hours max... at one time i wanted to do one for a cross-country flight but when i saved it i only got the last hour or two
|{{cite web |url=https://sourceforge.net/p/flightgear/mailman/message/34868768/
|title=<nowiki>[Flightgear-devel] memory leaks - long term testing - pre-2016.2.0</nowiki>
|author=<nowiki>Unknown</nowiki>
|date=<nowiki>2016-02-20</nowiki>
}}
}}

== FG 2.4.0 and earlier ==
[[File:FG-instant-replay.gif|thumb|220px|The instant replay dialog for FG2.4.0 and earlier.]]
For FG 2.4.0 and earlier, a simple dialog box is presented with a couple of options (duration of replay and view type).
* A value of 0 for duration will replay the entire flight. The default value is 90 seconds (similar to MSFS). If you want something different, just type the number of seconds desired in the text box.
* The view option is a drop-down box with three options corresponding to Cockpit, Chase and Tower views. No matter what this is initially set to, the view type can be changed as normal with v/V and ctrl-v to cycle forwards or backwards through all the available views or return to default Cockpit view.

To return to normal flight, press 'p' twice (pause/unpause). This returns you to the point where you selected Instant Replay. You cannot back up 30 seconds or so and try that landing again. Also, it is currently not possible to save the replay buffer to a file to load and replay a flight later on.

'''Note:''' only data directly related to your aircraft is saved and played back, AI objects, multiplayer aircraft or any random features will not be replayed.

{{FGCquote
|The replay system uses three buffer levels: short term memory records 60 <br/>
seconds at full frame rate, mid term buffer records another 10 minutes <br/>
at 2fps, and the long term buffer holds 1 hour at 1/5fps. As I stated <br/>
earlier, I'm not changing the buffering scheme itself. However, the <br/>
buffer durations and rates are exposed by properties now. So, if you had <br/>
enough memory, you could increase the buffer sizes or change their rates.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28045468/
|title=<nowiki>Re: [Flightgear-devel] flight recorder / replay system</nowiki>
|author=<nowiki>ThorstenB</nowiki>
|date=<nowiki>2011-09-05</nowiki>
}}
}}

{{FGCquote
|1= You should be able to extend the recording limit by changing the /sim/reply/duration property (e.g. by clicking on View -> Instant Replay and changing the duration in the textbox next to the "Loop" checkbox).
|2= {{cite web
| url = http://sourceforge.net/p/flightgear/mailman/message/34868828/
| title = <nowiki>Re: [Flightgear-devel] flight recorder time limit</nowiki>
| author = <nowiki>Alessandro Menti</nowiki>
| date = Feb 20th, 2016
| added = Feb 20th, 2016
| script_version = 0.25
}}
}}

== Feature requests ==
{{FGCquote
|1= If the F/R data was written to disk immediately, so it doesn't have to take up valueable RAM, would make it possible to record nearly indefinitely (depending on disk space). And delete this data like a tmp-file on shutdown, if it isn't stored somewhere else...
|2= {{cite web
| url = http://sourceforge.net/p/flightgear/mailman/message/34868775/
| title = <nowiki>[Flightgear-devel] flight recorder time limit</nowiki>
| author = <nowiki>chris</nowiki>
| date = Feb 20th, 2016
| added = Feb 20th, 2016
| script_version = 0.25
}}
}}
{{FGCquote
|1= This should be quite doable, the FlightRecorder code is quite self-contained. Also it uses thining of the history buckets so actually I think for multi-hour data, maybe it just needs a coarser (maybe one sample per 5 seconds?) bucket of larger sie. If you want to look at the code I’m happy provide guidance on enhancing it.
|2= {{cite web
| url = http://sourceforge.net/p/flightgear/mailman/message/34869713/
| title = <nowiki>Re: [Flightgear-devel] flight recorder time limit</nowiki>
| author = <nowiki>James Turner</nowiki>
| date = Feb 21st, 2016
| added = Feb 21st, 2016
| script_version = 0.25
}}
}}

[Something similar to this is on next - see above.]

== Related content ==
=== Wiki articles ===
* [[Howto:Record, analyze and replay multiplayer flights with network tools]]
* [[Redesigning the Replay System]]

=== Forum topics ===
* {{forum link|p=373973|title=Re: How to start an A320 on approach with engines running?}} - Starting FlightGear with the <code>--load-tape</code> option, for example for approach training.

=== Readme file ===
* {{flightgear source |path=docs-mini/README-recordings.md}} (Description of Normal and Continuous recordings, up to date as of 2021-10-10.)
* {{readme file|flightrecorder}} (Detailed description of Normal recordings, last modified 2013-06-20.)

=== Source code ===
* {{fgdata source|path=Aircraft/Generic/flightrecorder/}} - Generic flight recorder configuration files.

* {{flightgear source|path=src/Aircraft/replay.hxx}}
* {{flightgear source|path=src/Aircraft/replay.cxx}}

[[Category:FlightGear feature]]
[[Category:Menubar]]

Log time-stamper add-on

2024-08-12T09:04:32Z

Johan G: /* Known issues */ The Time Setter add-on by Colin must be loaded before this add-on for the status of it to be printed.

{{infobox addon
| name = Log time-stamper add-on
| started = 6 August 2024
| desc =
| contributors = {{usr|Johan G}}
| status = Under development
| coderepo = https://gitlab.com/JohanG/log-time-stamper
}}

The '''log time-stamper add-on''' will print time-stamps to the console and log, which can be useful when comparing timings of events with other resources.

== Features ==
FlightGear v. 2020.3.18 prints times-stamps each on line of the console output and log, but only with elapsed time of the FlightGear session.

This add-on prints timestamps to the console at configurable intervals. As of early August 2024 it can print the simulated UTC time, real local time, and, with some issues, real UTC time.

Additionally the add-on prints changes in
* Simulation rate, how fast the simulation is running.
* Time warp, if the time of day is running at at a different speed than the simulation rate.
* If FlightGear is paused or unpaused.
* If the Time Setter add-on by Colin<ref>See https://gitlab.com/colingeniet/flightgear-time-offset for his add-on.</ref> is enabled or disabled. It synchronizes the simulated time with real time, optionally with a number of hours offset.

Timestamps are printed in ISO 8601 / RFC 3339 format, in essence <code>YYYY-MM-DD"T"HH:MM:SS("Z"|("+"|"-")hh:mm:ss)</code>.

== Exposed properties ==
There are some exposed properties than can be configured through the <code>addon-config.xml</code> file or through the property tree.

These properties controls:
* The time-stamp interval
* If you want either of these time-stamps
** Simulated UTC time
** Real local time
** Real UTC time (though with some issues)

== Known issues ==
=== Real UTC time time-stamps ===
As of early August 2024 the real UTC time time-stamps ignores day rollovers, in essence if the offset and time makes it so that the UTC time would be on another day than the local real time day.

This means that days, months and years can be off by one.

=== The Time Setter add-on ===
The Time Setter add-on must be loaded before the time-stamper add-on for the time-stamper add-on to be able to print status changes of the Time Setter add-on.

This is due that to register a listener to the the relevant property, <code>/sim/time/time-setter/enable</code>, that property must exist. That property get initialized when the Time Setter add-on is loaded.

== Notes ==
<references/>

== Related content ==
=== Forum topic ===
* {{forum link |title=Log time-stamper add-on |t=42533}}

=== Source code ===
* {{gitlab url |user=JohanG |repo=log-time-stamper}}