FlightGear wiki - User contributions [en]

USB-HID

2026-04-03T09:15:49Z

Jsb:

[draft]

USB-HID (Human Interface Device) is one of the methods to connect input devices to FlightGear.

==Linux access rights for devices==
HID devices under linux have usually restricted access rights, e.g. normal users are not allowed to access them directly. As you should not run FlightGear as root user, you most likely need to create a few udev rules to allow normal users to access the device files.

First, use <code>lsusb</code> to get a list of all detected USB devices. The output should look similar to this:<syntaxhighlight lang="shell">
Bus 003 Device 004: ID 294b:1901 Honeycomb Aeronautical Bravo Throttle Quadrant
Bus 003 Device 006: ID 06a3:0763 Saitek PLC Pro Flight Rudder Pedals
Bus 003 Device 002: ID 294b:1900 Honeycomb Aeronautical Alpha Flight Controls
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 006 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 005 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

</syntaxhighlight>Find the lines containing your relevant input devices (joysticks, yoke, throttle, pedals, ...) and note the IDs. The format is <vendor-id>:<device-id>. For simplicity, this example uses only the vendor-id.

On Ubuntu, you can add for example the following file under <code>/etc/udev/rules.d</code> to allow r/w access to members of the <code>input</code> user group (or any user group you prefer). Of course, you have to add/modify the lines to match the vendor-ids of your devices and your user id (Linux login name) must be a member of the group mentioned in the rules.<syntaxhighlight lang="shell">
# /etc/udev/rules.d/40-usb-flightgear.rules
#
# To add your user to the input group try:
# sudo usermod --append --groups input <username>

# Honeycomb
SUBSYSTEMS=="usb", ATTRS{idVendor}=="294b", GROUP="input", MODE="0664"
# Saitek
SUBSYSTEMS=="usb", ATTRS{idVendor}=="06a3", GROUP="input", MODE="0664"
# Winctrl
SUBSYSTEMS=="usb", ATTRS{idVendor}=="4098", GROUP="input", MODE="0664"
</syntaxhighlight>To activate the new rules, try <code>udevadm control --reload-rules && udevadm trigger</code>

If this does not help, a reboot will do.

==Developing Configuration files for input devices==

=== Gathering data ===
Add the following parameters to your FlightGear command line or via the launcher Settings>Additional Settings<syntaxhighlight>
--log-class=input
--log-level=debug
</syntaxhighlight>This will create a lot of debug output for the input systems in which you can find all events supported by your devices

=== Creating a config file ===
The configuration files shall be stored in FGDATA/Input/Event/<Vendor>/<Model>.xml

As a starting point you can copy this example. Replace the data as needed.<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<PropertyList>

<vendor-name>honeycomb</vendor-name>
<model-name>bravo</model-name>


<name>Honeycomb Aeronautical Bravo Throttle Quadrant</name>


<debug-events type="bool">false</debug-events>

<nasal>
<open>
<![CDATA[
#bravo = input_helpers.honeycomb.bravo.new(cmdarg());
]]>
</open>
<close>
<![CDATA[
#if (ishash(bravo) and isfunc(bravo['close']))
# bravo.close(cmdarg());
]]>
</close>
</nasal>

</PropertyList>
</syntaxhighlight>Example for an axis event:<syntaxhighlight lang="xml">
<event>
<desc>Lever 0</desc>
<name>abs-x-translate</name>
<min-range>-1023</min-range>
<max-range>1023</max-range>
<binding>
<command>property-scale</command>
<property>/input/honeycomb/bravo/lever[0]</property>
</binding>
</event>
</syntaxhighlight>Example for a button event:<syntaxhighlight lang="xml">
<event>
<name>button-1</name>
<desc>AP mode HDG</desc>
<repeatable>false</repeatable>
<binding>
<command>property-assign</command>
<property>/input/honeycomb/bravo/buttons/hdg</property>
<value>1</value>
</binding>
<mod-up>
<binding>
<command>property-assign</command>
<property>/input/honeycomb/bravo/buttons/hdg</property>
<value>0</value>
</binding>
</mod-up>
</event>
</syntaxhighlight>

==Status of OS support==
Linux: Supported

MacOS: supported?

Windows: not yet supported?

== see also ==
[[Input helpers]]

[[Honeycomb Input Devices]]

Input helpers

2026-04-02T20:03:35Z

Jsb: Corrections

== Overview ==
This page is about Nasal script code for input devices like joysticks, yokes, throttle quadrants and pedals. While small scripts can be easily added directly into joystick <binding>, larger code blocks should be organized a bit differently.

As always: "do not repeat yourself" = to make everyones live easier, code should not be copy&pasted but put into a "central" place as functions or classes and be called whenever, wherever needed. This way maintenance has to be done only in one place.

== input_helpers namespace ==
Input helper code should be stored in FGDATA/Nasal/input_helpers/<vendorname>.nas

To avoid clashes, there should be one file per vendor and in each of these files a namespace (hash) for this vendor shall be created.

See honeycomb.nas for an example:<syntaxhighlight lang="shell">
#
# Helpers for Honeycomb input devices
#

# !!! Abbreviated sample !!!
# Check FGDATA repository for latest full version

# namespace
var honeycomb = {};

# Helper for the Honeycomb Alpha Yoke
honeycomb["alpha"] = {
new: func(cfgnode) {
var m = {
parents: [me, input_helpers.config_manager.new(cfgnode)],
};
return m;
},
# abreviated file
};
</syntaxhighlight>

== config_manager - supporting config variants for a device ==
The <code>input_helpers.config_manager</code> class is designed to allow configuration variants for an input device to be defined within a single XML config file.

Why? Take the Honeycomb Bravo throttle quadrant as an example. It supports six levers with replaceable lever "heads", one set for airliners and another one for GA single and dual engine models, so you can configure the hardware with levers from single throttle/mixture up to four jet engines.

Now, you need a way to tell FlightGear, what levers you put onto your throttle quadrant and how to interprete the lever inputs. To avoid juggling with XML files, we simply put the limited number of variants into the XML and let the config_manager do the rest.

If XML files containing <config-variants> are loaded during startup, config_manager will show a popup hint about this fact and open a dialog to select the desired config variant.

The selection is added to aircraft.data and thus is safed per aircraft for convenience.<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<PropertyList>
<vendor-name>honeycomb</vendor-name>
<model-name>bravo</model-name>
<name>Honeycomb Aeronautical Bravo Throttle Quadrant</name>

<debug-events type="bool">false</debug-events>
<hid-debug-raw type="bool">false</hid-debug-raw>


<nasal>
<open>
<![CDATA[
print("Honeycomb Bravo Nasal (event) open");
bravo = input_helpers.honeycomb.bravo.new(cmdarg());
]]>
</open>
<close>
<![CDATA[
print("Honeycomb Bravo Nasal (event) close");
if (ishash(bravo) and isfunc(bravo['close']))
bravo.close(cmdarg());
]]>
</close>
</nasal>

<config-variants>
<variant>

<id>jet2</id>

<description>Airliner (two engines)</description>


<mapping>
<input>/input/honeycomb/bravo/lever[0]</input>
<output>/controls/flight/speed-brake</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[2]</input>
<output>/controls/engines/engine[0]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[3]</input>
<output>/controls/engines/engine[1]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever-down-button[2]</input>
<output>/controls/engines/engine[0]/cutoff</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever-down-button[3]</input>
<output>/controls/engines/engine[1]/cutoff</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/reverser[2]</input>
<output>/controls/engines/engine[0]/reverser</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/reverser[3]</input>
<output>/controls/engines/engine[1]/reverser</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[5]</input>
<output>/controls/flaps-lever-continuous</output>
</mapping>
</variant>
<variant>
<id>tm</id>
<description>Throttle/Mixture</description>
<mapping>
<input>/input/honeycomb/bravo/lever[0]</input>
<output>/controls/engines/engine[0]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[1]</input>
<output>/controls/engines/engine[0]/mixture</output>
</mapping>
</variant>
<variant>
<id>tpm</id>
<description>Throttle/Prop/Mixture</description>
<mapping>
<input>/input/honeycomb/bravo/lever[0]</input>
<output>/controls/engines/engine[0]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[1]</input>
<output>/controls/engines/engine[0]/propeller-pitch</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[2]</input>
<output>/controls/engines/engine[0]/mixture</output>
</mapping>
</variant>
</config-variants>

</PropertyList>
</syntaxhighlight>

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

[[Honeycomb Input Devices]]
[[Category:Nasal]]
[[Category:Joysticks and Yokes]]

USB-HID

2026-04-02T20:02:21Z

Jsb: Corrections

[draft]

USB-HID (Human Interface Device) is one of the methods to connect input devices to FlightGear.

==Linux access rights for devices==
HID devices under linux have usually restricted access rights, e.g. normal users are not allowed to access them directly. As you should not run FlightGear as root user, you most likely need to create a few udev rules to allow normal users to access the device files.

First, use <code>lsusb</code> to get a list of all detected USB devices. The output should look similar to this:<syntaxhighlight lang="shell">
Bus 003 Device 004: ID 294b:1901 Honeycomb Aeronautical Bravo Throttle Quadrant
Bus 003 Device 006: ID 06a3:0763 Saitek PLC Pro Flight Rudder Pedals
Bus 003 Device 002: ID 294b:1900 Honeycomb Aeronautical Alpha Flight Controls
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 006 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 005 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

</syntaxhighlight>Find the lines containing your relevant input devices (joysticks, yoke, throttle, pedals, ...) and note the IDs. The format is <vendor-id>:<device-id>. For simplicity, this example uses only the vendor-id.

On Ubuntu, you can add for example the following file under <code>/etc/udev/rules.d</code> to allow r/w access to members of the <code>input</code> user group. Of course, you have to add/modify the lines to match the vendor-ids of your devices and your user id must be a member of the group.<syntaxhighlight lang="shell">
# /etc/udev/rules.d/40-usb-flightgear.rules
#
# To add your user to the input group try:
# sudo usermod --append --groups input <username>

# Honeycomb
SUBSYSTEMS=="usb", ATTRS{idVendor}=="294b", GROUP="input", MODE="0664"
# saitek
SUBSYSTEMS=="usb", ATTRS{idVendor}=="06a3", GROUP="input", MODE="0664"

</syntaxhighlight>To activate the new rules, try <code>udevadm control --reload-rules && udevadm trigger</code>

If this does not help, a reboot will do.

==Developing Configuration files for input devices==

=== Gathering data ===
Add the following parameters to your FlightGear command line or via the launcher Settings>Additional Settings<syntaxhighlight>
--log-class=input
--log-level=debug
</syntaxhighlight>This will create a lot of debug output for the input systems in which you can find all events supported by your devices

=== Creating a config file ===
The configuration files shall be stored in FGDATA/Input/Event/<Vendor>/<Model>.xml

As a starting point you can copy this example. Replace the data as needed.<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<PropertyList>

<vendor-name>honeycomb</vendor-name>
<model-name>bravo</model-name>


<name>Honeycomb Aeronautical Bravo Throttle Quadrant</name>


<debug-events type="bool">false</debug-events>

<nasal>
<open>
<![CDATA[
#bravo = input_helpers.honeycomb.bravo.new(cmdarg());
]]>
</open>
<close>
<![CDATA[
#if (ishash(bravo) and isfunc(bravo['close']))
# bravo.close(cmdarg());
]]>
</close>
</nasal>

</PropertyList>
</syntaxhighlight>Example for an axis event:<syntaxhighlight lang="xml">
<event>
<desc>Lever 0</desc>
<name>abs-x-translate</name>
<min-range>-1023</min-range>
<max-range>1023</max-range>
<binding>
<command>property-scale</command>
<property>/input/honeycomb/bravo/lever[0]</property>
</binding>
</event>
</syntaxhighlight>Example for a button event:<syntaxhighlight lang="xml">
<event>
<name>button-1</name>
<desc>AP mode HDG</desc>
<repeatable>false</repeatable>
<binding>
<command>property-assign</command>
<property>/input/honeycomb/bravo/buttons/hdg</property>
<value>1</value>
</binding>
<mod-up>
<binding>
<command>property-assign</command>
<property>/input/honeycomb/bravo/buttons/hdg</property>
<value>0</value>
</binding>
</mod-up>
</event>
</syntaxhighlight>

==Status of OS support==
Linux: Supported

MacOS: supported?

Windows: not yet supported?

== see also ==
[[Input helpers]]

[[Honeycomb Input Devices]]

USB-HID

2026-04-01T21:11:58Z

Jsb: /* Creating a config file */

[draft]

USB-HID (Human Interface Device) is one of the methods to connect input devices to FlightGear.

==Linux access rights for devices==
HID devices under linux have usually restricted access rights, e.g. normal users are not allowed to access them directly. As you should not run FlightGear as root user, you most likely need to create a few udev rules to allow normal users to access the device files.

First, use <code>lsusb</code> to get a list of all detected USB devices. The output should look similar to this:<syntaxhighlight lang="shell">
Bus 003 Device 004: ID 294b:1901 Honeycomb Aeronautical Bravo Throttle Quadrant
Bus 003 Device 006: ID 06a3:0763 Saitek PLC Pro Flight Rudder Pedals
Bus 003 Device 002: ID 294b:1900 Honeycomb Aeronautical Alpha Flight Controls
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 006 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 005 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

</syntaxhighlight>Find the lines containing your relevant input devices (joysticks, yoke, throttle, pedals, ...) and note the IDs. The format is <vendor-id>:<device-id>. For simplicity, this example uses only the vendor-id.

On Ubuntu, you can add for example the following file under <code>/etc/udev/rules.d</code> to allow r/w access to members of the <code>input</code> user group. Of course, you have to add/modify the lines to match the vendor-ids of your devices and your user id must be a member of the group.<syntaxhighlight lang="shell">
# /etc/udev/rules.d/40-usb-flightgear.rules
#
# To add your user to the input group try:
# sudo usermod --append --groups input <username>

# Honeycomb
SUBSYSTEMS=="usb", ATTRS{idVendor}=="294b", GROUP="input", MODE="0664"
# saitek
SUBSYSTEMS=="usb", ATTRS{idVendor}=="06a3", GROUP="input", MODE="0664"

</syntaxhighlight>To activate the new rules, try <code>udevadm control --reload-rules && udevadm trigger</code>

If this does not help, a reboot will do.

==Developing Configuration files for input devices==

=== Gathering data ===
Add the following parameters to your FlightGear command line or via the launcher Settings>Additional Settings<syntaxhighlight>
--log-class=input
--log-level=debug
</syntaxhighlight>This will create a lot of debug output for the input systems in which you can find all events supported by your devices

=== Creating a config file ===
The configuration files shall be stored in FGDATA/Input/Event/<Vendor>/<Model>.xml

As a starting point you can copy this example. Replace the data as needed.<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<PropertyList>

<vendor-id>honeycomb</vendor-id>
<model-id>bravo</model-id>


<name>Honeycomb Aeronautical Bravo Throttle Quadrant</name>


<debug-events type="bool">false</debug-events>

<nasal>
<open>
<![CDATA[
#bravo = input_helpers.honeycomb.bravo.new(cmdarg());
]]>
</open>
<close>
<![CDATA[
#if (ishash(bravo) and isfunc(bravo['close']))
# bravo.close(cmdarg());
]]>
</close>
</nasal>

</PropertyList>
</syntaxhighlight>Example for an axis event:<syntaxhighlight lang="xml">
<event>
<desc>Lever 0</desc>
<name>abs-x-translate</name>
<min-range>-1023</min-range>
<max-range>1023</max-range>
<binding>
<command>property-scale</command>
<property>/input/honeycomb/bravo/lever[0]</property>
</binding>
</event>
</syntaxhighlight>Example for a button event:<syntaxhighlight lang="xml">
<event>
<name>button-1</name>
<desc>AP mode HDG</desc>
<repeatable>false</repeatable>
<binding>
<command>property-assign</command>
<property>/input/honeycomb/bravo/buttons/hdg</property>
<value>1</value>
</binding>
<mod-up>
<binding>
<command>property-assign</command>
<property>/input/honeycomb/bravo/buttons/hdg</property>
<value>0</value>
</binding>
</mod-up>
</event>
</syntaxhighlight>

==Status of OS support==
Linux: Supported

MacOS: supported?

Windows: not yet supported?

== see also ==
[[Input helpers]]

[[Honeycomb Input Devices]]

Nasal library/props

2026-03-24T20:02:07Z

Jsb: Remove wrong notes regarding performance .

{{Nasal Navigation|nocat=1}}
This page contains documentation for the '''<code>props</code> namespace''' in [[Nasal]]. This namespace provides APIs for working with property trees (including the main [[Property Tree]]) via {{API Link|simgear|class|SGPropertyNode}}. The <code>props</code> namespace is sourced from {{fgdata source|Nasal/props.nas}} and {{flightgear source|src/Scripting/nasal-props.cxx}}.

== Class ==
=== Node ===
{{Nasal doc
|mode = class
|text = The main class, used widely for manipulating property trees.
}}
==== new() ====
{{Nasal doc
|syntax = props.Node.new([values]);
|text = Constructor function. Returns a new <code>props.Node</code> instance.
|param1 = values
|param1text = An optional hash that will be the initial property structure.
|example1 = var node = props.Node.new();
props.dump(node);
|example2 = var tree = {
a: 1,
b: ["a", "b", "c"],
c: {
d: 1 * 4
}
};

var node = props.Node.new(tree);
props.dump(node);
}}

==== addChild() ====
{{Nasal doc
|syntax = props.Node.addChild(name[, min_idx[, append]]);
|version = 2.10
|commit = {{fgdata commit|a15d5829379864c7138edff621d6864c5f426d0b|t=commit}}
|text = Add a new, blank child to the node. Returns the newly-created node.
|param1 = name
|param1text = The name of the node as a string.
|param2 = min_idx
|param2text = This specifies the minimum index to add the new one to. This takes precedence over '''append'''. Defaults to 0.
|param3 = append
|param3text = If there is already one or more children with the same name and this argument is true (1), the new child will be added after the child with the highest index. If false (0), the new child will be added at the lowest available index with the limit of '''min_idx'''. Defaults to true (1).
|example1 = var node = props.Node.new();
node.addChild("a");
props.dump(node);
|example2 = var node = props.Node.new();
node.addChild("a", 1);
props.dump(node); # a[1]
|example3 = var node = props.Node.new();
node.addChild("a", 1);
props.dump(node); # a[1]
node.addChild("a", 0, false);
props.dump(node); # a[1] and a[0]
|example4 = var node = props.Node.new();
node.addChild("a", 1);
props.dump(node); # a[1]
node.addChild("a", 0, true);
props.dump(node); # a[1] and a[2]
}}

==== addChildren() ====
{{Nasal doc
|syntax = props.Node.addChildren(name, count[, min_idx[, append]]);
|version = 2.10
|commit = {{fgdata commit|7f1117a5374beabb045fb76fbb6dd8bfb0128100|t=commit}}
|text = Adds multiple children with the same name to this node. Returns <code>'''nil</code>.
|param1 = name
|param1text = The name of the nodes as a string.
|param2 = count
|param2text = Number of new children to add.
|param3 = min_idx
|param3text = Performs the same function as in <code>[[#addChild.28.29|Node.addChild()]]</code>.
|param4 = append
|param4text = Performs the same function as in <code>[[#addChild.28.29|Node.addChild()]]</code>.
|example1 = var node = props.Node.new();
node.addChildren("a", 2);
props.dump(node); # a[0] and a[1]
|example2 = var node = props.Node.new();
node.addChildren("a", 2, 1);
props.dump(node); # a[1] and a[2]
|example3 = var node = props.Node.new();
node.addChild("a", 2);
props.dump(node); # a[2]
node.addChildren("a", 2, 0, 0);
props.dump(node); # a[2], a[0], and a[1]
}}

==== adjustValue() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.adjustValue(delta);
|text = Adds delta (numeric) to current value respecting the node type.
|param1 = delta
|param1text = Numeric value (can be negative) to add to current node value.
}}

==== alias() ====
{{Nasal doc
|syntax = props.Node.alias(node, chainListener=0);
|text = Aliases this node to another one. Returns 1 on success and 0 on failure.
|param1 = node
|param1text = The node to alias to. Can be one of:
* A path to a property in the [[Property Tree]] as a string.
* A <code>prop</code> ghost.
* A <code>props.Node</code> object.
|example1 = var node = props.Node.new();
node.alias("/position/altitude-ft");
props.dump(node); # equals the current altitude
|example2 = var node1 = props.Node.new();
node1.setDoubleValue(2.34);
var node2 = props.Node.new();
node2.alias(node1);
props.dump(node2); # equals 2.34
|param2=chainListener|param2text=Specify if listeners should work on aliased properties or not. Current default is false forbackwards compatability.}}

==== clearValue() ====
{{Nasal doc
|syntax = props.Node.clearValue();
|text = Clears the value and type of the node.
|example1 = var node = props.Node.new();
node.setDoubleValue(2.34);
props.dump(node); # prints "{DOUBLE} = 2.35"
node.clearValue();
props.dump(node); # prints "{NONE} = nil"
}}

==== decrement() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.decrement(n = 1);
|text = Decrements integer property by n (default: n = 1)
|param1 = n
|param1text = Value to subtract, will be converted to int, defaults to 1
}}

==== equals() ====
{{Nasal doc
|syntax = props.Node.equals(node);
|version = 2.12
|commit = {{fgdata commit|d80722065f3c11e0511fa888b1f5f310dd0183e3|t=commit}}
|text = Checks whether the node refers to the same one as another. Returns 1 (true) if it is, and 0 (false) if otherwise.
|param1 = node
|param1text = Node to check against. May be either a <code>prop</code> ghost or a <code>props.Node</code> object.
|example1 = var n = props.Node.new();
var a = n;
print(a.equals(n)); # prints "1" (true)
}}

==== getAliasTarget() ====
{{Nasal doc
|syntax = props.Node.getAliasTarget();
|text = Returns the alias target of a node as another <code>props.Node</code> instance.
|example1 = setprop("/test", 2.35);
var node = props.Node.new();
node.alias("/test");
var tgt = node.getAliasTarget();
print(tgt.getPath()); # prints "/test"
}}

==== getAttribute() ====
{{Nasal doc
|syntax = props.Node.getAttribute([rel_path, ]name);
props.Node.getAttribute();
|text = Returns an attribute. If no arguments are given, the function will return an integer specifying the attributes set for the node (see {{simgear source|simgear/props/props.hxx|l=767}} for a list). A list of attributes are below
{{{!}} class="wikitable"
! String !! Return value
{{!-}}
{{!}} last {{!!}} The highest used attribute code (should be 128). See for {{simgear source|simgear/props/props.hxx|l=767}} the codes.
{{!-}}
{{!}} children {{!!}} Number of child nodes.
{{!-}}
{{!}} listeners {{!!}} Number of listeners connected to this node.
{{!-}}
{{!}} references {{!!}} Number of times the node has previously been referenced.
{{!-}}
{{!}} tied {{!!}} Whether the node is tied.
{{!-}}
{{!}} alias {{!!}} Whether the node is aliased.
{{!-}}
{{!}} readable {{!!}} Whether the node can be read.
{{!-}}
{{!}} writable {{!!}} Whether the node can be written to.
{{!-}}
{{!}} archive {{!!}} Whether the node will be saved when the "save" [[fgcommands|fgcommand]] is triggered.
{{!-}}
{{!}} trace-read {{!!}} Whether the reading of the node will be logged when <code>--log-level=info</code>.
{{!-}}
{{!}} trace-write {{!!}} Whether the writing to the node will be logged when <code>--log-level=info</code>.
{{!-}}
{{!}} userarchive {{!!}} Whether the node will be saved to the [[FlightGear configuration via XML#autosave.xml|autosave file]] (only works for actual properties).
{{!-}}
{{!}} preserve {{!!}} Whether the value of node will be preserved during resets (only works for actual properties).
{{!}}}
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = name
|param2text = Attribute as a string. See the above table for a full list.
|example1 = var node = props.Node.new();
var child = node.addChild("a");
print(node.getAttribute("children")); # prints "1"
|example2text = Example using relative path
|example2 = var node = props.Node.new();
var child = node.addChild("a");
print(node.getAttribute("a", "readable")); # prints "1" (node can be read from)
|example3 = var node = props.Node.new();
var node2 = props.Node.new();
node2.alias(node);
print(node2.getAttribute("alias")); # prints "1" (true)
|example4 = print(props.globals.getNode("/sim/signals/fdm-initialized").getAttribute("listeners")); # prints the number of listeners
|example5 = print(props.globals.getNode("/sim/time/elapsed-sec").getAttribute("tied")); # prints "1" (true), meaning it is tied
|example6 = var node = props.Node.new();
print(node.getAttribute("writable")); # prints "1" (true), meaning the node can be written to
|example7text = Example using no arguments
|example7 = var node = props.Node.new();
print(node.getAttribute()); # prints "3" (true), meaning the node can be read from (1) and written to (2)
}}

==== getBoolValue() ====
{{Nasal doc
|syntax = props.Node.getBoolValue();
|text = Returns the value of a node converted to a boolean. If the node is a number type, 0 will return false, while 1 will return true. If the node is a string or unspecified type and the value is <code>"false"</code>, false will be returned. Otherwise, true will be returned. Remember that boolean values are represented in Nasal as 1 (true) and 0 (false).
|example1 = var node = props.Node.new();
node.setBoolValue(1);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setBoolValue(0);
print(node.getBoolValue() ? "true" : "false"); # prints "false"
|example2 = var node = props.Node.new();
node.setDoubleValue(1.23);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setDoubleValue(-1.23);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setDoubleValue(0.0);
print(node.getBoolValue() ? "true" : "false"); # prints "false"
|example3 = var node = props.Node.new();
node.setIntValue(2);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setIntValue(-2);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setIntValue(0);
print(node.getBoolValue() ? "true" : "false"); # prints "false"
|example4 = var node = props.Node.new();
node.setValue("Hello, World!");
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setValue("false");
print(node.getBoolValue() ? "true" : "false"); # prints "false"
}}

==== getChild() ====
{{Nasal doc
|syntax = props.Node.getChild(rel_path[, idx[, create]]);
|text = Returns a child of a node as another <code>props.Node</code> instance.
|param1 = rel_path
|param1text = Relative path to the child node as a string.
|param2 = idx
|param2text = Optional index for the child node as an integer.
|param3 = create
|param3text = If set to true (1), a new child will be created if it does not exist. If set to false (0), the function will not create a new child and the function will return <code>'''nil'''</code> if no child exists. Defaults to false.
|example1 = var node = props.Node.new();
node.addChild("a");
var c = node.getChild("a");
|example2 = var node = props.Node.new();
node.addChildren("a", 3);
node.getNode("a[1]").setDoubleValue(2.35);
var c = node.getChild("a", 1);
print(c.getValue()); # prints "2.35"
|example3 = var node = props.Node.new();
var c = node.getChild("a", 1, true);
props.dump(node); # new child a[1] will have appeared
}}

==== getChildren() ====
{{Nasal doc
|syntax = props.Node.getChildren([name]);
|text = Returns a vector of child nodes, optionally those with a certain name, as <code>props.Node</code> instances.
|param1 = name
|param1text = Optional name of the child nodes as a string. If not given, all children will be returned.
|example1 = var node = props.Node.new();
node.addChildren("a", 3);
node.addChildren("b", 3);
debug.dump(node.getChildren()); # all child nodes in the vector
|example2 = var node = props.Node.new();
node.addChildren("a", 3);
node.addChildren("b", 3);
debug.dump(node.getChildren("b")); # only children with the name "b" in the vector
}}

==== getIndex() ====
{{Nasal doc
|syntax = props.Node.getIndex();
|text = Returns the index of a node as an integer.
|example1 = var node = props.Node.new();
node.addChildren("a", 3);
print(node.getChild("a", 1).getIndex()); # prints "1"
|example2 = var node = props.Node.new();
node.addChild("b");
print(node.getChild("b").getIndex()); # prints "0"
}}

==== getName() ====
{{Nasal doc
|syntax = props.Node.getName();
|text = Returns the name of the node as a string.
|example1 = var node = props.Node.new();
var c = node.addChild("a");
debug.dump(c.getName()); # prints "a"
|example2 = var node = props.Node.new();
node.addChildren("a", 3);
debug.dump(node.getChild("a", 2).getName()); # prints "a"
}}

==== getNode() ====
{{Nasal doc
|syntax = props.Node.getNode(rel_path[, create]);
|text = Returns a subnode as another <code>props.Node</code> instance.
|param1 = rel_path
|param1text = Relative path to the subnode as a string.
|param2 = create
|param2text = If true (1), the node will be created if it does not exist. If false (0) and the node does not exist, the function will return <code>'''nil'''</code>. Default to false (0).
|example1 = var tree = {
"a": 1,
"b": "Hi",
"c": {
"d": "Hello, World!"
}
};
var node = props.Node.new(tree);
print(node.getNode("c/d").getValue()); # prints "Hello, World!"
|example2 = var tree = {
"a": 1,
"b": "Hi",
"c": {}
};
var node = props.Node.new(tree);
node.getNode("c/d", true).setDoubleValue(2.35);
props.dump(node); # c/d now exists
|example3 = var ac = props.globals.getNode("sim/aircraft");
print("Current aircraft is: ", ac.getValue());
}}

==== getParent() ====
{{Nasal doc
|syntax = props.Node.getParent();
|text = Returns the parent of a node, or <code>'''nil'''</code> if there is no parent.
|example1 = var tree = {
"a": 1,
"b": "Hi",
"c": {
"d": "Hello, World!"
}
};
var node = props.Node.new(tree);
props.dump(node.getNode("c/d").getParent()); # dumps "c"
|example2 = var node = props.Node.new();
debug.dump(node.getParent()); # prints nil
}}

==== getPath() ====
{{Nasal doc
|syntax = props.Node.getPath();
|text = Returns the path of the node as a string.
|example1 = var tree = {
"a": 1,
"b": "Hi",
"c": {
"d": "Hello, World!"
}
};
var node = props.Node.new(tree);
print(node.getNode("c/d").getPath()); # prints "/c/d"
}}

==== getType() ====
{{Nasal doc
|syntax = props.Node.getType();
|text = Returns node's type as a string. It should be one of "NONE", "ALIAS", "BOOL", "INT", "LONG" (long integer), "FLOAT", "DOUBLE", "STRING", "VEC3D", "VEC4D", "UNSPECIFIED".
|example1 = var node = props.Node.new();
print(node.getType()); # prints "NONE"
|example2 = var node = props.Node.new();
node.setIntValue(12);
print(node.getType()); # prints "INT"
|example3 = var node = props.Node.new();
node.setValue([0.4, 0.2, 1]);
debug.dump(node.getValue()); # prints "[0.4, 0.2, 1]"
print(node.getType()); # prints "VEC3D"
}}

==== getValue() ====
{{Nasal doc
|syntax = props.Node.getValue([rel_path]);
|text = {{hatnote|See also {{func link|getBoolValue()|page=this}}.}}

Returns the value of the node.
|param1 = rel_path
|param1text = Optional relative path to a subnode as a string, which may contain '/' characters. If the subnode does not exist, we return nil.
|example1 = var node = props.Node.new();
node.setDoubleValue(2.35);
print(node.getValue()); # prints "2.35"
|example2 = var node = props.Node.new();
node.setValue("Hi");
print(node.getValue()); # prints "Hi"
|example3 = var node = props.Node.new();
node.addChild("a").setValue("Hi");
print(node.getValue("a")); # prints "Hi"
|example4 = var node = props.Node.new();
node.setValue([0, 0.5, 1]);
debug.dump(node.getValue()); # prints "[0, 0.5, 1]"
}}

==== getValues() ====
{{Nasal doc
|syntax = props.Node.getValues();
|text = Returns the node tree as a hash, with all the various subnodes, etc. If the node has no children, the result is equivalent to {{func link|getValue()|page=this}}. Subnodes that are indexed will be combined into one key and their values placed in a vector (see example 2).
|example1 = var tree = {
"string": "Hi",
"number": 1.2,
"subnode": {
"idx-node": [1, 2, 3]
}
};
var node = props.Node.new(tree);
node.addChild("bool").setBoolValue(1);
props.dump(node); # dump to node tree
debug.dump(node.getValues()); # dump the node converted to hash
|example2 = var tree = {
"a": [1, 2, 3]
};
var node = props.Node.new(tree);
props.dump(node); # a[0] = 1, a[1] = 2, a[2] = 3
debug.dump(node.getValues()); # a: [1, 2, 3]
}}

==== increment() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.increment(n = 1);
|text = Increments integer property by n (default: n = 1)
|param1 = n
|param1text = Value to add, will be converted to int, defaults to 1
}}

==== initNode() ====
{{Nasal doc
|syntax = props.Node.initNode([path[, value[, type[, force]]]]);
|text = Initializes a node if it doesn't exist and returns that node as a <code>props.Node</code> object.
|param1 = path
|param1text = Optional path to a subnode as a string. If not given, the node itself will be initialized.
|param2 = value
|param2text = Optional default value to initialize the node with.
|param3 = type
|param3text = Optional string that will set the type of the node. Must be one of <code>"DOUBLE"</code>, <code>"INT"</code>, <code>"BOOL"</code>, or <code>"STRING"</code>.
|param4 = force
|param4text = If set to true (1), the node's type will be forced to change.
|example1 = var node = props.Node.new();
var a = node.initNode("a");
props.dump(a);
|example2 = var node = props.Node.new();
var a = node.initNode("a", "Hi");
props.dump(a);
|example3 = var node = props.Node.new();
var a = node.initNode("a", 1.25, "INT");
props.dump(a); # a = 1
|example4 = var node = props.Node.new();
node.addChild("a").setBoolValue(0);
props.dump(node.getChild("a")); # a = 0 (type: bool)
var a = node.initNode("a", 1.25, "INT", true);
props.dump(a); # a = 0 (type: int)
}}

==== isInt() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.isInt();
|text = Returns true (1) if node '''type''' is "INT" or "LONG" (long integer) otherwise false (0).
}}

==== isNumeric() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.isNumeric();
|text = Returns true (1) if node '''type''' is "INT", "LONG", "FLOAT" or "DOUBLE" otherwise false (0).
}}

==== remove() ====
{{Nasal doc
|syntax = props.Node.remove();
|text = Removes the node and returns the removed node.
|example1 = var node = props.Node.new();
node.addChild("a");
props.dump(node);
node.getChild("a").remove();
props.dump(node); # child "a" does not exist anymore
}}

==== removeAllChildren() ====
{{Caution|Be careful when using this API in conjunction with the Canvas system and element specific properties, for details please see [[Howto:Canvas Path Benchmarking]]}}
{{Nasal doc
|syntax = props.Node.removeAllChildren();
|version = 3.2
|commit = {{fgdata commit|4766ed21a68230c0c15265e5604a74f4d99e0f5d|t=commit}}
|text = Removes all child nodes and returns the node.
|example1 = var tree = {
"a": 1,
"b": 2,
"c": 3
};
var node = props.Node.new(tree);
props.dump(node);
node.removeAllChildren();
props.dump(node); # all children have been removed
}}

==== removeChild() ====
{{Nasal doc
|syntax = props.Node.removeChild(rel_path, idx);
|text = Removes a given child node child nodes and returns the node.
|param1 = rel_path
|param1text = Relative path to a subnode as a string.
|param2 = idx
|param2text = Index of the subnode to remove as an integer.
|example1 = var node = props.Node.new();
node.addChild("a");
props.dump(node);
node.removeChild("a", 0);
props.dump(node); # child "a" has been removed
|example2 = var node = props.Node.new();
node.addChildren("a", 2);
props.dump(node);
node.removeChild("a", 0);
props.dump(node); # just a[1] remains
}}

==== removeChildren() ====
{{Nasal doc
|syntax = props.Node.removeChildren([name]);
|text = Removes all children with a specified name. If no arguments are given, all children will be removed (see also {{func link|removeAllChildren()|page=this}}).
|param1 = name
|param1text = Optional name of children to remove as a string.
|example1 = var node = props.Node.new();
node.addChildren("a", 2);
node.addChildren("b", 2);
props.dump(node);
node.removeChildren("a");
props.dump(node); # just children named "b" remain
|example2 = var node = props.Node.new();
node.addChildren("a", 2);
node.addChildren("b", 2);
props.dump(node);
node.removeChildren();
props.dump(node); # all children removed
}}

==== setAttribute() ====
{{Nasal doc
|syntax = props.Node.setAttribute([rel_path, ]attr, value);
props.Node.setAttribute(attrs);
|text = Sets an attribute or multiple attributes. A list of attributes and their codes are below. For a brand new node, the default attributes are ''readable'' and ''writable''. Returns an integer specifying the old attributes.
{{{!}} class="wikitable"
! String !! Description
{{!-}}
{{!}} readable {{!!}} Whether the node can be read.
{{!-}}
{{!}} writable {{!!}} Whether the node can be written to.
{{!-}}
{{!}} archive {{!!}} Whether the node will be saved when the "save" [[fgcommands|fgcommand]] is triggered.
{{!-}}
{{!}} trace-read {{!!}} Whether the reading of the node will be logged when <code>--log-level=info</code>.
{{!-}}
{{!}} trace-write {{!!}} Whether the writing to the node will be logged when <code>--log-level=info</code>.
{{!-}}
{{!}} userarchive {{!!}} Whether the node will be saved to the [[FlightGear configuration via XML#autosave.xml|autosave file]] (only works for actual properties).
{{!-}}
{{!}} preserve {{!!}} Whether the value of node will be preserved during resets (only works for actual properties).
{{!}}}
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = attr
|param2text = Name of attribute to set as a string. See above.
|param3 = value
|param3text = Boolean value to set the property to.
|param4 = attrs
|param4text = When the function is used in its second form, this argument is used. This argument should be an integer specifying which arguments are set to true. See {{simgear source|simgear/props/props.hxx|l=767}} for the full list of codes. Simply add codes of the desired attributes together.
|example1 = var node = props.Node.new();
node.setAttribute("trace-write", 1);
node.setIntValue(12); # will be traced
|example2 = var node = props.Node.new();
node.setAttribute("readable", 0);
var val = node.getValue();
debug.dump(val); # prints "nil"
|example3 = var node = props.Node.new();
node.addChild("a");
node.setAttribute("a", "trace-write", 1);
node.getChild("a").setIntValue(12); # will be traced
|example4 = var node = props.Node.new();
node.setAttribute(35); # read + write + trace-write
node.setIntValue(12); # will be traced
}}

==== setBoolValue() ====
{{Nasal doc
|syntax = props.Node.setBoolValue([rel_path, ]value);
|text = Sets a node to a boolean value. If the node has no type, it will be set to a bool type. If the node is already a number type, it will be set to either 1 or 0. If it is a string, it will be set to either "true" or "false". Returns 1 (true) if the operation was successful.
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = value
|param2text = Value to set the node to, will be interpreted into a boolean. If it is <code>'''nil'''</code>, it will be false. If it is a string, it will be false. If it is a number, 0 will be false, while other numbers will be true. All other cases will be interpreted as 0.
|example1 = var node = props.Node.new();
node.setBoolValue(nil);
props.dump(node); # node = 0 (false)
|example2 = var node = props.Node.new();
node.setBoolValue("Hi");
props.dump(node); # node = 1 (true)
|example3 = var node = props.Node.new();
node.setBoolValue(0);
props.dump(node); # node = 0 (false)
node.setBoolValue(1.25);
props.dump(node); # node = 1 (true)
|example4 = var node = props.Node.new();
node.setValue("String");
props.dump(node); # node = "String" (type: string)
node.setBoolValue(1);
props.dump(node); # node = "true"
|example5 = var node = props.Node.new();
node.setDoubleValue(12.32);
props.dump(node); # node = 12.32 (type: double)
node.setBoolValue(1);
props.dump(node); # node = 1
|example6 = var node = props.Node.new();
node.addChild("a");
node.setBoolValue("a", 1);
props.dump(node); # /a = 1
}}

==== setDoubleValue() ====
{{Nasal doc
|syntax = props.Node.setDoubleValue([rel_path, ]value);
|text = Sets a node to a double value. If the node has no type, it will be set to a double type. If the node is a bool, values different from zero will be interpreted as true. If the node is a string, the value will be converted to a string. If the node is an integer type, it will be truncated to the closest integer to zero. Returns 1 (true) if the operation was successful.
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = value
|param2text = Value to set the node to, will be interpreted into a double number. It must be a valid number or a string that can be converted to a number.
|example1 = var node = props.Node.new();
node.setDoubleValue(1.1);
props.dump(node); # node = 1.1 (type: double)
|example2 = var node = props.Node.new();
node.setDoubleValue("1.1");
props.dump(node); # node = 1.1 (type: double)
|example3 = var node = props.Node.new();
node.setBoolValue(1);
node.setDoubleValue("1.1");
props.dump(node); # node = 1 (type: bool)
node.setDoubleValue(0.0);
props.dump(node); # node = 0 (type: bool)
|example4 = var node = props.Node.new();
node.setIntValue(1);
node.setDoubleValue(1.1);
props.dump(node); # node = 1 (type: int)
node.setDoubleValue("-1.1");
props.dump(node); # node = -1 (type: int)
|example5 = var node = props.Node.new();
node.addChild("a");
node.setDoubleValue("a", 12.2);
props.dump(node); # /a = 12.2
}}

==== setIntValue() ====
{{Nasal doc
|syntax = props.Node.setIntValue([rel_path, ]value);
|text = Sets a node to an integer value. If the node has no type, it will be set to a integer type. If the node is a bool, values different from zero will be interpreted as true. If the node is a string, the value will be converted to a string. Returns 1 (true) if the operation was successful.
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = value
|param2text = Value to set the node to, will be interpreted into a integer. It must be a valid number or a string that can be converted to a number. If the number is a double, it will be truncated to the closest integer to zero.
|example1 = var node = props.Node.new();
node.setIntValue(12);
props.dump(node); # node = 12
node.setIntValue("6");
props.dump(node); # node = 6
|example2 = var node = props.Node.new();
node.setIntValue(12.2);
props.dump(node); # node = 12
node.setIntValue(-12.2);
props.dump(node); # node = 12
|example3 = var node = props.Node.new();
node.setBoolValue(1);
node.setIntValue(12.5);
props.dump(node); # node = 1 (type: bool)
node.setIntValue(0);
props.dump(node); # node = 0 (type: bool)
|example4 = var node = props.Node.new();
node.setValue("Hi");
node.setIntValue(12);
props.dump(node); # node = "12" (type: string)
|example5 = var node = props.Node.new();
node.addChild("a");
node.setIntValue("a", 12);
props.dump(node); # /a = 12
}}

==== setValue() ====
{{Nasal doc
|syntax = props.Node.setValue([rel_path, ]value);
|text = {{hatnote|See also {{func link|setBoolValue()|page=this}}, {{func link|setDoubleValue()|page=this}}, and {{func link|setIntValue()|page=this}}.}}

Sets a node to a given value. See table below for conversions and effects. Note that vec3d and vec4d types are not fully integrated into SGPropertyNode. Returns 1 (true) if the operation was successful.

{{{!}} class="wikitable"
{{!}} colspan="2" style="text-align:right" {{!}} '''value''' type →
! rowspan="2" {{!}} Number
! rowspan="2" {{!}} String
! rowspan="2" {{!}} Vector
{{!-}}
{{!}} style="text-align:left" {{!}} Current node<br>type ↓
{{!}} style="text-align:right" {{!}} Result ↘
{{!-}}
! colspan="2" {{!}} None/unspecified
{{!}}
* Type set to <code>double</code>
* Node set to '''value'''.
{{!}}
* Type set to <code>string</code>
* Node set to '''value'''.
{{!}}
* Type set to <code>vec*d</code>
* Node set to '''value'''.
{{!-}}
! colspan="2" {{!}} Bool
{{!}}
* If '''value''' != 0, node set to true.
* If '''value''' == 0, node set to false.
{{!}}
* If '''value''' == "true", node set to true.
* If '''value''' can be converted to an integer,<br>and != 0, node set to true.
{{!}} Node set to true.
{{!-}}
! colspan="2" {{!}} Integer
{{!}} Node set to truncated '''value'''
{{!}} Node set to '''value ''' converted and truncated to an integer.
{{!}} Node set to 1.
{{!-}}
! colspan="2" {{!}} Double
{{!}} Node set to '''value'''.
{{!}} Node set to '''value''' converted to number.
{{!}} Throws an error (vector is not a number).
{{!-}}
! colspan="2" {{!}} String
{{!}} Node set to '''value''' converted to string. {{!!}} Node set to '''value'''. {{!!}} Node not set.
{{!}}}
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = value
|param2text = Value to set the node to. Must be a string, a valid number, or a vector consisting of 3 or 4 numbers. See table above for conversions and effects.
|example1 = var node = props.Node.new();
node.setValue("Hi");
props.dump(node); # node = "Hi"
|example2 = var node = props.Node.new();
node.addChild("a");
node.setValue("a", "Hi");
props.dump(node); # \a = "Hi"
|example3 = var node = props.Node.new();
node.setValue([0.4, 0.2, 1]);
debug.dump(node.getValue()); # prints "[0.4, 0.2, 1]"
print(node.getType()); # prints "VEC3D"
}}

==== setValues() ====
{{Nasal doc
|syntax = props.Node.setValues(val);
|text = {{hatnote|See also {{func link|getValues()|page=this}}.}}

Sets the nodes property tree from a Nasal hash. Scalars will become nodes in the tree and hashes will become named subnodes. Vectors will be converted into indexed nodes, with the values in the vector becoming their values (see examples below).
|param1 = val
|param1text = A hash that will become the property tree.
|example1 = var val = {
"a": 100 # "a" will become the subnode's name, and 100 its value
};
var node = props.Node.new();
node.setValues(val);
props.dump(node); # dump tree
|example2 = var val = {
"a": 1,
"b": "Hi",
"c": {
"d": [1, 2, 3]
}
};
var node = props.Node.new();
node.setValues(val);
props.dump(node); # dump tree
}}

==== unalias() ====
{{Nasal doc
|syntax = props.Node.unalias();
|text = Un-aliases the node and returns it to a blank state. Returns 1 on success and 0 on failure (e.g., when used on a tied property).
|example2 = var node1 = props.Node.new();
node1.setDoubleValue(2.35);
var node2 = props.Node.new();
node2.alias(node1);

props.dump(node2); # equals 2.35
node2.unalias();
props.dump(node2); # no value or type
}}

==== toggleBoolValue() (since FG 2020.1) ====
{{Nasal doc
|syntax = toggleBoolValue();
|text = Toggle a boolean property. You have to make sure the property is of type bool!
|example1 = var b = props.Node.new().initNode("/_test/bool", 1, "BOOL");
print("bool ", b.getValue());
b.toggleBoolValue();
print("after toggleBoolValue ", b.getValue());

}}

== Functions ==
=== compileCondition() ===
{{see also|Conditions}}

{{Nasal doc
|syntax = props.compileCondition(node);
|version = 3.2
|commit = {{fgdata commit|43f8ce08706629e69984b1cc34e5e979d03ef09a|t=commit}}
|text = Compiles a [[conditions|condition]] property branch and returns a <code>Condition</code> ghost object or <code>'''nil'''</code> on error. This ghost will contain a <code>test()</code> function that will return the result of the condition as either 1 (true) or 0 (false).
|param1 = node
|param1text = Either a props.Node containing the condition, or a string specifying a place in the [[Property Tree]] where there is a condition branch.
|example1 = var tree = {
"equals": {
"property": '/test',
"value": 12
}
};
var node = props.Node.new(tree);
setprop("/test", 12);

var cond = props.compileCondition(node);
print(cond.test()); # prints "1" (true)
setprop("/test", 15);
print(cond.test()); # prints "0" (false)
|example2 = var tree = {
"equals": {
"property": '/test',
"value": 12
}
};
props.globals.getNode("test2/condition", 1).setValues(tree); # place it in the Property Tree
setprop("/test", 12);

var cond = props.compileCondition(node);
print(cond.test()); # prints "1" (true)
setprop("/test", 15);
print(cond.test()); # prints "0" (false)
}}

=== condition() ===
{{Nasal doc
|syntax = props.condition(node);
|text = Evaluates a [[conditions|condition]] property branch and returns the result as a boolean.
|param1 = node
|param1text = Either a props.Node containing the condition, or a string specifying a place in the [[Property Tree]] where there is a condition branch.
|example1 = var tree = {
"equals": {
"property": '/test',
"value": 12
}
};
var node = props.Node.new(tree);
setprop("/test", 12);

print(props.condition(node)); # prints "1" (true)
setprop("/test", 15);
print(props.condition(node)); # prints "0" (false)
|example2 = var tree = {
"equals": {
"property": '/test',
"value": 12
}
};
props.globals.getNode("test2/condition", 1).setValues(tree); # place it in the Property Tree
setprop("/test", 12);

print(props.condition(node)); # prints "1" (true)
setprop("/test", 15);
print(props.condition(node)); # prints "0" (false)
}}

=== copy() ===
{{Nasal doc
|syntax = props.copy(src, dest[, attr]);
|text = Copies the property tree of the source into the destination node. Note that aliased properties will not be copied.
|param1 = src
|param1text = Source <code>props.Node object</code> to copy from.
|param2 = dest
|param2text = Destination <code>props.Node object</code> to copy to.
|param3 = attr
|param3text = If set to true (1), attributes will also be copied. Defaults to false (0).
|example1 = var tree = {
"a": 1.5,
"b": "Hi",
"c": {
"d": [1, 2, 3]
}
};
var src = props.Node.new(tree);
var dest = props.Node.new();
props.copy(src, dest);
props.dump(dest);
|example2 = var src = props.Node.new();
var a = src.addChild("a");
a.setAttribute("trace-write", 1);
a.setIntValue(12);
var dest = props.Node.new();
props.copy(src, dest, true);
print(dest.getNode("a").getAttribute("trace-write")); # prints "1" (true)
}}

=== dump() ===
{{Nasal doc
|syntax = props.dump(node);
|text = Recursively dump the state of a node into the console, showing value and type of each node. Note that as of 10/2016, the value of vec*d type nodes cannot be dumped.
|param1 = node
|param1text = Node to dump.
|example1 = var node = var tree = {
"a": 12,
"b": "Hi",
"c": {
"d": [1, 2, 3]
}
};
var node = props.Node.new(tree);
props.dump(node); # dump into console
|example2 = # Dump the entire Property Tree
# Warning! This is an intensive operation!
props.dump(props.globals);
}}

=== getNode() ===
{{Nasal doc
|syntax = props.getNode();
|version = 3.2
|commit = {{fgdata commit|807062d0b6f858885547f27325e829c2bf42a12b|t=commit}}
|text = Shortcut for <syntaxhighlight lang="nasal" inline>props.globals.getNode()</syntaxhighlight>. See {{func link|getNode()||Node|page=this}} for full documentation.
|example1 = print("Current aircraft is: ", props.getNode("/sim/aircraft").getValue());
}}

=== nodeList() ===
{{Nasal doc
|syntax = props.nodeList(arg[, arg[, ...]]);
|text = Converts its arguments into a vector of node objects if possible and returns that vector.
|param1 = arg
|param1text = Object to operate on. Must be a node object, string, vector, hash, function, or <code>prop</code> ghost. Vectors and hashes must contain any of the other acceptable types, functions must return any of the other types, strings will be assumed to be paths to global properties, and ghosts will be converted into node objects. There may be any number of arguments.
|example1 = var node = props.Node.new();
var f = func(){
var n = props.Node.new();
return n._g;
}
var list = props.nodeList(node,
"/sim/aircraft",
["/sim/fg-root"],
{ "path": "/sim/fg-home" },
f
);
debug.dump(list); # dump list
|example2 = var root = "/sim/version/";
var info = [
root ~ "build-id",
root ~ "build-number",
root ~ "flightgear",
root ~ "hla-support",
root ~ "openscenegraph",
root ~ "revision",
root ~ "simgear"
];
info = props.nodeList(info); # turn into list of nodes
foreach(var n; info){
print(n.getValue()); # dump info
}
}}

=== runBinding() ===
{{Nasal doc
|syntax = props.runBinding(node[, module]);
|text = Runs a [[Bindings|binding]] element in a node object. Returns 1 (true) on success and 0 (false) on failure.
|param1 = node
|param1text = A {{tag|binding}} element as a node object.
|param2 = module
|param2text = Optional string specifying a module to run Nasal scripts in if the command is <code>nasal</code>. This argument will not override any {{tag|module}} element in the '''node'''
|example1 = var tree = {
"command": "dialog-show",
"dialog-name": "map" # open map
};
var binding = props.Node.new(tree);
props.runBinding(binding);
|example2 = var tree = {
"command": "nasal",
"script": 'print(pi)' # prints value of math.pi
};
var binding = props.Node.new(tree);
props.runBinding(binding, "math");
|example3 = var tree = {
"command": "nasal",
"script": 'print(pi)', # prints value of math.pi
"module": "math" # this is used
};
var binding = props.Node.new(tree);
props.runBinding(binding, "debug");
}}

=== setAll() ===
{{Nasal doc
|syntax = props.setAll(base, child, value);
|text = Sets indexed subnodes in the Property Tree with the same name to the same value.
|param1 = base
|param1text = Base path to the nodes.
|param2 = child
|param2text = Path to child nodes.
|param3 = value
|param3text = Value to set the subnodes to.
|example1 = # apply 50% throttle to all engines
props.setAll("/controls/engines/engine", "throttle", 0.5);
|example2 = var nodes = props.globals.addChildren("/test", 3);
foreach(var node; nodes){
node.addChild("a");
}
props.setAll("/test", "a", "Hi"); # set all children (test[*]/a) to "Hi"
}}

=== wrap() ===
{{Nasal doc
|syntax = props.wrap(node);
|text = Turns <code>prop</code> ghosts, either in a vector or single, into <code>props.Node</code> objects.
|param1 = node
|param1text = <code>prop</code> ghost or vector of such ghosts.
|example1 = var ghost = canvas._newCanvasGhost();
var node = props.wrap(ghost._node_ghost);
props.dump(node);
|example2 = var vector = [canvas._newCanvasGhost()._node_ghost, props.Node.new()._g];
var nodes = props.wrap(vector);
foreach(var node; nodes){
props.dump(node);
print("----");
}
}}

=== wrapNode() ===
{{Nasal doc
|syntax = props.wrapNode(node);
|text = Turns a <code>prop</code> ghost into a <code>props.Node</code> object.
|param1 = node
|param1text = <code>prop</code> ghost to convert.
|example1 = var ghost = canvas._newCanvasGhost();
var node = props.wrapNode(ghost._node_ghost);
props.dump(node);
}}

== Variable ==
=== globals ===
{{Nasal doc
|syntax = props.globals;
|text = Exposes the [[Property Tree]] as a <code>props.Node</code> object.

|example1 = print("Current aircraft: ", props.globals.getNode("/sim/aircraft").getValue());
|example2text = Alternative using {{func link|getprop()}}.
|example2 = print("Current aircraft: ", getprop("/sim/aircraft"));
}}

{{Nasal namespaces}}

YASim

2026-03-19T21:00:59Z

Jsb: /* Variable tail incidence / elevator trim */

[[File:yasimlogo.png|thumb]]

'''YASim''' is one of two [[flight dynamics model]]s commonly used in [[FlightGear]], alongside [[JSBSim]]. The flight dynamics model (FDM) determines how the [[aircraft]] moves and flies.

Gary Neely wrote in his [http://www.buckarooshangar.com/flightgear/ introduction to YASim]:

:''The FDM is the mathematical model that controls the physics of flight within the simulator. The physical 3D aircraft model has nothing to do with flight dynamics-- in essence it's just a picture to look at. It's the FDM that dictates how the model flies.''

:''Why YASim? YASim uses the geometry of the aircraft to generate the base flight characteristics. While this suggests a 'realistic' or out-of-the-box approach, it is a only rough approximation that will require much tweaking before you get a result that approaches realism. If you have solid flight data for your aircraft such as wind-tunnel data or you are looking to eventually generate a hyper-realistic simulation, JSBSim is probably a better approach. If you lack such data but know the geometry of the aircraft and have access to the same flight characteristics and limits as a real pilot would, then YASim can provide a solution that is more than sufficient for most simulation needs.''

== Coordinate system notes ==
All positions specified are in metres (which is weird, since all other units in the file are English). The X axis points forward, Y is left, and Z is up. Take your right hand, and hold it like a gun. Your first and second fingers are the X and Y axes, and your upwards-pointing thumb is the Z. This is slightly different from the coordinate system used by [[JSBSim]]. Sorry. The origin can be placed anywhere, so long as you are consistent. I use the nose of the aircraft.

(In the [[JSBSim_Aerodynamics#Frames|JSBSim coordinate system]], X and Z are the same as in YASim, but Y points to the right instead of left.)

=== Checking alignment with Blender ===

Blender can display a '''.ac''' model and a yasim model at the same time, allowing one to check whether the wings, gear contact points etc are aligned correctly. But it seems that Blender ignores any top-level <code>loc <x> <y> <z></code> specification in the '''.ac''' file, which makes it non-trivial to check alignment if such a specification is used.

== YASim design notes ==
Andy Ross's original design notes for YASim can be found in [https://pdfhost.io/v/~iYsLl7xS_alldvi.pdf this PDF file]. These provide some useful background for how YASim works.

== XML Elements ==

=== airplane ===
The top-level element for the file. It contains the following attributes:
* '''mass:''' The empty (no fuel) weight, in pounds. It does include the weight of the engine(s), so when you add the engine weight in its tag, it acts just like a ballast.
* '''version:''' The version attribute is used to maintain compatibility when updating yasim (e.g. bugfixes). If this attribute i not given, the original version will be used. Several bugfixes to YASim were implemented in FlightGear 3.2 (see [[FlightGear Newsletter April 2014]]), some more are fixed in FlightGear 2017.2.
Available versions are:
* <code>YASIM_VERSION_ORIGINAL</code> explicitly use the old buggy calculations (same as no version attribute at all)
* <code>YASIM_VERSION_32</code> enable bugfixes up to version 3.2
* <code>2017.2</code> enable bugfixes up to version 2017.2
* <code>2018.1</code> (FIXME) no bugfixes by now. Use this version if your aircraft makes use of new features in YASim 2018.1 so it will cause at least a warning with older FG versions.
* <code>YASIM_VERSION_CURRENT</code> use latest version compiled into the users FlightGear.
{{Warning| Using YASIM_VERSION_CURRENT might make the aircraft unusable in case of future changes to YASim without updating the aircraft accordingly.}}

'''New in 2018.1'''
* '''mtow-lbs''' and '''mtow-kg:''' use one of them to specify max. takeoff weight. Does not affect the FDM, but is used by CLI tool to calculate some numbers.

=== approach ===
The approach parameters for the aircraft. The solver will generate an aircraft that matches these settings (by adjusting the parameters of the surface like drag and lift). It is extremely important to give parameters which could be really achieved by defined aircraft geometry, otherwise, it gives an unstable or not flyable result. The element can (and should) contain <control> elements indicating pilot input settings, such as flaps and throttle, for the approach.

* '''speed:''' The approach airspeed, in knots TAS.
* '''aoa:''' The approach angle of attack, in degrees
* '''fuel:''' Fraction (0-1) of fuel in the tanks. Default is 0.2.

=== cruise ===
The cruise speed and altitude for the solver to match. As above, this should contain <control> elements indicating aircraft configuration. Especially, make sure the engines are generating enough thrust at cruise!
* '''speed:''' The cruise speed, in knots TAS.
* '''alt:''' The cruise altitude, in feet MSL.
* '''fuel:''' Fraction (0-1) of fuel in the tanks. Default is 0.2.
=== cockpit ===
The location of the cockpit (pilot eyepoint).
* '''x,y,z:''' eyepoint location (see coordinates note)

=== fuselage ===
This defines a tubelike structure. It will be given an even mass and aerodynamic force distribution by the solver. You can have as many as you like, in any orientation you please.
* '''ax,ay,az:''' One end of the tube (typically the front)
* '''bx,by,bz:''' The other ("back") end.
* '''width:''' The width of the tube, in metres.
* '''taper:''' The approximate radius at the "tips" of the fuselage expressed as a fraction (0-1) of the width value.
* '''midpoint:''' The location of the widest part of the fuselage, expressed as a fraction of the distance between A and B.
* '''idrag:''' Multiplier for the "induced drag" generated by this object. Default is one. With idrag=0 the fuselage generates only drag.
* '''cx,cy,cz:''' Factors for the generated drag in the fuselages "local coordinate system" with x pointing from end to front, z perpendicular to x with y=0 in the aircraft coordinate system. E.g. for a fuselage of a height of 2 times the width you can define cy=2 and (due to the doubled front surface) cx=2.

=== Surfaces ===
==== wing ====
This defines the main wing of the aircraft. You can have only one (but see below about using vstab objects for extra lifting surfaces). The wing should have a <stall> subelement to indicate stall behavior, control surface subelements (flap0, flap1, spoiler, slat) to indicate what and where the control surfaces are, and <control> subelements to map user input properties to the control surfaces.
* '''x,y,z:''' The "base" of the wing, specified as the location of the mid-chord (not leading edge, trailing edge, or aerodynamic center) point at the root of the LEFT (!) wing.
* '''length:''' The length from the midchord point of the base of the wing to the midchord point at the tip. Note that this is not the same thing as span.
* '''chord:''' The chord of the wing at its base, along the X axis (not normal to the leading edge, as it is sometimes defined).
* '''incidence:''' The incidence angle at the wing root, in degrees. Zero is level with the fuselage (as in an aerobatic plane), positive means that the leading edge is higher than the trailing edge (as in a trainer).
* '''twist:''' The difference between the incidence angle at the wing root and the incidence angle at the wing tip. Typically, this is a negative number so that the wing tips have a lower angle of attack and stall after the wing root (washout).
* '''taper:''' The taper fraction, expressed as the tip chord divided by the root chord. A taper of one is a hershey bar wing, and zero would be a wing ending at a point. Defaults to one.
* '''sweep:''' The sweep angle of the wing, in degrees. Zero is no sweep, positive angles are swept back. Defaults to zero. [This looks to be the sweep of the mid-chord of the wing, not the sweep of the leading edge.]
* '''dihedral:''' The dihedral angle of the wing. Positive angles are upward dihedral. Defaults to zero.
* '''idrag:''' Multiplier for the "induced drag" generated by this surface. In general, low aspect wings will generate less induced drag per-AoA than high aspect (glider) wings. This value isn't constrained well by the solution process, and may require tuning to get throttle settings correct in high AoA (approach) situations.
* '''effectiveness:''' Multiplier for the "normal" drag generated by the wing. Defaults to 1. Arbitrary, dimensionless factor.
* '''camber:''' The lift produced by the wing at zero angle of attack, expressed as a fraction of the maximum lift produced at the stall AoA.
* '''flow:''' The flow regime for the wing. Valid values are "SUBSONIC" (default) and "TRANSONIC". Setting surface to transonic adds more lift above mach number 0.6 by applying a Prandl/Glauert correction term to each surface-element. The effect is a more balanced lift/drag distribution reported by the solver. Use for anything that flies faster than mach 0.6 or has supercritical airfoils.
* '''mcrit:''' The critical mach number for the wing. This point defines the begin of exponential drag rise due to mach speed. Default "0.6", only available if flow="TRANSONIC".

'''Wing section support (since 2018.1):'''

Wing section support to define variable geometry (geometry parameters per section)
* More than one <wing>-element is allowed now.
* x, y, z, chord and incidence attribute shall be specifed only for the first <wing> in the XML file. They will be overridden for subsequent <wing>-elements.
* Use '''append="1"''' for additional '''wing''' elements to skip x, y, z, chord and incidence attribute as the will be calculated from previous '''wing''' element tip chord. This workaround is currently needed due to limitations in the XML parser.

==== hstab ====
These define the horizontal stabilizer of the aircraft. Internally, it is just a wing object and therefore works the same in XML.
You are allowed only one hstab object; the solver needs to know which wing's incidence to play with to get the aircraft trimmed correctly.

'''New in 2018.1:'''
* '''hstab''' supports sections in the same way '''wing''' does, but it is still considered as /the/ (only) hstab used by the solver.
* '''incidence-min-deg''' and '''incidence-max-deg''': optional attributes to limit valid result range fore the solver. Use with care or you won't get a solution.

==== vstab ====
A "vertical" stabilizer. Like hstab, this is just another wing, with a few special properties. The surface is not "mirrored" as are wing and hstab objects. If you define a left wing only, you'll only get a left wing. The default dihedral, if unspecified, is 90 degrees instead of zero. But all parameters are equally settable, so there's no requirement that this object be "vertical" at all. You can use it for anything you like, such as extra wings for biplanes. Most importantly, these surfaces are not involved with the solver computation, so you can have none, or as many as you like.

==== mstab ====
A mirrored horizontal stabilizer. Exactly the same as wing, but not involved with the solver computation, so you can have none, or as many as you like.

==== stall ====
A subelement of a wing (or hstab/vstab/mstab) that specifies the stall behavior.
* '''aoa:''' The stall angle (maximum lift) in degrees. Note that this is relative to the wing, not the fuselage (since the wing may have a non-zero incidence angle).
* '''width:''' The "width" of the stall, in degrees. A high value indicates a gentle stall. Low values are viscious for a non-twisted wing, but are acceptable for a twisted one (since the whole wing will not stall at the same time).
* '''peak:''' The height of the lift peak, relative to the post-stall secondary lift peak at 45 degrees. Defaults to 1.5. This one is deep voodoo, and probably doesn't need to change much. Bug me for an explanation if you're curious.

==== flap0, flap1, slat, spoiler ====
These are subelements of wing/hstab/vstab objects, and specify the location and effectiveness of the control surfaces.
* '''start:''' The position along the wing where the control surface begins.Zero is the root, one is the tip.
* '''end:''' The position where the surface ends, as above.
* '''lift:''' The lift multiplier for a flap or slat at full extension. One is a no-op, a typical aileron might be 1.2 or so, a giant jetliner flap 2.0, and a spoiler 0.0. For spoilers, the interpretation is a little different -- they spoil only "prestall" lift. Lift due purely to "flat plate" effects isn't affected. For typical wings that stall at low AoA's essentially all lift is pre-stall and you don't have to care. Jet fighters tend not to have wing spoilers, for exactly this reason. This value is not applicable to slats, which affect stall AoA only.
* '''drag:''' The drag multiplier, as above. Typically should be higher than the lift multiplier for flaps.
* '''aoa:''' Applicable only to slats. This indicates the angle by which the stall AoA is translated by the slat extension.

=== Rotor and rotorgear ===
YASim has also possibility to simulate rotorcraft blades. The number properties of rotor elements are large therefore are spitted to the separate page [[Howto:Make a helicopter#XML%20Elements|howto make a helicopter in YASim]].

=== Engine ===
==== Thruster ====
A very simple "thrust only" engine object. Useful for things like thrust vectoring nozzles. All it does is map its THROTTLE input axis to its output thrust rating. Does not consume fuel, etc...
* '''thrust:''' Maximum thrust in pounds
* '''x,y,z:''' The point on the airframe where thrust will be applied.
* '''vx,vy,vy:''' The direction of the thrust in airframe coordinates. The vector will be normalized automatically, so any non-zero vector will work fine.

Example:

<syntaxhighlight lang="xml" line>
<thruster x="0" y="0" z="0.03" vx="1" vy="0" vz="0" thrust="6.61">
<control-input axis="/controls/engines/engine[0]/throttle" control="THROTTLE" src0="-1" src1="1" dst0="-1" dst1="1"/>
</thruster>
</syntaxhighlight>

==== Jet ====
A turbojet/fan engine. It accepts a <control> subelement to map a property to its throttle setting, and an <actionpt> subelement to place the action point of the thrust at a different position than the mass of the engine.
* '''x,y,z:''' The location of the engine, as a point mass. If no actionpt is specified, this will also be the point of application of thrust.
* '''mass:''' The mass of the engine, in pounds.
* '''thrust:''' The maximum sea-level thrust, in pounds.
* '''afterburner:''' Maximum total thrust with afterburner/reheat, in pounds [defaults to "no additional thrust"].
* '''rotate:''' Vector angle of the thrust in degrees about the Y axis [0].
* '''n1-idle:''' Idling low pressure core / fan speed [55].
* '''n1-max:''' Maximum low pressure core / fan speed [102].
* '''n2-idle:''' Idling high pressure core speed [73].
* '''n2-max:''' Maximum high pressure core speed [103].
* '''tsfc:''' Thrust-specific fuel consumption [0.8]. This should be considerably lower for modern turbofans.
* '''atsfc:''' (version >= 2016.3.1) Thrust specific fuel consumption with afterburner on. When set to zero defaults to older behaviour where it is calculated from dry fuel consumption [0].
* '''egt:''' Exhaust gas temperature at takeoff in K [1050].
* '''epr:''' Engine pressure ratio at takeoff [3.0].
* '''exhaust-speed:''' The maximum exhaust speed in knots [~1555].
* '''spool-time:''' Time, in seconds, for the engine to respond to 90% of a commanded powersetting.

==== Propeller ====
A propeller. This element requires an engine subtag. Currently <piston-engine> and <turbine-engine> are supported.
* '''x,y,z:''' The position of the mass (!) of the engine/propeller combination. If the point of force application is different (and it will be) it should be set with an <actionpt> subelement.
* '''mass:''' The mass of the engine/propeller, in pounds.
* '''moment:''' The moment, in kg-metres^2. This has to be hand calculated and guessed at for now. A more automated system will be forthcoming. Use a negative moment value for counter-rotating ("European" -- CCW as seen from behind the prop) propellers. A good guess for this value is the radius of the prop (in meters) squared times the mass (kg) divided by three; that is the moment of a plain "stick" bolted to the prop shaft.
* '''radius:''' The radius, in meters, or the propeller.
* '''cruise-speed:''' The max efficiency cruise speed of the propeller. Generally not the same as the aircraft's cruise speed.
* '''cruise-rpm:''' The RPM of the propeller at max-eff. cruise.
* '''cruise-power:''' The power sunk by the prop at cruise, in horsepower.
* '''cruise-alt:''' The reference cruise altitude in feet.
* '''takeoff-power:''' The takeoff power required by the propeller...
* '''takeoff-rpm:''' ...at the given takeoff RPM.
* '''gear-ratio:''' The factor by which the engine RPM is multiplied to produce the propeller RPM. Optional (defaults to 1.0).
* '''contra:''' When set (contra="1"), this indicates that the propeller is a contra-rotating pair. It will not contribute to the aircraft's net gyroscopic moment, nor will it produce asymmetric torque on the aircraft body. Asymmetric slipstream effects, when implemented, will also be zero when this is set.

YASim assumes a fixed-pitch propeller by default. If your engine is using a constant-speed propeller, you'll also need to provide these attributes:

* '''min-rpm:''' The minimum operational RPM for a constant speed propeller. This is the speed to which the prop governor will seek when the blue lever is at a minimum. The coarse-stop attribute limits how far the governor can go into trying to reach this RPM.
* '''max-rpm:''' The maximum operational RPM for a constant speed propeller. See above. The fine-stop attribute limits how far the governor can go in trying to reach this RPM.
* '''fine-stop:''' The minimum pitch of the propeller (high RPM) as a ratio of ideal cruise pitch. This is set to 0.25 by default -- a higher value will result in a lower RPM at low power settings (e.g. idle, taxi, and approach).
* '''coarse-stop:''' The maximum pitch of the propeller (low RPM) as a ratio of ideal cruise pitch. This is set to 4.0 by default -- a lower value may result in a higher RPM at high power settings.

===== piston-engine =====

A piston engine definition. This must be a subelement of an enclosing <propeller> tag.

* '''eng-power:''' Maximum BHP of the engine at sea level.
* '''eng-rpm:''' The engine RPM at which eng-power is developed
* '''displacement:''' The engine displacement in cubic inches.
* '''compression:''' The engine compression ratio.

<syntaxhighlight lang="xml" line>
<piston-engine eng-power="2" eng-rpm="3800" displacement="20" >
<control-input axis="/controls/engines/engine[0]/throttle" control="THROTTLE"/>
<control-input axis="/controls/engines/engine[0]/starter" control="STARTER"/>
<control-input axis="/controls/engines/engine[0]/magnetos" control="MAGNETOS"/>
<control-input axis="/controls/engines/engine[0]/mixture" control="MIXTURE"/>
</piston-engine>
</syntaxhighlight>

===== electric-engine =====

A simplified electric DC engine model. The model is available since the end of April 2020, therefore it is currently available in daily build FlightGear snapshots. This definition must be a subelement of an enclosing <propeller> tag.

* '''Kv''' electric engine constant in revolutions per minute to volt.
* '''voltage''' The voltage applied to the motor e.g. Nominal battery voltage in Volts.
* '''Rm''' The engine winding resistance in Ohms.

Example:

<syntaxhighlight lang="xml" line>
<propeller x="0.02" y="0" z="0.03"
mass="0.05"
moment="0.0006"
radius="0.203"
cruise-speed="26"
cruise-rpm="7000"
cruise-power="0.5"
cruise-alt="2000"
takeoff-power="0.70"
takeoff-rpm="9200"
contra="1">
<actionpt x="0" y="0" z="0.03"/>
<electric-engine Kv="750" voltage="15" Rm="0.02" >
<control-input axis="/controls/engines/engine[0]/throttle" control="THROTTLE"/>
</electric-engine>
</propeller>
</syntaxhighlight>

=== Landing gear ===
==== gear ====
Defines a landing gear. Accepts <control> subelements to map properties to steering and braking. Can also be used to simulate floats. Although the coefficients are still called ..fric, it is calculated in fluids as a drag (proportional to the square of the speed). In fluids gears are not considered to detect crashes (as on ground).
* '''x,y,z:''' The location of the fully-extended gear tip.
* '''compression:''' The distance in metres along the "up" axis that the gear will compress.
* '''initial-load:''' The initial load of the spring in multiples of compression. Defaults to 0. (With this parameter a lower spring-constants will be used for the gear-> can reduce numerical problems (jitter)) '''Note:''' the spring-constant is varied from 0% compression to 20% compression to get continuous behavior around 0 compression. (could be physically explained by wheel deformation)
* '''upx/upy/upz:''' The direction of compression, defaults to vertical (0,0,1) if unspecified. These are used only for a direction -- the vector need not be normalized, as the length is specified by "compression".
* '''sfric:''' Static (non-skidding) coefficient of friction. Defaults to 0.8.
* '''dfric:''' Dynamic friction. Defaults to 0.7.
* '''stiction:''' Stiction to ground. Defaults to 0. stiction = "1" ensures the gear isn't sliding unintentionally (Note: please correct docu here for more detailed facts, developers didn't document this extension here and this is based on trial and guessing only)
* '''spring:''' A dimensionless multiplier for the automatically generated spring constant. Increase to make the gear stiffer, decrease to make it squishier.
* '''damp:''' A dimensionless multiplier for the automatically generated damping coefficient. Decrease to make the gear "bouncier", increase to make it "slower". Beware of increasing this too far: very high damping forces can make the numerics unstable. If you can't make the gear stop bouncing with this number, try increasing the compression length instead.
* '''on-water:''' if this is set to "0" the gear will be ignored if on water. Defaults to "0"
* '''on-solid:''' if this set to "0" the gear will be ignored if not on water. Defaults to "1"
* '''speed-planing:'''
* '''spring-factor-not-planing:''' At zero speed the spring factor is multiplied by spring-factor-not-planing. Above speed-planing this factor is equal to 1. The idea is, to use this for floats simulating the transition from swimming to planing. speed-planing defaults to 0, spring-factor-not-planing defaults to 1.
* '''reduce-friction-by-extension:''' at full extension the friction is reduced by this relative value. 0.7 means 30% friction at full extension. If you specify a value greater than one, the friction will be zero before reaching full extension. Defaults to "0"
* '''ignored-by-solver:''' with the on-water/on-solid tags you can have more than one set of gears in one aircraft, If the solver (who automatically generates the spring constants) would take all gears into account, the result would be wrong. E. G. set this tag to "1" for all gears, which are not active on runways. Defaults to "0". You can not exclude all gears in the solving process.

Will define two properties associated with compression of landing gear:

* '''compression-norm''' - range from 0..1, 0 means gear fully extended, 1 means fully compressed.
* '''compression-m''' - vertical distance in metres that the wheel has moved in order to be on top of ground; this will usually be different from the animation distance.

<syntaxhighlight lang="xml" line>


<gear x="0.0" y="0.0" z="-0.205"
spring="0.9"
damp="0.8"
dfric="0.9"
sfric="1.1"
compression="0.051">
<control-input axis="/controls/flight/rudder" control="STEER" square="true" src0="-1.0" src1="1.0" dst0="-0.3" dst1="0.3"/>
<control-input axis="/controls/gear/brake-right" control="BRAKE" split="true"/>
<control-input axis="/controls/gear/brake-parking" control="BRAKE" split="true"/>
</gear>



<gear x="-0.4" y="0.25" z="-0.205"
spring="0.9"
damp="0.8"
dfric="0.9"
sfric="1.1"
compression="0.051">
<control-input axis="/controls/gear/brake-right" control="BRAKE" split="true"/>
<control-input axis="/controls/gear/brake-parking" control="BRAKE" split="true"/>
</gear>

<gear x="-0.4" y="-0.25" z="-0.205"
spring="0.9"
damp="0.8"
dfric="0.9"
sfric="1.1"
compression="0.051">
<control-input axis="/controls/gear/brake-left" control="BRAKE" split="true"/>
<control-input axis="/controls/gear/brake-parking" control="BRAKE" split="true"/>
</gear>
</syntaxhighlight>

===== Torus-shaped contact surface on next =====

On next as of 2022-3-19 one can specify a torus-shaped tyre contact surface using these new parameters:

* '''wheel-x'''
* '''wheel-y'''
* '''wheel-z'''
* '''wheel-radius''' (default 0)
* '''tyre-radius''' (default 0)
* '''wheel-axle-x'''
* '''wheel-axle-y'''
* '''wheel-axle-z'''

The contact point will be the lowest point on a torus with radius '''tyre-radius''' wrapped around a wheel with radius '''wheel-radius''' centred on point '''(wheel-x, wheel-y, wheel-z)''' with orientation defined by '''wheel-axle'''. This contact point will depend on the aircraft's orientation relative to the ground.

If not specified, '''wheel-axle''' defaults to (0, 1, 0), giving a conventional vertical wheel in line with the aircraft. Other values may allow modelling of, for example, a Bf109's non-vertical undercarriage.

Default values of zero for wheel-radius and tyre-radius give a fixed contact point at (wheel-x, wheel-y, wheel-z).

If an aircraft also specifies an old-style contact point with '''(x, y, z)''' it will work with both new and old builds of Flightgear.

==== Launchbar ====
Defines a catapult launchbar or strop.
* '''x,y,z:''' The location of the mount point of the launch bar or strop on the aircraft.
* '''length:''' The length of the launch bar from mount point to tip
* '''down-angle:''' The max angle below the horizontal the launchbar can achieve.
* '''up-angle:''' The max angle above the horizontal the launchbar can achieve.
* '''holdback-{x,y,z}:''' The location of the holdback mount point on the aircraft.
* '''holdback-length:''' The length of the holdback from mount point to tip. Note: holdback up-angle and down-angle are the same as those defined for the launchbar and are not specified in the configuration.

=== Fuel ===
==== tank ====
A fuel tank. Tanks in the aircraft are identified numerically (starting from zero), in the order they are defined in the file. If the left tank is first, "tank[0]" will be the left tank.
* '''x,y,z:''' The location of the tank.
* '''capacity:''' The maximum contents of the tank, in pounds. Not gallons -- YASim supports fuels of varying densities.
* '''jet:''' A boolean. If present, this causes the fuel density to be treated as Jet-A. Otherwise, gasoline density is used. A more elaborate density setting (in pounds per gallon, for example) would be easy to implement. Bug me.

=== Center of Gravity ===
==== Ballast ====
This is a mechanism for modifying the mass distribution of the aircraft. A ballast setting specifies that a particular amount of the empty weight of the aircraft must be placed at a given location. The remaining non-ballast weight will be distributed "intelligently" across the fuselage and wing objects. Note again: this does NOT change the empty weight of the aircraft.
* '''x,y,z:''' The location of the ballast.
* '''mass:''' How much mass, in pounds, to put there. Note that this value can be negative. I find that I often need to "lighten" the tail of the aircraft.

<syntaxhighlight lang="xml" line>
<ballast x="-0.24" y="0.0" z="0.33" mass-kg="0.5"/>
</syntaxhighlight>

==== Weight ====
This is an added weight, something not part of the empty weight of the aircraft, like passengers, cargo, or external stores. The actual value of the mass is not specified here, instead, a mapping to a property is used. This allows external code, such as the panel, to control the weight (loading a given cargo configuration from preference files, dropping bombs at runtime, etc...)
* '''x,y,z:''' The location of the weight.
* '''mass-prop:''' The name of the fgfs property containing the mass, in pounds, of this weight.
* '''size:''' The aerodynamic "size", in metres, of the object. This is important for external stores, which will cause drag. For reasonably aerodynamic stuff like bombs, the size should be roughly the width of the object. For other stuff, you're on your own. The default is zero, which results in no aerodynamic force (internal cargo).
* '''solve-weight:''' Subtag of approach and cruise parameters. Used to specify a non-zero setting for a <weight> tag during solution. The default is to assume all weights are zero at the given performance numbers.
* '''idx:''' Index of the weight in the file (starting with zero).
* '''weight:''' Weight setting in pounds.

<syntaxhighlight lang="xml" line>
<weight x="-0.06471" y="0.225" z="-0.2" mass-prop="/sim/weight[0]/weight-kg"/>
</syntaxhighlight>

=== Controls ===
==== control-input ====
This element manages a mapping from fgfs properties (user input) to settable values on the aircraft's objects. Note that the value to be set MUST (!) be valid on the given object type. This is not checked for by the parser, and will cause a runtime crash if you try it. Wing's don't have throttle controls, etc... Note that multiple axes may be set on the same value. They are summed before setting.
* '''axis:''' The name of the double-valued fgfs property "axis" to use as input, such as "/controls/flight/aileron".
* '''control:''' Which control axis to set on the objects. It can have the following values:
** THROTTLE - The throttle on a jet or propeller.
** MIXTURE - The mixture on a propeller.
** REHEAT - The afterburner on a jet
** PROP - The propeller advance
** BRAKE - The brake on a gear.
** STEER - The steering angle on a gear.
** INCIDENCE - The incidence angle of a wing.
** FLAP0 - The flap0 deflection of a wing.
** FLAP1 - The flap1 deflection of a wing.
** SLAT - The slat extension of a wing.
** SPOILER - The spoiler extension for a wing.
** CYCLICAIL - The "aileron" cyclic input of a rotor
** CYCLICELE - The "elevator" cyclic input of a rotor
** COLLECTIVE - The collective input of a rotor
** ROTORENGINEON - If not equal zero the rotor is rotating
** WINCHRELSPEED - The relative winch speed
** {... and many more, see [https://sourceforge.net/p/flightgear/flightgear/ci/next/tree/src/FDM/YASim/ControlMap.cpp#l25 ControlMap.cpp] ...}
* '''invert:''' Negate the value of the property before settling on the object.
* '''split:''' Applicable to wing control surfaces. Sets the normal value on the left-wing, and a negated value on the right-wing.
* '''square:''' Squares the value before setting. Useful for controls like a steering that needs a wide range, yet lots of sensitivity in the center. Obviously only applicable to values that have a range of [-1:1] or [0:1].
* '''src0/src1/dst0/dst1:''' If present, these define a linear mapping from the source to the output value. Input values in the range src0-src1 are mapped linearly to dst0-dst1, with clamping for input values that lie outside the range.

==== control-output ====
This can be used to pass the value of a YASim control axis (after all mapping and summing is applied) back to the property tree.
* '''control:''' Name of the control axis. See above.
* '''prop:''' Property node to receive the value.
* '''side:''' Optional, for split controls. Either "right" or "left"
* '''min/max:''' Clamping applied to output value.

==== control-speed ====
Some controls (most notably flaps and hydraulics) have maximum slew rates and cannot respond instantly to pilot input. This can be implemented with a control-speed tag, which defines a "transition time" required to slew through the full input range. Note that this tag is semi-deprecated, complicated control input filtering can be done much more robustly from a Nasal script.
* '''control:''' Name of the control axis. See above.
* '''transition-time:''' Time in seconds to slew through input range.

==== control-setting ====
This tag is used to define a particular setting for a control axis inside the <cruise> or <approach> tags, where obviously property input is not available. It can be used, for example, to inform the solver that the approach performance values assume full flaps, etc...
* '''axis:''' Name of the control input (i.e. a property name)
* '''value:''' Value of the control axis.

=== Winch and Aerotow ===
==== hitch ====
A hitch, can be used for winch-start (in gliders) or aerotow (in gliders and motor aircraft) or for external cargo with helicopter. You can do aerotow over the net via multiplayer (see j3 and bocian as an example).
* '''name:''' the name of the hitch. must be aerotow if you want to do aerotow via multiplayer. You will find many properties at /sim/hitches/name. Most of them are directly tied to the internal variables, you can modify them as you like. You can add a listener to the property "broken", e. g. for playing a sound.
* '''x,y,z:''' The position of the hitch
* '''force-is-calculated-by-other:''' if you want to simulate aerotowing over the internet, set this value to "1" in the motor aircraft. Don't specify or set this to zero in gliders. In a LAN the time lag might be small enough to set it on both aircraft to "0". It's intended, that this is done automatically in the future.
==== tow ====
The tow used for aerotow or winch. This must be a subelement of an enclosing <hitch> tag.
* '''length:''' upstretched length in metres
* '''weight-per-meter:''' in kg/metre
* '''elastic-constant:''' lower values give higher elasticity
* '''break-force:''' in N
* '''mp-auto-connect-period:''' the every x seconds a towed multiplayer aircraft is searched. If found, this tow is connected automatically, parameters are copied from the other aircraft. Should be set only in the motor aircraft, not in the glider
==== winch ====
The tow used for aerotow or winch. This must be a subelement of an enclosing <hitch> tag.
* '''max-tow-length:''' in m
* '''min-tow-length''': in m
* '''initial-tow-length:''' in m. The initial tow length also defines the length/search radius used for the mp-autoconnect feature
* '''max-winch-speed:''' in m/s
* '''power:''' in kW
* '''max-force:''' in N

<syntaxhighlight lang="xml" line>
<hitch name="winch" x="0.0" y="0.0" z="0.0">
<tow length="50" weight-per-meter="0.0035" elastic-constant="40000" break-force="10000"/>

<winch max-tow-length="1000" min-tow-length="1" initial-tow-length="1000" max-winch-speed="20" power="2" max-force="80"/>
<control-input axis="/controls/winch/place" control="PLACEWINCH"/>
</hitch>
<hitch name="aerotow" x="0.0" y="0.0" z="0.0" force-is-calculated-by-other="0">
<tow length="60" weight-per-meter="0.0035" elastic-constant="9000" break-force="100" mp-auto-connect-period="0.0"/>
<winch max-tow-length="1000" min-tow-length="60" initial-tow-length="60"/>
<control-input axis="/controls/aerotow/find-aircraft" control="FINDAITOW"/>
</hitch>
</syntaxhighlight>

== Visualization ==

=== Blender visualization tool ===

[[File:Yasim_visualisation_dc6.png|thumb|dc6 FDM in Blender]]To make the programmed aircraft visible it is possible to load and compare it with the 3D model within [[Blender]]. They applaud for this ''very'' useful script goes to M. Franz, thank you very much!

For Blender versions <= 2.4 the script is located in FlightGears source code {{flightgear file|utils/Modeller/yasim_import.py}}.

For Blender versions newer than 2.4, please see [[Blender YASim import]].

The howto, taken from inside the script:

yasim_import.py loads and visualizes a YASim FDM geometry
=========================================================

It is recommended to load the model superimposed over a greyed out and immutable copy of the aircraft model:

(0) put this script into ~/.blender/scripts/
(1) load or import aircraft model (menu -> "File" -> "Import" -> "AC3D (.ac) ...")
(2) create new *empty* scene (menu -> arrow button left of "SCE:scene1" combobox -> "ADD NEW" -> "empty")
(3) rename scene to yasim (not required)
(4) link to scene1 (F10 -> "Output" tab -> arrow button left of text entry "No Set Scene" -> "scene1")
(5) now load the YASim config file (menu -> "File" -> "Import" -> "YASim (.xml) ...")

This is good enough for simple checks. But if you are working on the YASim configuration, then you need a
quick and convenient way to reload the file. In that case, continue after (4):

(5) switch the button area at the bottom of the blender screen to "Scripts Window" mode (green python snake icon)
(6) load the YASim config file (menu -> "Scripts" -> "Import" -> "YASim (.xml) ...")
(7) make the "Scripts Window" area as small as possible by dragging the area separator down
(8) optionally split the "3D View" area and switch the right part to the "Outliner"
(9) press the "Reload YASim" button in the script area to reload the file

If the 3D model is displaced with respect to the FDM model, then the <offsets> values from the
model animation XML file should be added as comment to the YASim config file, as a line all by
itself, with no spaces surrounding the equal signs. Spaces elsewhere are allowed. For example:

<offsets>
<x-m>3.45</x-m>
<z-m>-0.4</z-m>
<pitch-deg>5</pitch-deg>
</offsets>

becomes:



Possible variables are:

x ... <x-m>
y ... <y-m>
z ... <z-m>
h ... <heading-deg>
p ... <pitch-deg>
r ... <roll-deg>

Of course, absolute FDM coordinates can then no longer directly be read from Blender's 3D view.
The cursor coordinates display in the script area, however, shows the coordinates in YASim space.
Note that object names don't contain XML indices but element numbers. YASim_hstab#2 is the third
hstab in the whole file, not necessarily in its parent XML group. A floating-point part in the
object name (e.g. YASim_hstab#2.004) only means that the geometry has been reloaded that often.
It's an unavoidable consequence of how Blender deals with meshes.

Elements are displayed as follows:

cockpit -> monkey head
fuselage -> blue "tube" (with only 12 sides for less clutter); center at "a"
vstab -> red with yellow flaps
wing/mstab/hstab -> green with yellow flaps/spoilers/slats (always 20 cm deep);
symmetric surfaces are only displayed on the left side
thrusters (jet/propeller/thruster) -> dashed line from center to actionpt;
arrow from actionpt along thrust vector (always 1 m long);
propeller circle
rotor -> radius and rel_len_blade_start circle, direction arrow,
normal and forward vector, one blade at phi0
gear -> contact point and compression vector (no arrow head)
tank -> cube (10 cm side length)
weight -> inverted cone
ballast -> cylinder
hitch -> circle (10 cm diameter)
hook -> dashed line for up angle, T-line for down angle
launchbar -> dashed line for up angles, T-line for down angles
A note about step (0) for Windows users: the mentioned path is inside the folder where Blender lives, something like <code>C:\Program Files\Blender Foundation\Blender\.blender\scripts</code>.

=== Visualize model in OpenSCAD or FreeCAD ===

There exist a possibility to display the YASim XML elements in the OpenSCAD or FreeCAD tools. This could be extremely useful in the case of UAV aircraft development.

* [https://github.com/ThunderFly-aerospace/YASim2SCAD YASim2SCAD] - This tool converts YASim XML to scad file which could be displayed as an overlay in OpenSCAD or FreeCAD project.
* [https://gitlab.com/yasimtoscad/yasimtoscad yasimtoscad] - Another tool to convert YASim XML to scad file which could be displayed as an overlay in OpenSCAD.

=== Visualization tools ===

* [https://github.com/bitwisetech/ysimi YSIMI] Interactive Tuning Tools for FlightGear's YASIM Flight Dynamics Model
* [https://github.com/bitwisetech/yasiVers yasiVers] is a tool for visualization of YASim calculations.

== Export of YASim internals to property tree ==
Ever wondered what is going on inside yasim? See the property tree under /fdm/yasim/

Some information is static and shows what yasim has compiled from your XML.
Other information is "run-time" like forces, speed, acceleration, c.g.

If note noted otherwise:
* expect metric unit (meter, kilogram, newton, ...)
* expect minimum version 2017.2

{| class="wikitable"
|-
! Path !! Description !! Information type !! min. version
|-
| accelerations/ || linear and rot. accelerations in aircraft coord. || run time ||
|-
| debug/ || misc internals, for now subject to change without notice || run time || 2018.1
|-
| forces/ || aerodynamic forces in N || run time ||
|-
| velocities/ || linear and rot. velocities in aircraft coord. || run time ||
|-
| model/cg-x-range-aft || desired CG range || compile time ||
|-
| model/cg-x-range-front || desired CG range || compile time ||
|-
| model/cg-x-max || CG hard limit from gear position || compile time ||
|-
| model/cg-x-min || CG hard limit from gear position || compile time ||
|-
| model/masses || shows the calculated mass points || compile time ||
|-
| model/wings || wing parameters || compile time ||
|}

== Command Line ==
=== Windows ===
By using the standard command line, we can see what the YASim solver is calculating. First, open up Command Prompt, enter in the location of yasim.exe, and then the location of the YASim XML file. For example, here's what you would type in for a standard Windows [[Changelog_2.12|FlightGear 2.12.0]] installation, and viewing the [[F-14_Tomcat|F-14B's]] YASim file.
{{Note|You can copy & paste the examples into Command Prompt by right-clicking on the title and navigate to Edit > Paste. Then, click Enter to execute.}}

<code>"C:\Program Files\FlightGear\bin\Win32\yasim.exe" "C:\Program Files\FlightGear\data\Aircraft\f-14b\f-14b-yasim.xml"</code>

The results will give many different values.

* '''Drag Coefficient:''' The drag coefficient of the aircraft.
* '''Lift Ratio:''' The lift ratio of the aircraft.
* '''Cruise AoA:''' The cruise AoA, from conditions at [[YASim#cruise|<cruise>]] in the xml file.
* '''Tail Incidence:''' The incidence angle of the tail, "solved" by YASim as a way to stabilize the aircraft.
* '''Approach Elevator:''' The approach elevator, from conditions at [[YASim#approach|<approach>]] in the xml file.
* '''CG:''' Center of gravity of the aircraft in coordinates. Unless it's supposed to be offset, it should always have a Y value of 0.

The YASim standalone solver also has some command line flags that change it's behaviour.

<code>"C:\Program Files\FlightGear\bin\Win32\yasim.exe" "C:\Program Files\FlightGear\data\Aircraft\f-14b\f-14b-yasim.xml" -g -a 1000 -s 490</code>

* '''-g:''' Instructs YASim to generate space-separated tabular data instead of the usual solver output. This can be redirected to a file and used in various plotting programs to visualize the actual lift, drag, L/D curves. The columns of the output from left to right are: AoA, Lift, Drag, L/D. (aoa in degrees, lift and drag in G's).
* '''-a <altitude in meter:>''' Run the solver at the given altitude in meter.
* '''-s <speed in knots>:''' Also run at the given airspeed in knots.

{{Note|The values generated by this method are for the aircraft taken as a whole, as solved by YASim, so they differ from the values of the wing airfoil.}}

To get the tabular output for the example above at 1000 m and 150 knots, and to redirect this to a file, one would issue:

<code>"C:\Program Files\FlightGear\bin\Win32\yasim.exe" "C:\Program Files\FlightGear\data\Aircraft\f-14b\f-14b-yasim.xml" -g -a 1000 -s 150 > "C:\Program Files\FlightGear\yasim.txt"</code>

== New features and bugfixes in version 2017.2 ==

=== XML parser ===
==== support for metric and imperial units ====
To make life easier for aircraft developers, the parser supports new additional attributes with a unit suffix, e.g. speed-kt for knots and speed-kmh for kilometers per hour.
* <code><airplane {mass, mass-lbs, mass-kg}="12345" ></code>
* <code><approach {speed, speed-kt, speed-kmh}="123" ></code>
* <code><cruise {speed, speed-kt, speed-kmh}="123" ></code>
* <code><solve-weight {weight, weight-lbs, weight-kg}="123" ></code>
* <code><jet {mass, mass-lbs, mass-kg}="1234" ></code>
* <code><tank {capacity, capacity-lbs, capacity-kg}="12345" ></code>
* <code><ballast {mass, mass-lbs, mass-kg}="1234" ></code>

{{Note|Aircraft using this new attributes will not run on older versions of FlightGear, so it is probably wise to publish those only after a reasonable number of users switched version 2017.2 or newer.}}

==== CG tuning help ====
{{Note| The feature described in this section is not fully implemented yet, however, it may be of some help already.
It is currently implemented for the yasim CLI tool only. It does not affect the airplane behaviour while running FlightGear. }}

New attributes have been added to <airplane> to assist tuning the center of gravity (CG).
The CG position is often expressed relative to the [https://en.wikipedia.org/wiki/Chord_(aeronautics)#Mean_aerodynamic_chord MAC] of the wing in percent. You can specify a desired range for CG in % relative to MAC, it will show up in the output of the yasim CLI tool (see example below):

* cg-min: default 25% (just a guess, better numbers are welcome)
* cg-max: default 30% (just a guess, better numbers are welcome)

{{Note| By convention 0% is leading edge, 100% is trailing edge, however the absolute values on x-axis are the other way round, e.g. nose is +x, tail is -x }}
{{warning|The MAC calculation in version 2017.2 works only on the <wing> element. Numbers will be wrong, if your model uses a combination of <wing> and <mstab> to build a wing with two or more sections.
Section support will be added in version 2018.1}}
YASim will print the leading edge coordinates of the MAC (x,y) and its length.

'''Example output'''
<pre>
$ yasim Citation-II-yasim.xml
This aircraft uses yasim version '2017.2'
==========================
= YASim solution results =
==========================
Iterations: 2210
Drag Coefficient: 12.304669
Lift Ratio: 85.317558
Cruise AoA: 4.016746 deg
Tail Incidence: -3.053278 deg
Approach Elevator: -0.377542

CG: x:-6.543, y:-0.000, z:0.044
Wing MAC (*1): x:-6.00, y:3.83, length:2.0
CG-x rel. MAC: 0.272
CG-x desired: -6.599 < -6.543 < -6.198

Inertia tensor [kg*m^2], origo at CG:

18009.289, -0.000, 7120.470
-0.000, 42459.316, 0.000
7120.470, 0.000, 56980.656

(*1) MAC calculation works on <wing> only! Numbers will be wrong for segmented wings, e.g. <wing>+<mstab>.
</pre>

=== Aircraft developer helpers ===
The command line utility got some new options. For some strange reason, the -a parameter expects altitude in meters instead of ft. This is now visible in the usage message but left unchanged for compatibility.
<syntaxhighlight>Usage:
yasim <aircraft.xml> [-g [-a meters] [-s kts] [-approach | -cruise] ]
yasim <aircraft.xml> [-d [-a meters] [-approach | -cruise] ]
yasim <aircraft.xml> [-m]
-g print lift/drag table: aoa, lift, drag, lift/drag
-d print drag over TAS: kts, drag
-a set altitude in meters!
-s set speed in knots
-m print mass distribution table: id, x, y, z, mass</syntaxhighlight>

=== Bugfixes ===
The following bugfixes require <airplane version="2017.2"> for backward compatibility
* Ground effect: corrected the calculation of the height where g.e. ends
* Stall parameters were set wrong for wings with camber=0

== New features and bugfixes in version 2018.1 ==
The following is under development and hopefully finds its way into FG version 2018.1

=== Wing Section Support ===
Many airliners have wings with a geometry that is just a little more complex than what YASim supported initially (tapered wing with some angles like sweep, dihedral, ...), e.g. they have an inboard section and an outboard section that can be described with YASim wing syntax. You can use a wing + a mstab XML element to describe this geometry but it is easier if YASim can just append more wing sections by simply adding more wing XML elements. This is now (Version 2018.1) possible, yasim will simply append sections if it finds more than one wing or hstab in the XML.
You should use '''<wing append="1" ... >''' for all but the first wing/hstab declaration.
{{Note|YASim will ignore the root point (x,y,z), the chord length and the incidence attributes, if you add "append" and calculate those from the previous wing section. }}
MAC calculation works for the whole wing.

{{warning|Aircrafts using this feature will not work with older versions of flightgear. }}
To keep the aircraft backward compatible for a while, it is recommended to create a copy of its yasim XML file for development.
Once you are happy with the CG and wing parameters you can use the output of the YASim CLI tool to modifiy the original XML.
The tool will output the needed x,y,z etc per wing section to create a XML in old format with (only one) <wing> + <mstab>.

=== More information from CLI tools ===
You should configure the maximum take of weight (MTOW) in your XML file by adding either ''mtow-lbs'' or ''mtow-kg'' attribute to the airplane:

<code> <airplane mass="7500" version="2018.1" mtow-lbs="12500"> </code>

'''Example output'''
<pre>
yasim CRJ700.xml
==========================
= YASim solution results =
==========================
Iterations : 1024
Drag Coefficient : 17.707
Lift Ratio : 145.841
Cruise AoA : -0.11 deg
Tail Incidence : 3.47 deg
Approach Elevator : -0.792

CG : x:-0.046, y:0.000, z:-1.222
Wing MAC : (x:0.79, y:4.99), length:3.4
hard limit CG-x : 14.232 m
soft limit CG-x : -0.058 m
CG-x : -0.046 m
CG-x rel. MAC : 25%
soft limit CG-x : -0.228 m
hard limit CG-x : -0.986 m

wing lever : -0.012 m
tail lever : -13.997 m

max thrust : 157.18 kN
thrust/empty : 0.81
thrust/mtow : 0.49

wing span : 22.64 m
sweep lead. edge : 30.2 .. 30.6 deg
wing area : 58.70 m^2
wing load empty : 336.15 kg/m^2 (Empty 19731 kg)
wing load MTOW : 562.18 kg/m^2 (MTOW 32999 kg)

tail span : 8.533 m
tail area : 14.838 m^2

#wing sections: 2
Section 0 base point (0.450, 1.226, -2.034), chord 5.085, incidence at section root 5.0deg
Section 1 base point (-0.663, 4.754, -1.942), chord 3.204, incidence at section root 3.0deg

Inertia tensor [kg*m^2], origo at CG:

195646, 0, 122265
0, 1757279, 0
122265, 0, 1904528
</pre>

=== Variable tail incidence / elevator trim ===
Small GA aircrafts usually trim with a trim tab on the elevator. For efficiency, airliners normally do not trim the elevator ("flap") but rotate the whole horizontal stabilizer (tail wing), e.g. they change the incidence for this wing. While this feature was somehow foreseen, it was not implemented yet, most likely because the "tail incidence" is one of the free variables used by the YASim solver. However, it is now possible to use the control="INCIDENCE" within the <hstab> to implement an alternative trim '''while maintaining full elevator authority'''.
<pre>
<hstab ... incidence-min-deg="-13.0" incidence-max-deg="2.0">
...
<control-input axis="/controls/flight/hstab-trim" control="INCIDENCE" />
<control-speed control="INCIDENCE" transition-time="20.0" />
<control-output control="INCIDENCE" prop="/surface-positions/hstab-rad" />
</hstab>
</pre>
{{Note|The control output of INCIDENCE is the angle in radians, not in degree, as that is the unit internally used by YASim.}}
{{warning|The OPTIONAL incidence-min-deg and incidence-max-deg set the limits for the solver. You must make sure to select a sufficiently large range or solver will fail. }}
First experiments with this feature were successful in that the aircraft pitch could be changed as expected but fine tuning will be necessary.

==== Trim System Configuration ====
To have <code>controls.elevatorTrim()</code> trim the hstab instead of elevator, set <code>/sim/config/hstab-trim</code> to true (YASim only).

If no detailed system simulation is desired, simply set <code>/systems/hstab-trim/engaged</code> to true in the aircrafts -set.xml to enable hstab trim. The trim rate is read from <code>/systems/hstab-trim/trim-rate</code> and can be adjusted if needed (default is set in controls.nas).
== Related content ==
* [[Howto:Make a helicopter#XML Elements]] – Rotor and rotorgear YASim elements
* [[Towing]]
* [[YASim Development Tools]]

== External links ==
* {{cite web
| url = http://www.buckarooshangar.com/flightgear/yasimtut.html
| title = Guide to YASim
| first = Gary R. "Buckaroo"
| last = Neely
| authorlink = http://www.buckarooshangar.com/flightgear/
| date = 2013
| accessdate = April 16, 2020
}} - A very helpful guide
* {{cite web
| url = https://sourceforge.net/projects/dacpei/
| title = DACPEI
| author = pytoche
| date = February 2012
| publisher = SourceForge
| accessdate = April 16, 2020
}} - A fixed wing light aircraft WYSIWUG concept design suite that can export an YASim FDM to FlightGear.

{{FDM}}

[[Category:Flight Dynamics Model]]

[[fr:YASim]]

YASim

2026-03-18T15:06:16Z

Jsb: /* Variable tail incidence / elevator trim */

[[File:yasimlogo.png|thumb]]

'''YASim''' is one of two [[flight dynamics model]]s commonly used in [[FlightGear]], alongside [[JSBSim]]. The flight dynamics model (FDM) determines how the [[aircraft]] moves and flies.

Gary Neely wrote in his [http://www.buckarooshangar.com/flightgear/ introduction to YASim]:

:''The FDM is the mathematical model that controls the physics of flight within the simulator. The physical 3D aircraft model has nothing to do with flight dynamics-- in essence it's just a picture to look at. It's the FDM that dictates how the model flies.''

:''Why YASim? YASim uses the geometry of the aircraft to generate the base flight characteristics. While this suggests a 'realistic' or out-of-the-box approach, it is a only rough approximation that will require much tweaking before you get a result that approaches realism. If you have solid flight data for your aircraft such as wind-tunnel data or you are looking to eventually generate a hyper-realistic simulation, JSBSim is probably a better approach. If you lack such data but know the geometry of the aircraft and have access to the same flight characteristics and limits as a real pilot would, then YASim can provide a solution that is more than sufficient for most simulation needs.''

== Coordinate system notes ==
All positions specified are in metres (which is weird, since all other units in the file are English). The X axis points forward, Y is left, and Z is up. Take your right hand, and hold it like a gun. Your first and second fingers are the X and Y axes, and your upwards-pointing thumb is the Z. This is slightly different from the coordinate system used by [[JSBSim]]. Sorry. The origin can be placed anywhere, so long as you are consistent. I use the nose of the aircraft.

(In the [[JSBSim_Aerodynamics#Frames|JSBSim coordinate system]], X and Z are the same as in YASim, but Y points to the right instead of left.)

=== Checking alignment with Blender ===

Blender can display a '''.ac''' model and a yasim model at the same time, allowing one to check whether the wings, gear contact points etc are aligned correctly. But it seems that Blender ignores any top-level <code>loc <x> <y> <z></code> specification in the '''.ac''' file, which makes it non-trivial to check alignment if such a specification is used.

== YASim design notes ==
Andy Ross's original design notes for YASim can be found in [https://pdfhost.io/v/~iYsLl7xS_alldvi.pdf this PDF file]. These provide some useful background for how YASim works.

== XML Elements ==

=== airplane ===
The top-level element for the file. It contains the following attributes:
* '''mass:''' The empty (no fuel) weight, in pounds. It does include the weight of the engine(s), so when you add the engine weight in its tag, it acts just like a ballast.
* '''version:''' The version attribute is used to maintain compatibility when updating yasim (e.g. bugfixes). If this attribute i not given, the original version will be used. Several bugfixes to YASim were implemented in FlightGear 3.2 (see [[FlightGear Newsletter April 2014]]), some more are fixed in FlightGear 2017.2.
Available versions are:
* <code>YASIM_VERSION_ORIGINAL</code> explicitly use the old buggy calculations (same as no version attribute at all)
* <code>YASIM_VERSION_32</code> enable bugfixes up to version 3.2
* <code>2017.2</code> enable bugfixes up to version 2017.2
* <code>2018.1</code> (FIXME) no bugfixes by now. Use this version if your aircraft makes use of new features in YASim 2018.1 so it will cause at least a warning with older FG versions.
* <code>YASIM_VERSION_CURRENT</code> use latest version compiled into the users FlightGear.
{{Warning| Using YASIM_VERSION_CURRENT might make the aircraft unusable in case of future changes to YASim without updating the aircraft accordingly.}}

'''New in 2018.1'''
* '''mtow-lbs''' and '''mtow-kg:''' use one of them to specify max. takeoff weight. Does not affect the FDM, but is used by CLI tool to calculate some numbers.

=== approach ===
The approach parameters for the aircraft. The solver will generate an aircraft that matches these settings (by adjusting the parameters of the surface like drag and lift). It is extremely important to give parameters which could be really achieved by defined aircraft geometry, otherwise, it gives an unstable or not flyable result. The element can (and should) contain <control> elements indicating pilot input settings, such as flaps and throttle, for the approach.

* '''speed:''' The approach airspeed, in knots TAS.
* '''aoa:''' The approach angle of attack, in degrees
* '''fuel:''' Fraction (0-1) of fuel in the tanks. Default is 0.2.

=== cruise ===
The cruise speed and altitude for the solver to match. As above, this should contain <control> elements indicating aircraft configuration. Especially, make sure the engines are generating enough thrust at cruise!
* '''speed:''' The cruise speed, in knots TAS.
* '''alt:''' The cruise altitude, in feet MSL.
* '''fuel:''' Fraction (0-1) of fuel in the tanks. Default is 0.2.
=== cockpit ===
The location of the cockpit (pilot eyepoint).
* '''x,y,z:''' eyepoint location (see coordinates note)

=== fuselage ===
This defines a tubelike structure. It will be given an even mass and aerodynamic force distribution by the solver. You can have as many as you like, in any orientation you please.
* '''ax,ay,az:''' One end of the tube (typically the front)
* '''bx,by,bz:''' The other ("back") end.
* '''width:''' The width of the tube, in metres.
* '''taper:''' The approximate radius at the "tips" of the fuselage expressed as a fraction (0-1) of the width value.
* '''midpoint:''' The location of the widest part of the fuselage, expressed as a fraction of the distance between A and B.
* '''idrag:''' Multiplier for the "induced drag" generated by this object. Default is one. With idrag=0 the fuselage generates only drag.
* '''cx,cy,cz:''' Factors for the generated drag in the fuselages "local coordinate system" with x pointing from end to front, z perpendicular to x with y=0 in the aircraft coordinate system. E.g. for a fuselage of a height of 2 times the width you can define cy=2 and (due to the doubled front surface) cx=2.

=== Surfaces ===
==== wing ====
This defines the main wing of the aircraft. You can have only one (but see below about using vstab objects for extra lifting surfaces). The wing should have a <stall> subelement to indicate stall behavior, control surface subelements (flap0, flap1, spoiler, slat) to indicate what and where the control surfaces are, and <control> subelements to map user input properties to the control surfaces.
* '''x,y,z:''' The "base" of the wing, specified as the location of the mid-chord (not leading edge, trailing edge, or aerodynamic center) point at the root of the LEFT (!) wing.
* '''length:''' The length from the midchord point of the base of the wing to the midchord point at the tip. Note that this is not the same thing as span.
* '''chord:''' The chord of the wing at its base, along the X axis (not normal to the leading edge, as it is sometimes defined).
* '''incidence:''' The incidence angle at the wing root, in degrees. Zero is level with the fuselage (as in an aerobatic plane), positive means that the leading edge is higher than the trailing edge (as in a trainer).
* '''twist:''' The difference between the incidence angle at the wing root and the incidence angle at the wing tip. Typically, this is a negative number so that the wing tips have a lower angle of attack and stall after the wing root (washout).
* '''taper:''' The taper fraction, expressed as the tip chord divided by the root chord. A taper of one is a hershey bar wing, and zero would be a wing ending at a point. Defaults to one.
* '''sweep:''' The sweep angle of the wing, in degrees. Zero is no sweep, positive angles are swept back. Defaults to zero. [This looks to be the sweep of the mid-chord of the wing, not the sweep of the leading edge.]
* '''dihedral:''' The dihedral angle of the wing. Positive angles are upward dihedral. Defaults to zero.
* '''idrag:''' Multiplier for the "induced drag" generated by this surface. In general, low aspect wings will generate less induced drag per-AoA than high aspect (glider) wings. This value isn't constrained well by the solution process, and may require tuning to get throttle settings correct in high AoA (approach) situations.
* '''effectiveness:''' Multiplier for the "normal" drag generated by the wing. Defaults to 1. Arbitrary, dimensionless factor.
* '''camber:''' The lift produced by the wing at zero angle of attack, expressed as a fraction of the maximum lift produced at the stall AoA.
* '''flow:''' The flow regime for the wing. Valid values are "SUBSONIC" (default) and "TRANSONIC". Setting surface to transonic adds more lift above mach number 0.6 by applying a Prandl/Glauert correction term to each surface-element. The effect is a more balanced lift/drag distribution reported by the solver. Use for anything that flies faster than mach 0.6 or has supercritical airfoils.
* '''mcrit:''' The critical mach number for the wing. This point defines the begin of exponential drag rise due to mach speed. Default "0.6", only available if flow="TRANSONIC".

'''Wing section support (since 2018.1):'''

Wing section support to define variable geometry (geometry parameters per section)
* More than one <wing>-element is allowed now.
* x, y, z, chord and incidence attribute shall be specifed only for the first <wing> in the XML file. They will be overridden for subsequent <wing>-elements.
* Use '''append="1"''' for additional '''wing''' elements to skip x, y, z, chord and incidence attribute as the will be calculated from previous '''wing''' element tip chord. This workaround is currently needed due to limitations in the XML parser.

==== hstab ====
These define the horizontal stabilizer of the aircraft. Internally, it is just a wing object and therefore works the same in XML.
You are allowed only one hstab object; the solver needs to know which wing's incidence to play with to get the aircraft trimmed correctly.

'''New in 2018.1:'''
* '''hstab''' supports sections in the same way '''wing''' does, but it is still considered as /the/ (only) hstab used by the solver.
* '''incidence-min-deg''' and '''incidence-max-deg''': optional attributes to limit valid result range fore the solver. Use with care or you won't get a solution.

==== vstab ====
A "vertical" stabilizer. Like hstab, this is just another wing, with a few special properties. The surface is not "mirrored" as are wing and hstab objects. If you define a left wing only, you'll only get a left wing. The default dihedral, if unspecified, is 90 degrees instead of zero. But all parameters are equally settable, so there's no requirement that this object be "vertical" at all. You can use it for anything you like, such as extra wings for biplanes. Most importantly, these surfaces are not involved with the solver computation, so you can have none, or as many as you like.

==== mstab ====
A mirrored horizontal stabilizer. Exactly the same as wing, but not involved with the solver computation, so you can have none, or as many as you like.

==== stall ====
A subelement of a wing (or hstab/vstab/mstab) that specifies the stall behavior.
* '''aoa:''' The stall angle (maximum lift) in degrees. Note that this is relative to the wing, not the fuselage (since the wing may have a non-zero incidence angle).
* '''width:''' The "width" of the stall, in degrees. A high value indicates a gentle stall. Low values are viscious for a non-twisted wing, but are acceptable for a twisted one (since the whole wing will not stall at the same time).
* '''peak:''' The height of the lift peak, relative to the post-stall secondary lift peak at 45 degrees. Defaults to 1.5. This one is deep voodoo, and probably doesn't need to change much. Bug me for an explanation if you're curious.

==== flap0, flap1, slat, spoiler ====
These are subelements of wing/hstab/vstab objects, and specify the location and effectiveness of the control surfaces.
* '''start:''' The position along the wing where the control surface begins.Zero is the root, one is the tip.
* '''end:''' The position where the surface ends, as above.
* '''lift:''' The lift multiplier for a flap or slat at full extension. One is a no-op, a typical aileron might be 1.2 or so, a giant jetliner flap 2.0, and a spoiler 0.0. For spoilers, the interpretation is a little different -- they spoil only "prestall" lift. Lift due purely to "flat plate" effects isn't affected. For typical wings that stall at low AoA's essentially all lift is pre-stall and you don't have to care. Jet fighters tend not to have wing spoilers, for exactly this reason. This value is not applicable to slats, which affect stall AoA only.
* '''drag:''' The drag multiplier, as above. Typically should be higher than the lift multiplier for flaps.
* '''aoa:''' Applicable only to slats. This indicates the angle by which the stall AoA is translated by the slat extension.

=== Rotor and rotorgear ===
YASim has also possibility to simulate rotorcraft blades. The number properties of rotor elements are large therefore are spitted to the separate page [[Howto:Make a helicopter#XML%20Elements|howto make a helicopter in YASim]].

=== Engine ===
==== Thruster ====
A very simple "thrust only" engine object. Useful for things like thrust vectoring nozzles. All it does is map its THROTTLE input axis to its output thrust rating. Does not consume fuel, etc...
* '''thrust:''' Maximum thrust in pounds
* '''x,y,z:''' The point on the airframe where thrust will be applied.
* '''vx,vy,vy:''' The direction of the thrust in airframe coordinates. The vector will be normalized automatically, so any non-zero vector will work fine.

Example:

<syntaxhighlight lang="xml" line>
<thruster x="0" y="0" z="0.03" vx="1" vy="0" vz="0" thrust="6.61">
<control-input axis="/controls/engines/engine[0]/throttle" control="THROTTLE" src0="-1" src1="1" dst0="-1" dst1="1"/>
</thruster>
</syntaxhighlight>

==== Jet ====
A turbojet/fan engine. It accepts a <control> subelement to map a property to its throttle setting, and an <actionpt> subelement to place the action point of the thrust at a different position than the mass of the engine.
* '''x,y,z:''' The location of the engine, as a point mass. If no actionpt is specified, this will also be the point of application of thrust.
* '''mass:''' The mass of the engine, in pounds.
* '''thrust:''' The maximum sea-level thrust, in pounds.
* '''afterburner:''' Maximum total thrust with afterburner/reheat, in pounds [defaults to "no additional thrust"].
* '''rotate:''' Vector angle of the thrust in degrees about the Y axis [0].
* '''n1-idle:''' Idling low pressure core / fan speed [55].
* '''n1-max:''' Maximum low pressure core / fan speed [102].
* '''n2-idle:''' Idling high pressure core speed [73].
* '''n2-max:''' Maximum high pressure core speed [103].
* '''tsfc:''' Thrust-specific fuel consumption [0.8]. This should be considerably lower for modern turbofans.
* '''atsfc:''' (version >= 2016.3.1) Thrust specific fuel consumption with afterburner on. When set to zero defaults to older behaviour where it is calculated from dry fuel consumption [0].
* '''egt:''' Exhaust gas temperature at takeoff in K [1050].
* '''epr:''' Engine pressure ratio at takeoff [3.0].
* '''exhaust-speed:''' The maximum exhaust speed in knots [~1555].
* '''spool-time:''' Time, in seconds, for the engine to respond to 90% of a commanded powersetting.

==== Propeller ====
A propeller. This element requires an engine subtag. Currently <piston-engine> and <turbine-engine> are supported.
* '''x,y,z:''' The position of the mass (!) of the engine/propeller combination. If the point of force application is different (and it will be) it should be set with an <actionpt> subelement.
* '''mass:''' The mass of the engine/propeller, in pounds.
* '''moment:''' The moment, in kg-metres^2. This has to be hand calculated and guessed at for now. A more automated system will be forthcoming. Use a negative moment value for counter-rotating ("European" -- CCW as seen from behind the prop) propellers. A good guess for this value is the radius of the prop (in meters) squared times the mass (kg) divided by three; that is the moment of a plain "stick" bolted to the prop shaft.
* '''radius:''' The radius, in meters, or the propeller.
* '''cruise-speed:''' The max efficiency cruise speed of the propeller. Generally not the same as the aircraft's cruise speed.
* '''cruise-rpm:''' The RPM of the propeller at max-eff. cruise.
* '''cruise-power:''' The power sunk by the prop at cruise, in horsepower.
* '''cruise-alt:''' The reference cruise altitude in feet.
* '''takeoff-power:''' The takeoff power required by the propeller...
* '''takeoff-rpm:''' ...at the given takeoff RPM.
* '''gear-ratio:''' The factor by which the engine RPM is multiplied to produce the propeller RPM. Optional (defaults to 1.0).
* '''contra:''' When set (contra="1"), this indicates that the propeller is a contra-rotating pair. It will not contribute to the aircraft's net gyroscopic moment, nor will it produce asymmetric torque on the aircraft body. Asymmetric slipstream effects, when implemented, will also be zero when this is set.

YASim assumes a fixed-pitch propeller by default. If your engine is using a constant-speed propeller, you'll also need to provide these attributes:

* '''min-rpm:''' The minimum operational RPM for a constant speed propeller. This is the speed to which the prop governor will seek when the blue lever is at a minimum. The coarse-stop attribute limits how far the governor can go into trying to reach this RPM.
* '''max-rpm:''' The maximum operational RPM for a constant speed propeller. See above. The fine-stop attribute limits how far the governor can go in trying to reach this RPM.
* '''fine-stop:''' The minimum pitch of the propeller (high RPM) as a ratio of ideal cruise pitch. This is set to 0.25 by default -- a higher value will result in a lower RPM at low power settings (e.g. idle, taxi, and approach).
* '''coarse-stop:''' The maximum pitch of the propeller (low RPM) as a ratio of ideal cruise pitch. This is set to 4.0 by default -- a lower value may result in a higher RPM at high power settings.

===== piston-engine =====

A piston engine definition. This must be a subelement of an enclosing <propeller> tag.

* '''eng-power:''' Maximum BHP of the engine at sea level.
* '''eng-rpm:''' The engine RPM at which eng-power is developed
* '''displacement:''' The engine displacement in cubic inches.
* '''compression:''' The engine compression ratio.

<syntaxhighlight lang="xml" line>
<piston-engine eng-power="2" eng-rpm="3800" displacement="20" >
<control-input axis="/controls/engines/engine[0]/throttle" control="THROTTLE"/>
<control-input axis="/controls/engines/engine[0]/starter" control="STARTER"/>
<control-input axis="/controls/engines/engine[0]/magnetos" control="MAGNETOS"/>
<control-input axis="/controls/engines/engine[0]/mixture" control="MIXTURE"/>
</piston-engine>
</syntaxhighlight>

===== electric-engine =====

A simplified electric DC engine model. The model is available since the end of April 2020, therefore it is currently available in daily build FlightGear snapshots. This definition must be a subelement of an enclosing <propeller> tag.

* '''Kv''' electric engine constant in revolutions per minute to volt.
* '''voltage''' The voltage applied to the motor e.g. Nominal battery voltage in Volts.
* '''Rm''' The engine winding resistance in Ohms.

Example:

<syntaxhighlight lang="xml" line>
<propeller x="0.02" y="0" z="0.03"
mass="0.05"
moment="0.0006"
radius="0.203"
cruise-speed="26"
cruise-rpm="7000"
cruise-power="0.5"
cruise-alt="2000"
takeoff-power="0.70"
takeoff-rpm="9200"
contra="1">
<actionpt x="0" y="0" z="0.03"/>
<electric-engine Kv="750" voltage="15" Rm="0.02" >
<control-input axis="/controls/engines/engine[0]/throttle" control="THROTTLE"/>
</electric-engine>
</propeller>
</syntaxhighlight>

=== Landing gear ===
==== gear ====
Defines a landing gear. Accepts <control> subelements to map properties to steering and braking. Can also be used to simulate floats. Although the coefficients are still called ..fric, it is calculated in fluids as a drag (proportional to the square of the speed). In fluids gears are not considered to detect crashes (as on ground).
* '''x,y,z:''' The location of the fully-extended gear tip.
* '''compression:''' The distance in metres along the "up" axis that the gear will compress.
* '''initial-load:''' The initial load of the spring in multiples of compression. Defaults to 0. (With this parameter a lower spring-constants will be used for the gear-> can reduce numerical problems (jitter)) '''Note:''' the spring-constant is varied from 0% compression to 20% compression to get continuous behavior around 0 compression. (could be physically explained by wheel deformation)
* '''upx/upy/upz:''' The direction of compression, defaults to vertical (0,0,1) if unspecified. These are used only for a direction -- the vector need not be normalized, as the length is specified by "compression".
* '''sfric:''' Static (non-skidding) coefficient of friction. Defaults to 0.8.
* '''dfric:''' Dynamic friction. Defaults to 0.7.
* '''stiction:''' Stiction to ground. Defaults to 0. stiction = "1" ensures the gear isn't sliding unintentionally (Note: please correct docu here for more detailed facts, developers didn't document this extension here and this is based on trial and guessing only)
* '''spring:''' A dimensionless multiplier for the automatically generated spring constant. Increase to make the gear stiffer, decrease to make it squishier.
* '''damp:''' A dimensionless multiplier for the automatically generated damping coefficient. Decrease to make the gear "bouncier", increase to make it "slower". Beware of increasing this too far: very high damping forces can make the numerics unstable. If you can't make the gear stop bouncing with this number, try increasing the compression length instead.
* '''on-water:''' if this is set to "0" the gear will be ignored if on water. Defaults to "0"
* '''on-solid:''' if this set to "0" the gear will be ignored if not on water. Defaults to "1"
* '''speed-planing:'''
* '''spring-factor-not-planing:''' At zero speed the spring factor is multiplied by spring-factor-not-planing. Above speed-planing this factor is equal to 1. The idea is, to use this for floats simulating the transition from swimming to planing. speed-planing defaults to 0, spring-factor-not-planing defaults to 1.
* '''reduce-friction-by-extension:''' at full extension the friction is reduced by this relative value. 0.7 means 30% friction at full extension. If you specify a value greater than one, the friction will be zero before reaching full extension. Defaults to "0"
* '''ignored-by-solver:''' with the on-water/on-solid tags you can have more than one set of gears in one aircraft, If the solver (who automatically generates the spring constants) would take all gears into account, the result would be wrong. E. G. set this tag to "1" for all gears, which are not active on runways. Defaults to "0". You can not exclude all gears in the solving process.

Will define two properties associated with compression of landing gear:

* '''compression-norm''' - range from 0..1, 0 means gear fully extended, 1 means fully compressed.
* '''compression-m''' - vertical distance in metres that the wheel has moved in order to be on top of ground; this will usually be different from the animation distance.

<syntaxhighlight lang="xml" line>


<gear x="0.0" y="0.0" z="-0.205"
spring="0.9"
damp="0.8"
dfric="0.9"
sfric="1.1"
compression="0.051">
<control-input axis="/controls/flight/rudder" control="STEER" square="true" src0="-1.0" src1="1.0" dst0="-0.3" dst1="0.3"/>
<control-input axis="/controls/gear/brake-right" control="BRAKE" split="true"/>
<control-input axis="/controls/gear/brake-parking" control="BRAKE" split="true"/>
</gear>



<gear x="-0.4" y="0.25" z="-0.205"
spring="0.9"
damp="0.8"
dfric="0.9"
sfric="1.1"
compression="0.051">
<control-input axis="/controls/gear/brake-right" control="BRAKE" split="true"/>
<control-input axis="/controls/gear/brake-parking" control="BRAKE" split="true"/>
</gear>

<gear x="-0.4" y="-0.25" z="-0.205"
spring="0.9"
damp="0.8"
dfric="0.9"
sfric="1.1"
compression="0.051">
<control-input axis="/controls/gear/brake-left" control="BRAKE" split="true"/>
<control-input axis="/controls/gear/brake-parking" control="BRAKE" split="true"/>
</gear>
</syntaxhighlight>

===== Torus-shaped contact surface on next =====

On next as of 2022-3-19 one can specify a torus-shaped tyre contact surface using these new parameters:

* '''wheel-x'''
* '''wheel-y'''
* '''wheel-z'''
* '''wheel-radius''' (default 0)
* '''tyre-radius''' (default 0)
* '''wheel-axle-x'''
* '''wheel-axle-y'''
* '''wheel-axle-z'''

The contact point will be the lowest point on a torus with radius '''tyre-radius''' wrapped around a wheel with radius '''wheel-radius''' centred on point '''(wheel-x, wheel-y, wheel-z)''' with orientation defined by '''wheel-axle'''. This contact point will depend on the aircraft's orientation relative to the ground.

If not specified, '''wheel-axle''' defaults to (0, 1, 0), giving a conventional vertical wheel in line with the aircraft. Other values may allow modelling of, for example, a Bf109's non-vertical undercarriage.

Default values of zero for wheel-radius and tyre-radius give a fixed contact point at (wheel-x, wheel-y, wheel-z).

If an aircraft also specifies an old-style contact point with '''(x, y, z)''' it will work with both new and old builds of Flightgear.

==== Launchbar ====
Defines a catapult launchbar or strop.
* '''x,y,z:''' The location of the mount point of the launch bar or strop on the aircraft.
* '''length:''' The length of the launch bar from mount point to tip
* '''down-angle:''' The max angle below the horizontal the launchbar can achieve.
* '''up-angle:''' The max angle above the horizontal the launchbar can achieve.
* '''holdback-{x,y,z}:''' The location of the holdback mount point on the aircraft.
* '''holdback-length:''' The length of the holdback from mount point to tip. Note: holdback up-angle and down-angle are the same as those defined for the launchbar and are not specified in the configuration.

=== Fuel ===
==== tank ====
A fuel tank. Tanks in the aircraft are identified numerically (starting from zero), in the order they are defined in the file. If the left tank is first, "tank[0]" will be the left tank.
* '''x,y,z:''' The location of the tank.
* '''capacity:''' The maximum contents of the tank, in pounds. Not gallons -- YASim supports fuels of varying densities.
* '''jet:''' A boolean. If present, this causes the fuel density to be treated as Jet-A. Otherwise, gasoline density is used. A more elaborate density setting (in pounds per gallon, for example) would be easy to implement. Bug me.

=== Center of Gravity ===
==== Ballast ====
This is a mechanism for modifying the mass distribution of the aircraft. A ballast setting specifies that a particular amount of the empty weight of the aircraft must be placed at a given location. The remaining non-ballast weight will be distributed "intelligently" across the fuselage and wing objects. Note again: this does NOT change the empty weight of the aircraft.
* '''x,y,z:''' The location of the ballast.
* '''mass:''' How much mass, in pounds, to put there. Note that this value can be negative. I find that I often need to "lighten" the tail of the aircraft.

<syntaxhighlight lang="xml" line>
<ballast x="-0.24" y="0.0" z="0.33" mass-kg="0.5"/>
</syntaxhighlight>

==== Weight ====
This is an added weight, something not part of the empty weight of the aircraft, like passengers, cargo, or external stores. The actual value of the mass is not specified here, instead, a mapping to a property is used. This allows external code, such as the panel, to control the weight (loading a given cargo configuration from preference files, dropping bombs at runtime, etc...)
* '''x,y,z:''' The location of the weight.
* '''mass-prop:''' The name of the fgfs property containing the mass, in pounds, of this weight.
* '''size:''' The aerodynamic "size", in metres, of the object. This is important for external stores, which will cause drag. For reasonably aerodynamic stuff like bombs, the size should be roughly the width of the object. For other stuff, you're on your own. The default is zero, which results in no aerodynamic force (internal cargo).
* '''solve-weight:''' Subtag of approach and cruise parameters. Used to specify a non-zero setting for a <weight> tag during solution. The default is to assume all weights are zero at the given performance numbers.
* '''idx:''' Index of the weight in the file (starting with zero).
* '''weight:''' Weight setting in pounds.

<syntaxhighlight lang="xml" line>
<weight x="-0.06471" y="0.225" z="-0.2" mass-prop="/sim/weight[0]/weight-kg"/>
</syntaxhighlight>

=== Controls ===
==== control-input ====
This element manages a mapping from fgfs properties (user input) to settable values on the aircraft's objects. Note that the value to be set MUST (!) be valid on the given object type. This is not checked for by the parser, and will cause a runtime crash if you try it. Wing's don't have throttle controls, etc... Note that multiple axes may be set on the same value. They are summed before setting.
* '''axis:''' The name of the double-valued fgfs property "axis" to use as input, such as "/controls/flight/aileron".
* '''control:''' Which control axis to set on the objects. It can have the following values:
** THROTTLE - The throttle on a jet or propeller.
** MIXTURE - The mixture on a propeller.
** REHEAT - The afterburner on a jet
** PROP - The propeller advance
** BRAKE - The brake on a gear.
** STEER - The steering angle on a gear.
** INCIDENCE - The incidence angle of a wing.
** FLAP0 - The flap0 deflection of a wing.
** FLAP1 - The flap1 deflection of a wing.
** SLAT - The slat extension of a wing.
** SPOILER - The spoiler extension for a wing.
** CYCLICAIL - The "aileron" cyclic input of a rotor
** CYCLICELE - The "elevator" cyclic input of a rotor
** COLLECTIVE - The collective input of a rotor
** ROTORENGINEON - If not equal zero the rotor is rotating
** WINCHRELSPEED - The relative winch speed
** {... and many more, see [https://sourceforge.net/p/flightgear/flightgear/ci/next/tree/src/FDM/YASim/ControlMap.cpp#l25 ControlMap.cpp] ...}
* '''invert:''' Negate the value of the property before settling on the object.
* '''split:''' Applicable to wing control surfaces. Sets the normal value on the left-wing, and a negated value on the right-wing.
* '''square:''' Squares the value before setting. Useful for controls like a steering that needs a wide range, yet lots of sensitivity in the center. Obviously only applicable to values that have a range of [-1:1] or [0:1].
* '''src0/src1/dst0/dst1:''' If present, these define a linear mapping from the source to the output value. Input values in the range src0-src1 are mapped linearly to dst0-dst1, with clamping for input values that lie outside the range.

==== control-output ====
This can be used to pass the value of a YASim control axis (after all mapping and summing is applied) back to the property tree.
* '''control:''' Name of the control axis. See above.
* '''prop:''' Property node to receive the value.
* '''side:''' Optional, for split controls. Either "right" or "left"
* '''min/max:''' Clamping applied to output value.

==== control-speed ====
Some controls (most notably flaps and hydraulics) have maximum slew rates and cannot respond instantly to pilot input. This can be implemented with a control-speed tag, which defines a "transition time" required to slew through the full input range. Note that this tag is semi-deprecated, complicated control input filtering can be done much more robustly from a Nasal script.
* '''control:''' Name of the control axis. See above.
* '''transition-time:''' Time in seconds to slew through input range.

==== control-setting ====
This tag is used to define a particular setting for a control axis inside the <cruise> or <approach> tags, where obviously property input is not available. It can be used, for example, to inform the solver that the approach performance values assume full flaps, etc...
* '''axis:''' Name of the control input (i.e. a property name)
* '''value:''' Value of the control axis.

=== Winch and Aerotow ===
==== hitch ====
A hitch, can be used for winch-start (in gliders) or aerotow (in gliders and motor aircraft) or for external cargo with helicopter. You can do aerotow over the net via multiplayer (see j3 and bocian as an example).
* '''name:''' the name of the hitch. must be aerotow if you want to do aerotow via multiplayer. You will find many properties at /sim/hitches/name. Most of them are directly tied to the internal variables, you can modify them as you like. You can add a listener to the property "broken", e. g. for playing a sound.
* '''x,y,z:''' The position of the hitch
* '''force-is-calculated-by-other:''' if you want to simulate aerotowing over the internet, set this value to "1" in the motor aircraft. Don't specify or set this to zero in gliders. In a LAN the time lag might be small enough to set it on both aircraft to "0". It's intended, that this is done automatically in the future.
==== tow ====
The tow used for aerotow or winch. This must be a subelement of an enclosing <hitch> tag.
* '''length:''' upstretched length in metres
* '''weight-per-meter:''' in kg/metre
* '''elastic-constant:''' lower values give higher elasticity
* '''break-force:''' in N
* '''mp-auto-connect-period:''' the every x seconds a towed multiplayer aircraft is searched. If found, this tow is connected automatically, parameters are copied from the other aircraft. Should be set only in the motor aircraft, not in the glider
==== winch ====
The tow used for aerotow or winch. This must be a subelement of an enclosing <hitch> tag.
* '''max-tow-length:''' in m
* '''min-tow-length''': in m
* '''initial-tow-length:''' in m. The initial tow length also defines the length/search radius used for the mp-autoconnect feature
* '''max-winch-speed:''' in m/s
* '''power:''' in kW
* '''max-force:''' in N

<syntaxhighlight lang="xml" line>
<hitch name="winch" x="0.0" y="0.0" z="0.0">
<tow length="50" weight-per-meter="0.0035" elastic-constant="40000" break-force="10000"/>

<winch max-tow-length="1000" min-tow-length="1" initial-tow-length="1000" max-winch-speed="20" power="2" max-force="80"/>
<control-input axis="/controls/winch/place" control="PLACEWINCH"/>
</hitch>
<hitch name="aerotow" x="0.0" y="0.0" z="0.0" force-is-calculated-by-other="0">
<tow length="60" weight-per-meter="0.0035" elastic-constant="9000" break-force="100" mp-auto-connect-period="0.0"/>
<winch max-tow-length="1000" min-tow-length="60" initial-tow-length="60"/>
<control-input axis="/controls/aerotow/find-aircraft" control="FINDAITOW"/>
</hitch>
</syntaxhighlight>

== Visualization ==

=== Blender visualization tool ===

[[File:Yasim_visualisation_dc6.png|thumb|dc6 FDM in Blender]]To make the programmed aircraft visible it is possible to load and compare it with the 3D model within [[Blender]]. They applaud for this ''very'' useful script goes to M. Franz, thank you very much!

For Blender versions <= 2.4 the script is located in FlightGears source code {{flightgear file|utils/Modeller/yasim_import.py}}.

For Blender versions newer than 2.4, please see [[Blender YASim import]].

The howto, taken from inside the script:

yasim_import.py loads and visualizes a YASim FDM geometry
=========================================================

It is recommended to load the model superimposed over a greyed out and immutable copy of the aircraft model:

(0) put this script into ~/.blender/scripts/
(1) load or import aircraft model (menu -> "File" -> "Import" -> "AC3D (.ac) ...")
(2) create new *empty* scene (menu -> arrow button left of "SCE:scene1" combobox -> "ADD NEW" -> "empty")
(3) rename scene to yasim (not required)
(4) link to scene1 (F10 -> "Output" tab -> arrow button left of text entry "No Set Scene" -> "scene1")
(5) now load the YASim config file (menu -> "File" -> "Import" -> "YASim (.xml) ...")

This is good enough for simple checks. But if you are working on the YASim configuration, then you need a
quick and convenient way to reload the file. In that case, continue after (4):

(5) switch the button area at the bottom of the blender screen to "Scripts Window" mode (green python snake icon)
(6) load the YASim config file (menu -> "Scripts" -> "Import" -> "YASim (.xml) ...")
(7) make the "Scripts Window" area as small as possible by dragging the area separator down
(8) optionally split the "3D View" area and switch the right part to the "Outliner"
(9) press the "Reload YASim" button in the script area to reload the file

If the 3D model is displaced with respect to the FDM model, then the <offsets> values from the
model animation XML file should be added as comment to the YASim config file, as a line all by
itself, with no spaces surrounding the equal signs. Spaces elsewhere are allowed. For example:

<offsets>
<x-m>3.45</x-m>
<z-m>-0.4</z-m>
<pitch-deg>5</pitch-deg>
</offsets>

becomes:



Possible variables are:

x ... <x-m>
y ... <y-m>
z ... <z-m>
h ... <heading-deg>
p ... <pitch-deg>
r ... <roll-deg>

Of course, absolute FDM coordinates can then no longer directly be read from Blender's 3D view.
The cursor coordinates display in the script area, however, shows the coordinates in YASim space.
Note that object names don't contain XML indices but element numbers. YASim_hstab#2 is the third
hstab in the whole file, not necessarily in its parent XML group. A floating-point part in the
object name (e.g. YASim_hstab#2.004) only means that the geometry has been reloaded that often.
It's an unavoidable consequence of how Blender deals with meshes.

Elements are displayed as follows:

cockpit -> monkey head
fuselage -> blue "tube" (with only 12 sides for less clutter); center at "a"
vstab -> red with yellow flaps
wing/mstab/hstab -> green with yellow flaps/spoilers/slats (always 20 cm deep);
symmetric surfaces are only displayed on the left side
thrusters (jet/propeller/thruster) -> dashed line from center to actionpt;
arrow from actionpt along thrust vector (always 1 m long);
propeller circle
rotor -> radius and rel_len_blade_start circle, direction arrow,
normal and forward vector, one blade at phi0
gear -> contact point and compression vector (no arrow head)
tank -> cube (10 cm side length)
weight -> inverted cone
ballast -> cylinder
hitch -> circle (10 cm diameter)
hook -> dashed line for up angle, T-line for down angle
launchbar -> dashed line for up angles, T-line for down angles
A note about step (0) for Windows users: the mentioned path is inside the folder where Blender lives, something like <code>C:\Program Files\Blender Foundation\Blender\.blender\scripts</code>.

=== Visualize model in OpenSCAD or FreeCAD ===

There exist a possibility to display the YASim XML elements in the OpenSCAD or FreeCAD tools. This could be extremely useful in the case of UAV aircraft development.

* [https://github.com/ThunderFly-aerospace/YASim2SCAD YASim2SCAD] - This tool converts YASim XML to scad file which could be displayed as an overlay in OpenSCAD or FreeCAD project.
* [https://gitlab.com/yasimtoscad/yasimtoscad yasimtoscad] - Another tool to convert YASim XML to scad file which could be displayed as an overlay in OpenSCAD.

=== Visualization tools ===

* [https://github.com/bitwisetech/ysimi YSIMI] Interactive Tuning Tools for FlightGear's YASIM Flight Dynamics Model
* [https://github.com/bitwisetech/yasiVers yasiVers] is a tool for visualization of YASim calculations.

== Export of YASim internals to property tree ==
Ever wondered what is going on inside yasim? See the property tree under /fdm/yasim/

Some information is static and shows what yasim has compiled from your XML.
Other information is "run-time" like forces, speed, acceleration, c.g.

If note noted otherwise:
* expect metric unit (meter, kilogram, newton, ...)
* expect minimum version 2017.2

{| class="wikitable"
|-
! Path !! Description !! Information type !! min. version
|-
| accelerations/ || linear and rot. accelerations in aircraft coord. || run time ||
|-
| debug/ || misc internals, for now subject to change without notice || run time || 2018.1
|-
| forces/ || aerodynamic forces in N || run time ||
|-
| velocities/ || linear and rot. velocities in aircraft coord. || run time ||
|-
| model/cg-x-range-aft || desired CG range || compile time ||
|-
| model/cg-x-range-front || desired CG range || compile time ||
|-
| model/cg-x-max || CG hard limit from gear position || compile time ||
|-
| model/cg-x-min || CG hard limit from gear position || compile time ||
|-
| model/masses || shows the calculated mass points || compile time ||
|-
| model/wings || wing parameters || compile time ||
|}

== Command Line ==
=== Windows ===
By using the standard command line, we can see what the YASim solver is calculating. First, open up Command Prompt, enter in the location of yasim.exe, and then the location of the YASim XML file. For example, here's what you would type in for a standard Windows [[Changelog_2.12|FlightGear 2.12.0]] installation, and viewing the [[F-14_Tomcat|F-14B's]] YASim file.
{{Note|You can copy & paste the examples into Command Prompt by right-clicking on the title and navigate to Edit > Paste. Then, click Enter to execute.}}

<code>"C:\Program Files\FlightGear\bin\Win32\yasim.exe" "C:\Program Files\FlightGear\data\Aircraft\f-14b\f-14b-yasim.xml"</code>

The results will give many different values.

* '''Drag Coefficient:''' The drag coefficient of the aircraft.
* '''Lift Ratio:''' The lift ratio of the aircraft.
* '''Cruise AoA:''' The cruise AoA, from conditions at [[YASim#cruise|<cruise>]] in the xml file.
* '''Tail Incidence:''' The incidence angle of the tail, "solved" by YASim as a way to stabilize the aircraft.
* '''Approach Elevator:''' The approach elevator, from conditions at [[YASim#approach|<approach>]] in the xml file.
* '''CG:''' Center of gravity of the aircraft in coordinates. Unless it's supposed to be offset, it should always have a Y value of 0.

The YASim standalone solver also has some command line flags that change it's behaviour.

<code>"C:\Program Files\FlightGear\bin\Win32\yasim.exe" "C:\Program Files\FlightGear\data\Aircraft\f-14b\f-14b-yasim.xml" -g -a 1000 -s 490</code>

* '''-g:''' Instructs YASim to generate space-separated tabular data instead of the usual solver output. This can be redirected to a file and used in various plotting programs to visualize the actual lift, drag, L/D curves. The columns of the output from left to right are: AoA, Lift, Drag, L/D. (aoa in degrees, lift and drag in G's).
* '''-a <altitude in meter:>''' Run the solver at the given altitude in meter.
* '''-s <speed in knots>:''' Also run at the given airspeed in knots.

{{Note|The values generated by this method are for the aircraft taken as a whole, as solved by YASim, so they differ from the values of the wing airfoil.}}

To get the tabular output for the example above at 1000 m and 150 knots, and to redirect this to a file, one would issue:

<code>"C:\Program Files\FlightGear\bin\Win32\yasim.exe" "C:\Program Files\FlightGear\data\Aircraft\f-14b\f-14b-yasim.xml" -g -a 1000 -s 150 > "C:\Program Files\FlightGear\yasim.txt"</code>

== New features and bugfixes in version 2017.2 ==

=== XML parser ===
==== support for metric and imperial units ====
To make life easier for aircraft developers, the parser supports new additional attributes with a unit suffix, e.g. speed-kt for knots and speed-kmh for kilometers per hour.
* <code><airplane {mass, mass-lbs, mass-kg}="12345" ></code>
* <code><approach {speed, speed-kt, speed-kmh}="123" ></code>
* <code><cruise {speed, speed-kt, speed-kmh}="123" ></code>
* <code><solve-weight {weight, weight-lbs, weight-kg}="123" ></code>
* <code><jet {mass, mass-lbs, mass-kg}="1234" ></code>
* <code><tank {capacity, capacity-lbs, capacity-kg}="12345" ></code>
* <code><ballast {mass, mass-lbs, mass-kg}="1234" ></code>

{{Note|Aircraft using this new attributes will not run on older versions of FlightGear, so it is probably wise to publish those only after a reasonable number of users switched version 2017.2 or newer.}}

==== CG tuning help ====
{{Note| The feature described in this section is not fully implemented yet, however, it may be of some help already.
It is currently implemented for the yasim CLI tool only. It does not affect the airplane behaviour while running FlightGear. }}

New attributes have been added to <airplane> to assist tuning the center of gravity (CG).
The CG position is often expressed relative to the [https://en.wikipedia.org/wiki/Chord_(aeronautics)#Mean_aerodynamic_chord MAC] of the wing in percent. You can specify a desired range for CG in % relative to MAC, it will show up in the output of the yasim CLI tool (see example below):

* cg-min: default 25% (just a guess, better numbers are welcome)
* cg-max: default 30% (just a guess, better numbers are welcome)

{{Note| By convention 0% is leading edge, 100% is trailing edge, however the absolute values on x-axis are the other way round, e.g. nose is +x, tail is -x }}
{{warning|The MAC calculation in version 2017.2 works only on the <wing> element. Numbers will be wrong, if your model uses a combination of <wing> and <mstab> to build a wing with two or more sections.
Section support will be added in version 2018.1}}
YASim will print the leading edge coordinates of the MAC (x,y) and its length.

'''Example output'''
<pre>
$ yasim Citation-II-yasim.xml
This aircraft uses yasim version '2017.2'
==========================
= YASim solution results =
==========================
Iterations: 2210
Drag Coefficient: 12.304669
Lift Ratio: 85.317558
Cruise AoA: 4.016746 deg
Tail Incidence: -3.053278 deg
Approach Elevator: -0.377542

CG: x:-6.543, y:-0.000, z:0.044
Wing MAC (*1): x:-6.00, y:3.83, length:2.0
CG-x rel. MAC: 0.272
CG-x desired: -6.599 < -6.543 < -6.198

Inertia tensor [kg*m^2], origo at CG:

18009.289, -0.000, 7120.470
-0.000, 42459.316, 0.000
7120.470, 0.000, 56980.656

(*1) MAC calculation works on <wing> only! Numbers will be wrong for segmented wings, e.g. <wing>+<mstab>.
</pre>

=== Aircraft developer helpers ===
The command line utility got some new options. For some strange reason, the -a parameter expects altitude in meters instead of ft. This is now visible in the usage message but left unchanged for compatibility.
<syntaxhighlight>Usage:
yasim <aircraft.xml> [-g [-a meters] [-s kts] [-approach | -cruise] ]
yasim <aircraft.xml> [-d [-a meters] [-approach | -cruise] ]
yasim <aircraft.xml> [-m]
-g print lift/drag table: aoa, lift, drag, lift/drag
-d print drag over TAS: kts, drag
-a set altitude in meters!
-s set speed in knots
-m print mass distribution table: id, x, y, z, mass</syntaxhighlight>

=== Bugfixes ===
The following bugfixes require <airplane version="2017.2"> for backward compatibility
* Ground effect: corrected the calculation of the height where g.e. ends
* Stall parameters were set wrong for wings with camber=0

== New features and bugfixes in version 2018.1 ==
The following is under development and hopefully finds its way into FG version 2018.1

=== Wing Section Support ===
Many airliners have wings with a geometry that is just a little more complex than what YASim supported initially (tapered wing with some angles like sweep, dihedral, ...), e.g. they have an inboard section and an outboard section that can be described with YASim wing syntax. You can use a wing + a mstab XML element to describe this geometry but it is easier if YASim can just append more wing sections by simply adding more wing XML elements. This is now (Version 2018.1) possible, yasim will simply append sections if it finds more than one wing or hstab in the XML.
You should use '''<wing append="1" ... >''' for all but the first wing/hstab declaration.
{{Note|YASim will ignore the root point (x,y,z), the chord length and the incidence attributes, if you add "append" and calculate those from the previous wing section. }}
MAC calculation works for the whole wing.

{{warning|Aircrafts using this feature will not work with older versions of flightgear. }}
To keep the aircraft backward compatible for a while, it is recommended to create a copy of its yasim XML file for development.
Once you are happy with the CG and wing parameters you can use the output of the YASim CLI tool to modifiy the original XML.
The tool will output the needed x,y,z etc per wing section to create a XML in old format with (only one) <wing> + <mstab>.

=== More information from CLI tools ===
You should configure the maximum take of weight (MTOW) in your XML file by adding either ''mtow-lbs'' or ''mtow-kg'' attribute to the airplane:

<code> <airplane mass="7500" version="2018.1" mtow-lbs="12500"> </code>

'''Example output'''
<pre>
yasim CRJ700.xml
==========================
= YASim solution results =
==========================
Iterations : 1024
Drag Coefficient : 17.707
Lift Ratio : 145.841
Cruise AoA : -0.11 deg
Tail Incidence : 3.47 deg
Approach Elevator : -0.792

CG : x:-0.046, y:0.000, z:-1.222
Wing MAC : (x:0.79, y:4.99), length:3.4
hard limit CG-x : 14.232 m
soft limit CG-x : -0.058 m
CG-x : -0.046 m
CG-x rel. MAC : 25%
soft limit CG-x : -0.228 m
hard limit CG-x : -0.986 m

wing lever : -0.012 m
tail lever : -13.997 m

max thrust : 157.18 kN
thrust/empty : 0.81
thrust/mtow : 0.49

wing span : 22.64 m
sweep lead. edge : 30.2 .. 30.6 deg
wing area : 58.70 m^2
wing load empty : 336.15 kg/m^2 (Empty 19731 kg)
wing load MTOW : 562.18 kg/m^2 (MTOW 32999 kg)

tail span : 8.533 m
tail area : 14.838 m^2

#wing sections: 2
Section 0 base point (0.450, 1.226, -2.034), chord 5.085, incidence at section root 5.0deg
Section 1 base point (-0.663, 4.754, -1.942), chord 3.204, incidence at section root 3.0deg

Inertia tensor [kg*m^2], origo at CG:

195646, 0, 122265
0, 1757279, 0
122265, 0, 1904528
</pre>

=== Variable tail incidence / elevator trim ===
Small GA aircrafts usually trim with a trim tab on the elevator. For efficiency, airliners normally do not trim the elevator ("flap") but rotate the whole horizontal stabilizer (tail wing), e.g. they change the incidence for this wing. While this feature was somehow foreseen, it was not implemented yet, most likely because the "tail incidence" is one of the free variables used by the YASim solver. However, it is now possible to use the control="INCIDENCE" within the <hstab> to implement an alternative trim '''while maintaining full elevator authority'''.
<pre>
<hstab ... incidence-min-deg="-13.0" incidence-max-deg="2.0">
...
<control-input axis="/controls/flight/hstab-trim" control="INCIDENCE" />
<control-speed control="INCIDENCE" transition-time="20.0" />
<control-output control="INCIDENCE" prop="/surface-positions/hstab-rad" />
</hstab>
</pre>
{{Note|The control output of INCIDENCE is the angle in radians, not in degree, as that is the unit internally used by YASim.}}
{{warning|The OPTIONAL incidence-min-deg and incidence-max-deg set the limits for the solver. You must make sure to select a sufficiently large range or solver will fail. }}
First experiments with this feature were successful in that the aircraft pitch could be changed as expected but fine tuning will be necessary.

== Related content ==
* [[Howto:Make a helicopter#XML Elements]] – Rotor and rotorgear YASim elements
* [[Towing]]
* [[YASim Development Tools]]

== External links ==
* {{cite web
| url = http://www.buckarooshangar.com/flightgear/yasimtut.html
| title = Guide to YASim
| first = Gary R. "Buckaroo"
| last = Neely
| authorlink = http://www.buckarooshangar.com/flightgear/
| date = 2013
| accessdate = April 16, 2020
}} - A very helpful guide
* {{cite web
| url = https://sourceforge.net/projects/dacpei/
| title = DACPEI
| author = pytoche
| date = February 2012
| publisher = SourceForge
| accessdate = April 16, 2020
}} - A fixed wing light aircraft WYSIWUG concept design suite that can export an YASim FDM to FlightGear.

{{FDM}}

[[Category:Flight Dynamics Model]]

[[fr:YASim]]

Property tree

2026-03-18T08:48:32Z

Jsb:

{{PropertyTree}}
The '''property tree''' is considered [[FlightGear]]'s central nervous system and one of its greatest assets. It is the interface to low level, run time state variables via a very intuitive tree-like hierarchy, allowing for FlightGear's behavior to be easily controlled and manipulated at run time.

The concepts and mechanisms behind the property tree may not be immediately obvious to FlightGear beginners. This page is meant to help new users familiarize themselves with the FlightGear property tree.

== The purpose of the property tree ==
The property system - or property tree - represents most of the internal state of all systems within FlightGear, like for example the flight dynamics models, or the weather simulation. The content of these internal state variables are presented in a hierarchically manner and can easily be accessed through a well known API. A system may present its current state to other systems and let them change its current state by allowing to write to its own properties.

One might think of the property system as a global, normalized communication platform, where subsystems may publish variables and access other subsystem's variables. In addition, ''callbacks'' can be registered to invoke code upon read/write access of properties, which serves as the backbone for a very simple, but powerful, ''signalling mechanism'' in FlightGear. Thus, the property system acts as a routing interface, both between different high-level FG sub-systems and the outside world. Data that is required by one FG sub-system can be exposed in the property tree, where it can then be read or modified, either by other internal FG sub-systems, or by and for external input/output.

There is some basic property-debugging support to FlightGear and SimGear. In FlightGear, the --trace-read option causes all read access for a property to be traced, and the --trace-write option causes all write access for a property to be traced, both through SG_LOG messages.

=== Examples of use ===
For example, a left banking joystick input is exposed in the property tree where it is read by the FlightGear FDM sub-system. The FDM subsystem then in turn outputs an aileron deflection back to the property tree where it is then read by the FG animation subsystem to animate the aileron deflection in the 3D model.

Alternatively the joystick input, once exposed in the property tree, can be read and modified by an external application via the [[FlightGear I/O subsystem]], such as an external FDM. The output from the external FDM can then be fed back to FlightGear by writing its data back to the property tree, once again, via the FlightGear I/O subsystem.

There are several subsystems that implement a full API by extending the property tree, such as the AI traffic system, the multiplayer mode, but also Canvas - basically, setting certain properties (for example via Nasal's setprop()), triggering certain code (through listener callbacks) - with arguments and return values passed through the property tree, which in turn allows arbitrary 3D models to be placed, but also AI traffic to be created / controlled, as well as OpenGL textures to be created and modified and run-time, which is what we use to implement HUDs, GUIs, instruments, MFD avionics, and even liveries or scenery textures (VGDS).

== The organization of the property tree ==
Naming a property is very much like naming a file in a file system, with levels of hierarchy. For example:
<pre>
/sim/aircraft = A333

/position/
/position/longitude-deg = '-122.3576677' (double)
/position/latitude-deg = '37.61372424' (double)
/position/altitude-ft = '28.24418581' (double)
/position/altitude-agl-ft = '22.47049626' (double)

/controls/seat/eject/initiate
/controls/electric/APU-generator
</pre>

Some of these variables are "calculated" within the sim (for example updated regularly, in essence at frame rate), whilst others can be manipulated. Writing a variable is as easy as
/* Its my turn to play the sim */
set('/controls/seat/eject/initiate', 1)

What makes FlightGear powerful is that a new aircraft can easily be designed with its unique set of properties that somehow affect the simulation. The aircraft model has an xml file of properties that will be used within the property tree.

== Customizing and manipulating the property tree through Nasal ==
An important feature of the property tree interface is that it can be tailored and new entries added as required through [[Nasal]] scripts, without requiring C++ changes. If you wish to use a custom-written subsystem, such as your own terrain following and avoidance subsystem, for example, and perhaps implemented in [[Nasal]], adding new property tree branches and nodes to handle your unique data presents no problems.

The property tree is read, written, accessed and manipulated in a variety of ways, such as
* startup arguments via <nowiki>--prop:/sim/foo=bar</nowiki>
* XML files
* internal compiled code within FG - the c/c++ code
* [[Nasal]] scripts - this is javascript-like scripting with read/write to the property tree. This is the way most aircraft are implemented.
* Using native protocols, implemented in C++ (see {{fg src file|src/Network}}). [[Property Tree/Sockets]]
* Using the generic protocol, either in/out/bi - this allows send/receive to the FG sim via the [[Generic Protocol]]
* telnet interface - query and fly the plane on the command line or using a scripted session (see [[Telnet usage]])
* html interface - access the property tree using a conventional web browser like firefox/safari or chrome
* using the built in [[Property browser]]
* using other GUI dialogs
* using cockpit bindings
* using joystick bindings etc

So they can come from many places, thus there's no single source file where you'll find ALL properties/types. You will need to look at the corresponding subsystem/component. $FG_SRC/Network is the right pace to look for hardcoded protocols, make sure to also understand their inheritance (the interface being implemented).

== XML and property lists ==
The property tree maps very nicely to XML. This is convenient for initializing the property tree and saving its state. Values in the tree are typed, but they can also be untyped strings which will be converted to a typed value when read.

PropertyList-encoded XML files are mapped to a/the property tree - typically, such XML files are not manually processed, they are "transparently" processed by FlightGear, loaded and mapped into a Property Tree.

== Network Protocols to access the property tree ==
In addition to the protocols supported by the FlightGear I/O subsystem, other interfaces are provided by a built-in [[Property Tree/Web Server]] and a built-in [[Telnet usage|Telnet server]], which allow property tree data to be read and modified via these interfaces, in essence using a telnet client or a conventional web browser, at run time.

Note that you can setup as many of these servers as you want, for instance, just to be obscene you could do:
<pre>
fgfs --httpd=5400 --httpd=5401 --httpd=5402 --telnet=5403 --telnet=5404 --telnet=5405
</pre>

Now there are six network interfaces running that you can access from anywhere ;-)

>> "can I borrow your ipod please?" "why?"

=== Protocol options ===
Usually the "best" way depends on your specific circumstances. Will the two applications be running on the same machine? If not, do the two machines have a high speed network connection or some slow radio modem type connection? How much data are you sending and at what rate? Do you need really tight timing or can you get by with some delays and sloppiness in the communication?

==Dumping the Property Tree to an XML File==

Nasal command "io.write_properties" is used to dump all or part of the property tree to an xml file. The command can be entered interactively while using the simulator or as part of a script.

To enter the command interactively, select Nasal Console from the Debug menu and enter the command:

<code>io.write_properties(getprop("/sim/fg-home") ~ "/Export/PropTree.xml", "/");</code>

This will dump the entire property tree, in a file containing more than 50,000 lines

We can also dump only part of the property tree. For example, to dump everything in /instrumentation/kma20, we would use this:

<code>io.write_properties(getprop("/sim/fg-home") ~ "/Export/PropTree.xml", "/instrumentation/kma20");</code>

In addition to debugging, there are other good reasons for doing a dump of portions of the property tree.

* [[Howto:Create_animation_XML_files_from_Nasal|Creating Animation XML files]]
* [[State Overlay System|Creating State Overlays for Aircraft]]

== Reference documentation to the property tree ==
By what was said above, the property tree is not consistent with fixed variables, they are created dynamically, to represent a propeller plane, a Jumbo or even a "Caspian Sea Monster", or depending on which subsystems are active. Many properties availability may even depend on the startup/runtime settings you are using.

There are a bunch of "common" properties - especially among similar FDMs and aircraft. Obviously, different FDMs/aircraft will use different properties (single piston, helicopter, jet, twin turbine helicopter etc).

You may want to have a look at $FG_ROOT/Docs/README.properties and [[PropertyTree:Reference]]

There are a couple ways that they 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, another is all Nasal files, and the last place (and often most useful!) is grepping (searching) through the C++ code. To determine how a property works and what it does often requires looking through any code that uses it. This is a part of FlightGear that we could certainly document better

== Flight Dynamics Model (FDM) ==
FlightGear uses a few [[Flight Dynamics Models]], such as
* [[JSBSim]]
* [[YASim]]
These flight dynamics models present themselves differently in the tree, using different variables, in different places. That is what an aircraft can be designed around. Most FDMs use so called tied properties, which are directly mapped to memory in C++, so that they cannot be written to - so that you would need to disable the FDM using the null FDM instead.

== Related content ==
* [[PropertyTree:Reference]]
* [[Property browser]]
* [[Property Key Handler]]

[[Category:Property Tree| ]]
[[Category:Nasal]]
[[Category:XML]]

Property tree

2026-03-18T08:47:46Z

Jsb: Add link to PropertyTree:Reference

{{PropertyTree}}
The '''property tree''' is considered [[FlightGear]]'s central nervous system and one of its greatest assets. It is the interface to low level, run time state variables via a very intuitive tree-like hierarchy, allowing for FlightGear's behavior to be easily controlled and manipulated at run time.

The concepts and mechanisms behind the property tree may not be immediately obvious to FlightGear beginners. This page is meant to help new users familiarize themselves with the FlightGear property tree.

== The purpose of the property tree ==
The property system - or property tree - represents most of the internal state of all systems within FlightGear, like for example the flight dynamics models, or the weather simulation. The content of these internal state variables are presented in a hierarchically manner and can easily be accessed through a well known API. A system may present its current state to other systems and let them change its current state by allowing to write to its own properties.

One might think of the property system as a global, normalized communication platform, where subsystems may publish variables and access other subsystem's variables. In addition, ''callbacks'' can be registered to invoke code upon read/write access of properties, which serves as the backbone for a very simple, but powerful, ''signalling mechanism'' in FlightGear. Thus, the property system acts as a routing interface, both between different high-level FG sub-systems and the outside world. Data that is required by one FG sub-system can be exposed in the property tree, where it can then be read or modified, either by other internal FG sub-systems, or by and for external input/output.

There is some basic property-debugging support to FlightGear and SimGear. In FlightGear, the --trace-read option causes all read access for a property to be traced, and the --trace-write option causes all write access for a property to be traced, both through SG_LOG messages.

=== Examples of use ===
For example, a left banking joystick input is exposed in the property tree where it is read by the FlightGear FDM sub-system. The FDM subsystem then in turn outputs an aileron deflection back to the property tree where it is then read by the FG animation subsystem to animate the aileron deflection in the 3D model.

Alternatively the joystick input, once exposed in the property tree, can be read and modified by an external application via the [[FlightGear I/O subsystem]], such as an external FDM. The output from the external FDM can then be fed back to FlightGear by writing its data back to the property tree, once again, via the FlightGear I/O subsystem.

There are several subsystems that implement a full API by extending the property tree, such as the AI traffic system, the multiplayer mode, but also Canvas - basically, setting certain properties (for example via Nasal's setprop()), triggering certain code (through listener callbacks) - with arguments and return values passed through the property tree, which in turn allows arbitrary 3D models to be placed, but also AI traffic to be created / controlled, as well as OpenGL textures to be created and modified and run-time, which is what we use to implement HUDs, GUIs, instruments, MFD avionics, and even liveries or scenery textures (VGDS).

== The organization of the property tree ==
Naming a property is very much like naming a file in a file system, with levels of hierarchy. For example:
<pre>
/sim/aircraft = A333

/position/
/position/longitude-deg = '-122.3576677' (double)
/position/latitude-deg = '37.61372424' (double)
/position/altitude-ft = '28.24418581' (double)
/position/altitude-agl-ft = '22.47049626' (double)

/controls/seat/eject/initiate
/controls/electric/APU-generator
</pre>

Some of these variables are "calculated" within the sim (for example updated regularly, in essence at frame rate), whilst others can be manipulated. Writing a variable is as easy as
/* Its my turn to play the sim */
set('/controls/seat/eject/initiate', 1)

What makes FlightGear powerful is that a new aircraft can easily be designed with its unique set of properties that somehow affect the simulation. The aircraft model has an xml file of properties that will be used within the property tree.

== Customizing and manipulating the property tree through Nasal ==
An important feature of the property tree interface is that it can be tailored and new entries added as required through [[Nasal]] scripts, without requiring C++ changes. If you wish to use a custom-written subsystem, such as your own terrain following and avoidance subsystem, for example, and perhaps implemented in [[Nasal]], adding new property tree branches and nodes to handle your unique data presents no problems.

The property tree is read, written, accessed and manipulated in a variety of ways, such as
* startup arguments via <nowiki>--prop:/sim/foo=bar</nowiki>
* XML files
* internal compiled code within FG - the c/c++ code
* [[Nasal]] scripts - this is javascript-like scripting with read/write to the property tree. This is the way most aircraft are implemented.
* Using native protocols, implemented in C++ (see {{fg src file|src/Network}}). [[Property Tree/Sockets]]
* Using the generic protocol, either in/out/bi - this allows send/receive to the FG sim via the [[Generic Protocol]]
* telnet interface - query and fly the plane on the command line or using a scripted session (see [[Telnet usage]])
* html interface - access the property tree using a conventional web browser like firefox/safari or chrome
* using the built in [[Property browser]]
* using other GUI dialogs
* using cockpit bindings
* using joystick bindings etc

So they can come from many places, thus there's no single source file where you'll find ALL properties/types. You will need to look at the corresponding subsystem/component. $FG_SRC/Network is the right pace to look for hardcoded protocols, make sure to also understand their inheritance (the interface being implemented).

== XML and property lists ==
The property tree maps very nicely to XML. This is convenient for initializing the property tree and saving its state. Values in the tree are typed, but they can also be untyped strings which will be converted to a typed value when read.

PropertyList-encoded XML files are mapped to a/the property tree - typically, such XML files are not manually processed, they are "transparently" processed by FlightGear, loaded and mapped into a Property Tree.

== Network Protocols to access the property tree ==
In addition to the protocols supported by the FlightGear I/O subsystem, other interfaces are provided by a built-in [[Property Tree/Web Server]] and a built-in [[Telnet usage|Telnet server]], which allow property tree data to be read and modified via these interfaces, in essence using a telnet client or a conventional web browser, at run time.

Note that you can setup as many of these servers as you want, for instance, just to be obscene you could do:
<pre>
fgfs --httpd=5400 --httpd=5401 --httpd=5402 --telnet=5403 --telnet=5404 --telnet=5405
</pre>

Now there are six network interfaces running that you can access from anywhere ;-)

>> "can I borrow your ipod please?" "why?"

=== Protocol options ===
Usually the "best" way depends on your specific circumstances. Will the two applications be running on the same machine? If not, do the two machines have a high speed network connection or some slow radio modem type connection? How much data are you sending and at what rate? Do you need really tight timing or can you get by with some delays and sloppiness in the communication?

==Dumping the Property Tree to an XML File==

Nasal command "io.write_properties" is used to dump all or part of the property tree to an xml file. The command can be entered interactively while using the simulator or as part of a script.

To enter the command interactively, select Nasal Console from the Debug menu and enter the command:

<code>io.write_properties(getprop("/sim/fg-home") ~ "/Export/PropTree.xml", "/");</code>

This will dump the entire property tree, in a file containing more than 50,000 lines

We can also dump only part of the property tree. For example, to dump everything in /instrumentation/kma20, we would use this:

<code>io.write_properties(getprop("/sim/fg-home") ~ "/Export/PropTree.xml", "/instrumentation/kma20");</code>

In addition to debugging, there are other good reasons for doing a dump of portions of the property tree.

* [[Howto:Create_animation_XML_files_from_Nasal|Creating Animation XML files]]
* [[State Overlay System|Creating State Overlays for Aircraft]]

== Reference documentation to the property tree ==
By what was said above, the property tree is not consistent with fixed variables, they are created dynamically, to represent a propeller plane, a Jumbo or even a "Caspian Sea Monster", or depending on which subsystems are active. Many properties availability may even depend on the startup/runtime settings you are using.

There are a bunch of "common" properties - especially among similar FDMs and aircraft. Obviously, different FDMs/aircraft will use different properties (single piston, helicopter, jet, twin turbine helicopter etc).

You may want to have a look at $FG_ROOT/Docs/README.properties and [[PropertyTree:Reference]]

There are a couple ways that they 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, another is all Nasal files, and the last place (and often most useful!) is grepping (searching) through the C++ code. To determine how a property works and what it does often requires looking through any code that uses it. This is a part of FlightGear that we could certainly document better

== Flight Dynamics Model (FDM) ==
FlightGear uses a few [[Flight Dynamics Models]], such as
* [[JSBSim]]
* [[YASim]]
These flight dynamics models present themselves differently in the tree, using different variables, in different places. That is what an aircraft can be designed around. Most FDMs use so called tied properties, which are directly mapped to memory in C++, so that they cannot be written to - so that you would need to disable the FDM using the null FDM instead.

== Related content ==
* [[Property browser]]
* [[Property Key Handler]]

[[Category:Property Tree| ]]
[[Category:Nasal]]
[[Category:XML]]

USB-HID

2026-01-14T20:12:58Z

Jsb: /* Linux access rights for devices */

[draft]

USB-HID (Human Interface Device) is one of the methods to connect input devices to FlightGear.

==Linux access rights for devices==
HID devices under linux have usually restricted access rights, e.g. normal users are not allowed to access them directly. As you should not run FlightGear as root user, you most likely need to create a few udev rules to allow normal users to access the device files.

First, use <code>lsusb</code> to get a list of all detected USB devices. The output should look similar to this:<syntaxhighlight lang="shell">
Bus 003 Device 004: ID 294b:1901 Honeycomb Aeronautical Bravo Throttle Quadrant
Bus 003 Device 006: ID 06a3:0763 Saitek PLC Pro Flight Rudder Pedals
Bus 003 Device 002: ID 294b:1900 Honeycomb Aeronautical Alpha Flight Controls
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 006 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 005 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

</syntaxhighlight>Find the lines containing your relevant input devices (joysticks, yoke, throttle, pedals, ...) and note the IDs. The format is <vendor-id>:<device-id>. For simplicity, this example uses only the vendor-id.

On Ubuntu, you can add for example the following file under <code>/etc/udev/rules.d</code> to allow r/w access to members of the <code>input</code> user group. Of course, you have to add/modify the lines to match the vendor-ids of your devices and your user id must be a member of the group.<syntaxhighlight lang="shell">
# /etc/udev/rules.d/40-usb-flightgear.rules
#
# To add your user to the input group try:
# sudo usermod --append --groups input <username>

# Honeycomb
SUBSYSTEMS=="usb", ATTRS{idVendor}=="294b", GROUP="input", MODE="0664"
# saitek
SUBSYSTEMS=="usb", ATTRS{idVendor}=="06a3", GROUP="input", MODE="0664"

</syntaxhighlight>To activate the new rules, try <code>udevadm control --reload-rules && udevadm trigger</code>

If this does not help, a reboot will do.

==Developing Configuration files for input devices==

=== Gathering data ===
Add the following parameters to your FlightGear command line or via the launcher Settings>Additional Settings<syntaxhighlight>
--log-class=input
--log-level=debug
</syntaxhighlight>This will create a lot of debug output for the input systems in which you can find all events supported by your devices

=== Creating a config file ===
The configuration files shall be stored in FGDATA/Input/Event/<Vendor>/<Model>.xml

As a starting point you can copy this example. Replace the data as needed.<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<PropertyList>

<vendor-id>honeycomb</vendor-id>
<model-id>bravo</model-id>


<name>Honeycomb Aeronautical Bravo Throttle Quadrant</name>


<debug-events type="bool">false</debug-events>

<nasal>
<open>
<![CDATA[
#print("Honeycomb Bravo Nasal (event) open");
#bravo = input_helpers.honeycomb.bravo.new(cmdarg());
]]>
</open>
<close>
<![CDATA[
#print("Honeycomb Bravo Nasal (event) close");
#if (ishash(bravo) and isfunc(bravo['close']))
# bravo.close(cmdarg());
]]>
</close>
</nasal>

</PropertyList>
</syntaxhighlight>Example for an axis event:<syntaxhighlight lang="xml">
<event>
<desc>Lever 0</desc>
<name>abs-x-translate</name>
<min-range>-1023</min-range>
<max-range>1023</max-range>
<binding>
<command>property-scale</command>
<property>/input/honeycomb/bravo/lever[0]</property>
</binding>
</event>
</syntaxhighlight>Example for a button event:<syntaxhighlight lang="xml">
<event>
<name>button-1</name>
<desc>AP mode HDG</desc>
<repeatable>false</repeatable>
<binding>
<command>property-assign</command>
<property>/input/honeycomb/bravo/buttons/hdg</property>
<value>1</value>
</binding>
<mod-up>
<binding>
<command>property-assign</command>
<property>/input/honeycomb/bravo/buttons/hdg</property>
<value>0</value>
</binding>
</mod-up>
</event>
</syntaxhighlight>

==Status of OS support==
Linux: Supported

MacOS: supported?

Windows: not yet supported?

== see also ==
[[Input helpers]]

[[Honeycomb Input Devices]]

Conditions

2026-01-14T08:50:05Z

Jsb: /* Supported elements */

'''Conditions''' (or '''<code>SGCondition</code>s''') in the SimGear library are a property-based representation of custom conditions based on comparing property values. They can be evaluated from both C++ and Nasal (see <code>$SGSOURCE/simgear/props/condition.hxx</code> and <code>[[$FG_ROOT]]/Nasal/props.nas</code>). Comparison of string-typed properties involves lexicographic ordering, as specified by the C++ operators <tt><</tt> and <tt>></tt>.

== Usage ==
Conditions are supported in
* All [[bindings]], all [[animations]]
* State machines
* Various parts of [[HUD]]s, 2D panels, [[PUI]]/XML dialogs
* Autopilot / PropertyRule systems
… and several other places.

== Sample conditions ==
This is a sample expression for checking if the throttle on the first engine is above half:
<syntaxhighlight lang="xml">
<condition>
<greater-than>
<property>/controls/engines/engine[0]/throttle</property>
<value type="double">0.5</value>
</greater-than>
</condition>
</syntaxhighlight>

== Supported elements ==
Each comparison (like <code>less-than</code> or <code>greater-than-equals</code>) requires either two <code><property></code> elements (the first with index=0 and the second with index=1) or a <code><property></code> (considered first) and <code><value></code> (considered second); booleans compare each of their child conditions. A <code><condition></code> element itself functions as an <and<tt>></tt> element; that is, it can have several children, all of which must be true to make the whole condition true. Instead of <code><property></code> or <code><value></code>you can also use an <code><expression></code>
<syntaxhighlight lang="xml" enclose="div">
<and>
<or>
<not> 
<equals>
<not-equals>
<less-than>
<greater-than>
<less-than-equals>
<greater-than-equals>
<property> 
<false/> 
<true/>
</syntaxhighlight>

== Related content ==
=== Wiki articles ===
* [[Expressions]]
* [[PropertyList XML files]]

=== Readme file ===
* {{readme file|conditions}}

=== Source code ===
* {{simgear source
| path = simgear/props/condition.hxx
| text = simgear/props/condition.hxx
}}
* {{simgear source
| path = simgear/props/condition.cxx
| text = simgear/props/condition.cxx
}}

[[Category:FlightGear]]
[[Category:XML]]

Expressions

2026-01-11T11:56:22Z

Jsb: /* Table */

{{Stub}}
{{-}}
'''Expressions''' (or '''SGExpressions''') are a feature of the SimGear library and provide a nice way of implementing complex math formulas using XML syntax.
They are supported in many systems within the FlightGear code.

{{caution|Expressions do not check if your math creates floating point exceptions (like division by zero conditions, taking the square root of a negative number, etc.). This can cause undefined behavior and may result in NaNs or even Cascading NaNs.}}

== Usage ==
Expressions are supported in
* [[Autopilot Configuration Reference#Expressions|Autopilot configuration files]]
* Particle system configuration files
* Animations (translate, rotate, scale, range, blend)
* The shader technique
* [[Conditions]]

== Sample Expressions ==
This is a sample expression for <code>c = sqrt(a*a + b^2)</code>. Children/arguments are parsed in the order they appear in in the file (or the order in which they are set via property methods).
<syntaxhighlight lang="xml">
<expression>
<sqrt>
<sum>
<product>
<property>/value/a</property>
<property>/value/a</property>
</product>
<pow>
<property>/value/b</property>
<value>2</value>
</pow>
</sum>
</sqrt>
</expression>
</syntaxhighlight>

== Supported elements ==
<syntaxhighlight lang="xml">
<abs> 
<acos>
<asin>
<atan>
<atan2>
<ceil>
<clip> 
<cos>
<cosh>
<difference> 
<div>
<exp>
<floor>
<log>
<log10>
<max>
<min>
<mod>
<pow>
<product> 
<property> 
<rad2deg>
<deg2rad>
<sin>
<sinh>
<sqr>
<sqrt>
<sum>
<table> 
<tan>
<tanh>
<value>
</syntaxhighlight>

=== Table ===
The table expression uses the following syntax, similarly to the <interpolation> element:<syntaxhighlight lang="xml">
<table>

<entry>
<ind>0.0</ind> 
<dep>0.0</dep> 
</entry>
... 
</table>
</syntaxhighlight>The entries must be sorted by the independent (input) variable strictly ascending. If input is outside the range of the table, output will be determined from the first / last table row.

==== Example ====
The table:
{| class="wikitable"
|0.0
|5.0
|-
|0.5
|7.5
|-
|0.9
| -5.0
|-
|1.0
|25.0
|}
translates to the following code:<syntaxhighlight lang="xml">
<table>

<entry>
<ind>0.0</ind>
<dep>5.0</dep>
</entry>
<entry>
<ind>0.5</ind>
<dep>7.5</dep>
</entry>
<entry>
<ind>0.9</ind>
<dep>-5.0</dep>
</entry>
<entry>
<ind>1.0</ind>
<dep>25.0</dep>
</entry>
</table>
</syntaxhighlight>

=== Quantize continuous input values with nearest-match mode ===
{{Caution|This feature was added to the development branch (aka 'next') in 01/2026. After some more testing, it may be backported or just become part of the next release.}}As an alternative to interpolating, the <nowiki><table> expression can also search the nearest match for an input and return a fixed value. This feature was developed to transform a continuous joystick axis reading from a throttle quadrant into discrete flaps setting numbers.</nowiki>

The discrete return values have to be written into the <dep> elements, the <ind> elements mark the reference input value (e.g. js axis reading for a certain flap setting). The <ind> values must be sorted and no duplicates are allowed.

The output will change "half way" between two <ind> values. <syntaxhighlight lang="xml">
<expression>
<table>

<property></property>

<mode>nearest</mode>
<entry>
<ind>0</ind>
<dep>30</dep>
</entry>
<entry>
<ind>0.12</ind>
<dep>25</dep>
</entry>
<entry>
<ind>0.30</ind>
<dep>20</dep>
</entry>
<entry>
<ind>0.48</ind>
<dep>15</dep>
</entry>
<entry>
<ind>0.66</ind>
<dep>5</dep>
</entry>
<entry>
<ind>0.83</ind>
<dep>1</dep>
</entry>
<entry>
<ind>1.0</ind>
<dep>0</dep>
</entry>
</table>
</expression>

</syntaxhighlight>
===Clip===
An expression to limit e.g. rotation:
<syntaxhighlight lang="xml">
<expression>
<clip>
<clipMin>-45</clipMin>
<clipMax>45</clipMax>
<property>orientation/pitch-deg</property>
</clip>
</expression>
</syntaxhighlight>

== Hints and tips ==
=== Rounding ===
While there is no element for rounding, this workaround can be used for that:
<syntaxhighlight lang="xml">
<expression>
<floor>
<sum>
<property>your/property/here</property>
<value>0.5</value>
</sum>
</floor>
</expression>
</syntaxhighlight>

== Related content ==
=== Wiki articles ===
* [[Conditions]]
* [[PropertyList XML files]]

=== Source code ===
* {{simgear file|simgear/structure/SGExpression.hxx}}
* {{simgear file|simgear/structure/SGExpression.cxx}}

[[Category:XML]]

Bindings

2026-01-11T11:42:26Z

Jsb: /* Related Content */

'''Bindings''' define what happens when a user:
* [[Howto: Make a clickable panel|Clicks an object]] in the [[scenery]] or in an [[aircraft]].
* Presses a key/button on the keyboard or [[joystick]].
* Clicks a [[menu]] item
* Interacts with a dialog (clicking a button, selecting list entries etc)

In other words, '''bindings''' are simply the term for '''actions''' that are associated with certain '''events''' in FlightGear.

There are different types of events supported by various subsystems, but the resulting action that can be triggered will typically involve either a hard-coded command (a so called <code>fgcommand</code>), or a block of scripted code (using [[Nasal]]). Bindings can be parameterized / customized using properties as arguments that are passed to each binding as a props.Node object.
And Nasal code can also be registered to become available as a dedicated <code>fgcommand</code>.

An object, button or key can have multiple bindings assigned to them. The bindings will be executed in the order in which they appear in the XML file. Bindings may contain [[conditions]] to make them conditionally executed. Each binding must specify a command node with its particular type, see below.

{{Note|Aircraft are free to override key bindings to fullfill their needs. The Space Shuttle for instance has no mixture control, so the m-key switches from translational to rotational hand controller.
The key only performs as mixture control if the plane has mixture settings and if the plane didn't re-assign the key - so dependent on what plane you try, it may or may not. Usually the aircraft-specific help spells it out.<ref>{{cite web
|url = https://forum.flightgear.org/viewtopic.php?p=298436#p298436
|title = <nowiki> Re: trouble with m-key </nowiki>
|author = <nowiki> Thorsten </nowiki>
|date = Nov 9th, 2016
|added = Nov 9th, 2016
|script_version = 0.40
}}</ref>
}}

This article gives a small overview of frequently used bindings. Please refer to {{readme file|commands}} for additional information and refer to <code>$FG_SRC/Main/fg_commands.cxx</code> for a complete list of available bindings.

All given codes are examples, found on various places in the [[FlightGear]] package.

== Commands ==
Below are some useful commands, some also with their equivalent Nasal call. A more complete listing can be found in the readme file, {{readme file|commands}}.

To learn more about adding your own custom <code>fgcommands</code> to the source code, see [[Howto:Add new fgcommands to FlightGear]].

=== replay ===
Toggles replay.
<syntaxhighlight lang="xml">
<binding>
<command>replay</command>
</binding>
</syntaxhighlight>
<syntaxhighlight lang="nasal">
fgcommand("replay");
</syntaxhighlight>

=== dialog-close ===
Closes the active dialog.
<syntaxhighlight lang="xml">
<binding>
<command>dialog-close</command>
</binding>
</syntaxhighlight>
<syntaxhighlight lang="nasal">
fgcommand("dialog-close");
</syntaxhighlight>
To close a specific dialog use for example:
<syntaxhighlight lang="nasal">
fgcommand("dialog-close", props.Node.new({"dialog-name": "chat-full"}));
</syntaxhighlight>

=== dialog-show ===
Shows a dialog, which should be present in <tt>''[[$FG_ROOT]]/gui/dialogs''</tt>. In addition, from FlightGear 2.8, dialog files located in <tt>''<aircraft directory>/gui/dialogs''</tt> are also loaded. This should be used for dialogs specific to a certain aircraft.
<syntaxhighlight lang="xml">
<binding>
<command>dialog-show</command>
<dialog-name>location-in-air</dialog-name>
</binding>
</syntaxhighlight>
<syntaxhighlight lang="nasal">
fgcommand("dialog-show", props.Node.new({"dialog-name": "location-in-air"}));
</syntaxhighlight>

; dialog-name : The name of the dialog, as designated in its XML file.

=== nasal ===
[[Nasal]] is frequently used for complicated systems, because it can execute virtually any function and allows running previously-defined Nasal functions.
<syntaxhighlight lang="xml">
<binding>
<command>nasal</command>
<script>b777.afds.input(0,1);</script>
</binding>
</syntaxhighlight>

; script : The Nasal script to execute.
: {{inote|Make sure that the script does not conflict with the {{wikipedia|List of XML and HTML character entity references#Predefined entities in XML|predefined XML entities}}. If it does, you can either put it in a {{wikipedia|CDATA|CDATA section}} or use a non-interpreted version (e.g., <code>&gt;</code> in place of <code>></code>).}}

The {{func link|cmdarg()}} function is often useful in these situations to extract offset values passed to the binding. It returns the specific <tt><binding></tt> node, which contains a <tt><setting></tt> node at runtime if used in a joystick axis that represents the value of that axis.

In joysticks and keyboard keys, the script is run in a specific namespace; please see [[Howto:Understand Namespaces and Methods]] for more information on namespaces.

=== property-adjust ===
Increases or decreases a property's value with a given step. Maximum and minimum values are optional.
<syntaxhighlight lang="xml">
<binding>
<command>property-adjust</command>
<property>/autopilot/settings/heading-bug-deg</property>
<step>1</step>
<min>0</min>
<max>360</max>
<wrap>true</wrap>
</binding>
</syntaxhighlight>

; property : Property that will be changed.
; step : Amount to increase or decrease the property's value. Defaults to 0.
; offset : Offset from the property's current value. If '''step''' is not given, this is multiplied by '''factor'''.
; factor : When '''step''' is not given, '''offset''' is multiplied by this. Defaults to 1.
; min : The minimum allowed value. Defaults to "no minimum."
; max : The maximum allowed value. Defaults to "no maximum."
; wrap : If true, the value will be wrapped when it passes min or max; both min and max must be present for this to work. Defaults to false.:{{Note|When wrap is set to true, the max parameter must be set to the desired maximum value + step or factor in order to work correctly !}}
; mask :This argument accepts three value: <code>integer</code>, <code>decimal</code> and <code>all</code> (default). <code>integer</code> means that <code>step</code> or <code>offset * factor</code> is applied to the part of the property's current value left of the decimal point first. <code>decimal</code> does the same, but applies it to the part to the right of the decimal point. <code>all</code> simply applies it to the whole number. This is especially useful for COM / NAV radio frequency knobs - use <code>integer</code> for the outer (big) knob and <code>decimal</code> for the inner (small) knob.

=== property-assign ===
One of the most important commands. It sets a property to a predefined value or to the value of another property.<ref>{{flightgear source
| path = src/Main/fg_commands.cxx
| line = 446
}}</ref>
<syntaxhighlight lang="xml">
<binding>
<command>property-assign</command>
<property>/autopilot/settings/target-speed-kt</property>
<value>0</value>
</binding>
</syntaxhighlight>
or<syntaxhighlight lang="xml">
<binding>
<command>property-assign</command>
<property>autopilot/input/hdg</property>
<property>instrumentation/heading-indicator/hdg-autopilot</property>
</binding>
</syntaxhighlight>

=== property-cycle ===
Cycles between a list of values and assigns one to a property. The value-list can vary in length. If the current value is <code>value1</code>, it will change to <code>value2</code>; if it is <code>value2</code>, it will change to <code>value3</code>, and so on. If the current value is not in the list, it will jump to the first one.
<syntaxhighlight lang="xml">
<binding>
<command>property-cycle</command>
<property>/autopilot/autobrake/setting</property>
<value type="string">ARM</value>
<value type="string">DISARM</value>
<value type="string">OFF</value>
</binding>
</syntaxhighlight>
As of May 2013, the command supports additional behaviours to simplify use with the new [[Knob_/_slider_animation|knob and slider animations]]. The wrapping behaviour can be disabled by setting <code><wrap>0</wrap></code>, and the command uses the <code>offset</code> argument to select a direction of movement. This means a <code>property-cycle</code> bound to a multi-position knob will function as expected for movement in both directions.

=== property-interpolate ===
Interpolates to a value with a given rate of change (per second).
<syntaxhighlight lang="xml">
<binding>
<command>property-interpolate</command>
<property>/controls/flight/aileron-trim</property>
<value type="double">0</value>
<rate>0.5</rate>
</binding>
</syntaxhighlight>

Instead of using <code><rate></code>, one could use <code><nowiki><time></nowiki></code><time>, to specify the time (in seconds) it takes to go to the new value, independent of the current value.
<syntaxhighlight lang="xml">
<binding>
<command>property-interpolate</command>
<property>/controls/flight/aileron-trim</property>
<value type="double">0</value>
<time>2</time>
</binding>
</syntaxhighlight>

You can also interpolate to a value given by a property.
<syntaxhighlight lang="xml">
<binding>
<command>property-interpolate</command>
<property>/controls/flight/aileron-trim</property>
<property>/controls/flight/default-aileron-trim</property>
<rate>0.5</rate>
</binding>
</syntaxhighlight>

=== property-multiply ===
Multiply the value of a property by a given factor.
<syntaxhighlight>
<binding>
<command>property-multiply</command>
<property>/controls/flight/aileron</property>
<factor>0.5</factor>
<min>-1</min>
<max>1</max>
<mask>all</mask>
<wrap>true</wrap>
</binding>
</syntaxhighlight>
*'''factor:''' the amount to multiply by.
*'''min:''' minimum value.
*'''max:''' maximum value.
*'''mask:'''
** '''integer:''' mutiply only left of the decimal point.
** '''decimal:''' multiply only the right of the decimal point.
** '''all:''' multiply the entire value.
*'''wrap:''' true if the value should be wrapped if it passes min/max. It is required to set both min and max in that case.

=== property-randomize ===
Assigns a random value (between min and max) to a property.
<syntaxhighlight lang="xml">
<binding>
<command>property-randomize</command>
<property>/orientation/pitch-deg</property>
<min>0</min>
<max>360</max>
</binding>
</syntaxhighlight>

=== property-scale ===
Set the value of a property based on an axis, often used in [[joystick]] configuration files.
<syntaxhighlight lang="xml">
<binding>
<command>property-scale</command>
<property>/controls/flight/aileron</property>
<offset>0.001</offset>
<factor>-1</factor>
<power>3</power>
</binding>
</syntaxhighlight>

* '''setting:''' the current input setting (usually a joystick axis from -1 or 0 to 1)
* '''offset:''' the offset to shift by, before applying the factor.
* '''factor:''' the factor to multiply by (use negative to reverse).
* '''squared:''' if true will square the resulting value (same as power=2).
* '''power:''' the resulting value will be taken to the power of this integer value (overrides squared).

Remember: <code>(property ^ power + offset) * factor = result</code>

=== property-swap ===
Swaps the values of two properties, useful for radio panels.
<syntaxhighlight lang="xml">
<binding>
<command>property-swap</command>
<property>/instrumentation/comm/frequencies/selected-mhz</property>
<property>/instrumentation/comm/frequencies/standby-mhz</property>
</binding>
</syntaxhighlight>

=== property-toggle ===
Toggles the value of a property on each click, between <code>true</code> <code>(1</code>) and <code>false</code> (<code>0</code>):
<syntaxhighlight lang="xml">
<binding>
<command>property-toggle</command>
<property>/controls/gear/gear-down</property>
</binding>
</syntaxhighlight>
Or - if defined - it toggles between two custom values:
<syntaxhighlight lang="xml">
<binding>
<command>property-toggle</command>
<property>/controls/gear/gear-down</property>
<value>2</value>
<value>3</value>
</binding>
</syntaxhighlight>

===request-metar ===
{{cquote|
<syntaxhighlight lang="nasal">
fgcommand("request-metar", props.Node.new({"path": "/foo/mymetar", "station": "LOWI"}));
</syntaxhighlight>

If you pass an existing path, the station ID will be updated, and if you pass the same station ID as before, no additional request is made. As usual for metar-properties, there's a time-to-live and valid flags you can check, and the metar refreshes automatically every 900 seconds. You can also write to the station ID directly to change station, update the time-to-live, and wait for the valid signal.

There's also an unregister command ('clear-metar') to cancel the binding into the property tree.<ref>{{cite web |url=http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg38372.html|title=<nowiki>[Flightgear-devel] Requesting arbitrary metar</nowiki>|author=James Turner|date=Sun, 23 Sep 2012 08:56:48 -0700}}</ref>|James Turner}}

<references/>

== Using Expressions in Bindings ==
{{Caution|This feature was added to the development branch (aka 'next') in 01/2026. After some more testing, it may be backported or just become part of the next release.}}
Instead of using one of the commands shown above you can also add an expression to a binding to perform some math on the input raw value, before writing it into the property tree.

Do not add a <command>, just add an <expression> and a <property> were the result should be stored. Inside the expression, an empty property path (<code><property></property></code>) refers to the input value of the binding.

=== Example: ===
We have a lever on a throttle quadrant which initially gives us a floating point number between 0 and 1. Now, if this lever shall drive the flaps, we want to map certain positions to discrete flaps settings.
To achieve this, we can use a table expression using nearest-match mode.
<syntaxhighlight lang="xml">
<event>
<desc>Lever 5</desc>
<min-range>-1023</min-range>
<max-range>1023</max-range>
<name>abs-z-translate</name>
<binding>

<property>/input/honeycomb/bravo/flaps-boeing</property>

<expression>
<table>

<property></property>

<mode>nearest</mode>
<entry>
<ind>0</ind>
<dep>30</dep>
</entry>
<entry>
<ind>0.12</ind>
<dep>25</dep>
</entry>
<entry>
<ind>0.30</ind>
<dep>20</dep>
</entry>
<entry>
<ind>0.48</ind>
<dep>15</dep>
</entry>
<entry>
<ind>0.66</ind>
<dep>5</dep>
</entry>
<entry>
<ind>0.83</ind>
<dep>1</dep>
</entry>
<entry>
<ind>1.0</ind>
<dep>0</dep>
</entry>
</table>
</expression>
</binding>
</event>
</syntaxhighlight>

== Related Content ==
=== Wiki ===
* [[Conditions]]
* [[Expressions]]
* [[Howto:Make a clickable panel]]
* [[Howto:Reassign keyboard bindings]]

=== Forum topics ===
* {{forum link|t=37443|title=Order of multiple bindings}}
* {{forum link|t=37447|title=Amending to key bindings}} - Partially about indices (<code><nowiki><binding n="<index>"></nowiki></code>) for bindings.

=== Readme file ===
* {{readme file|commands}}

=== Source ===
Note that many commands are defined elsewhere. The readme file has a more complete listing.

* {{flightgear source|path=src/Main/fg_commands.hxx}}
* {{flightgear source|path=src/Main/fg_commands.cxx}}

* {{simgear source|path=simgear/structure/commands.hxx}}
* {{simgear source|path=simgear/structure/commands.cxx}}

[[Category:Development]]
[[Category:XML]]
[[Category:FlightGear keyboard]]
[[Category:Joysticks and Yokes]]

Bindings

2026-01-11T11:41:46Z

Jsb: Add section "Using Expressions in Bindings"

'''Bindings''' define what happens when a user:
* [[Howto: Make a clickable panel|Clicks an object]] in the [[scenery]] or in an [[aircraft]].
* Presses a key/button on the keyboard or [[joystick]].
* Clicks a [[menu]] item
* Interacts with a dialog (clicking a button, selecting list entries etc)

In other words, '''bindings''' are simply the term for '''actions''' that are associated with certain '''events''' in FlightGear.

There are different types of events supported by various subsystems, but the resulting action that can be triggered will typically involve either a hard-coded command (a so called <code>fgcommand</code>), or a block of scripted code (using [[Nasal]]). Bindings can be parameterized / customized using properties as arguments that are passed to each binding as a props.Node object.
And Nasal code can also be registered to become available as a dedicated <code>fgcommand</code>.

An object, button or key can have multiple bindings assigned to them. The bindings will be executed in the order in which they appear in the XML file. Bindings may contain [[conditions]] to make them conditionally executed. Each binding must specify a command node with its particular type, see below.

{{Note|Aircraft are free to override key bindings to fullfill their needs. The Space Shuttle for instance has no mixture control, so the m-key switches from translational to rotational hand controller.
The key only performs as mixture control if the plane has mixture settings and if the plane didn't re-assign the key - so dependent on what plane you try, it may or may not. Usually the aircraft-specific help spells it out.<ref>{{cite web
|url = https://forum.flightgear.org/viewtopic.php?p=298436#p298436
|title = <nowiki> Re: trouble with m-key </nowiki>
|author = <nowiki> Thorsten </nowiki>
|date = Nov 9th, 2016
|added = Nov 9th, 2016
|script_version = 0.40
}}</ref>
}}

This article gives a small overview of frequently used bindings. Please refer to {{readme file|commands}} for additional information and refer to <code>$FG_SRC/Main/fg_commands.cxx</code> for a complete list of available bindings.

All given codes are examples, found on various places in the [[FlightGear]] package.

== Commands ==
Below are some useful commands, some also with their equivalent Nasal call. A more complete listing can be found in the readme file, {{readme file|commands}}.

To learn more about adding your own custom <code>fgcommands</code> to the source code, see [[Howto:Add new fgcommands to FlightGear]].

=== replay ===
Toggles replay.
<syntaxhighlight lang="xml">
<binding>
<command>replay</command>
</binding>
</syntaxhighlight>
<syntaxhighlight lang="nasal">
fgcommand("replay");
</syntaxhighlight>

=== dialog-close ===
Closes the active dialog.
<syntaxhighlight lang="xml">
<binding>
<command>dialog-close</command>
</binding>
</syntaxhighlight>
<syntaxhighlight lang="nasal">
fgcommand("dialog-close");
</syntaxhighlight>
To close a specific dialog use for example:
<syntaxhighlight lang="nasal">
fgcommand("dialog-close", props.Node.new({"dialog-name": "chat-full"}));
</syntaxhighlight>

=== dialog-show ===
Shows a dialog, which should be present in <tt>''[[$FG_ROOT]]/gui/dialogs''</tt>. In addition, from FlightGear 2.8, dialog files located in <tt>''<aircraft directory>/gui/dialogs''</tt> are also loaded. This should be used for dialogs specific to a certain aircraft.
<syntaxhighlight lang="xml">
<binding>
<command>dialog-show</command>
<dialog-name>location-in-air</dialog-name>
</binding>
</syntaxhighlight>
<syntaxhighlight lang="nasal">
fgcommand("dialog-show", props.Node.new({"dialog-name": "location-in-air"}));
</syntaxhighlight>

; dialog-name : The name of the dialog, as designated in its XML file.

=== nasal ===
[[Nasal]] is frequently used for complicated systems, because it can execute virtually any function and allows running previously-defined Nasal functions.
<syntaxhighlight lang="xml">
<binding>
<command>nasal</command>
<script>b777.afds.input(0,1);</script>
</binding>
</syntaxhighlight>

; script : The Nasal script to execute.
: {{inote|Make sure that the script does not conflict with the {{wikipedia|List of XML and HTML character entity references#Predefined entities in XML|predefined XML entities}}. If it does, you can either put it in a {{wikipedia|CDATA|CDATA section}} or use a non-interpreted version (e.g., <code>&gt;</code> in place of <code>></code>).}}

The {{func link|cmdarg()}} function is often useful in these situations to extract offset values passed to the binding. It returns the specific <tt><binding></tt> node, which contains a <tt><setting></tt> node at runtime if used in a joystick axis that represents the value of that axis.

In joysticks and keyboard keys, the script is run in a specific namespace; please see [[Howto:Understand Namespaces and Methods]] for more information on namespaces.

=== property-adjust ===
Increases or decreases a property's value with a given step. Maximum and minimum values are optional.
<syntaxhighlight lang="xml">
<binding>
<command>property-adjust</command>
<property>/autopilot/settings/heading-bug-deg</property>
<step>1</step>
<min>0</min>
<max>360</max>
<wrap>true</wrap>
</binding>
</syntaxhighlight>

; property : Property that will be changed.
; step : Amount to increase or decrease the property's value. Defaults to 0.
; offset : Offset from the property's current value. If '''step''' is not given, this is multiplied by '''factor'''.
; factor : When '''step''' is not given, '''offset''' is multiplied by this. Defaults to 1.
; min : The minimum allowed value. Defaults to "no minimum."
; max : The maximum allowed value. Defaults to "no maximum."
; wrap : If true, the value will be wrapped when it passes min or max; both min and max must be present for this to work. Defaults to false.:{{Note|When wrap is set to true, the max parameter must be set to the desired maximum value + step or factor in order to work correctly !}}
; mask :This argument accepts three value: <code>integer</code>, <code>decimal</code> and <code>all</code> (default). <code>integer</code> means that <code>step</code> or <code>offset * factor</code> is applied to the part of the property's current value left of the decimal point first. <code>decimal</code> does the same, but applies it to the part to the right of the decimal point. <code>all</code> simply applies it to the whole number. This is especially useful for COM / NAV radio frequency knobs - use <code>integer</code> for the outer (big) knob and <code>decimal</code> for the inner (small) knob.

=== property-assign ===
One of the most important commands. It sets a property to a predefined value or to the value of another property.<ref>{{flightgear source
| path = src/Main/fg_commands.cxx
| line = 446
}}</ref>
<syntaxhighlight lang="xml">
<binding>
<command>property-assign</command>
<property>/autopilot/settings/target-speed-kt</property>
<value>0</value>
</binding>
</syntaxhighlight>
or<syntaxhighlight lang="xml">
<binding>
<command>property-assign</command>
<property>autopilot/input/hdg</property>
<property>instrumentation/heading-indicator/hdg-autopilot</property>
</binding>
</syntaxhighlight>

=== property-cycle ===
Cycles between a list of values and assigns one to a property. The value-list can vary in length. If the current value is <code>value1</code>, it will change to <code>value2</code>; if it is <code>value2</code>, it will change to <code>value3</code>, and so on. If the current value is not in the list, it will jump to the first one.
<syntaxhighlight lang="xml">
<binding>
<command>property-cycle</command>
<property>/autopilot/autobrake/setting</property>
<value type="string">ARM</value>
<value type="string">DISARM</value>
<value type="string">OFF</value>
</binding>
</syntaxhighlight>
As of May 2013, the command supports additional behaviours to simplify use with the new [[Knob_/_slider_animation|knob and slider animations]]. The wrapping behaviour can be disabled by setting <code><wrap>0</wrap></code>, and the command uses the <code>offset</code> argument to select a direction of movement. This means a <code>property-cycle</code> bound to a multi-position knob will function as expected for movement in both directions.

=== property-interpolate ===
Interpolates to a value with a given rate of change (per second).
<syntaxhighlight lang="xml">
<binding>
<command>property-interpolate</command>
<property>/controls/flight/aileron-trim</property>
<value type="double">0</value>
<rate>0.5</rate>
</binding>
</syntaxhighlight>

Instead of using <code><rate></code>, one could use <code><nowiki><time></nowiki></code><time>, to specify the time (in seconds) it takes to go to the new value, independent of the current value.
<syntaxhighlight lang="xml">
<binding>
<command>property-interpolate</command>
<property>/controls/flight/aileron-trim</property>
<value type="double">0</value>
<time>2</time>
</binding>
</syntaxhighlight>

You can also interpolate to a value given by a property.
<syntaxhighlight lang="xml">
<binding>
<command>property-interpolate</command>
<property>/controls/flight/aileron-trim</property>
<property>/controls/flight/default-aileron-trim</property>
<rate>0.5</rate>
</binding>
</syntaxhighlight>

=== property-multiply ===
Multiply the value of a property by a given factor.
<syntaxhighlight>
<binding>
<command>property-multiply</command>
<property>/controls/flight/aileron</property>
<factor>0.5</factor>
<min>-1</min>
<max>1</max>
<mask>all</mask>
<wrap>true</wrap>
</binding>
</syntaxhighlight>
*'''factor:''' the amount to multiply by.
*'''min:''' minimum value.
*'''max:''' maximum value.
*'''mask:'''
** '''integer:''' mutiply only left of the decimal point.
** '''decimal:''' multiply only the right of the decimal point.
** '''all:''' multiply the entire value.
*'''wrap:''' true if the value should be wrapped if it passes min/max. It is required to set both min and max in that case.

=== property-randomize ===
Assigns a random value (between min and max) to a property.
<syntaxhighlight lang="xml">
<binding>
<command>property-randomize</command>
<property>/orientation/pitch-deg</property>
<min>0</min>
<max>360</max>
</binding>
</syntaxhighlight>

=== property-scale ===
Set the value of a property based on an axis, often used in [[joystick]] configuration files.
<syntaxhighlight lang="xml">
<binding>
<command>property-scale</command>
<property>/controls/flight/aileron</property>
<offset>0.001</offset>
<factor>-1</factor>
<power>3</power>
</binding>
</syntaxhighlight>

* '''setting:''' the current input setting (usually a joystick axis from -1 or 0 to 1)
* '''offset:''' the offset to shift by, before applying the factor.
* '''factor:''' the factor to multiply by (use negative to reverse).
* '''squared:''' if true will square the resulting value (same as power=2).
* '''power:''' the resulting value will be taken to the power of this integer value (overrides squared).

Remember: <code>(property ^ power + offset) * factor = result</code>

=== property-swap ===
Swaps the values of two properties, useful for radio panels.
<syntaxhighlight lang="xml">
<binding>
<command>property-swap</command>
<property>/instrumentation/comm/frequencies/selected-mhz</property>
<property>/instrumentation/comm/frequencies/standby-mhz</property>
</binding>
</syntaxhighlight>

=== property-toggle ===
Toggles the value of a property on each click, between <code>true</code> <code>(1</code>) and <code>false</code> (<code>0</code>):
<syntaxhighlight lang="xml">
<binding>
<command>property-toggle</command>
<property>/controls/gear/gear-down</property>
</binding>
</syntaxhighlight>
Or - if defined - it toggles between two custom values:
<syntaxhighlight lang="xml">
<binding>
<command>property-toggle</command>
<property>/controls/gear/gear-down</property>
<value>2</value>
<value>3</value>
</binding>
</syntaxhighlight>

===request-metar ===
{{cquote|
<syntaxhighlight lang="nasal">
fgcommand("request-metar", props.Node.new({"path": "/foo/mymetar", "station": "LOWI"}));
</syntaxhighlight>

If you pass an existing path, the station ID will be updated, and if you pass the same station ID as before, no additional request is made. As usual for metar-properties, there's a time-to-live and valid flags you can check, and the metar refreshes automatically every 900 seconds. You can also write to the station ID directly to change station, update the time-to-live, and wait for the valid signal.

There's also an unregister command ('clear-metar') to cancel the binding into the property tree.<ref>{{cite web |url=http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg38372.html|title=<nowiki>[Flightgear-devel] Requesting arbitrary metar</nowiki>|author=James Turner|date=Sun, 23 Sep 2012 08:56:48 -0700}}</ref>|James Turner}}

<references/>

== Using Expressions in Bindings ==
{{Caution|This feature was added to the development branch (aka 'next') in 01/2026. After some more testing, it may be backported or just become part of the next release.}}
Instead of using one of the commands shown above you can also add an expression to a binding to perform some math on the input raw value, before writing it into the property tree.

Do not add a <command>, just add an <expression> and a <property> were the result should be stored. Inside the expression, an empty property path (<code><property></property></code>) refers to the input value of the binding.

=== Example: ===
We have a lever on a throttle quadrant which initially gives us a floating point number between 0 and 1. Now, if this lever shall drive the flaps, we want to map certain positions to discrete flaps settings.
To achieve this, we can use a table expression using nearest-match mode.
<syntaxhighlight lang="xml">
<event>
<desc>Lever 5</desc>
<min-range>-1023</min-range>
<max-range>1023</max-range>
<name>abs-z-translate</name>
<binding>

<property>/input/honeycomb/bravo/flaps-boeing</property>

<expression>
<table>

<property></property>

<mode>nearest</mode>
<entry>
<ind>0</ind>
<dep>30</dep>
</entry>
<entry>
<ind>0.12</ind>
<dep>25</dep>
</entry>
<entry>
<ind>0.30</ind>
<dep>20</dep>
</entry>
<entry>
<ind>0.48</ind>
<dep>15</dep>
</entry>
<entry>
<ind>0.66</ind>
<dep>5</dep>
</entry>
<entry>
<ind>0.83</ind>
<dep>1</dep>
</entry>
<entry>
<ind>1.0</ind>
<dep>0</dep>
</entry>
</table>
</expression>
</binding>
</event>
</syntaxhighlight>

== Related Content ==
=== Wiki ===
* [[Conditions]]
* [[Howto:Make a clickable panel]]
* [[Howto:Reassign keyboard bindings]]

=== Forum topics ===
* {{forum link|t=37443|title=Order of multiple bindings}}
* {{forum link|t=37447|title=Amending to key bindings}} - Partially about indices (<code><nowiki><binding n="<index>"></nowiki></code>) for bindings.

=== Readme file ===
* {{readme file|commands}}

=== Source ===
Note that many commands are defined elsewhere. The readme file has a more complete listing.

* {{flightgear source|path=src/Main/fg_commands.hxx}}
* {{flightgear source|path=src/Main/fg_commands.cxx}}

* {{simgear source|path=simgear/structure/commands.hxx}}
* {{simgear source|path=simgear/structure/commands.cxx}}

[[Category:Development]]
[[Category:XML]]
[[Category:FlightGear keyboard]]
[[Category:Joysticks and Yokes]]

Nasal library/string

2026-01-09T15:15:03Z

Jsb: /* string.squeeze(s,length) */

{{Stub}}
{{Nasal Navigation}}
== String Handling ==
This page contains description of functions available in "$FG_ROOT\data\Nasal\strings.nas".
For string related functions in Nasal also see [[Nasal_library|Nasal library]] page.
UTF8 specific functions are from Nasal core library.

== One Character Functions ==
=== string.isalnum() ===

Checks whether the character is an ASCII alphanumeric character (either a letter `A–Z`/`a–z` or a digit `0–9`).

<syntaxhighlight lang="nasal">
string.isalnum();
</syntaxhighlight>

=== string.isalpha() ===

Checks whether the character is an ASCII alphabetic letter (either uppercase `A–Z` or lowercase `a–z`).

<syntaxhighlight lang="nasal">
string.isalpha();
</syntaxhighlight>

=== string.isascii() ===

Checks whether the character code is a valid ASCII value (in the range 0–127).

<syntaxhighlight lang="nasal">
string.isascii();
</syntaxhighlight>

=== string.isblank() ===

Checks whether the given character code represents a blank character (a space or a horizontal tab).

<syntaxhighlight lang="nasal">
string.isblank();
</syntaxhighlight>

=== string.iscntrl() ===

Checks whether the given character code represents an ASCII control character (in the range 1–31 or 127).

<syntaxhighlight lang="nasal">
string.iscntrl();
</syntaxhighlight>

=== string.isdigit() ===

Checks whether the character represents a decimal digit (0–9).

<syntaxhighlight lang="nasal">
string.isdigit();
</syntaxhighlight>

=== string.isgraph() ===

Checks whether the character is a graphical character, meaning any visible character that is either alphanumeric or punctuation, excluding whitespace.

<syntaxhighlight lang="nasal">
string.isgraph();
</syntaxhighlight>

=== string.islower() ===

Checks whether the character is a lowercase ASCII letter (`a–z`).

<syntaxhighlight lang="nasal">
string.islower();
</syntaxhighlight>

=== string.isprint() ===

Checks whether the character is printable, meaning it is either a visible graphical character or a space character.

<syntaxhighlight lang="nasal">
string.isprint();
</syntaxhighlight>

=== string.ispunct() ===

Checks whether the given character code represents a punctuation character (based on standard ASCII punctuation ranges).

<syntaxhighlight lang="nasal">
string.ispunct();
</syntaxhighlight>

=== string.isspace() ===

Checks whether the character is a whitespace character (space, tab, newline, vertical tab, form feed, or carriage return).

<syntaxhighlight lang="nasal">
string.isspace();
</syntaxhighlight>

=== string.isupper() ===

Checks whether the character is an uppercase ASCII letter (A–Z).

<syntaxhighlight lang="nasal">
string.isupper();
</syntaxhighlight>

=== string.isxdigit() ===

Checks whether the character represents a valid hexadecimal digit (0–9, a–f, or A–F).

<syntaxhighlight lang="nasal">
string.isxdigit();
</syntaxhighlight>

=== string.isxspace() ===

Checks whether the character is an extended whitespace character — includes all standard whitespace characters (space, tab, vertical tab, form feed, carriage return) plus the newline character, making it an extended version of isspace().

<syntaxhighlight lang="nasal">
string.isxspace();
</syntaxhighlight>

=== string.toupper() ===

Converts a lowercase ASCII letter to its corresponding uppercase letter; if the character is not lowercase, it is returned unchanged.

<syntaxhighlight lang="nasal">
string.toupper();
</syntaxhighlight>

=== string.tolower() ===

Converts an uppercase ASCII letter to its corresponding lowercase letter; if the character is not uppercase, it is returned unchanged.

<syntaxhighlight lang="nasal">
string.tolower();
</syntaxhighlight>

== String Functions ==
=== string.icmp(a,b) ===
Case insensitive string compare function.
<syntaxhighlight lang="nasal">
string.icmp(a,b);
</syntaxhighlight>

=== string.imatch(a,b) ===
Case insensitive match function.
<syntaxhighlight lang="nasal">
string.imatch(a,b);
</syntaxhighlight>
For example:
*string.imatch("alpha","beta") -> 0
*string.imatch("alpha","alpha") -> 1
*string.imatch("","alpha") -> 0
*string.imatch("","") -> 1

=== string.join(sep,list) ===
Join all elements of a list inserting a separator between every two of them. See [[Nasal_library#split()|split()]].
<syntaxhighlight lang="nasal">
string.join(sep,list);
</syntaxhighlight>

=== string.lc(str) ===
Return string converted to lower case letters.
<syntaxhighlight lang="nasal">
string.lc(str);
</syntaxhighlight>

=== string.match(str, patt) ===
Check if string <str> matches shell style pattern <patt>
<syntaxhighlight lang="nasal">
# Rules:
# ? stands for any single character
# * stands for any number (including zero) of arbitrary characters
# \ escapes the next character and makes it stand for itself; that is:
# \? stands for a question mark (not the "any single character" placeholder)
# [] stands for a group of characters:
# [abc] stands for letters a, b or c
# [^abc] stands for any character but a, b, and c (^ as first character -> inversion)
# [1-4] stands for digits 1 to 4 (1, 2, 3, 4)
# [1-4-] stands for digits 1 to 4, and the minus
# [-1-4] same as above
# [1-3-6] stands for digits 1 to 3, minus, and 6
# [1-3-6-9] stands for digits 1 to 3, minus, and 6 to 9
# [][] stands for the closing and the opening bracket (']' must be first!)
# [^^] stands for all characters but the caret symbol
# [\/] stands for a backslash or a slash (the backslash isn't an
# escape character in a [] character group)
#
# Note that a minus can't be a range delimiter, as in [a--e],
# which would be interpreted as any of a, e, or minus.
#
# Example:

string.match(name, "*[0-9].xml"); ... true if 'name' ends with digit followed by ".xml"
</syntaxhighlight>
=== string.normpath(path) ===
Removes superfluous slashes, empty and "." elements,
expands all ".." elements keeping relative paths,
and turns all backslashes into slashes.
The result will start with a slash if it started with a slash or backslash, it will end without slash.
<syntaxhighlight lang="nasal">
string.normpath(path);
</syntaxhighlight>
See also [[Nasal_library#resolvepath|resolvepath()]] function, which can be used to test if a file exists.

=== string.replace(str,old,new) ===
Replace all occurrences of 'old' by 'new'.
<syntaxhighlight lang="nasal">
string.replace(str,old,new);
</syntaxhighlight>
=== string.scanf(test,format,result) ===
Simple scanf function. Takes an input string, a pattern, and a vector.
It returns 0 if the format didn't match, and appends all found elements to the given vector.

Return values:
-1 string matched format ending with % (i.e. more chars than format cared about)
0 string didn't match format
1 string matched, but would still match if the right chars were added
2 string matched, and would not if any character would be added

<syntaxhighlight lang="nasal">
var r = string.scanf("comm3freq123.456", "comm%ufreq%f", var result = []);
</syntaxhighlight>
The result vector will be set to [3, 123.456].

=== string.squeeze(s,length) ===
Shorten string s to length by replacing characters in the middle by '...'. Works for length >= 7

(since 2020.4 / next as of 03.08.2024)

<syntaxhighlight>
var r = string.squeeze("ABCDEFGH", 7);
</syntaxhighlight>
r now contains the string "AB...GH".

=== string.trim(str,lr[,func]) ===
Trim spaces at the left (lr < 0), at the right (lr > 0), or both (lr = 0) is default.
An optional function argument defines which characters should be trimmed:
<syntaxhighlight lang="nasal">
string.trim(a); # trim spaces
string.trim(a, 1, string.isdigit); # trim digits at the right
string.trim(a, 0, func(c) c == `\\` or c == `/`); # trim slashes/backslashes
</syntaxhighlight>
=== string.uc(str) ===
Return string converted to upper case letters.
<syntaxhighlight lang="nasal">
string.uc(str);
</syntaxhighlight>

=== string.compileTemplate(template,type=nil) ===
Get a function out of a string template for fast insertion of template parameters.
This allows to use the same templates as with most available tile mapping engines (eg. Leaflet, Polymaps).
Return a callable function object on success, and nil if parsing the templated fails.
<syntaxhighlight lang="nasal">
string.compileTemplate(template);
</syntaxhighlight>
Example (Build MapQuest tile url):
<syntaxhighlight lang="nasal">
var makeUrl = string.compileTemplate(
"http://otile1.mqcdn.com/tiles/1.0.0/map/{z}/{x}/{y}.jpg"
);
print( makeUrl({x: 5, y: 4, z: 3}) );

Output: http://otile1.mqcdn.com/tiles/1.0.0/map/3/5/4.jpg
</syntaxhighlight>

== UTF8 String Functions (Core) ==
=== utf8.chstr(unicode) ===
Returns a string containing the UTF8 representation of the specified unicode character value.
=== utf8.strc(string, index) ===
Returns the unicode character at the specified index within the UTF8 string. Dies on encoding error or overrun.
=== utf8.substr(string, start, len=nil) ===
As for regular substr(), but the indices are of UTF8 characters intead of bytes. Dies on encoding error or overflow.
=== utf8.size(string) ===
As for regular size() when called on a string, but returns the number of UTF8 unicode characters instead of bytes. Dies on encoding error.
=== utf8.validate(string, replace=`?`) ===
Checks the string for UTF8 validity. At every byte position where an encoding error is found, it replaces that byte with the specified replacement character (default is `?`). Note that the second argument is a number, not a string.

Expressions

2025-12-16T19:36:12Z

Jsb: Add remark to Table

{{Stub}}
{{-}}
'''Expressions''' (or '''SGExpressions''') are a feature of the SimGear library and provide a nice way of implementing complex math formulas using XML syntax.
They are supported in many systems within the FlightGear code.

{{caution|Expressions do not check if your math creates floating point exceptions (like division by zero conditions, taking the square root of a negative number, etc.). This can cause undefined behavior and may result in NaNs or even Cascading NaNs.}}

== Usage ==
Expressions are supported in
* [[Autopilot Configuration Reference#Expressions|Autopilot configuration files]]
* Particle system configuration files
* Animations (translate, rotate, scale, range, blend)
* The shader technique
* [[Conditions]]

== Sample Expressions ==
This is a sample expression for <code>c = sqrt(a*a + b^2)</code>. Children/arguments are parsed in the order they appear in in the file (or the order in which they are set via property methods).
<syntaxhighlight lang="xml">
<expression>
<sqrt>
<sum>
<product>
<property>/value/a</property>
<property>/value/a</property>
</product>
<pow>
<property>/value/b</property>
<value>2</value>
</pow>
</sum>
</sqrt>
</expression>
</syntaxhighlight>

== Supported elements ==
<syntaxhighlight lang="xml">
<abs> 
<acos>
<asin>
<atan>
<atan2>
<ceil>
<clip> 
<cos>
<cosh>
<difference> 
<div>
<exp>
<floor>
<log>
<log10>
<max>
<min>
<mod>
<pow>
<product> 
<property> 
<rad2deg>
<deg2rad>
<sin>
<sinh>
<sqr>
<sqrt>
<sum>
<table> 
<tan>
<tanh>
<value>
</syntaxhighlight>

=== Table ===
The table expression uses the following syntax, similarly to the <interpolation> element:<syntaxhighlight lang="xml">
<table>

<entry>
<ind>0.0</ind> 
<dep>0.0</dep> 
</entry>
... 
</table>
</syntaxhighlight>The entries must be sorted by the independent (input) variable strictly ascending. If input is outside the range of the table, output will be determined from the first / last table row.

==== Example ====
The table:
{| class="wikitable"
|0.0
|5.0
|-
|0.5
|7.5
|-
|0.9
| -5.0
|-
|1.0
|25.0
|}
translates to the following code:<syntaxhighlight lang="xml">
<table>

<entry>
<ind>0.0</ind>
<dep>5.0</dep>
</entry>
<entry>
<ind>0.5</ind>
<dep>7.5</dep>
</entry>
<entry>
<ind>0.9</ind>
<dep>-5.0</dep>
</entry>
<entry>
<ind>1.0</ind>
<dep>25.0</dep>
</entry>
</table>
</syntaxhighlight>

===Clip===
An expression to limit e.g. rotation:
<syntaxhighlight lang="xml">
<expression>
<clip>
<clipMin>-45</clipMin>
<clipMax>45</clipMax>
<property>orientation/pitch-deg</property>
</clip>
</expression>
</syntaxhighlight>

== Hints and tips ==
=== Rounding ===
While there is no element for rounding, this workaround can be used for that:
<syntaxhighlight lang="xml">
<expression>
<floor>
<sum>
<property>your/property/here</property>
<value>0.5</value>
</sum>
</floor>
</expression>
</syntaxhighlight>

== Related content ==
=== Wiki articles ===
* [[Conditions]]
* [[PropertyList XML files]]

=== Source code ===
* {{simgear file|simgear/structure/SGExpression.hxx}}
* {{simgear file|simgear/structure/SGExpression.cxx}}

[[Category:XML]]

Actions

2025-12-03T21:57:11Z

Jsb:

This page drafts a new feature not implemented at the time of writing (12-2025). It shall aid the planing and development of the feature.

== Introduction ==
FlightGear is a very flexible and modular system. Often there is more than one way to control a certain aspects of the simulator or the simulated aircraft.

One important element are '''[[bindings]]''' which are used in several places to link some ''event'' (key pressed, joystick button, click to 3D cockpit element, ...) to a ''[[Commands|command]]'' (e.g. pause the simulation, retract landing gear, ...).

=== Definition ===
Actions are essentially a named binding, with some extra information + state:

# can be enabled / disabled
# have a unique identifier, e.g. 'toggle COM1 frequency'
# Can be modified, optionally (so aircraft can redefine what a standard action such 'toggle active COM frequency' does in their cockpit)
# can have UI prompts (description / tooltip text)

This feature is targeted for <code>next</code>, but could potentially be back-ported, since it needs to be done backwards compatibly anyway.

https://gitlab.com/groups/flightgear/-/epics/18

=== Use cases ===

* Places, where <binding> is already in use like
** Mapping of input events from hardware devices like keyboard, mouse, joystick, yoke, rudder pedals, throttle quadrant, MCDU, custom made cockpit hardware ...
** 3D cockpit elements ("pick animation")
* Multi-player events

Actions

2025-12-03T21:55:45Z

Jsb: Initial stub

This page drafts a new feature not implemented at the time of writing (12-2025). It shall aid the planing and development of the feature.

== Introduction ==
FlightGear is a very flexible and modular system. Often there is more than one way to control a certain aspects of the simulator or the simulated aircraft.

One important element are '''[[bindings]]''' which are used in several places to link some ''event'' (key pressed, joystick button, click to 3D cockpit element, ...) to a ''[[Commands|command]]'' (e.g. pause the simulation, retract landing gear, ...).

=== Definition ===
Actions are essentially a named binding, with some extra information + state:

# can be enabled / disabled
# have a unique identifier, e.g. 'toggle COM1 frequency'
# Can be modified, optionally (so aircraft can redefine what a standard action such 'toggle active COM frequency' does in their cockpit)
# can have UI prompts (description / tooltip text)

This feature is targeted for <code>next</code>, but could potentially be back-ported, since it needs to be done backwards compatibly anyway.

<ref>Actions are essentially a named binding, with some extra information + state:

can be enabled / disabled

have a unique identifier, e.g. 'toggle COM1 frequency'

Can be modified, optionally (so aircraft can redefine what a standard action such 'toggle active COM frequency' does in their cockpit)

can have UI prompts (description / tooltip text)

This feature is targeted for <code>next</code>, but could potentially be back-ported, since it needs to be done backwards compatibly anyway.

https://gitlab.com/groups/flightgear/-/epics/18</ref>

=== Use cases ===

* Places, where <binding> is already in use like
** Mapping of input events from hardware devices like keyboard, mouse, joystick, yoke, rudder pedals, throttle quadrant, MCDU, custom made cockpit hardware ...
** 3D cockpit elements ("pick animation")
* Multi-player events

Nasal library/props

2025-11-01T19:26:25Z

Jsb: /* alias() */

{{Nasal Navigation|nocat=1}}
This page contains documentation for the '''<code>props</code> namespace''' in [[Nasal]]. This namespace provides APIs for working with property trees (including the main [[Property Tree]]) via {{API Link|simgear|class|SGPropertyNode}}. The <code>props</code> namespace is sourced from {{fgdata file|Nasal/props.nas}} and {{flightgear file|src/Scripting/nasal-props.cxx}}.

== Class ==
=== Node ===
{{Nasal doc
|mode = class
|text = The main class, used widely for manipulating property trees.
}}
==== new() ====
{{Nasal doc
|syntax = props.Node.new([values]);
|text = Constructor function. Returns a new <code>props.Node</code> instance.
|param1 = values
|param1text = An optional hash that will be the initial property structure.
|example1 = var node = props.Node.new();
props.dump(node);
|example2 = var tree = {
a: 1,
b: ["a", "b", "c"],
c: {
d: 1 * 4
}
};

var node = props.Node.new(tree);
props.dump(node);
}}

==== addChild() ====
{{Nasal doc
|syntax = props.Node.addChild(name[, min_idx[, append]]);
|version = 2.10
|commit = {{fgdata commit|a15d58|t=commit}}
|text = Add a new, blank child to the node. Returns the newly-created node.
|param1 = name
|param1text = The name of the node as a string.
|param2 = min_idx
|param2text = This specifies the minimum index to add the new one to. This takes precedence over '''append'''. Defaults to 0.
|param3 = append
|param3text = If there is already one or more children with the same name and this argument is 1 (true), the new child will be added after the child with the highest index. If 0 (false), the new child will be added at the lowest available index with the limit of '''min_idx'''. Defaults to 1 (true).
|example1 = var node = props.Node.new();
node.addChild("a");
props.dump(node);
|example2 = var node = props.Node.new();
node.addChild("a", 1);
props.dump(node); # a[1]
|example3 = var node = props.Node.new();
node.addChild("a", 1);
props.dump(node); # a[1]
node.addChild("a", 0, 0);
props.dump(node); # a[1] and a[0]
|example4 = var node = props.Node.new();
node.addChild("a", 1);
props.dump(node); # a[1]
node.addChild("a", 0, 1);
props.dump(node); # a[1] and a[2]
}}

==== addChildren() ====
{{Nasal doc
|syntax = props.Node.addChildren(name, count[, min_idx[, append]]);
|version = 2.10
|commit = {{fgdata commit|7f1117|t=commit}}
|text = Adds multiple children with the same name to this node. Returns <code>'''nil</code>.
|param1 = name
|param1text = The name of the nodes as a string.
|param2 = count
|param2text = Number of new children to add.
|param3 = min_idx
|param3text = Performs the same function as in <code>[[#addChild.28.29|Node.addChild()]]</code>.
|param4 = append
|param4text = Performs the same function as in <code>[[#addChild.28.29|Node.addChild()]]</code>.
|example1 = var node = props.Node.new();
node.addChildren("a", 2);
props.dump(node); # a[0] and a[1]
|example2 = var node = props.Node.new();
node.addChildren("a", 2, 1);
props.dump(node); # a[1] and a[2]
|example3 = var node = props.Node.new();
node.addChild("a", 2);
props.dump(node); # a[2]
node.addChildren("a", 2, 0, 0);
props.dump(node); # a[2], a[0], and a[1]
}}

==== adjustValue() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.adjustValue(delta);
|text = Adds delta (numeric) to current value respecting the node type.
|param1 = delta
|param1text = Numeric value (can be negative) to add to current node value.
}}

==== alias() ====
{{Nasal doc
|syntax = props.Node.alias(node, chainListener=0);
|text = Aliases this node to another one. Returns 1 on success and 0 on failure.
|param1 = node
|param1text = The node to alias to. Can be one of:
* A path to a property in the [[Property Tree]] as a string.
* A <code>prop</code> ghost.
* A <code>props.Node</code> object.
|example1 = var node = props.Node.new();
node.alias("/position/altitude-ft");
props.dump(node); # equals the current altitude
|example2 = var node1 = props.Node.new();
node1.setDoubleValue(2.34);
var node2 = props.Node.new();
node2.alias(node1);
props.dump(node2); # equals 2.34
|param2=chainListener|param2text=Specify if listeners should work on aliased properties or not. Current default is false forbackwards compatability.}}

==== clearValue() ====
{{Nasal doc
|syntax = props.Node.clearValue();
|text = Clears the value and type of the node.
|example1 = var node = props.Node.new();
node.setDoubleValue(2.34);
props.dump(node); # prints "{DOUBLE} = 2.35"
node.clearValue();
props.dump(node); # prints "{NONE} = nil"
}}

==== decrement() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.decrement(n = 1);
|text = Decrements integer property by n (default: n = 1)
|param1 = n
|param1text = Value to subtract, will be converted to int, defaults to 1
}}

==== equals() ====
{{Nasal doc
|syntax = props.Node.equals(node);
|version = 2.12
|commit = {{fgdata commit|d80722|t=commit}}
|text = Checks whether the node refers to the same one as another. Returns 1 (true) if it is, and 0 (false) if otherwise.
|param1 = node
|param1text = Node to check against. May be either a <code>prop</code> ghost or a <code>props.Node</code> object.
|example1 = var n = props.Node.new();
var a = n;
print(a.equals(n)); # prints "1" (true)
}}

==== getAliasTarget() ====
{{Nasal doc
|syntax = props.Node.getAliasTarget();
|text = Returns the alias target of a node as another <code>props.Node</code> instance.
|example1 = setprop("/test", 2.35);
var node = props.Node.new();
node.alias("/test");
var tgt = node.getAliasTarget();
print(tgt.getPath()); # prints "/test"
}}

==== getAttribute() ====
{{Nasal doc
|syntax = props.Node.getAttribute([rel_path, ]name);
props.Node.getAttribute();
|text = Returns an attribute. If no arguments are given, the function will return an integer specifying the attributes set for the node (see {{simgear file|simgear/props/props.hxx|l=767}} for a list). A list of attributes are below
{{{!}} class="wikitable"
! String !! Return value
{{!-}}
{{!}} last {{!!}} The highest used attribute code (should be 128). See for {{simgear file|simgear/props/props.hxx|l=767}} the codes.
{{!-}}
{{!}} children {{!!}} Number of child nodes.
{{!-}}
{{!}} listeners {{!!}} Number of listeners connected to this node.
{{!-}}
{{!}} references {{!!}} Number of times the node has previously been referenced.
{{!-}}
{{!}} tied {{!!}} Whether the node is tied.
{{!-}}
{{!}} alias {{!!}} Whether the node is aliased.
{{!-}}
{{!}} readable {{!!}} Whether the node can be read.
{{!-}}
{{!}} writable {{!!}} Whether the node can be written to.
{{!-}}
{{!}} archive {{!!}} Whether the node will be saved when the "save" [[fgcommands|fgcommand]] is triggered.
{{!-}}
{{!}} trace-read {{!!}} Whether the reading of the node will be logged when <code>--log-level=info</code>.
{{!-}}
{{!}} trace-write {{!!}} Whether the writing to the node will be logged when <code>--log-level=info</code>.
{{!-}}
{{!}} userarchive {{!!}} Whether the node will be saved to the [[FlightGear configuration via XML#autosave.xml|autosave file]] (only works for actual properties).
{{!-}}
{{!}} preserve {{!!}} Whether the value of node will be preserved during resets (only works for actual properties).
{{!}}}
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = name
|param2text = Attribute as a string. See the above table for a full list.
|example1 = var node = props.Node.new();
var child = node.addChild("a");
print(node.getAttribute("children")); # prints "1"
|example2text = Example using relative path
|example2 = var node = props.Node.new();
var child = node.addChild("a");
print(node.getAttribute("a", "readable")); # prints "1" (node can be read from)
|example3 = var node = props.Node.new();
var node2 = props.Node.new();
node2.alias(node);
print(node2.getAttribute("alias")); # prints "1" (true)
|example4 = print(props.globals.getNode("/sim/signals/fdm-initialized").getAttribute("listeners")); # prints the number of listeners
|example5 = print(props.globals.getNode("/sim/time/elapsed-sec").getAttribute("tied")); # prints "1" (true), meaning it is tied
|example6 = var node = props.Node.new();
print(node.getAttribute("writable")); # prints "1" (true), meaning the node can be written to
|example7text = Example using no arguments
|example7 = var node = props.Node.new();
print(node.getAttribute()); # prints "3" (true), meaning the node can be read from (1) and written to (2)
}}

==== getBoolValue() ====
{{Nasal doc
|syntax = props.Node.getBoolValue();
|text = Returns the value of a node converted to a boolean. If the node is a number type, 0 will return false, while 1 will return true. If the node is a string or unspecified type and the value is <code>"false"</code>, false will be returned. Otherwise, true will be returned. Remember that boolean values are represented in Nasal as 1 (true) and 0 (false).
|example1 = var node = props.Node.new();
node.setBoolValue(1);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setBoolValue(0);
print(node.getBoolValue() ? "true" : "false"); # prints "false"
|example2 = var node = props.Node.new();
node.setDoubleValue(1.23);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setDoubleValue(-1.23);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setDoubleValue(0.0);
print(node.getBoolValue() ? "true" : "false"); # prints "false"
|example3 = var node = props.Node.new();
node.setIntValue(2);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setIntValue(-2);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setIntValue(0);
print(node.getBoolValue() ? "true" : "false"); # prints "false"
|example4 = var node = props.Node.new();
node.setValue("Hello, World!");
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setValue("false");
print(node.getBoolValue() ? "true" : "false"); # prints "false"
}}

==== getChild() ====
{{Nasal doc
|syntax = props.Node.getChild(rel_path[, idx[, create]]);
|text = Returns a child of a node as another <code>props.Node</code> instance.
|param1 = rel_path
|param1text = Relative path to the child node as a string.
|param2 = idx
|param2text = Optional index for the child node as an integer.
|param3 = create
|param3text = If set to 1 (true), a new child will be created if it does not exist. If set to 0 (false), the function will not create a new child and the function will return <code>'''nil'''</code> if no child exists. Defaults to 0.
|example1 = var node = props.Node.new();
node.addChild("a");
var c = node.getChild("a");
|example2 = var node = props.Node.new();
node.addChildren("a", 3);
node.getNode("a[1]").setDoubleValue(2.35);
var c = node.getChild("a", 1);
print(c.getValue()); # prints "2.35"
|example3 = var node = props.Node.new();
var c = node.getChild("a", 1, 1);
props.dump(node); # new child a[1] will have appeared
}}

==== getChildren() ====
{{Nasal doc
|syntax = props.Node.getChildren([name]);
|text = Returns a vector of child nodes, optionally those with a certain name, as <code>props.Node</code> instances.
|param1 = name
|param1text = Optional name of the child nodes as a string. If not given, all children will be returned.
|example1 = var node = props.Node.new();
node.addChildren("a", 3);
node.addChildren("b", 3);
debug.dump(node.getChildren()); # all child nodes in the vector
|example2 = var node = props.Node.new();
node.addChildren("a", 3);
node.addChildren("b", 3);
debug.dump(node.getChildren("b")); # only children with the name "b" in the vector
}}

==== getIndex() ====
{{Nasal doc
|syntax = props.Node.getIndex();
|text = Returns the index of a node as an integer.
|example1 = var node = props.Node.new();
node.addChildren("a", 3);
print(node.getChild("a", 1).getIndex()); # prints "1"
|example2 = var node = props.Node.new();
node.addChild("b");
print(node.getChild("b").getIndex()); # prints "0"
}}

==== getName() ====
{{Nasal doc
|syntax = props.Node.getName();
|text = Returns the name of the node as a string.
|example1 = var node = props.Node.new();
var c = node.addChild("a");
debug.dump(c.getName()); # prints "a"
|example2 = var node = props.Node.new();
node.addChildren("a", 3);
debug.dump(node.getChild("a", 2).getName()); # prints "a"
}}

==== getNode() ====
{{Nasal doc
|syntax = props.Node.getNode(rel_path[, create]);
|text = Returns a subnode as another <code>props.Node</code> instance.
|param1 = rel_path
|param1text = Relative path to the subnode as a string.
|param2 = create
|param2text = If 1 (true), the node will be created if it does not exist. If 0 (false) and the node does not exist, the function will return <code>'''nil'''</code>. Default to 0 (false).
|example1 = var tree = {
"a": 1,
"b": "Hi",
"c": {
"d": "Hello, World!"
}
};
var node = props.Node.new(tree);
print(node.getNode("c/d").getValue()); # prints "Hello, World!"
|example2 = var tree = {
"a": 1,
"b": "Hi",
"c": {}
};
var node = props.Node.new(tree);
node.getNode("c/d", 1).setDoubleValue(2.35);
props.dump(node); # c/d now exists
|example3 = var ac = props.globals.getNode("sim/aircraft");
print("Current aircraft is: ", ac.getValue());
}}

==== getParent() ====
{{Nasal doc
|syntax = props.Node.getParent();
|text = Returns the parent of a node, or <code>'''nil'''</code> if there is no parent.
|example1 = var tree = {
"a": 1,
"b": "Hi",
"c": {
"d": "Hello, World!"
}
};
var node = props.Node.new(tree);
props.dump(node.getNode("c/d").getParent()); # dumps "c"
|example2 = var node = props.Node.new();
debug.dump(node.getParent()); # prints nil
}}

==== getPath() ====
{{Nasal doc
|syntax = props.Node.getPath();
|text = Returns the path of the node as a string.
|example1 = var tree = {
"a": 1,
"b": "Hi",
"c": {
"d": "Hello, World!"
}
};
var node = props.Node.new(tree);
print(node.getNode("c/d").getPath()); # prints "/c/d"
}}

==== getType() ====
{{Nasal doc
|syntax = props.Node.getType();
|text = Returns node's type as a string. It should be one of "NONE", "ALIAS", "BOOL", "INT", "LONG" (long integer), "FLOAT", "DOUBLE", "STRING", "VEC3D", "VEC4D", "UNSPECIFIED".
|example1 = var node = props.Node.new();
print(node.getType()); # prints "NONE"
|example2 = var node = props.Node.new();
node.setIntValue(12);
print(node.getType()); # prints "INT"
|example3 = var node = props.Node.new();
node.setValue([0.4, 0.2, 1]);
debug.dump(node.getValue()); # prints "[0.4, 0.2, 1]"
print(node.getType()); # prints "VEC3D"
}}

==== getValue() ====
{{Nasal doc
|syntax = props.Node.getValue([rel_path]);
|text = {{hatnote|See also {{func link|getBoolValue()|page=this}}.}}

Returns the value of the node.
|param1 = rel_path
|param1text = Optional relative path to a subnode as a string, which may contain '/' characters. If the subnode does not exist, we return nil.
|example1 = var node = props.Node.new();
node.setDoubleValue(2.35);
print(node.getValue()); # prints "2.35"
|example2 = var node = props.Node.new();
node.setValue("Hi");
print(node.getValue()); # prints "Hi"
|example3 = var node = props.Node.new();
node.addChild("a").setValue("Hi");
print(node.getValue("a")); # prints "Hi"
|example4 = var node = props.Node.new();
node.setValue([0, 0.5, 1]);
debug.dump(node.getValue()); # prints "[0, 0.5, 1]"
}}

==== getValues() ====
{{Nasal doc
|syntax = props.Node.getValues();
|text = Returns the node tree as a hash, with all the various subnodes, etc. If the node has no children, the result is equivalent to {{func link|getValue()|page=this}}. Subnodes that are indexed will be combined into one key and their values placed in a vector (see example 2).
|example1 = var tree = {
"string": "Hi",
"number": 1.2,
"subnode": {
"idx-node": [1, 2, 3]
}
};
var node = props.Node.new(tree);
node.addChild("bool").setBoolValue(1);
props.dump(node); # dump to node tree
debug.dump(node.getValues()); # dump the node converted to hash
|example2 = var tree = {
"a": [1, 2, 3]
};
var node = props.Node.new(tree);
props.dump(node); # a[0] = 1, a[1] = 2, a[2] = 3
debug.dump(node.getValues()); # a: [1, 2, 3]
}}

==== increment() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.increment(n = 1);
|text = Increments integer property by n (default: n = 1)
|param1 = n
|param1text = Value to add, will be converted to int, defaults to 1
}}

==== initNode() ====
{{Nasal doc
|syntax = props.Node.initNode([path[, value[, type[, force]]]]);
|text = Initializes a node if it doesn't exist and returns that node as a <code>props.Node</code> object.
|param1 = path
|param1text = Optional path to a subnode as a string. If not given, the node itself will be initialized.
|param2 = value
|param2text = Optional default value to initialize the node with.
|param3 = type
|param3text = Optional string that will set the type of the node. Must be one of <code>"DOUBLE"</code>, <code>"INT"</code>, <code>"BOOL"</code>, or <code>"STRING"</code>.
|param4 = force
|param4text = If set to 1 (true), the node's type will be forced to change.
|example1 = var node = props.Node.new();
var a = node.initNode("a");
props.dump(a);
|example2 = var node = props.Node.new();
var a = node.initNode("a", "Hi");
props.dump(a);
|example3 = var node = props.Node.new();
var a = node.initNode("a", 1.25, "INT");
props.dump(a); # a = 1
|example4 = var node = props.Node.new();
node.addChild("a").setBoolValue(0);
props.dump(node.getChild("a")); # a = 0 (type: bool)
var a = node.initNode("a", 1.25, "INT", 1);
props.dump(a); # a = 0 (type: int)
}}

==== isInt() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.isInt();
|text = Returns true (1) if node '''type''' is "INT" or "LONG" (long integer) otherwise false (0).
}}

==== isNumeric() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.isNumeric();
|text = Returns true (1) if node '''type''' is "INT", "LONG", "FLOAT" or "DOUBLE" otherwise false (0).
}}

==== remove() ====
{{Nasal doc
|syntax = props.Node.remove();
|text = Removes the node and returns the removed node.
|example1 = var node = props.Node.new();
node.addChild("a");
props.dump(node);
node.getChild("a").remove();
props.dump(node); # child "a" does not exist anymore
}}

==== removeAllChildren() ====
{{Caution|Be careful when using this API in conjunction with the Canvas system and element specific properties, for details please see [[Howto:Canvas Path Benchmarking]]}}
{{Nasal doc
|syntax = props.Node.removeAllChildren();
|version = 3.2
|commit = {{fgdata commit|4766ed|t=commit}}
|text = Removes all child nodes and returns the node.
|example1 = var tree = {
"a": 1,
"b": 2,
"c": 3
};
var node = props.Node.new(tree);
props.dump(node);
node.removeAllChildren();
props.dump(node); # all children have been removed
}}

==== removeChild() ====
{{Nasal doc
|syntax = props.Node.removeChild(rel_path, idx);
|text = Removes a given child node child nodes and returns the node.
|param1 = rel_path
|param1text = Relative path to a subnode as a string.
|param2 = idx
|param2text = Index of the subnode to remove as an integer.
|example1 = var node = props.Node.new();
node.addChild("a");
props.dump(node);
node.removeChild("a", 0);
props.dump(node); # child "a" has been removed
|example2 = var node = props.Node.new();
node.addChildren("a", 2);
props.dump(node);
node.removeChild("a", 0);
props.dump(node); # just a[1] remains
}}

==== removeChildren() ====
{{Nasal doc
|syntax = props.Node.removeChildren([name]);
|text = Removes all children with a specified name. If no arguments are given, all children will be removed (see also {{func link|removeAllChildren()|page=this}}).
|param1 = name
|param1text = Optional name of children to remove as a string.
|example1 = var node = props.Node.new();
node.addChildren("a", 2);
node.addChildren("b", 2);
props.dump(node);
node.removeChildren("a");
props.dump(node); # just children named "b" remain
|example2 = var node = props.Node.new();
node.addChildren("a", 2);
node.addChildren("b", 2);
props.dump(node);
node.removeChildren();
props.dump(node); # all children removed
}}

==== setAttribute() ====
{{Nasal doc
|syntax = props.Node.setAttribute([rel_path, ]attr, value);
props.Node.setAttribute(attrs);
|text = Sets an attribute or multiple attributes. A list of attributes and their codes are below. For a brand new node, the default attributes are ''readable'' and ''writable''. Returns an integer specifying the old attributes.
{{{!}} class="wikitable"
! String !! Description
{{!-}}
{{!}} readable {{!!}} Whether the node can be read.
{{!-}}
{{!}} writable {{!!}} Whether the node can be written to.
{{!-}}
{{!}} archive {{!!}} Whether the node will be saved when the "save" [[fgcommands|fgcommand]] is triggered.
{{!-}}
{{!}} trace-read {{!!}} Whether the reading of the node will be logged when <code>--log-level=info</code>.
{{!-}}
{{!}} trace-write {{!!}} Whether the writing to the node will be logged when <code>--log-level=info</code>.
{{!-}}
{{!}} userarchive {{!!}} Whether the node will be saved to the [[FlightGear configuration via XML#autosave.xml|autosave file]] (only works for actual properties).
{{!-}}
{{!}} preserve {{!!}} Whether the value of node will be preserved during resets (only works for actual properties).
{{!}}}
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = attr
|param2text = Name of attribute to set as a string. See above.
|param3 = value
|param3text = Boolean value to set the property to.
|param4 = attrs
|param4text = When the function is used in its second form, this argument is used. This argument should be an integer specifying which arguments are set to true. See {{simgear file|simgear/props/props.hxx|l=767}} for the full list of codes. Simply add codes of the desired attributes together.
|example1 = var node = props.Node.new();
node.setAttribute("trace-write", 1);
node.setIntValue(12); # will be traced
|example2 = var node = props.Node.new();
node.setAttribute("readable", 0);
var val = node.getValue();
debug.dump(val); # prints "nil"
|example3 = var node = props.Node.new();
node.addChild("a");
node.setAttribute("a", "trace-write", 1);
node.getChild("a").setIntValue(12); # will be traced
|example4 = var node = props.Node.new();
node.setAttribute(35); # read + write + trace-write
node.setIntValue(12); # will be traced
}}

==== setBoolValue() ====
{{Nasal doc
|syntax = props.Node.setBoolValue([rel_path, ]value);
|text = {{note|For setting the values of [[Property Tree]] nodes, it is recommended to use {{func link|setprop()}} if possible, due to performance differences.}}

Sets a node to a boolean value. If the node has no type, it will be set to a bool type. If the node is already a number type, it will be set to either 1 or 0. If it is a string, it will be set to either "true" or "false". Returns 1 (true) if the operation was successful.
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = value
|param2text = Value to set the node to, will be interpreted into a boolean. If it is <code>'''nil'''</code>, it will be false. If it is a string, it will be false. If it is a number, 0 will be false, while other numbers will be true. All other cases will be interpreted as 0.
|example1 = var node = props.Node.new();
node.setBoolValue(nil);
props.dump(node); # node = 0 (false)
|example2 = var node = props.Node.new();
node.setBoolValue("Hi");
props.dump(node); # node = 1 (true)
|example3 = var node = props.Node.new();
node.setBoolValue(0);
props.dump(node); # node = 0 (false)
node.setBoolValue(1.25);
props.dump(node); # node = 1 (true)
|example4 = var node = props.Node.new();
node.setValue("String");
props.dump(node); # node = "String" (type: string)
node.setBoolValue(1);
props.dump(node); # node = "true"
|example5 = var node = props.Node.new();
node.setDoubleValue(12.32);
props.dump(node); # node = 12.32 (type: double)
node.setBoolValue(1);
props.dump(node); # node = 1
|example6 = var node = props.Node.new();
node.addChild("a");
node.setBoolValue("a", 1);
props.dump(node); # /a = 1
}}

==== setDoubleValue() ====
{{Nasal doc
|syntax = props.Node.setDoubleValue([rel_path, ]value);
|text = {{note|For setting the values of [[Property Tree]] nodes, it is recommended to use {{func link|setprop()}} if possible, due to performance differences.}}

Sets a node to a double value. If the node has no type, it will be set to a double type. If the node is a bool, values different from zero will be interpreted as true. If the node is a string, the value will be converted to a string. If the node is an integer type, it will be truncated to the closest integer to zero. Returns 1 (true) if the operation was successful.
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = value
|param2text = Value to set the node to, will be interpreted into a double number. It must be a valid number or a string that can be converted to a number.
|example1 = var node = props.Node.new();
node.setDoubleValue(1.1);
props.dump(node); # node = 1.1 (type: double)
|example2 = var node = props.Node.new();
node.setDoubleValue("1.1");
props.dump(node); # node = 1.1 (type: double)
|example3 = var node = props.Node.new();
node.setBoolValue(1);
node.setDoubleValue("1.1");
props.dump(node); # node = 1 (type: bool)
node.setDoubleValue(0.0);
props.dump(node); # node = 0 (type: bool)
|example4 = var node = props.Node.new();
node.setIntValue(1);
node.setDoubleValue(1.1);
props.dump(node); # node = 1 (type: int)
node.setDoubleValue("-1.1");
props.dump(node); # node = -1 (type: int)
|example5 = var node = props.Node.new();
node.addChild("a");
node.setDoubleValue("a", 12.2);
props.dump(node); # /a = 12.2
}}

==== setIntValue() ====
{{Nasal doc
|syntax = props.Node.setIntValue([rel_path, ]value);
|text = {{note|For setting the values of [[Property Tree]] nodes, it is recommended to use {{func link|setprop()}} if possible, due to performance differences.}}

Sets a node to an integer value. If the node has no type, it will be set to a integer type. If the node is a bool, values different from zero will be interpreted as true. If the node is a string, the value will be converted to a string. Returns 1 (true) if the operation was successful.
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = value
|param2text = Value to set the node to, will be interpreted into a integer. It must be a valid number or a string that can be converted to a number. If the number is a double, it will be truncated to the closest integer to zero.
|example1 = var node = props.Node.new();
node.setIntValue(12);
props.dump(node); # node = 12
node.setIntValue("6");
props.dump(node); # node = 6
|example2 = var node = props.Node.new();
node.setIntValue(12.2);
props.dump(node); # node = 12
node.setIntValue(-12.2);
props.dump(node); # node = 12
|example3 = var node = props.Node.new();
node.setBoolValue(1);
node.setIntValue(12.5);
props.dump(node); # node = 1 (type: bool)
node.setIntValue(0);
props.dump(node); # node = 0 (type: bool)
|example4 = var node = props.Node.new();
node.setValue("Hi");
node.setIntValue(12);
props.dump(node); # node = "12" (type: string)
|example5 = var node = props.Node.new();
node.addChild("a");
node.setIntValue("a", 12);
props.dump(node); # /a = 12
}}

==== setValue() ====
{{Nasal doc
|syntax = props.Node.setValue([rel_path, ]value);
|text = {{hatnote|See also {{func link|setBoolValue()|page=this}}, {{func link|setDoubleValue()|page=this}}, and {{func link|setIntValue()|page=this}}.}}

{{note|For setting the values of [[Property Tree]] nodes, it is recommended to use {{func link|setprop()}} if possible, due to performance differences.}}

Sets a node to a given value. See table below for conversions and effects. Note that vec3d and vec4d types are not fully integrated into SGPropertyNode. Returns 1 (true) if the operation was successful.

{{{!}} class="wikitable"
{{!}} colspan="2" style="text-align:right" {{!}} '''value''' type →
! rowspan="2" {{!}} Number
! rowspan="2" {{!}} String
! rowspan="2" {{!}} Vector
{{!-}}
{{!}} style="text-align:left" {{!}} Current node<br>type ↓
{{!}} style="text-align:right" {{!}} Result ↘
{{!-}}
! colspan="2" {{!}} None/unspecified
{{!}}
* Type set to <code>double</code>
* Node set to '''value'''.
{{!}}
* Type set to <code>string</code>
* Node set to '''value'''.
{{!}}
* Type set to <code>vec*d</code>
* Node set to '''value'''.
{{!-}}
! colspan="2" {{!}} Bool
{{!}}
* If '''value''' != 0, node set to true.
* If '''value''' == 0, node set to false.
{{!}}
* If '''value''' == "true", node set to true.
* If '''value''' can be converted to an integer,<br>and != 0, node set to true.
{{!}} Node set to true.
{{!-}}
! colspan="2" {{!}} Integer
{{!}} Node set to truncated '''value'''
{{!}} Node set to '''value ''' converted and truncated to an integer.
{{!}} Node set to 1.
{{!-}}
! colspan="2" {{!}} Double
{{!}} Node set to '''value'''.
{{!}} Node set to '''value''' converted to number.
{{!}} Throws an error (vector is not a number).
{{!-}}
! colspan="2" {{!}} String
{{!}} Node set to '''value''' converted to string. {{!!}} Node set to '''value'''. {{!!}} Node not set.
{{!}}}
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = value
|param2text = Value to set the node to. Must be a string, a valid number, or a vector consisting of 3 or 4 numbers. See table above for conversions and effects.
|example1 = var node = props.Node.new();
node.setValue("Hi");
props.dump(node); # node = "Hi"
|example2 = var node = props.Node.new();
node.addChild("a");
node.setValue("a", "Hi");
props.dump(node); # \a = "Hi"
|example3 = var node = props.Node.new();
node.setValue([0.4, 0.2, 1]);
debug.dump(node.getValue()); # prints "[0.4, 0.2, 1]"
print(node.getType()); # prints "VEC3D"
}}

==== setValues() ====
{{Nasal doc
|syntax = props.Node.setValues(val);
|text = {{hatnote|See also {{func link|getValues()|page=this}}.}}

Sets the nodes property tree from a Nasal hash. Scalars will become nodes in the tree and hashes will become named subnodes. Vectors will be converted into indexed nodes, with the values in the vector becoming their values (see examples below).
|param1 = val
|param1text = A hash that will become the property tree.
|example1 = var val = {
"a": 100 # "a" will become the subnode's name, and 100 its value
};
var node = props.Node.new();
node.setValues(val);
props.dump(node); # dump tree
|example2 = var val = {
"a": 1,
"b": "Hi",
"c": {
"d": [1, 2, 3]
}
};
var node = props.Node.new();
node.setValues(val);
props.dump(node); # dump tree
}}

==== unalias() ====
{{Nasal doc
|syntax = props.Node.unalias();
|text = Un-aliases the node and returns it to a blank state. Returns 1 on success and 0 on failure (e.g., when used on a tied property).
|example2 = var node1 = props.Node.new();
node1.setDoubleValue(2.35);
var node2 = props.Node.new();
node2.alias(node1);

props.dump(node2); # equals 2.35
node2.unalias();
props.dump(node2); # no value or type
}}

==== toggleBoolValue() (since FG 2020.1) ====
{{Nasal doc
|syntax = toggleBoolValue();
|text = Toggle a boolean property. You have to make sure the property is of type bool!
|example1 = var b = props.Node.new().initNode("/_test/bool", 1, "BOOL");
print("bool ", b.getValue());
b.toggleBoolValue();
print("after toggleBoolValue ", b.getValue());

}}

== Functions ==
=== compileCondition() ===
{{see also|Conditions}}

{{Nasal doc
|syntax = props.compileCondition(node);
|version = 3.2
|commit = {{fgdata commit|43f8ce|t=commit}}
|text = Compiles a [[conditions|condition]] property branch and returns a <code>Condition</code> ghost object or <code>'''nil'''</code> on error. This ghost will contain a <code>test()</code> function that will return the result of the condition as either 1 (true) or 0 (false).
|param1 = node
|param1text = Either a props.Node containing the condition, or a string specifying a place in the [[Property Tree]] where there is a condition branch.
|example1 = var tree = {
"equals": {
"property": '/test',
"value": 12
}
};
var node = props.Node.new(tree);
setprop("/test", 12);

var cond = props.compileCondition(node);
print(cond.test()); # prints "1" (true)
setprop("/test", 15);
print(cond.test()); # prints "0" (false)
|example2 = var tree = {
"equals": {
"property": '/test',
"value": 12
}
};
props.globals.getNode("test2/condition", 1).setValues(tree); # place it in the Property Tree
setprop("/test", 12);

var cond = props.compileCondition(node);
print(cond.test()); # prints "1" (true)
setprop("/test", 15);
print(cond.test()); # prints "0" (false)
}}

=== condition() ===
{{Nasal doc
|syntax = props.condition(node);
|text = Evaluates a [[conditions|condition]] property branch and returns the result as a boolean.
|param1 = node
|param1text = Either a props.Node containing the condition, or a string specifying a place in the [[Property Tree]] where there is a condition branch.
|example1 = var tree = {
"equals": {
"property": '/test',
"value": 12
}
};
var node = props.Node.new(tree);
setprop("/test", 12);

print(props.condition(node)); # prints "1" (true)
setprop("/test", 15);
print(props.condition(node)); # prints "0" (false)
|example2 = var tree = {
"equals": {
"property": '/test',
"value": 12
}
};
props.globals.getNode("test2/condition", 1).setValues(tree); # place it in the Property Tree
setprop("/test", 12);

print(props.condition(node)); # prints "1" (true)
setprop("/test", 15);
print(props.condition(node)); # prints "0" (false)
}}

=== copy() ===
{{Nasal doc
|syntax = props.copy(src, dest[, attr]);
|text = Copies the property tree of the source into the destination node. Note that aliased properties will not be copied.
|param1 = src
|param1text = Source <code>props.Node object</code> to copy from.
|param2 = dest
|param2text = Destination <code>props.Node object</code> to copy to.
|param3 = attr
|param3text = If set to 1 (true), attributes will also be copied. Defaults to 0 (false).
|example1 = var tree = {
"a": 1.5,
"b": "Hi",
"c": {
"d": [1, 2, 3]
}
};
var src = props.Node.new(tree);
var dest = props.Node.new();
props.copy(src, dest);
props.dump(dest);
|example2 = var src = props.Node.new();
var a = src.addChild("a");
a.setAttribute("trace-write", 1);
a.setIntValue(12);
var dest = props.Node.new();
props.copy(src, dest, 1);
print(dest.getNode("a").getAttribute("trace-write")); # prints "1" (true)
}}

=== dump() ===
{{Nasal doc
|syntax = props.dump(node);
|text = Recursively dump the state of a node into the console, showing value and type of each node. Note that as of 10/2016, the value of vec*d type nodes cannot be dumped.
|param1 = node
|param1text = Node to dump.
|example1 = var node = var tree = {
"a": 12,
"b": "Hi",
"c": {
"d": [1, 2, 3]
}
};
var node = props.Node.new(tree);
props.dump(node); # dump into console
|example2 = # Dump the entire Property Tree
# Warning! This is an intensive operation!
props.dump(props.globals);
}}

=== getNode() ===
{{Nasal doc
|syntax = props.getNode();
|version = 3.2
|commit = {{fgdata commit|807062|t=commit}}
|text = Shortcut for <syntaxhighlight lang="nasal" inline>props.globals.getNode()</syntaxhighlight>. See {{func link|getNode()||Node|page=this}} for full documentation.
|example1 = print("Current aircraft is: ", props.getNode("/sim/aircraft").getValue());
}}

=== nodeList() ===
{{Nasal doc
|syntax = props.nodeList(arg[, arg[, ...]]);
|text = Converts its arguments into a vector of node objects if possible and returns that vector.
|param1 = arg
|param1text = Object to operate on. Must be a node object, string, vector, hash, function, or <code>prop</code> ghost. Vectors and hashes must contain any of the other acceptable types, functions must return any of the other types, strings will be assumed to be paths to global properties, and ghosts will be converted into node objects. There may be any number of arguments.
|example1 = var node = props.Node.new();
var f = func(){
var n = props.Node.new();
return n._g;
}
var list = props.nodeList(node,
"/sim/aircraft",
["/sim/fg-root"],
{ "path": "/sim/fg-home" },
f
);
debug.dump(list); # dump list
|example2 = var root = "/sim/version/";
var info = [
root ~ "build-id",
root ~ "build-number",
root ~ "flightgear",
root ~ "hla-support",
root ~ "openscenegraph",
root ~ "revision",
root ~ "simgear"
];
info = props.nodeList(info); # turn into list of nodes
foreach(var n; info){
print(n.getValue()); # dump info
}
}}

=== runBinding() ===
{{Nasal doc
|syntax = props.runBinding(node[, module]);
|text = Runs a [[Bindings|binding]] element in a node object. Returns 1 (true) on success and 0 (false) on failure.
|param1 = node
|param1text = A {{tag|binding}} element as a node object.
|param2 = module
|param2text = Optional string specifying a module to run Nasal scripts in if the command is <code>nasal</code>. This argument will not override any {{tag|module}} element in the '''node'''
|example1 = var tree = {
"command": "dialog-show",
"dialog-name": "map" # open map
};
var binding = props.Node.new(tree);
props.runBinding(binding);
|example2 = var tree = {
"command": "nasal",
"script": 'print(pi)' # prints value of math.pi
};
var binding = props.Node.new(tree);
props.runBinding(binding, "math");
|example3 = var tree = {
"command": "nasal",
"script": 'print(pi)', # prints value of math.pi
"module": "math" # this is used
};
var binding = props.Node.new(tree);
props.runBinding(binding, "debug");
}}

=== setAll() ===
{{Nasal doc
|syntax = props.setAll(base, child, value);
|text = Sets indexed subnodes in the Property Tree with the same name to the same value.
|param1 = base
|param1text = Base path to the nodes.
|param2 = child
|param2text = Path to child nodes.
|param3 = value
|param3text = Value to set the subnodes to.
|example1 = # apply 50% throttle to all engines
props.setAll("/controls/engines/engine", "throttle", 0.5);
|example2 = var nodes = props.globals.addChildren("/test", 3);
foreach(var node; nodes){
node.addChild("a");
}
props.setAll("/test", "a", "Hi"); # set all children (test[*]/a) to "Hi"
}}

=== wrap() ===
{{Nasal doc
|syntax = props.wrap(node);
|text = Turns <code>prop</code> ghosts, either in a vector or single, into <code>props.Node</code> objects.
|param1 = node
|param1text = <code>prop</code> ghost or vector of such ghosts.
|example1 = var ghost = canvas._newCanvasGhost();
var node = props.wrap(ghost._node_ghost);
props.dump(node);
|example2 = var vector = [canvas._newCanvasGhost()._node_ghost, props.Node.new()._g];
var nodes = props.wrap(vector);
foreach(var node; nodes){
props.dump(node);
print("----");
}
}}

=== wrapNode() ===
{{Nasal doc
|syntax = props.wrapNode(node);
|text = Turns a <code>prop</code> ghost into a <code>props.Node</code> object.
|param1 = node
|param1text = <code>prop</code> ghost to convert.
|example1 = var ghost = canvas._newCanvasGhost();
var node = props.wrapNode(ghost._node_ghost);
props.dump(node);
}}

== Variable ==
=== globals ===
{{Nasal doc
|syntax = props.globals;
|text = Exposes the [[Property Tree]] as a <code>props.Node</code> object.

|example1 = print("Current aircraft: ", props.globals.getNode("/sim/aircraft").getValue());
|example2text = Alternative using {{func link|getprop()}}.
|example2 = print("Current aircraft: ", getprop("/sim/aircraft"));
}}

{{Nasal namespaces}}

Honeycomb Input Devices

2025-09-12T19:14:28Z

Jsb:

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

Honeycomb Input Devices

2025-09-09T20:38:46Z

Jsb: Add sections for new devices

(Work in progress)

This page shall provide information about the input devices available from 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 switch, double 2-way rocker switch (e.g. trim switch) and two buttons (e.g. PTT and AP disconnect). Right side has two buttons and double 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.

=== 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]]

Input helpers

2025-09-06T20:14:45Z

Jsb: Fix typos

== Overview ==
This page is about Nasal script code for input devices like joysticks, yokes, throttle quadrants and pedals. While small scripts can be easily added directly into joystick <binding>, larger code blocks should be organized a bit differently.

As always: "do not repeat yourself" = to make everyones live easier, code should not be copy&pasted but put into a "central" place as functions or classes and be called whenever, wherever needed. This way maintenance has to be done only in one place.

== input_helpers namespace ==
Input helper code should be stored in FGDATA/Nasal/input_helpers/<vendorname>.nas

To avoid clashes, there should be one file per vendor and in each of these files a namespace (hash) for this vendor shall be created.

See honeycomb.nas for an example:<syntaxhighlight lang="shell">
#
# Helpers for Honeycomb input devices
#

# !!! Abbreviated sample !!!
# Check FGDATA repository for latest full version

# namespace
var honeycomb = {};

# Helper for the Honeycomb Alpha Yoke
honeycomb["alpha"] = {
new: func(cfgnode) {
var m = {
parents: [me, input_helpers.config_manager.new(cfgnode)],
};
return m;
},
# abreviated file
};
</syntaxhighlight>

== config_manager - supporting config variants for a device ==
The <code>input_helpers.config_manager</code> class is designed to allow configuration variants for an input device to be defined within a single XML config file.

Why? Take the Honeycomb Bravo throttle quadrant as an example. It supports six levers with replaceable lever "heads", one set for airliners and another one for GA single and dual engine models, so you can configure the hardware with levers from single throttle/mixture up to four jet engines.

Now, you need a way to tell FlightGear, what levers you put onto your throttle quadrant and how to interprete the lever inputs. To avoid juggling with XML files, we simply put the limited number of variants into the XML and let the config_manager do the rest.

If XML files containing <config-variants> are loaded during startup, config_manager will show a popup hint about this fact and open a dialog to select the desired config variant.

The selection is added to aircraft.data and thus is safed per aircraft for convenience.<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<PropertyList>
<vendor-id>honeycomb</vendor-id>
<model-id>bravo</model-id>
<name>Honeycomb Aeronautical Bravo Throttle Quadrant</name>

<debug-events type="bool">false</debug-events>
<hid-debug-raw type="bool">false</hid-debug-raw>


<nasal>
<open>
<![CDATA[
print("Honeycomb Bravo Nasal (event) open");
bravo = input_helpers.honeycomb.bravo.new(cmdarg());
]]>
</open>
<close>
<![CDATA[
print("Honeycomb Bravo Nasal (event) close");
if (ishash(bravo) and isfunc(bravo['close']))
bravo.close(cmdarg());
]]>
</close>
</nasal>

<config-variants>
<variant>

<id>jet2</id>

<description>Airliner (two engines)</description>


<mapping>
<input>/input/honeycomb/bravo/lever[0]</input>
<output>/controls/flight/speed-brake</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[2]</input>
<output>/controls/engines/engine[0]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[3]</input>
<output>/controls/engines/engine[1]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever-down-button[2]</input>
<output>/controls/engines/engine[0]/cutoff</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever-down-button[3]</input>
<output>/controls/engines/engine[1]/cutoff</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/reverser[2]</input>
<output>/controls/engines/engine[0]/reverser</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/reverser[3]</input>
<output>/controls/engines/engine[1]/reverser</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[5]</input>
<output>/controls/flaps-lever-continuous</output>
</mapping>
</variant>
<variant>
<id>tm</id>
<description>Throttle/Mixture</description>
<mapping>
<input>/input/honeycomb/bravo/lever[0]</input>
<output>/controls/engines/engine[0]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[1]</input>
<output>/controls/engines/engine[0]/mixture</output>
</mapping>
</variant>
<variant>
<id>tpm</id>
<description>Throttle/Prop/Mixture</description>
<mapping>
<input>/input/honeycomb/bravo/lever[0]</input>
<output>/controls/engines/engine[0]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[1]</input>
<output>/controls/engines/engine[0]/propeller-pitch</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[2]</input>
<output>/controls/engines/engine[0]/mixture</output>
</mapping>
</variant>
</config-variants>

</PropertyList>
</syntaxhighlight>

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

[[Honeycomb Input Devices]]
[[Category:Nasal]]
[[Category:Joysticks and Yokes]]

USB-HID

2025-04-04T10:48:14Z

Jsb: add 'see also' section

[draft]

USB-HID (Human Interface Device) is one of the methods to connect input devices to FlightGear.

==Linux access rights for devices==
HID devices under linux have usually restricted access rights, e.g. normal users are not allowed to access them directly. As you should not run FlightGear as root user, you most likely need to create a few udev rules to allow normal users to access the device files.

First, use <code>lsusb</code> to get a list of all detected USB devices. The output should look similar to this:<syntaxhighlight lang="shell">
Bus 003 Device 004: ID 294b:1901 Honeycomb Aeronautical Bravo Throttle Quadrant
Bus 003 Device 006: ID 06a3:0763 Saitek PLC Pro Flight Rudder Pedals
Bus 003 Device 002: ID 294b:1900 Honeycomb Aeronautical Alpha Flight Controls
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 006 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 005 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

</syntaxhighlight>Find the lines containing your relevant input devices (joysticks, yoke, throttle, pedals, ...) and note the IDs. The format is <vendor-id>:<device-id>. For simplicity, this example uses only the vendor-id.

On Ubuntu, you can add for example the following file under <code>/etc/udev/rules.d</code> to allow r/w access to members of the <code>input</code> user group. Of course, you have to add/modify the lines to match the vendor-ids of your devices.<syntaxhighlight lang="shell">
# /etc/udev/rules.d/40-usb-flightgear.rules
#
# To add your user to the input group try:
# sudo usermod --append --groups input <username>

# Honeycomb
SUBSYSTEMS=="usb", ATTRS{idVendor}=="294b", GROUP="input", MODE="0664"
# saitek
SUBSYSTEMS=="usb", ATTRS{idVendor}=="06a3", GROUP="input", MODE="0664"

</syntaxhighlight>To activate the new rules, try <code>udevadm control --reload-rules && udevadm trigger</code>

If this does not help, a reboot will do.

==Developing Configuration files for input devices==

=== Gathering data ===
Add the following parameters to your FlightGear command line or via the launcher Settings>Additional Settings<syntaxhighlight>
--log-class=input
--log-level=debug
</syntaxhighlight>This will create a lot of debug output for the input systems in which you can find all events supported by your devices

=== Creating a config file ===
The configuration files shall be stored in FGDATA/Input/Event/<Vendor>/<Model>.xml

As a starting point you can copy this example. Replace the data as needed.<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<PropertyList>

<vendor-id>honeycomb</vendor-id>
<model-id>bravo</model-id>


<name>Honeycomb Aeronautical Bravo Throttle Quadrant</name>


<debug-events type="bool">false</debug-events>

<nasal>
<open>
<![CDATA[
#print("Honeycomb Bravo Nasal (event) open");
#bravo = input_helpers.honeycomb.bravo.new(cmdarg());
]]>
</open>
<close>
<![CDATA[
#print("Honeycomb Bravo Nasal (event) close");
#if (ishash(bravo) and isfunc(bravo['close']))
# bravo.close(cmdarg());
]]>
</close>
</nasal>

</PropertyList>
</syntaxhighlight>Example for an axis event:<syntaxhighlight lang="xml">
<event>
<desc>Lever 0</desc>
<name>abs-x-translate</name>
<min-range>-1023</min-range>
<max-range>1023</max-range>
<binding>
<command>property-scale</command>
<property>/input/honeycomb/bravo/lever[0]</property>
</binding>
</event>
</syntaxhighlight>Example for a button event:<syntaxhighlight lang="xml">
<event>
<name>button-1</name>
<desc>AP mode HDG</desc>
<repeatable>false</repeatable>
<binding>
<command>property-assign</command>
<property>/input/honeycomb/bravo/buttons/hdg</property>
<value>1</value>
</binding>
<mod-up>
<binding>
<command>property-assign</command>
<property>/input/honeycomb/bravo/buttons/hdg</property>
<value>0</value>
</binding>
</mod-up>
</event>
</syntaxhighlight>

==Status of OS support==
Linux: Supported

MacOS: supported?

Windows: not yet supported?

== see also ==
[[Input helpers]]

[[Honeycomb Input Devices]]

Input helpers

2025-04-04T10:47:07Z

Jsb:

== Overview ==
This page is about Nasal script code for input devices like joysticks, yokes, throttle quadrands and pedals.

While small scripts can be easily added directly into joystick <binding>, larger code blocks should be organized a bit differently. As always: "do not repeat yourself". This means, to make everyones live easier, code should not be copy&pasted but put into a "central" place as functions or classes and be called whenever, wherever needed. This way, maintenance has to be done only in one place.

== input_helpers namespace ==
Input helper code should be stored in FGDATA/Nasal/input_helpers/<myvendor>.nas

To avoid clashes, there should be one file per vendor and in each of these files a namespace (hash) for this vendor shall be created.

See honeycomb.nas for an example:<syntaxhighlight lang="shell">
#
# Helpers for Honeycomb input devices
#

# !!! Abbreviated sample !!!
# Check FGDATA repository for latest full version

# namespace
var honeycomb = {};

# Helper for the Honeycomb Alpha Yoke
honeycomb["alpha"] = {
new: func(cfgnode) {
var m = {
parents: [me, input_helpers.config_manager.new(cfgnode)],
};
return m;
},
# abreviated file
};
</syntaxhighlight>

== config_manager - supporting config variants for a device ==
The <code>input_helpers.config_manager</code> class is designed to allow configuration variants for an input device to be defined within a single XML config file.

Why? Take the Honeycomb Bravo throttle quadrant as an example. It supports six levers with replaceable lever "heads", one set for airliners and another one for GA single and dual engine models, so you can configure the hardware with levers from single throttle/mixture up to four jet engines.

Now, you need a way to tell FlightGear, what levers you put onto your throttle quadrant and how to interprete the lever inputs. To avoid juggling with XML files, we simply put the limited number of variants into the XML and let the config_manager do the rest.

If XML files containing <config-variants> are loaded during startup, config_manager will show a popup hint about this fact and open a dialog to select the desired config variant.

The selection is added to aircraft.data and thus is safed per aircraft for convenience.<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<PropertyList>
<vendor-id>honeycomb</vendor-id>
<model-id>bravo</model-id>
<name>Honeycomb Aeronautical Bravo Throttle Quadrant</name>

<debug-events type="bool">false</debug-events>
<hid-debug-raw type="bool">false</hid-debug-raw>


<nasal>
<open>
<![CDATA[
print("Honeycomb Bravo Nasal (event) open");
bravo = input_helpers.honeycomb.bravo.new(cmdarg());
]]>
</open>
<close>
<![CDATA[
print("Honeycomb Bravo Nasal (event) close");
if (ishash(bravo) and isfunc(bravo['close']))
bravo.close(cmdarg());
]]>
</close>
</nasal>

<config-variants>
<variant>

<id>jet2</id>

<description>Airliner (two engines)</description>


<mapping>
<input>/input/honeycomb/bravo/lever[0]</input>
<output>/controls/flight/speed-brake</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[2]</input>
<output>/controls/engines/engine[0]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[3]</input>
<output>/controls/engines/engine[1]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever-down-button[2]</input>
<output>/controls/engines/engine[0]/cutoff</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever-down-button[3]</input>
<output>/controls/engines/engine[1]/cutoff</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/reverser[2]</input>
<output>/controls/engines/engine[0]/reverser</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/reverser[3]</input>
<output>/controls/engines/engine[1]/reverser</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[5]</input>
<output>/controls/flaps-lever-continuous</output>
</mapping>
</variant>
<variant>
<id>tm</id>
<description>Throttle/Mixture</description>
<mapping>
<input>/input/honeycomb/bravo/lever[0]</input>
<output>/controls/engines/engine[0]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[1]</input>
<output>/controls/engines/engine[0]/mixture</output>
</mapping>
</variant>
<variant>
<id>tpm</id>
<description>Throttle/Prop/Mixture</description>
<mapping>
<input>/input/honeycomb/bravo/lever[0]</input>
<output>/controls/engines/engine[0]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[1]</input>
<output>/controls/engines/engine[0]/propeller-pitch</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[2]</input>
<output>/controls/engines/engine[0]/mixture</output>
</mapping>
</variant>
</config-variants>

</PropertyList>
</syntaxhighlight>

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

[[Honeycomb Input Devices]]
[[Category:Nasal]]
[[Category:Joysticks and Yokes]]

Honeycomb Input Devices

2025-04-04T10:26:29Z

Jsb: Initial draft

(Work in progress)

This page shall provide information about the input devices available from Honeycomb Aeronautical and their integration into FlightGear.

== Honeycomb Alpha Yoke ==
Classic yoke designed for GA aircrafts like the C172 or PA28 with switches for e.g. battery, alternator, lights, starter 'key'.

=== Integration ===
Partly done

== Honeycomb 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
|
|}

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

=== Integration ===
{{Done}}

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

Aircraft properties reference

2025-03-31T15:27:35Z

Jsb: /* Electric */

{{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, buttons, etc.). Consider these as the pilots 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 ===
Control elements for electrical systems like battery, generators/alternators, avionics etc.
<pre>
/controls/electric/battery-switch
/controls/electric/external-power
/controls/electric/APU-generator
/controls/electric/engine[%d]/generator
/controls/electric/engine[%d]/bus-tie
/controls/electric/avionics[%d]

</pre>

{{Note|/controls/electric/APU-generator should be aliased to /controls/electric/engine[%d]/generator (where %d is the index of the engine representing the APU) by the aircraft code.}}

=== 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]]

Addon

2025-02-03T15:57:44Z

Jsb: Add modules.nas to Related content/Wiki articles

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

== 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}}
* [[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>
* [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,...
* [[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
* [[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-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)
* [https://github.com/hbeni/fgfs-noGroundDamage noGroundDamage] - Addon to temporarily disable damage after landing and for ground operations for the c172/c182

== 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| ]]

Debug.nas

2024-11-03T16:39:12Z

Jsb: Redirected page to Nasal library/debug

#REDIRECT [[Nasal library/debug]]

Nasal Modules

2024-11-03T16:37:19Z

Jsb: /* debug.nas */

{{Stub}}

This page is meant to help document the purpose and function of the standard Nasal modules provided in the FlightGear base package ([[$FG_ROOT]]/Nasal). Ideally, all modules will be introduced along with a description, provided methods and example source code.

{{tip|see [[Nasal Initialization]] for information on different module types and how Nasal and its modules are initialized.}}

= aircraft.nas =
This module provide basic functions and classes for use in aircraft specific Nasal context.
= atc-chatter.nas =
Simple sequenced ATC background chatter function
= bits.nas =
bit level manipulation routines
= controls.nas =
controls related functions
= debug.nas =
see [[Nasal library/debug]]

= dynamic_view.nas =
Dynamic Cockpit View manager. Tries to simulate the pilot's most likely deliberate view direction. Doesn't consider forced view changes due to acceleration.
= fuel.nas =
Manages consumables
= geo.nas =
geo functions

= modules.nas =
[[Modules.nas]] - support for runtime re-loadable Nasal modules

= props.nas =
[[Nasal library/props|Props.nas]] - functions to work with FlightGear's [[Property tree]]

also see: http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg10326.html
and: http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg18962.html

Aircraft properties reference

2024-10-16T21:06:03Z

Jsb: /* Annunciators */

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

== 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]]

Aircraft properties reference/Instrumentation/COMM

2024-10-08T20:42:14Z

Jsb: Add link to parent page

Full documentation: [[Aircraft properties reference]]<pre>
/instrumentation/comm[%d]/add-noise
/instrumentation/comm[%d]/airport-id
/instrumentation/comm[%d]/atis
/instrumentation/comm[%d]/channel-button
/instrumentation/comm[%d]/chanel-mode-selector
/instrumentation/comm[%d]/cutoff-signal-quality
/instrumentation/comm[%d]/frequencies
/instrumentation/comm[%d]/frequencies/dial-khz
/instrumentation/comm[%d]/frequencies/dial-mhz
/instrumentation/comm[%d]/frequencies/selected-channel
/instrumentation/comm[%d]/frequencies/selected-channel-width-khz
/instrumentation/comm[%d]/frequencies/selected-mhz
/instrumentation/comm[%d]/frequencies/selected-mhz-fmt
/instrumentation/comm[%d]/frequencies/selected-real-frequency-mhz
/instrumentation/comm[%d]/frequencies/standby-channel
/instrumentation/comm[%d]/frequencies/standby-channel-width-khz
/instrumentation/comm[%d]/frequencies/standby-mhz
/instrumentation/comm[%d]/frequencies/standby-mhz-fmt
/instrumentation/comm[%d]/frequencies/standby-real-frequency-mhz
/instrumentation/comm[%d]/frq-swap-btn
/instrumentation/comm[%d]/height-above-station-ft
/instrumentation/comm[%d]/operable
/instrumentation/comm[%d]/power-btn
/instrumentation/comm[%d]/ptt
/instrumentation/comm[%d]/servicable
/instrumentation/comm[%d]/signal-quality-norm
/instrumentation/comm[%d]/slant-distance-m
/instrumentation/comm[%d]/station-name
/instrumentation/comm[%d]/station-type
/instrumentation/comm[%d]/test-btn
/instrumentation/comm[%d]/track-distance-m
/instrumentation/comm[%d]/true-bearing-from-deg
/instrumentation/comm[%d]/true-bearing-to-deg
/instrumentation/comm[%d]/volume
/instrumentation/comm[%d]/volume-selected
</pre>

Aircraft properties reference

2024-09-27T20:54:25Z

Jsb: /* Annunciators */

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

== Annunciators ==
!! This section is work in progress !!

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

Aircraft properties reference

2024-09-27T20:50:55Z

Jsb: /* Annunciators [draft] */

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

== Annunciators ==
!! This section is work in progress !!

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 $FGDATA/Aircraft/Generic/generic-annunciators.xml 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]]

Annunciators

2024-09-27T20:50:07Z

Jsb:

To better support external hardware "out of the box", please consider using standard annunciator properties in your aircrafts as well as in your (input) device configs.

see [[Aircraft properties reference]]

Annunciators

2024-09-27T20:13:33Z

Jsb: Initial version

To better support external hardware "out of the box", please consider to use standard annunciator properties in your aircrafts as well as in your (input) device configs.

see [[Aircraft properties reference]]

Input helpers

2024-09-27T19:59:47Z

Jsb:

This page is about Nasal script code for input devices like joysticks, yokes, throttle quadrands and pedals.

While small scripts can be easily added directly into joystick <binding>, larger code blocks should be organized a bit differently. As always: "do not repeat yourself". This means, to make everyones live easier, code should not be copy&pasted but put into a "central" place as functions or classes and be called whenever, wherever needed. This way, maintenance has to be done only in one place.

=== input_helpers namespace ===
Input helper code should be stored in FGDATA/Nasal/input_helpers/<myvendor>.nas

To avoid clashes, there should be one file per vendor and in each of these files a namespace (hash) for this vendor shall be created.

See honeycomb.nas for an example:<syntaxhighlight lang="shell">
#
# Helpers for Honeycomb input devices
#

# !!! Abbreviated sample !!!
# Check FGDATA repository for latest full version

# namespace
var honeycomb = {};

# Helper for the Honeycomb Alpha Yoke
honeycomb["alpha"] = {
new: func(cfgnode) {
var m = {
parents: [me, input_helpers.config_manager.new(cfgnode)],
};
return m;
},
# abreviated file
};
</syntaxhighlight>

=== config_manager - supporting config variants for a device ===
The <code>input_helpers.config_manager</code> class is designed to allow configuration variants for an input device to be defined within a single XML config file.

Why? Take the Honeycomb Bravo throttle quadrant as an example. It supports six levers with replaceable lever "heads", one set for airliners and another one for GA single and dual engine models, so you can "configure" the hardware with levers from single throttle/mixture up to four jet engines.

Now, you need a way to tell FlightGear, what levers you put onto your throttle quadrant and how to interprete the lever inputs. To avoid juggling with XML files, we simply put the limited number of variants into the XML and let the config_manager do the rest.

If XML files containing <config-variants> are loaded during startup, config_manager will show a popup hint about this fact and open a dialog to select the desired config variant. The selection is added to aircraft.data and safed for convenience.<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<PropertyList>
<vendor-id>honeycomb</vendor-id>
<model-id>bravo</model-id>
<name>Honeycomb Aeronautical Bravo Throttle Quadrant</name>

<debug-events type="bool">false</debug-events>
<hid-debug-raw type="bool">false</hid-debug-raw>


<nasal>
<open>
<![CDATA[
print("Honeycomb Bravo Nasal (event) open");
bravo = input_helpers.honeycomb.bravo.new(cmdarg());
]]>
</open>
<close>
<![CDATA[
print("Honeycomb Bravo Nasal (event) close");
if (ishash(bravo) and isfunc(bravo['close']))
bravo.close(cmdarg());
]]>
</close>
</nasal>

<config-variants>
<variant>

<id>jet2</id>

<description>Airliner (two engines)</description>


<mapping>
<input>/input/honeycomb/bravo/lever[0]</input>
<output>/controls/flight/speed-brake</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[2]</input>
<output>/controls/engines/engine[0]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[3]</input>
<output>/controls/engines/engine[1]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever-down-button[2]</input>
<output>/controls/engines/engine[0]/cutoff</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever-down-button[3]</input>
<output>/controls/engines/engine[1]/cutoff</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/reverser[2]</input>
<output>/controls/engines/engine[0]/reverser-cmd</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/reverser[3]</input>
<output>/controls/engines/engine[1]/reverser-cmd</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[5]</input>
<output>/controls/flaps-lever-continuous</output>
</mapping>
</variant>
<variant>
<id>jet4</id>
<description>Airliner (four engines)</description>
<mapping>
<input>/input/honeycomb/bravo/lever[0]</input>
<output>/controls/flight/speed-brake</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[1]</input>
<output>/controls/engines/engine[0]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[2]</input>
<output>/controls/engines/engine[1]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[3]</input>
<output>/controls/engines/engine[2]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[4]</input>
<output>/controls/engines/engine[3]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever-down-button[1]</input>
<output>/controls/engines/engine[0]/cutoff</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever-down-button[2]</input>
<output>/controls/engines/engine[1]/cutoff</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever-down-button[3]</input>
<output>/controls/engines/engine[2]/cutoff</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever-down-button[4]</input>
<output>/controls/engines/engine[3]/cutoff</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/reverser[1]</input>
<output>/controls/engines/engine[0]/reverser-cmd</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/reverser[2]</input>
<output>/controls/engines/engine[1]/reverser-cmd</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/reverser[3]</input>
<output>/controls/engines/engine[2]/reverser-cmd</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/reverser[4]</input>
<output>/controls/engines/engine[3]/reverser-cmd</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[5]</input>
<output>/controls/flaps-lever-continuous</output>
</mapping>
</variant>
<variant>
<id>tm</id>
<description>Throttle/Mixture</description>
<mapping>
<input>/input/honeycomb/bravo/lever[0]</input>
<output>/controls/engines/engine[0]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[1]</input>
<output>/controls/engines/engine[0]/mixture</output>
</mapping>
</variant>
<variant>
<id>tpm</id>
<description>Throttle/Prop/Mixture</description>
<mapping>
<input>/input/honeycomb/bravo/lever[0]</input>
<output>/controls/engines/engine[0]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[1]</input>
<output>/controls/engines/engine[0]/propeller-pitch</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[2]</input>
<output>/controls/engines/engine[0]/mixture</output>
</mapping>
</variant>
<variant>
<id>ttmm</id>
<description>Throttle/Mixture (two engines)</description>
<mapping>
<input>/input/honeycomb/bravo/lever[0]</input>
<output>/controls/engines/engine[0]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[1]</input>
<output>/controls/engines/engine[1]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[2]</input>
<output>/controls/engines/engine[0]/mixture</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[3]</input>
<output>/controls/engines/engine[1]/mixture</output>
</mapping>
</variant>
<variant>
<id>ttppmm</id>
<description>Throttle/Prop/Mixture (two engines)</description>
<mapping>
<input>/input/honeycomb/bravo/lever[0]</input>
<output>/controls/engines/engine[0]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[1]</input>
<output>/controls/engines/engine[1]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[2]</input>
<output>/controls/engines/engine[0]/propeller-pitch</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[3]</input>
<output>/controls/engines/engine[1]/propeller-pitch</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[4]</input>
<output>/controls/engines/engine[0]/mixture</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[5]</input>
<output>/controls/engines/engine[1]/mixture</output>
</mapping>
</variant>
</config-variants>

</PropertyList>
</syntaxhighlight>
[[Category:Nasal]]
[[Category:Joysticks and Yokes]]

Input helper

2024-09-27T19:59:17Z

Jsb: Jsb moved page Input helper to Input helpers

#REDIRECT [[Input helpers]]

Input helpers

2024-09-27T19:59:17Z

Jsb: Jsb moved page Input helper to Input helpers

This page is about Nasal script code for input devices like joysticks, yokes, throttle quadrands and pedals.

While small scripts can be easily added directly into joystick <binding>, larger code blocks should be organized a bit differently. As always: "do not repeat yourself". This means, to make everyones live easier, code should not be copy&pasted but put into a "central" place as functions or classes and be called whenever, wherever needed. This way, maintenance has to be done only in one place.

=== input_helper namespace ===
Input helper code should be stored in FGDATA/Nasal/input_helpers/<myvendor>.nas

To avoid clashes, there should be one file per vendor and in each of these files a namespace (hash) for this vendor shall be created.

See honeycomb.nas for an example:<syntaxhighlight lang="shell">
#
# Helpers for Honeycomb input devices
#

# !!! Abbreviated sample !!!
# Check FGDATA repository for latest full version

# namespace
var honeycomb = {};

# Helper for the Honeycomb Alpha Yoke
honeycomb["alpha"] = {
new: func(cfgnode) {
var m = {
parents: [me, input_helpers.config_manager.new(cfgnode)],
};
return m;
},
# abreviated file
};
</syntaxhighlight>

=== config_manager - supporting config variants for a device ===
The <code>input_helpers.config_manager</code> class is designed to allow configuration variants for an input device to be defined within a single XML config file.

Why? Take the Honeycomb Bravo throttle quadrant as an example. It supports six levers with replaceable lever "heads", one set for airliners and another one for GA single and dual engine models, so you can "configure" the hardware with levers from single throttle/mixture up to four jet engines.

Now, you need a way to tell FlightGear, what levers you put onto your throttle quadrant and how to interprete the lever inputs. To avoid juggling with XML files, we simply put the limited number of variants into the XML and let the config_manager do the rest.

If XML files containing <config-variants> are loaded during startup, config_manager will show a popup hint about this fact and open a dialog to select the desired config variant. The selection is added to aircraft.data and safed for convenience.<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<PropertyList>
<vendor-id>honeycomb</vendor-id>
<model-id>bravo</model-id>
<name>Honeycomb Aeronautical Bravo Throttle Quadrant</name>

<debug-events type="bool">false</debug-events>
<hid-debug-raw type="bool">false</hid-debug-raw>


<nasal>
<open>
<![CDATA[
print("Honeycomb Bravo Nasal (event) open");
bravo = input_helpers.honeycomb.bravo.new(cmdarg());
]]>
</open>
<close>
<![CDATA[
print("Honeycomb Bravo Nasal (event) close");
if (ishash(bravo) and isfunc(bravo['close']))
bravo.close(cmdarg());
]]>
</close>
</nasal>

<config-variants>
<variant>

<id>jet2</id>

<description>Airliner (two engines)</description>


<mapping>
<input>/input/honeycomb/bravo/lever[0]</input>
<output>/controls/flight/speed-brake</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[2]</input>
<output>/controls/engines/engine[0]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[3]</input>
<output>/controls/engines/engine[1]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever-down-button[2]</input>
<output>/controls/engines/engine[0]/cutoff</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever-down-button[3]</input>
<output>/controls/engines/engine[1]/cutoff</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/reverser[2]</input>
<output>/controls/engines/engine[0]/reverser-cmd</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/reverser[3]</input>
<output>/controls/engines/engine[1]/reverser-cmd</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[5]</input>
<output>/controls/flaps-lever-continuous</output>
</mapping>
</variant>
<variant>
<id>jet4</id>
<description>Airliner (four engines)</description>
<mapping>
<input>/input/honeycomb/bravo/lever[0]</input>
<output>/controls/flight/speed-brake</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[1]</input>
<output>/controls/engines/engine[0]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[2]</input>
<output>/controls/engines/engine[1]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[3]</input>
<output>/controls/engines/engine[2]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[4]</input>
<output>/controls/engines/engine[3]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever-down-button[1]</input>
<output>/controls/engines/engine[0]/cutoff</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever-down-button[2]</input>
<output>/controls/engines/engine[1]/cutoff</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever-down-button[3]</input>
<output>/controls/engines/engine[2]/cutoff</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever-down-button[4]</input>
<output>/controls/engines/engine[3]/cutoff</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/reverser[1]</input>
<output>/controls/engines/engine[0]/reverser-cmd</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/reverser[2]</input>
<output>/controls/engines/engine[1]/reverser-cmd</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/reverser[3]</input>
<output>/controls/engines/engine[2]/reverser-cmd</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/reverser[4]</input>
<output>/controls/engines/engine[3]/reverser-cmd</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[5]</input>
<output>/controls/flaps-lever-continuous</output>
</mapping>
</variant>
<variant>
<id>tm</id>
<description>Throttle/Mixture</description>
<mapping>
<input>/input/honeycomb/bravo/lever[0]</input>
<output>/controls/engines/engine[0]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[1]</input>
<output>/controls/engines/engine[0]/mixture</output>
</mapping>
</variant>
<variant>
<id>tpm</id>
<description>Throttle/Prop/Mixture</description>
<mapping>
<input>/input/honeycomb/bravo/lever[0]</input>
<output>/controls/engines/engine[0]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[1]</input>
<output>/controls/engines/engine[0]/propeller-pitch</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[2]</input>
<output>/controls/engines/engine[0]/mixture</output>
</mapping>
</variant>
<variant>
<id>ttmm</id>
<description>Throttle/Mixture (two engines)</description>
<mapping>
<input>/input/honeycomb/bravo/lever[0]</input>
<output>/controls/engines/engine[0]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[1]</input>
<output>/controls/engines/engine[1]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[2]</input>
<output>/controls/engines/engine[0]/mixture</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[3]</input>
<output>/controls/engines/engine[1]/mixture</output>
</mapping>
</variant>
<variant>
<id>ttppmm</id>
<description>Throttle/Prop/Mixture (two engines)</description>
<mapping>
<input>/input/honeycomb/bravo/lever[0]</input>
<output>/controls/engines/engine[0]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[1]</input>
<output>/controls/engines/engine[1]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[2]</input>
<output>/controls/engines/engine[0]/propeller-pitch</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[3]</input>
<output>/controls/engines/engine[1]/propeller-pitch</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[4]</input>
<output>/controls/engines/engine[0]/mixture</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[5]</input>
<output>/controls/engines/engine[1]/mixture</output>
</mapping>
</variant>
</config-variants>

</PropertyList>
</syntaxhighlight>
[[Category:Nasal]]
[[Category:Joysticks and Yokes]]

Input helpers

2024-09-27T19:57:59Z

Jsb: Initial version

This page is about Nasal script code for input devices like joysticks, yokes, throttle quadrands and pedals.

While small scripts can be easily added directly into joystick <binding>, larger code blocks should be organized a bit differently. As always: "do not repeat yourself". This means, to make everyones live easier, code should not be copy&pasted but put into a "central" place as functions or classes and be called whenever, wherever needed. This way, maintenance has to be done only in one place.

=== input_helper namespace ===
Input helper code should be stored in FGDATA/Nasal/input_helpers/<myvendor>.nas

To avoid clashes, there should be one file per vendor and in each of these files a namespace (hash) for this vendor shall be created.

See honeycomb.nas for an example:<syntaxhighlight lang="shell">
#
# Helpers for Honeycomb input devices
#

# !!! Abbreviated sample !!!
# Check FGDATA repository for latest full version

# namespace
var honeycomb = {};

# Helper for the Honeycomb Alpha Yoke
honeycomb["alpha"] = {
new: func(cfgnode) {
var m = {
parents: [me, input_helpers.config_manager.new(cfgnode)],
};
return m;
},
# abreviated file
};
</syntaxhighlight>

=== config_manager - supporting config variants for a device ===
The <code>input_helpers.config_manager</code> class is designed to allow configuration variants for an input device to be defined within a single XML config file.

Why? Take the Honeycomb Bravo throttle quadrant as an example. It supports six levers with replaceable lever "heads", one set for airliners and another one for GA single and dual engine models, so you can "configure" the hardware with levers from single throttle/mixture up to four jet engines.

Now, you need a way to tell FlightGear, what levers you put onto your throttle quadrant and how to interprete the lever inputs. To avoid juggling with XML files, we simply put the limited number of variants into the XML and let the config_manager do the rest.

If XML files containing <config-variants> are loaded during startup, config_manager will show a popup hint about this fact and open a dialog to select the desired config variant. The selection is added to aircraft.data and safed for convenience.<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<PropertyList>
<vendor-id>honeycomb</vendor-id>
<model-id>bravo</model-id>
<name>Honeycomb Aeronautical Bravo Throttle Quadrant</name>

<debug-events type="bool">false</debug-events>
<hid-debug-raw type="bool">false</hid-debug-raw>


<nasal>
<open>
<![CDATA[
print("Honeycomb Bravo Nasal (event) open");
bravo = input_helpers.honeycomb.bravo.new(cmdarg());
]]>
</open>
<close>
<![CDATA[
print("Honeycomb Bravo Nasal (event) close");
if (ishash(bravo) and isfunc(bravo['close']))
bravo.close(cmdarg());
]]>
</close>
</nasal>

<config-variants>
<variant>

<id>jet2</id>

<description>Airliner (two engines)</description>


<mapping>
<input>/input/honeycomb/bravo/lever[0]</input>
<output>/controls/flight/speed-brake</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[2]</input>
<output>/controls/engines/engine[0]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[3]</input>
<output>/controls/engines/engine[1]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever-down-button[2]</input>
<output>/controls/engines/engine[0]/cutoff</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever-down-button[3]</input>
<output>/controls/engines/engine[1]/cutoff</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/reverser[2]</input>
<output>/controls/engines/engine[0]/reverser-cmd</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/reverser[3]</input>
<output>/controls/engines/engine[1]/reverser-cmd</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[5]</input>
<output>/controls/flaps-lever-continuous</output>
</mapping>
</variant>
<variant>
<id>jet4</id>
<description>Airliner (four engines)</description>
<mapping>
<input>/input/honeycomb/bravo/lever[0]</input>
<output>/controls/flight/speed-brake</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[1]</input>
<output>/controls/engines/engine[0]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[2]</input>
<output>/controls/engines/engine[1]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[3]</input>
<output>/controls/engines/engine[2]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[4]</input>
<output>/controls/engines/engine[3]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever-down-button[1]</input>
<output>/controls/engines/engine[0]/cutoff</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever-down-button[2]</input>
<output>/controls/engines/engine[1]/cutoff</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever-down-button[3]</input>
<output>/controls/engines/engine[2]/cutoff</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever-down-button[4]</input>
<output>/controls/engines/engine[3]/cutoff</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/reverser[1]</input>
<output>/controls/engines/engine[0]/reverser-cmd</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/reverser[2]</input>
<output>/controls/engines/engine[1]/reverser-cmd</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/reverser[3]</input>
<output>/controls/engines/engine[2]/reverser-cmd</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/reverser[4]</input>
<output>/controls/engines/engine[3]/reverser-cmd</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[5]</input>
<output>/controls/flaps-lever-continuous</output>
</mapping>
</variant>
<variant>
<id>tm</id>
<description>Throttle/Mixture</description>
<mapping>
<input>/input/honeycomb/bravo/lever[0]</input>
<output>/controls/engines/engine[0]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[1]</input>
<output>/controls/engines/engine[0]/mixture</output>
</mapping>
</variant>
<variant>
<id>tpm</id>
<description>Throttle/Prop/Mixture</description>
<mapping>
<input>/input/honeycomb/bravo/lever[0]</input>
<output>/controls/engines/engine[0]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[1]</input>
<output>/controls/engines/engine[0]/propeller-pitch</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[2]</input>
<output>/controls/engines/engine[0]/mixture</output>
</mapping>
</variant>
<variant>
<id>ttmm</id>
<description>Throttle/Mixture (two engines)</description>
<mapping>
<input>/input/honeycomb/bravo/lever[0]</input>
<output>/controls/engines/engine[0]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[1]</input>
<output>/controls/engines/engine[1]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[2]</input>
<output>/controls/engines/engine[0]/mixture</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[3]</input>
<output>/controls/engines/engine[1]/mixture</output>
</mapping>
</variant>
<variant>
<id>ttppmm</id>
<description>Throttle/Prop/Mixture (two engines)</description>
<mapping>
<input>/input/honeycomb/bravo/lever[0]</input>
<output>/controls/engines/engine[0]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[1]</input>
<output>/controls/engines/engine[1]/throttle</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[2]</input>
<output>/controls/engines/engine[0]/propeller-pitch</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[3]</input>
<output>/controls/engines/engine[1]/propeller-pitch</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[4]</input>
<output>/controls/engines/engine[0]/mixture</output>
</mapping>
<mapping>
<input>/input/honeycomb/bravo/lever[5]</input>
<output>/controls/engines/engine[1]/mixture</output>
</mapping>
</variant>
</config-variants>

</PropertyList>
</syntaxhighlight>
[[Category:Nasal]]
[[Category:Joysticks and Yokes]]

USB-HID

2024-09-27T19:02:31Z

Jsb: Initial draft

[draft]

USB-HID (Human Interface Device) is one of the methods to connect input devices to FlightGear.

==Linux access rights for devices==
HID devices under linux have usually restricted access rights, e.g. normal users are not allowed to access them directly. As you should not run FlightGear as root user, you most likely need to create a few udev rules to allow normal users to access the device files.

First, use <code>lsusb</code> to get a list of all detected USB devices. The output should look similar to this:<syntaxhighlight lang="shell">
Bus 003 Device 004: ID 294b:1901 Honeycomb Aeronautical Bravo Throttle Quadrant
Bus 003 Device 006: ID 06a3:0763 Saitek PLC Pro Flight Rudder Pedals
Bus 003 Device 002: ID 294b:1900 Honeycomb Aeronautical Alpha Flight Controls
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 006 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 005 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

</syntaxhighlight>Find the lines containing your relevant input devices (joysticks, yoke, throttle, pedals, ...) and note the IDs. The format is <vendor-id>:<device-id>. For simplicity, this example uses only the vendor-id.

On Ubuntu, you can add for example the following file under <code>/etc/udev/rules.d</code> to allow r/w access to members of the <code>input</code> user group. Of course, you have to add/modify the lines to match the vendor-ids of your devices.<syntaxhighlight lang="shell">
# /etc/udev/rules.d/40-usb-flightgear.rules
#
# To add your user to the input group try:
# sudo usermod --append --groups input <username>

# Honeycomb
SUBSYSTEMS=="usb", ATTRS{idVendor}=="294b", GROUP="input", MODE="0664"
# saitek
SUBSYSTEMS=="usb", ATTRS{idVendor}=="06a3", GROUP="input", MODE="0664"

</syntaxhighlight>To activate the new rules, try <code>udevadm control --reload-rules && udevadm trigger</code>

If this does not help, a reboot will do.

==Developing Configuration files for input devices==

=== Gathering data ===
Add the following parameters to your FlightGear command line or via the launcher Settings>Additional Settings<syntaxhighlight>
--log-class=input
--log-level=debug
</syntaxhighlight>This will create a lot of debug output for the input systems in which you can find all events supported by your devices

=== Creating a config file ===
The configuration files shall be stored in FGDATA/Input/Event/<Vendor>/<Model>.xml

As a starting point you can copy this example. Replace the data as needed.<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<PropertyList>

<vendor-id>honeycomb</vendor-id>
<model-id>bravo</model-id>


<name>Honeycomb Aeronautical Bravo Throttle Quadrant</name>


<debug-events type="bool">false</debug-events>

<nasal>
<open>
<![CDATA[
#print("Honeycomb Bravo Nasal (event) open");
#bravo = input_helpers.honeycomb.bravo.new(cmdarg());
]]>
</open>
<close>
<![CDATA[
#print("Honeycomb Bravo Nasal (event) close");
#if (ishash(bravo) and isfunc(bravo['close']))
# bravo.close(cmdarg());
]]>
</close>
</nasal>

</PropertyList>
</syntaxhighlight>Example for an axis event:<syntaxhighlight lang="xml">
<event>
<desc>Lever 0</desc>
<name>abs-x-translate</name>
<min-range>-1023</min-range>
<max-range>1023</max-range>
<binding>
<command>property-scale</command>
<property>/input/honeycomb/bravo/lever[0]</property>
</binding>
</event>
</syntaxhighlight>Example for a button event:<syntaxhighlight lang="xml">
<event>
<name>button-1</name>
<desc>AP mode HDG</desc>
<repeatable>false</repeatable>
<binding>
<command>property-assign</command>
<property>/input/honeycomb/bravo/buttons/hdg</property>
<value>1</value>
</binding>
<mod-up>
<binding>
<command>property-assign</command>
<property>/input/honeycomb/bravo/buttons/hdg</property>
<value>0</value>
</binding>
</mod-up>
</event>
</syntaxhighlight>

==Status of OS support==
Linux: Supported

MacOS: supported?

Windows: not yet supported?

Aircraft properties reference

2024-07-26T12:57:58Z

Jsb: /* Controls */

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

== Annunciators [draft] ==
!! This section is work in progress !!

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 $FGDATA/Aircraft/Generic/generic-annunciators.xml 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]]

Nasal library

2024-07-14T08:10:02Z

Jsb: /* contains() */ Correct comment (c&p error) and merge examples for better readability

{{Nasal Navigation|nocat=1}}
This page documents the global '''library functions and variables''' of FlightGear's built-in scripting language, [[Nasal]]. This includes ''[[#Core library functions|core library functions]]'', which were included in Nasal before its integration into FlightGear, the ''[[#Extension functions|extension functions]]'', which have been subsequently added, and are specifically designed for FlightGear, and the ''[[#variables|global variables]]'', which are conversion variables, added with extension functions, for converting between units. The relevant folders in [[Git]] are:
* {{flightgear file|src/Scripting}}
* {{simgear file|simgear/nasal}}

All these functions and variables are in the global namespace, that is, they are directly accessible (e.g., one can call <syntaxhighlight lang="nasal" inline>magvar()</syntaxhighlight> instead of <syntaxhighlight lang="nasal" inline>namespace.magvar()</syntaxhighlight>). However, if a namespace must be used, <code>globals</code> is the correct namespace, but using it is not recommended. For a more complete explanation, see [[Nasal Namespaces in-depth]].

{{tip|Copy & paste the examples into your [[Nasal Console]] and execute them to see what they do.|width=70%}}

== Core library functions ==
This is the list of the basic '''core library functions.''' Most of these functions were part of the original Nasal library (before its integration in to FlightGear), while some have been added or changed over time. See also:
* http://plausible.org/nasal/lib.html ([http://web.archive.org/web/20101010094553/http://plausible.org/nasal/lib.html archive])
* {{simgear file|simgear/nasal/lib.c}} ([http://sourceforge.net/p/flightgear/simgear/ci/next/log/?path=/simgear/nasal/lib.c history])

=== append() ===
{{Nasal doc
|syntax = append(vector, element[, element[, ...]]);
|source = {{simgear file|simgear/nasal/lib.c|l=42|t=Source}}
|text = This function appends, or adds, the given element(s) to the end of the vector given in the first argument. Returns the vector operated on.
|param1 = vector
|param1text = The vector to which the arguments will be appended.
|param2 = element
|param2text = An element to be added to the vector.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector
append(vector, 4); # Append the number 4 to the end of the vector
debug.dump(vector); # Print the contents of the vector
|example2 =
var vector = [1, 2, 3]; # Initialize the vector
append(vector, 4, 5, 6); # Append the numbers 4, 5, and 6 to the end of the vector
debug.dump(vector); # Print the contents of the vector
}}

=== bind() ===
{{Nasal doc
|syntax = bind(function, locals[, outer_scope]);
|source = {{simgear file|simgear/nasal/lib.c|l=502|t=Source}}
|text = This creates a new function object. A function in Nasal is three things: the actual code, a hash/namespace of local variables available to the function namespace, and the closure object of that namespace. These correspond to the three arguments respectively.
|param1 = function
|param1text = Function to evaluate.
|param2 = locals
|param2text = Hash containing values that will become the namespace (first closure) for the function.
|param3 = outer_scope
|param3text = Optional function which is bound to the next closure. This can be bound to yet another, making a linked list.
|example1 = # This is a namespace/hash with a single member, named "key," which is initialized to 12
var Namespace = {
key: 12
};

# This is different namespace/hash containing a function
# dividing a variable "key" (which is unavailable/nil in this namespace) by 2
var AnotherNamespace = {
ret: func {
key /= 2;
}
};

# To see that key is not available, try to call AnotherNamespace.ret() first
call(AnotherNamespace.ret, [], nil, nil, var errors = []);
if(size(errors)){
print("Key could not be divided/resolved!");
debug.printerror(errors);
}

# Associate the AnotherNamespace.ret() function with the first namespace
# so that "key" is now available
var function = bind(AnotherNamespace.ret, Namespace);

# Invoke the new function
function();

# Print out the value of Namespace.key
# It was changed to 12 from 6 by AnotherNamespace.ret()
print(Namespace.key);
}}

=== call() ===
{{Nasal doc
|syntax = call(func[, args[, me[, locals[, error]]]);
|source = {{simgear file|simgear/nasal/lib.c|l=247|t=Source}}
|text = Calls the given function with the given arguments and returns the result. This function is very useful as it allows much more control over function calls and catches any errors or {{func link|die()}} calls that would normally trigger run-time errors cancelling execution of the script otherwise.
|param1 = func
|param1text = Function to execute.
|param2 = args
|param2text = Vector containing arguments to give to the called function.
|param3 = me
|param3text = <code>'''me'''</code> reference for the function call (i.e., for method calls). If given, this will override any <code>'''me'''</code> value existing in the namespace (locals argument).
|param4 = locals
|param4text = A hash with key/value pairs that will be available to the called function, typically used as the namespace for the function to be called.
|param5 = error
|param5text = A vector to append errors to. If the called function generates an error, the error, place, and line will be written to this. These errors can be printed using {{func link|printerror()|debug}}.
|example1 =
# prints "Called from call()"
call(func {
print("Called from call()");
});
|example2 =
# prints "a = 1 : b = 2
call(func(a, b){
print("a = ", a, " : b = ", b);
},
[1, 2]
);
|example3 =
var Hash = {
new: func {
var m = { parents: [Hash] };

m.el1 = "string1";
m.el2 = "string2";

return m;
}
};

# prints "me.el1 = string1", then "me.el2 = string2" on the next line
call(func(a, b){
print("me.el", a, " = ", me["el" ~ a]);
print("me.el", b, " = ", me["el" ~ b]);
},
[1, 2],
Hash.new()
);
|example4 =
# prints the value of math.pi
call(func {
print(pi);
}, nil, nil,
math
);
|example5 =
call(func {
print(math.ip); # math.ip doesn't exist
}, nil, nil, nil,
var errs = []
);
debug.printerror(errs); # The error is caught and printed using debug.printerror()
}}

=== caller() ===
{{Nasal doc
|syntax = caller([level]);
|source = {{simgear file|simgear/nasal/lib.c|l=404|t=Source}}
|text = Returns a vector containing a record from the current call stack. The level numbering starts from the currently executing function (level 0). Level 1 (the default) is the caller of the current function, and so on.

The result is a four-element vector containing '''[0]''' a hash of local variables, '''[1]''' the function object, '''[2]''' the full source file name (incl. path) and '''[3]''' the line number.
|param1 = level
|param1text = Optional integer specifying the stack level to return a result from. Defaults to 1 (i.e. the caller of the currently executing function).
|example1 =
var myFunction = func(a, b){
debug.dump(caller(0)[0]); # prints a hash of local variables, including arguments a and b
return 2 * 2;
};

print("2 x 2 = ", myFunction(2, 2));
|example2 =
var get_arg_value = func(){
print("Argument to myFunc = ", caller(1)[0]['a']); # print the value of myFunc's single argument, using caller()
};

var myFunc = func(a){
get_arg_value();
};

myFunc(3);
|example3text = This is a real example taken from {{fgdata file|Nasal/canvas/MapStructure.nas}}. Function <code>r()</code> (above the TODOs) returns a hash with the key/value pairs as per its arguments. For example, something like this is returned: <code>{ name: "<name>", vis: 1, zindex: nil }</code>.
|example3 =
var MapStructure_selfTest = func() {
var temp = {};
temp.dlg = canvas.Window.new([600,400],"dialog");
temp.canvas = temp.dlg.createCanvas().setColorBackground(1,1,1,0.5);
temp.root = temp.canvas.createGroup();
var TestMap = temp.root.createChild("map");
TestMap.setController("Aircraft position");
TestMap.setRange(25); # TODO: implement zooming/panning via mouse/wheel here, for lack of buttons :-/
TestMap.setTranslation(
temp.canvas.get("view[0]")/2,
temp.canvas.get("view[1]")/2
);
var r = func(name,vis=1,zindex=nil) return caller(0)[0];
# TODO: we'll need some z-indexing here, right now it's just random
# TODO: use foreach/keys to show all layers in this case by traversing SymbolLayer.registry direclty ?
# maybe encode implicit z-indexing for each lcontroller ctor call ? - i.e. preferred above/below order ?
foreach(var type; [r('TFC',0),r('APT'),r('DME'),r('VOR'),r('NDB'),r('FIX',0),r('RTE'),r('WPT'),r('FLT'),r('WXR'),r('APS'), ] )
TestMap.addLayer(factory: canvas.SymbolLayer, type_arg: type.name,
visible: type.vis, priority: type.zindex,
);
}; # MapStructure_selfTest
}}

=== chr() ===
{{Nasal doc
|syntax = chr(code);
|source = {{simgear file|simgear/nasal/lib.c|l=175|t=Source}}
|text = Returns a character as per the single argument. Extended ASCII is supported (see http://www.asciitable.com/ for a list of supported characters), although this may vary between different systems. For a list of the most commonly used characters, see the {{wikipedia|ASCII#ASCII printable code chart|ASCII printable code chart}} ('''Dec''' column). The following table lists supported control characters, along with their equivalent control characters in Nasal strings. {{Note|In Nasal, only strings enclosed with double-quotes (<code>"string"</code>) supports control chracters. Strings in single quotes (<code>'string'</code>) do not.}}
{{{!}} class="wikitable"
! Code !! Name !! Equivalent to
{{!-}}
{{!}} 10 {{!!}} {{Wikipedia|Newline}} {{!!}} <code>\n</code>
{{!-}}
{{!}} 9 {{!!}} {{Wikipedia|Tab key#Tab characters|Horizontal tab}} {{!!}} <code>\t</code>
{{!-}}
{{!}} 13 {{!!}} {{Wikipedia|Carriage return}} {{!!}} <code>\r</code>
{{!}}}
|param1 = code
|param1text = Integer character code for the desired glyph.
|example1 = print("Code 65 = ", chr(65)); # prints "Code 65 = A"
|example2text = This example displays all of the characters in a list, in the format <code>Code '''n''' = >'''char'''<</code>, '''n''' being the index, and '''char''' being the character.
|example2 =
for(var i = 0; i <= 255; i += 1){
print("Code ", i, " = >", chr(i), "<");
}
}}

=== closure() ===
{{Nasal doc
|syntax = closure(func[, level]);
|source = {{simgear file|simgear/nasal/lib.c|l=421|t=Source}}
|text = Returns the hash table containing the lexical namespace of the given function. The level numbering start with level 0 being the namespace of '''func'''.
|param1 = func
|param1text = Function to evaluate.
|param2 = level
|param2text = Optional integer specifying the scope level. Defaults to 0 (the namespace of '''func''').
|example1 =
var get_math_e = func {
return e; # return the value of math.e
}

var myFunction = bind(get_math_e, math); # bind get_math_e to the math namespace, so that math.e is immediately available to get_math_e
debug.dump(closure(myFunction)); # print the namespace of get_math_e

print(myFunction());
}}

=== cmp() ===
{{Nasal doc
|syntax = cmp(a, b);
|source = {{simgear file|simgear/nasal/lib.c|l=112|t=Source}}
|text = Compares two strings, returning -1 if '''a''' is less than '''b''', 0 if they are identical and 1 if '''a''' is greater than '''b'''.
|param1 = a
|param1text = First string argument for comparison.
|param2 = b
|param2text = Second string argument for comparison.
|example1 = print(cmp("1", "two")); # prints -1
|example2 = print(cmp("string", "string")); # prints 0
|example3 = print(cmp("one", "2")); # prints 1
|example4 = print(cmp("string1", "string2")); # prints -1
}}

=== compile() ===
{{Nasal doc
|syntax = compile(code[, filename]);
|source = {{simgear file|simgear/nasal/lib.c|l=220|t=Source}}
|text = Compiles the specified code string and returns a function object bound to the current lexical context. If there is an error, the function dies, with the argument to {{func link|die()}} being '''filename'''.
|param1 = code
|param1text = String containing Nasal code to be compiled.
|param2 = filename
|param2text = Optional string used for error messages/logging. Defaults to <code><compile></code>
|example1 =
var myCode = 'print("hello");';
var helloFunc = compile(myCode, "myCode");
helloFunc();
|example2text = <code>compile</code> is very convenient to support Nasal loaded from other files. For instance, [[PropertyList XML files]] (such as GUI dialogs) may contain embedded Nasal sections that need to be parsed, processed and compiled. For an example of how to do this, save the below XML code as <tt>''[[$FG_ROOT]]/gui/dialogs/test.xml''</tt>.
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<PropertyList>

<nasal><![CDATA[
print("You have FlightGear v", getprop("/sim/version/flightgear"));
]]></nasal>

</PropertyList>
</syntaxhighlight>
Now, start FlightGear and execute this code in the [[Nasal Console]].
|example2 =
# Build the path
var FGRoot = getprop("/sim/fg-root");
var filename = "/gui/dialogs/test.xml";
var path = FGRoot ~ filename;

var blob = io.read_properties(path);
var script = blob.getValues().nasal; # Get the nasal string

# Compile the script. We're passing the filename here for better runtime diagnostics
var code = call(func {
compile(script, filename);
}, nil, nil, var compilation_errors = []);

if(size(compilation_errors)){
die("Error compiling code in: " ~ filename);
}

# Invoke the compiled script, equivalent to code();
# We're using call() here to detect errors:
call(code, [], nil, nil, var runtime_errors = []);

if(size(runtime_errors)){
die("Error calling code compiled loaded from: " ~ filename);
}
}}

=== contains() ===
{{Nasal doc
|syntax = contains(hash, key);
|source = {{simgear file|simgear/nasal/lib.c|l=184|t=Source}}
|text = Returns 1 (True) if the hash contains the specified key, or 0 (False) if not.
|param1 = hash
|param1text = The hash to search in.
|param2 = key
|param2text = The scalar to be searched for, contained as a key in the hash.
|example1 =
# Initialize a hash
var hash = {
element: "value"
};
print(contains(hash, "element") ? "Yes" : "No"); # This will print "Yes"
print(contains(hash, "element2") ? "Yes" : "No"); # This will print "No"
}}

===contains()===
{{Requires commit|desc=Vector support|details=see {{Merge-request|project=fgdata|id=305}}|commit=ee39abbd3b70c9b6d5e3a1c4ccedddaac1a92b11|repo=Simgear}}
{{Nasal doc
|syntax = contains(vector, item);
|source = {{simgear file|simgear/nasal/lib.c|l=184|t=Source}}
|text = Returns 1 (True) if the vector contains the specified item, or 0 (False) if not.
|param1 = vector
|param1text = The vector to search in.
|param2 = item
|param2text = The object to be searched for in the vector.
|example1 =
# Initialize a vector
var vec = ["element", "foo"];
print(contains(vec, "element") ? "Yes" : "No"); # This will print "Yes"
print(contains(vec, "element2") ? "Yes" : "No"); # This will print "No"
}}

===delete() ===
{{Nasal doc
|syntax = delete(hash, key);
|source = {{simgear file|simgear/nasal/lib.c|l=83|t=Source}}
|text = Deletes the key from the hash if it exists. Operationally, this is NOT identical to setting the hash value specified by the key to <code>'''nil'''</code> as the key will stay in the hash (at least for a while). This variant potentially frees storage by deleting the reference to the key and by shrinking the hash. Returns the hash that has been operated on.
|param1 = hash
|param1text = The hash from which to delete the key.
|param2 = key
|param2text = The scalar to be deleted, contained as a key in the hash.
|example1 =
# Initialize the hash
var hash = {
element1: "value1",
element2: "value2"
};
delete(hash, "element1"); # Delete element1
debug.dump(hash); # prints the hash, which is now minus element1
}}

===die()===
{{Nasal doc
|syntax = die(error);
|source = {{simgear file|simgear/nasal/lib.c|l=288|t=Source}}
|text = Terminates execution and unwinds the stack. The place and the line will be added to the '''error'''. This invokes the same internal exception handler used for internal runtime errors. Use this to signal fatal errors, or to implement exception handling. The error thrown (including internal runtime errors) can be caught with {{func link|call()}}.
|param1 = error
|param1text = String describing the error.
:{{inote|This parameter is technically optional, but it is highly recommended to use it.}}
|example1 =
print("Will print");
die("Don't go any further!");
print("Won't print"); # Will not be printed because die() stops the process
}}

=== find()===
{{Nasal doc
|syntax = find(needle, haystack);
|source = {{simgear file|simgear/nasal/lib.c|l=450|t=Source}}
|text = Finds and returns the index of the first occurrence of the string '''needle''' in the string '''haystack''', or -1 if no such occurrence was found.
|param1 = needle
|param1text = String to search for.
|param2 = haystack
|param2text = String to search in.
|example1 = print(find("c", "abcdef")); # prints 2
|example2 = print(find("x", "abcdef")); # prints -1
|example3 = print(find("cd", "abcdef")); # prints 2
}}

===ghosttype()===
{{Nasal doc
|syntax = ghosttype(ghost);
|source = {{simgear file|simgear/nasal/lib.c|l=207|t=Source}}
|text = Returns a string containing either a descriptive name of a ghost (a raw C/C++ object), or a unique id (the pointer to the C/C++ <code>naGhostType</code> instance) if no name has been set. Ghost is an acronym that stands for '''G'''arbage-collected '''H'''andle to '''O'''ut'''S'''ide '''T'''hingy.
|param1 = ghost
|param1text = Ghost to return a description for.
|example1 = print(ghosttype(airportinfo())); # prints "airport"
}}

===id()===
{{Nasal doc
|syntax = id(object);
|source = {{simgear file|simgear/nasal/lib.c|l=570|t=Source}}
|text = Returns a string containing information on the type and ID of the object provided in the single argument. The information is returned in the form of <code>'''<type>''':'''<id>'''</code>, where '''<type>''' is the type of object, and '''<id>''' is the ID.
|param1 = object
|param1text = Can be either of a string, a vector, a hash, a code, a function, or a ghost.
|example1 = print(id("A")); # prints "str:000000001624A590"
}}

===int() ===
{{Nasal doc
|syntax = int(number);
|source = {{simgear file|simgear/nasal/lib.c|l=90|t=Source}}
|text = Returns the integer part of the numeric value of the single argument, or <code>'''nil'''</code> if none exists.
|param1 = number
|param1text = Number or string with just a number in it to return an integer from.
|example1 = print(int(23)); # prints "23"
|example2 = print(int(23.123)); # prints "23"
|example3 = debug.dump(int("string")); # prints "nil"
}}

===keys()===
{{Nasal doc
|syntax = keys(hash);
|source = {{simgear file|simgear/nasal/lib.c|l=33|t=Source}}
|text = Returns a vector containing the list of keys found in the single hash argument.
|param1 = hash
|param1text = The hash to return the keys from.
|example1 =
# Initialize a hash
var hash = {
element1: "value",
element2: "value"
};
debug.dump(keys(hash)); # print the vector
}}

===left()===
{{Nasal doc
|syntax = left(string, length);
|source = {{simgear file|simgear/nasal/lib.c|l=149|t=Source}}
|version = 2.12
|commit = {{simgear commit|bd7163|t=commit}}
|text = Returns a substring of '''string''', starting from the left.
|param1 = string
|param1text = String to return part of.
|param2 = length
|param2text = Integer specifying the length of the substring to return.
|example1 = print(left("string", 2)); # prints "st"
}}

=== num()===
{{Nasal doc
|syntax = num(number);
|source = {{simgear file|simgear/nasal/lib.c|l=102|t=Source}}
|text = Returns the numerical value of the single string argument, or <code>'''nil'''</code> if none exists.
|param1 = number
|param1text = String with just a number in it to return a number from.
|example1 = print(num("23")); # prints "23"
|example2 = print(num("23.123")); # prints "23.123"
|example3 = debug.dump(num("string")); # prints "nil"
}}

===pop()===
{{Nasal doc
|syntax = pop(vector);
|source = {{simgear file|simgear/nasal/lib.c|l=50|t=Source}}
|text = Removes and returns the last element of the single vector argument, or <code>'''nil'''</code> if the vector is empty.
|param1 = vector
|param1text = Vector to remove an element from.
|example1 =
var vector = [1, 2, 3];
pop(vector);
debug.dump(vector); # prints "[1, 2]"
|example2 =
var vector = [1, 2, 3];
debug.dump(pop(vector)); # prints "3"
|example3 =
var vector = [];
debug.dump(pop(vector)); # prints "nil"
}}

===right()===
{{Nasal doc
|syntax = right(string, length);
|source = {{simgear file|simgear/nasal/lib.c|l=161|t=Source}}
|version = 2.12
|commit = {{simgear commit|bd7163|t=commit}}
|text = Returns a substring of '''string''', starting from the right.
|param1 = string
|param1text = String to return part of.
|param2 = length
|param2text = Integer specifying the length of the substring to return.
|example1 = print(right("string", 2)); # prints "ng"
}}

=== setsize()===
{{Nasal doc
|syntax = setsize(vector, size);
|source = {{simgear file|simgear/nasal/lib.c|l=56|t=Source}}
|text = Sets the size of a vector. The first argument specifies a vector, the second a number representing the desired size of that vector. If the vector is currently larger than the specified size, it is truncated. If it is smaller, it is padded with <code>'''nil'''</code> entries. Returns the vector operated upon.
|param1 = vector
|param1text = The vector to be operated on.
|param2 = size
|param2text = The desired size of the vector in number of entries.
|example1 =
var vector = [1, 2, 3]; # Initialize a vector
setsize(vector, 4);
debug.dump(vector); # print the vector
|example2 =
var vector = [1, 2, 3]; # Initialize a vector
setsize(vector, 2);
debug.dump(vector); # print the vector
}}

===size()===
{{Nasal doc
|syntax = size(object);
|source = {{simgear file|simgear/nasal/lib.c|l=23|t=Source}}
|text = Returns the size of the single argument. For strings, this is the length in bytes. For vectors, this is the number of elements. For hashes, it is the number of key/value pairs. If the argument is <code>'''nil'''</code> or a number, this error will be thrown: <code>object has no size()</code>.
|param1 = object
|param1text = Object to find the size of. Must be a string, a vector or a hash.
|example1 =
var string = "string";
print(size(string)); # prints "6"
|example2 =
var vector = [1, 2, 3];
print(size(vector)); # prints "3"
|example3 =
var hash = {
element1: "value1",
element2: "value2",
element3: "value3"
};
print(size(hash)); # prints "3"
}}

=== sort()===
{{Nasal doc
|syntax = sort(vector, function);
|source = {{simgear file|simgear/nasal/lib.c|l=542|t=Source}}
|text = Returns a vector containing the elements in the input '''vector''' sorted in according to the rule given by '''function'''. Implemented with the ANSI C {{func link|qsort()|link=http://www.cplusplus.com/reference/cstdlib/qsort/}}, <code>sort()</code> is stable. This means that if the rules in the first example are used, equal elements in the output vector will appear in the same relative order as they do in the input. It is run in a loop, so '''function''' is run several times.
|param1 = vector
|param1text = Input vector to sort.
|param2 = function
|param2text = Function according to which the elements will be sorted by. It should take two arguments and should return one of 1, 0, or -1.
{{{!}} class="wikitable"
! Return value !! Meaning
{{!-}}
{{!}} less than 0 {{!!}} first argument should go before second argument
{{!-}}
{{!}} 0 {{!!}} first argument equals second argument
{{!-}}
{{!}} greater than 0 {{!!}} first argument should go after second argument
{{!}}}

|example1text = This example sorts elements from smallest to greatest.
|example1 =
var sort_rules = func(a, b){
if(a < b){
return -1; # A should before b in the returned vector
}elsif(a == b){
return 0; # A is equivalent to b
}else{
return 1; # A should after b in the returned vector
}
}
debug.dump(sort([3, 2, 5, 6, 4, 1], sort_rules)); # prints "[1, 2, 3, 4, 5, 6]"
|example2text = This example sorts elements from greatest to smallest.
|example2 =
# Outputs the elements in reverse order (greatest to smallest)
var sort_rules = func(a, b){
if(a < b){
return 1; # -1 in the above example
}elsif(a == b){
return 0;
}else{
return -1; # 1 in the above example
}
}
debug.dump(sort([3, 2, 5, 6, 4, 1], sort_rules)); # prints "[6, 5, 4, 3, 2, 1]"
|example3text = This example sorts a vector of strings (runways for example) from smallest to greatest.
|example3 =
var runways = ["09R","27R","26L","09L","15"];
var rwy = sort(runways,func(a,b) cmp(a,b));
debug.dump(rwy); # prints ['09L','09R','15','26L','27R']
}}

=== split()===
{{Nasal doc
|syntax = split(delimiter, string);
|source = {{simgear file|simgear/nasal/lib.c|l=460|t=Source}}
|text = Splits the input string into a vector of substrings bounded by occurrences of the delimiter substring. See [[Nasal_library/string#string.join(sep,list)|string.join()]].
|param1 = delimiter
|param1text = String that will split the substrings in the returned vector.
|param2 = string
|param2text = String to split up.
|example1 = debug.dump(split("cd", "abcdef")); # prints "['ab', 'ef']"
|example2 = debug.dump(split(".", "3.2.0")); # prints "[3, 2, 0]"
|example3 = debug.dump(split("/", "path/to/file")); # prints "['path', 'to', 'file']"
}}

===sprintf()===
{{Nasal doc
|syntax = <nowiki>sprintf(format[, arg[, arg, [...]]]);</nowiki>
|source = {{simgear file|simgear/nasal/lib.c|l=355|t=Source}}
|text = Creates and returns a string formatted using ANSI C {{func link|vsnprintf()|link=http://en.cppreference.com/w/c/io/vfprintf}} <ref>
{{Cite web
|url = http://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/nasal/lib.c#l308
|title = fgdata/simgear/simgear/nasal/lib.c, line 308
|accessdate = October 2015
}}
</ref>. Below is a table of supported format specifiers.
{{{!}} class="wikitable" width="75%"
{{!}}+ %[flags][width][.precision]specifier
! colspan="2" {{!}} Flags
{{!-}}
! Flag !! Output
{{!-}}
{{!}} <code>+</code> {{!!}} Forces to precede the result with a plus or minus sign ('''+''' or '''-''') even for positive numbers. By default, only negative numbers are preceded with a '''-''' sign.
{{!-}}
{{!}} ''space'' {{!!}} Prefixes non-signed numbers with a space.
{{!-}}
{{!}} <code>-</code> {{!!}} Left-align the output of this placeholder (the default is to right-align the output) when the width option is specified.
{{!-}}
{{!}} <code>0</code> {{!!}} Use 0 instead of spaces to pad a field when the width option is specified.
{{!-}}
{{!}} <code>#</code> {{!!}} Used with <code>o</code>, <code>x</code> or <code>X</code> specifiers the value is preceded with <tt>0</tt>, <tt>0x</tt> or <tt>0X</tt> respectively for values different than zero. Used with <code>e</code>, <code>E</code> and <code>f</code>, it forces the written output to contain a decimal point even if no digits would follow. By default, if no digits follow, no decimal point is written. Used with <code>g</code> or <code>G</code> the result is the same as with <code>e</code> or <code>E</code> but trailing zeros are not removed.
{{!-}}
! colspan="2" {{!}} Width
{{!-}}
{{!}} colspan="2" {{!}} Integer specifying the minimum number of characters to be returned. This includes the decimal point and decimal fraction as well as + or - signs.
{{!-}}
! colspan="2" {{!}} Precision
{{!-}}
{{!}} colspan="2" {{!}} Integer preceded by a dot specifying the number of decimal places to be written.
{{!-}}
! colspan="2" {{!}} Specifiers
{{!-}}
! Specifier !! Output
{{!-}}
{{!}} <code>d</code>, <code>i</code> {{!!}} Signed decimal number.
{{!-}}
{{!}} <code>s</code> {{!!}} A string
{{!-}}
{{!}} <code>%</code> {{!!}} Percent (%) character.
{{!-}}
{{!}} <code>c</code> {{!!}} A single character assigned to a character code, the code given in an integer argument. See http://www.asciitable.com/ for a list of supported characters and their codes.
{{!-}}
{{!}} <code>o</code> {{!!}} Unsigned integer as an octal number.
{{!-}}
{{!}} <code>u</code> {{!!}} Unsigned decimal integer.
{{!-}}
{{!}} <code>x</code>, <code>X</code> {{!!}} Unsigned integer as a hexadecimal number. If <code>x</code> is used, any letters in the number are lowercase, while <code>X</code> gives uppercase.
{{!-}}
{{!}} <code>e</code>, <code>E</code> {{!!}} Double value in scientific notation (i.e., ''[-]ddd.ddd'''e'''[+/-]ddd''), with an exponent being denoted by <tt>e</tt> or <tt>E</tt> depending on whether an upper or lowercase is used respectively.
{{!-}}
{{!}} <code>f</code> {{!!}} Floating-point number, in fixed decimal notation, by default with 6 decimal places.
{{!-}}
{{!}} <code>F</code> {{!!}} Appears to be available<ref>
{{Cite web
|url = http://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/nasal/lib.c#l389
|title = fgdata/simgear/simgear/nasal/lib.c, line 389
|accessdate = October 2015
}}
</ref>, but doesn't work.
{{!-}}
{{!}} <code>g</code>, <code>G</code> {{!!}} Double in either normal or exponential notation, whichever is more appropriate for its magnitude. <code>g</code> uses lower-case letters, <code>G</code> uses upper-case letters. This type differs slightly from fixed-point notation in that insignificant zeroes to the right of the decimal point are not included. Also, the decimal point is not included on whole numbers.
{{!}}}

|param1 = format
|param1text = String specifying the format. Can be used with or without a format specifiers. See below for examples.
|param2 = arg
|param2text = Argument specifying a value to replace a format placeholder (such as <code>%d</code>) in the format string. Not required if there are no format specifiers.

|example1 = print(sprintf("%i", 54)); # prints "54"
|example2 = print(sprintf("Pi = %+.10f", math.pi)); # prints "Pi = +3.1415926536"
|example3 =
print(sprintf("%6d", 23)); # prints " 23"
print(sprintf("%06d", 23)); # prints "000023"
|example4 =
var FGVer = getprop("/sim/version/flightgear");
print(sprintf("You have FlightGear v%s", FGVer)); # prints "You have FlightGear v<your version>"
|example5 =
print(sprintf("Hexadecimal 100000 = %X", 100000)); # prints "Hexadecimal 100000 = 186A0"
print(sprintf("Hexadecimal 100000 = %x", 100000)); # prints "Hexadecimal 100000 = 186a0"
|example6 = print(sprintf("Code 65 is %c", 65)); # prints "Code 65 is A"
|example7 =
print(sprintf("%e", 54)); # prints "5.400000e+001"
print(sprintf("%E", 54)); # prints "5.400000E+001"
|example8 = print(sprintf("%o", 54)); # prints "66"
|example9 = print(sprintf("50%% of 100 is %i", 100 / 2)); # prints "50% of 100 is 50"
|example10 =
print(sprintf("%.2f", 1.4)); #prints "1.40"
print(sprintf("%.1f", 1.4)); #prints "1.4"
print(sprintf("% 4.1f", 1.4)); #prints " 1.4"
print(sprintf("%04.1f", 1.4)); #prints "01.4"
print(sprintf("% 6.1f", 1.4)); #prints " 1.4"
print(sprintf("%06.1f", 1.4)); #prints "0001.4"
}}

===streq()===
{{Nasal doc
|syntax = streq(a, b);
|source = {{simgear file|simgear/nasal/lib.c|l=129|t=Source}}
|text = Tests the string values of the two arguments for equality. This function is needed because the <code>'''=='''</code> operator (see [[Nasal_Operators#Equality|Nasal Operators]]) tests for numeric equality first. If either or both the arguments are not strings, 0 (False) will be returned. Returns either 0 (False) or 1 (True). {{Note|This function is rarely required in typical code.}}
|param1 = a
|param1text = First argument for testing equality.
|param2 = b
|param2text = Second argument for testing equality.
|example1 = print(streq("0", "0")); # prints "1" (True)
|example2 =
print(0 == 0.0); # prints "1" (True)
print(streq("0", "0.0")); # prints "0" (False)
}}

===substr()===
{{Nasal doc
|syntax = substr(string, start [, length]);
|source = {{simgear file|simgear/nasal/lib.c|l=129|t=Source}}
|text = Similar the {{func link|subvec()}}, but operates on strings. Computes and returns a substring. The first argument specifies a string, the second is the index of the start of a substring, the optional third argument specifies a length (the default is to return the rest of the string from the start).
|param1 = string
|param1text = String to return a substring from.
|param2 = start
|param2text = Integer specifying the start of a substring. Negative values specify a position from the end of the string.
|param3 = length
|param3text = Optional argument specifying the length of the substring. Defaults to the end of the string.
|example1 = print(substr("abcde", 1, 3)); # prints "bcd"
|example2 = print(substr("abcde", 1)); # prints "bcde"
|example3 = print(substr("abcde", 2, 1)); # prints "c"
|example4 = print(substr("abcde", -2)); # prints "de"
|example5 = print(substr("abcde", -3, 2)); # prints "cd"
}}

===subvec()===
{{Nasal doc
|syntax = subvec(vector, start[, length]);
|source = {{simgear file|simgear/nasal/lib.c|l=63|t=Source}}
|text = Returns a sub-range of a vector. The first argument specifies a vector, the second a starting index, and the optional third argument indicates a length (the default is to the end of the vector).
|param1 = vector
|param1text = The vector to take the sub-vector from.
|param2 = start
|param2text = The starting point of the sub-vector within the given vector.
|param3 = length
|param3text = Optional argument specifying the length of the sub-vector, from the starting point.
'''Notes:'''
* Omitting the ''vector'' and ''start'' arguments is not an error (possibly it should be) but the return value is ''nil''.
* A negative ''start'' argument ''is'' an error. This seems wrong. Perhaps the language designer could comment.
* A value of ''start'' greater than ''size(vector)'' causes an error. A value equal to ''size(vector)'' returns an empty vector.
* If the value of ''length'' is greater than ''size(vector) - start'' then it is ignored. That is, all elements from ''start'' to the end of ''vector'' are returned. If ''length'' is zero then an empty vector is returned. A negative value of ''length'' causes an error.
|example1 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 0)); # prints "[1, 2, 3]"
|example2 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 1)); # prints "[2, 3]"
|example3 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 1, 1)); # prints "[2]"
}}

=== typeof()===
{{Nasal doc
|syntax = typeof(object);
|source = {{simgear file|simgear/nasal/lib.c|l=193|t=Source}}
|text = Returns a string indicating the whether the object is <code>'''nil'''</code>, a scalar (number or string), a vector, a hash, a function, or a ghost.
|param1 = object
|param1text = Object to return the type of.
|example1 =
var object = nil;
print(typeof(object)); # prints "nil"
|example2 =
var object = "Hello world!";
print(typeof(object)); # prints "scalar"
|example3 =
var object = math.pi;
print(typeof(object)); # prints "scalar"
|example4 =
var object = [1, 2, 3];
print(typeof(object)); # prints "vector"
|example5 =
var object = {};
print(typeof(object)); # prints "hash"
|example6 =
var object = func {};
print(typeof(object)); # prints "func"
|example7 =
var object = airportinfo();
print(typeof(object)); # prints "ghost"
}}



==Extension functions==
The '''extension functions''' are global functions that have been added to Nasal since its integration into FlightGear. Unlike the core library functions, they are generally specifically designed to interact directly with FlightGear. Extension functions come from three source files:
*{{flightgear file|src/Scripting/NasalPositioned.cxx}}
*{{flightgear file|src/Scripting/NasalSys.cxx}}
*{{fgdata file|Nasal/globals.nas}}

===abort()===
{{Nasal doc
|syntax = abort();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=565|t=Source}}
|text = This function is a wrapper for the C++ {{func link|abort()|link=http://www.cplusplus.com/reference/cstdlib/abort/}} function. It simply aborts FlightGear with an error, which varies depending on the operating system. This function should not really be used; instead, please use the "exit" [[Fgcommands|fgcommand]], which will exit FlightGear more gracefully (see example below).
|example1text = This example will immediately stop FlightGear with an error, such as "FlightGear has stopped working."
|example1 = abort();
|example2text = For exiting FlightGear in a better way, please use the following code:
|example2 = fgcommand("exit");
}}

=== abs() ===
{{Nasal doc
|syntax = abs(number);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = This simple function returns the {{wikipedia|absolute value|noicon=1}} of the provided number.
|param1 = number
|param1text = This argument is required and should be a number.
|example1 = print(abs(1)); # prints "1"
|example2 = print(abs(-1)); # prints "1"
}}

===aircraftToCart() ===
This new function in FG 2017.2.1 takes coordinates in aircraft structural coordinate system, and translate them into geocentric coordinates.
Example for (5,6,7):
<syntaxhighlight lang="nasal">
var pos = aircraftToCart({x: -5, y: 6, z: -7});
var coord = geo.Coord.new();
coord.set_xyz(pos.x, pos.y, pos.z);
</syntaxhighlight>
Notice: x and z is inverted sign on purpose.
if you want lat. lon, alt from that, just call: (degrees and meters)

<syntaxhighlight lang="nasal">
coord.lat()
coord.lon()
coord.alt()
</syntaxhighlight>

===addcommand() ===
{{Nasal doc
|syntax = addcommand(name, code);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=659|t=Source}}
|version = 2.12
|commit = {{flightgear commit|7b663c|t=commit}}
|text = {{see also|Howto:Add new fgcommands to FlightGear}}

This function enables the addition of a new custom [[fgcommands|fgcommand]] to FlightGear from within Nasal. An fgcommand created using this method can be used in exactly the same way as the built-in fgcommands. Also, an fgcommand created via this method will always return True or 1, like all other fgcommands.
|param1 = name
|param1text = This will become the name of the new fgcommand. Must be a string.
|param2 = code
|param2text = The code that will be executed when the fgcommand is run. Must be a function.
|example1text = This example adds a new fgcommand and then runs it. Although it executes a simple {{func link|print()}} statement, any valid Nasal code can be used.
|example1 = addcommand("myFGCmd", func(node) {
print("fgcommand 'myFGCmd' has been run.");
props.dump( node );
});
fgcommand("myFGCmd", props.Node.new({foo:1, bar:2}) );
|example2text = This example demonstrates how parameters are defined in a new fgcommand.
|example2 = addcommand("myFGCmd", func(node){
print(node.getNode("number").getValue()); # prints the value of "number," which is 12
});
fgcommand("myFGCmd", props.Node.new({"number": 12}));
}}

===airportinfo()===
{{Nasal doc
|syntax = airportinfo();
airportinfo(type);
airportinfo(id);
airportinfo(lat, lon[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1024|t=Source}}
|text = Function for retrieval of airport, heliport, or seaplane base information. It returns a Nasal ghost; however, its structure is like that of a Nasal hash. The following information is returned:
* '''parents''': A vector containing a hash of various functions to access information about the runway. See {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2659}} for full list.
* '''lon''': Longitude of the location.
* '''lat''': Latitude of the location.
* '''has_metar''': True or false depending whether the airport has a [[METAR]] code defined for it.
* '''elevation''': Elevation of the location in metres.
* '''id''': ICAO code of the airport (or ID of the seaplane base/heliport).
* '''name''': Name of the airport/heliport/seaplane base.
* '''runways'''
** '''<runway name>'''
*** '''id''': Name of runway.
*** '''lat''': Latitude of the runway.
*** '''lon''': Longitude of the runway.
*** '''heading''': Heading of the runway.
*** '''length''': Length of the runway in metres.
*** '''width''': Width of the runway in metres.
*** '''surface''': Runway surface type.
*** '''threshold''': Length of the runway's {{wikipedia|displaced threshold}} in metres. Will return 0 if there is none.
*** '''stopway''': Length of the runway's stopway (the area before the threshold) in metres. Will return 0 if there is none.
*** '''reciprocal''': <code>runway</code> ghost of the reciprocal runway.
*** '''ils_frequency_mhz''': ILS frequency in megahertz.
*** '''ils''': <code>navaid</code> ghost of the ILS transmitter.
* '''helipads'''
** '''<helipad name>'''
*** '''id''': Name of helipad.
*** '''lat''': Latitude of the helipad.
*** '''lon''': Longitude of the helipad.
*** '''heading''': Heading of the helipad.
*** '''length''': Length of the helipad in metres.
*** '''width''': Width of the helipad in metres.
*** '''surface''': Helipad surface type.
* '''taxiways'''
** '''<taxiway name>'''
*** '''id''': Name of taxiway.
*** '''lat''': Latitude of the taxiway.
*** '''lon''': Longitude of the taxiway.
*** '''heading''': Heading of the taxiway.
*** '''length''': Length of the taxiway in metres.
*** '''width''': Width of the taxiway in metres.
*** '''surface''': Taxiway surface type.

Information is extracted in the same way as accessing members of a Nasal hash. For example:
<syntaxhighlight lang="nasal">
# prints to lengths of the runways of the nearest airport in feet and metres
var info = airportinfo();
print("-- Lengths of the runways at ", info.name, " (", info.id, ") --");
foreach(var rwy; keys(info.runways)){
print(rwy, ": ", math.round(info.runways[rwy].length * M2FT), " ft (", info.runways[rwy].length, " m)");
}
</syntaxhighlight>

Note that searches for locations that are a long way away (e.g., the nearest seaplane base to the middle of the Sahara) may cause FlightGear to pause for an amount of time.
|param1 = id
|param1text = The {{wikipedia|International Civil Aviation Organization airport code|ICAO code|noicon=1}} of an airport to retrieve information about.
|param2 = type
|param2text = When this argument is used, the function will return the closest airport of a certain type. Can be one of "heliport," "seaport," or "airport" (default).
: {{inote|Running this function without any parameters is equivalent to this:
: <syntaxhighlight lang="nasal">
airportinfo("airport");
</syntaxhighlight>
}}
|param3 = lat ''and'' lon
|param3text = When these parameters are used, the function will return information on the nearest airport, heliport or seaplane base (depending on the '''type''' parameter) to those coordinates.
|example1 = var info = airportinfo();
print("Nearest airport: ", info.name, " (", info.id, ")"); # prints the name and ICAO code of the nearest airport
|example2 = var info = airportinfo("heliport");
print("Elevation of the nearest heliport: ", math.round(info.elevation * M2FT), " ft"); # prints the elevation and name of the nearest heliport
|example3 = var info = airportinfo("KSQL");
print("-- Runways of ", info.name, " (", info.id, "): --");
foreach(var rwy; keys(info.runways)) {
print(rwy); # prints the runways of KSQL
}
|example4 = var info = airportinfo(37.81909385, -122.4722484);
print("Coordinates of the nearest airport: ", info.lat, ", ", info.lon); # print the name and ICAO of the nearest airport to the Golden Gate Bridge
|example5 = var info = airportinfo(37.81909385, -122.4722484, "seaport");
print("Nearest seaplane base: ", info.name, " (", info.id, ")"); # print the name and ID of the nearest seaplane base to the Golden Gate Bridge
|example6text = This example prints the all information from an <code>airportinfo()</code> call.
|example6 = var info = airportinfo("KSFO");
print(info.name);
print(info.id);
print(info.lat);
print(info.lon);
print(info.has_metar);
print(info.elevation);
foreach(var rwy; keys(info.runways)){
print("-- ", rwy, " --");
print(info.runways[rwy].lat);
print(info.runways[rwy].lon);
print(info.runways[rwy].length);
print(info.runways[rwy].width);
print(info.runways[rwy].heading);
print(info.runways[rwy].stopway);
print(info.runways[rwy].threshold);
<nowiki>}</nowiki>
}}

===airwaysRoute() ===
{{Nasal doc
|syntax = airwaysRoute(start, end[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1933|t=Source}}
|text = {{see also|Nasal Flightplan}}
This function returns a vector containing waypoints between two given waypoints. The returned waypoints are ghosts, but can be accessed in the same way as a Nasal hash. See [[Nasal Flightplan]] for more information.
|param1 = start
|param1text = Start waypoint, in the form of a waypoint ghost, such as that provided by {{func link|flightplan()}}.
|param2 = end
|param2text = Same as above.
|param3 = type
|param3text = Instructs the function to compute a high level route (when set to "highlevel"), or a low level route (when set to "lowlevel"). Defaults to "highlevel."
|example1text = In the [[route manager]] dialog, add two waypoints to the flightplan, ideally ones that are far apart (tip: use the [[Map]] for this). Then run this code in your Nasal Console.
|example1 = var fp = flightplan();
var start = fp.getWP(0);
var end = fp.getWP(fp.getPlanSize() - 1);
var rt = airwaysRoute(start, end);
foreach(var wp; rt){
print(wp.wp_name); # print the waypoints in the computed route
}
|example2text = Exactly the same as above, but computes a low level path.
|example2 = var fp = flightplan();
var start = fp.getWP(0);
var end = fp.getWP(fp.getPlanSize() - 1);
var rt = airwaysRoute(start, end, "lowlevel");
foreach(var wp; rt){
print(wp.wp_name); # print the waypoints in the computed route
<nowiki>}</nowiki>
}}

===airway()===

{{Nasal doc
|syntax = airway(ident [, pos]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2644|t=Source}}
|text = {{see also|Nasal Flightplan}}
This function returns a ghost containing an airway of a specified id.
|param1 = ident
|param1text = a Positioned ghost (leg, navaid, airport) and so on, passed to the search function.
|param2 = pos
}}

===assert()===
{{Nasal doc
|syntax = assert(condition[, message]);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|version = 3.2
|commit = {{fgdata commit|8b16a7|t=commit}}
|text = Returns either true if the condition evaluates as true, or aborts with a {{func link|die()}} call, which can be customised.
|param1 = condition
|param1text = Condition to evaluate.
|param2 = message
|param2text = Optional message that will be used in any {{func link|die()}} call. Defaults to "assertion failed!"
|example1 = var a = 1;
var b = 2;
print(assert(a < b)); # prints "1" (true)
|example2 = var a = 1;
var b = 2;
assert(a > b, 'a is not greater than b'); # aborts with a custom error message
}}

===carttogeod()===
{{Nasal doc
|syntax = carttogeod(x, y, z);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=945|t=Source}}
|text = Converts {{wikipedia|ECEF|Earth-centered, Earth-fixed}} coordinates (x, y and z) to {{wikipedia|geodetic coordinates}} (latitude, longitude, and altitude). A vector is returned containing latitude and longitude, both in degrees, and altitude, which is returned in metres above the equatorial radius of Earth as defined by the {{wikipedia|WGS 84}} (6,378,137 metres).<ref>{{simgear file|simgear/math/sg_geodesy.hxx|l=43}}</ref>
|param1 = x
|param1text = Mandatory x-axis value, in metres.
|param2 = y
|param2text = Mandatory y-axis value, in metres.
|param3 = z
|param3text = Mandatory z-axis value, in metres.
|example1 = var (lat, lon, alt) = carttogeod(6378137, 0, 0); # point is the intersection of the prime meridian and equator.
print("Latitude: ", lat); # prints lat, lon and alt, which are all zero, see above
print("Longitude: ", lon);
print("Altitude: ", alt);
}}

===cmdarg()===
{{Nasal doc
|private = _cmdarg()
|syntax = cmdarg();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=513|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|text = <code>cmdarg()</code> returns the property root of certain types of XML files. These could be nodes in the [[Property Tree]], or temporary and/or non-public nodes outside the Property tree.
It is used by Nasal scripts embedded in XML files. It returns a <code>props.Node</code> object (see {{fgdata file|Nasal/props.nas}}), and you can use all of its methods on the returned value. <code>cmdarg()</code> should only be used in four types/places of XML files:
* Bindings: This is needed so that the value of a joystick's axis can be accessed internally.
* Dialogs: This will return the root of the dialog in the Property Tree. This is useful for dialogs that are created/modified procedurally (e.g. for populating/changing widgets while loading the dialog).
* Embedded Canvases: The Nasal code behind [[Canvas]] windows [[Howto:Adding a canvas to a GUI dialog|embedded in PUI dialogs]] can use it to accessing the root directory of their Canvas.
* Animation XML files: If the animation XML file is used in an AI/MP model, <code>cmdarg()</code> will return the root of the AI model in the <code>/ai/models/</code> directory. Examples: <code>/ai/models/aircraft[3]/</code>, <code>/ai/models/multiplayer[1]/</code>

You should not use <code>cmdarg()</code> in places other than those stated above. Although it won't cause an error, it will return the value of the last legitimate <code>cmdarg()</code> call.

Also, you should not delay <code>cmdarg()</code> using {{func link|maketimer()}}, {{func link|settimer()}} or {{func link|setlistener()}}, because it will return an unrelated property.
|example1 = fgcommand("dialog-show", {"dialog-name": "cmdarg-demo"});
|example1text = <br>This example demonstrates the usage of <code>cmdarg()</code> in a binding. Save the below XML snippet as <tt>[[$FG_ROOT]]/gui/dialogs/cmdarg-demo.xml</tt>. Then run the Nasal snippet below in your [[Nasal Console]]. Upon clicking {{button|Close}}, a message will be printed sowing the root of the binding in the Property Tree.
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>cmdarg-demo</name>
<layout>vbox</layout>

<text>
<label>Click "Close" to activate the demonstration (a message in the console).</label>
</text>

<button>
<legend>Close</legend>
<binding>
<command>nasal</command>
<script>print("Button binding root: '" ~ cmdarg().getPath() ~ "'");</script>
</binding>
<binding>
<command>dialog-close</command>
</binding>
</button>

</PropertyList>
</syntaxhighlight>
|example2text = This example demonstrates the usage of <code>cmdarg()</code> in Nasal code within dialogs. Open <tt>[[$FG_ROOT]]/gui/dialogs/cmdarg-demo.xml</tt> from the previous example, copy & paste the code below, and save it. Then run the same Nasal snippet as the previous example in your Nasal Console. If you click {{button|Click me!}}, the button's label will change to "I've been changed!"
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>cmdarg-demo</name>
<layout>vbox</layout>

<text>
<label>Click "Click me!" to activate the demonstration (the button's label will change).</label>
</text>

<button>
<legend>Click me!</legend>
<binding>
<command>nasal</command>
<script>change_label();</script>
</binding>
</button>

<button>
<legend>Close</legend>
<binding>
<command>dialog-close</command>
</binding>
</button>

<nasal>
<open><![CDATA[
var dlg_root = cmdarg();
var dlg_name = {"dialog-name": "cmdarg-demo"};
var change_label = func {
dlg_root.getNode("button[0]/legend").setValue("I've been changed!");
fgcommand("dialog-close", dlg_name);
fgcommand("dialog-show", dlg_name);
}
]]></open>
</nasal>

</PropertyList>
</syntaxhighlight>
|example3text = For an example of <code>cmdarg()</code> used with Canvas, please see [[Howto:Adding a canvas to a GUI dialog#FGPlot|Howto:Adding a canvas to a GUI dialog]].
}}

===courseAndDistance()===
{{Nasal doc
|syntax = courseAndDistance(to);
courseAndDistance(from, to);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1668|t=Source}}
|text = Returns a vector containing the course from one point to another and the distance between them in nautical miles. The course is the initial bearing (see [http://www.movable-type.co.uk/scripts/latlong.html#bearing here]), and is in the range 0–360. Both arguments can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object with geodetic coordinates (cartesian coordinates will not be accepted)
|param1 = from
|param1text = Optional parameter defining the from where the function should calculate its results. If the function is given one argument ('''to'''), the aircraft's current position will be used. As well as the argument types as defined above, this argument can be two numbers separated with a comma, as if the function is taking three arguments. See example 5 below.
|param2 = to
|param2text = Like the first parameter, but defines the second point.
|example1text = This example demonstrates the usage of the function with the <code>airport</code> ghost type.
|example1 = var from = airportinfo("KSFO");
var to = airportinfo("KSQL");
var (course, dist) = courseAndDistance(from, to);
print(course); # prints course from KSFO to KSQL
print(dist); # prints distance in nm from KSFO to KSQL
|example2text = This example demonstrates the usage of the function with hashes containing ''lat'' and ''lon''.
|example2 = var from = {lat: 0, lon: 0};
var to = {lat: 1, lon: 1};
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example3text = This example demonstrates usage of a geo.Coord object.
|example3 = var from = geo.Coord.new().set_latlon(0, 0);
var to = geo.Coord.new().set_latlon(1, 1);
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example4text = This example demonstrates usage of differing parameter types.
|example4 = var from = airportinfo("KSFO");
var to = geo.Coord.new().set_latlon(0, 0);
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example5text = The same as above, but the other way round.
|example5 = var to = {lat: 1, lon: 1};
var (course, dist) = courseAndDistance(0, 0, to);
print(course);
print(dist);
|example6text = Usage of just one parameter.
|example6 = var dest = airportinfo("KSQL");
var (course, dist) = courseAndDistance(dest);
print("Turn to heading ", math.round(course), ". You have ", sprintf("%.2f", dist), " nm to go");
}}

===createFlightplan()===
{{Nasal doc
|syntax = createFlightplan(path);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2331|t=Source}}
|text = Creates an empty flightplan object. It accepts one argument, ''path'' passed an absolute path to a .fgfp / .gpx file, it will populate the flightplan with waypoints from the file.
|param1 = path
|param1text = Optional parameter defining the file from which a flightplan will be populated.
|example1 =
var path = getprop("/sim/fg-home") ~ "/Export/test.fgfp";
var flightplan = createFlightplan(path);
debug.dump(flightplan);
}}

===createDiscontinuity()===
{{Nasal doc
|syntax = createDiscontinuity();
|text = Returns a <code>waypoint</code> ghost object. A route discontinuity is inserted by an {{abbr|FMS|Flight Management System}} when it is unsure how to connect two waypoints.
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2045|t=Source}}
|version = 2016.1
|commit = {{flightgear commit|caead6|t=commit}}
}}
===createViaTo()===
{{Nasal doc
|syntax = createViaTo(airway, waypoint);
|text = Returns a <code>waypoint</code> ghost object. It represents a route "via '''airway''' to '''waypoint'''".
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2009|t=Source}}
|version = 2016.1
|commit = {{flightgear commit|caead6|t=commit}}
|param1 = airway
|param1text = The name of an airway.
|param2 = waypoint
|param2text = Must be in the airway and one of:
* The name of a waypoint.
* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, or <code>fix</code> ghost object.
}}
===createWP()===
{{Nasal doc
|syntax = createWP(pos, name[, flag]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1964|t=Source}}
|text = Creates a new waypoint ghost object.
|param1 = pos
|param1text = Dictates the position of the new waypoint. It can be one of the following:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. See example 4 below.
|param2 = name
|param2text = String that will become the name of the new waypoint.
|param3 = flag
|param3text = Optional string that will tell FlightGear what type of waypoint it is. Must be one of "sid," "star," "approach," "missed," or "pseudo."
|example1text = Creates a waypoint directly in front and 1 km away and appends it to the flight plan.
|example1 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example2 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP({lat: pos.lat(), lon: pos.lon()}, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example3 = var apt = airportinfo();
var wp = createWP(apt, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example4 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos.lat(), pos.lon(), "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example5text = Creates a new waypoint and adds it to the flight plan. Waypoints of the type "pseudo" are then removed from the flight plan, including the new waypoint. The {{func link|print()}} statements show this.
|example5 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos, "NEWWP", "pseudo");
var fp = flightplan();
fp.appendWP(wp);
print(fp.getPlanSize());
fp.clearWPType("pseudo");
print(fp.getPlanSize());
}}

===createWPFrom()===
{{Nasal doc
|syntax = createWPFrom(object[, flag]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1989|t=Source}}
|text = Creates a new waypoint object from another object.
|param1 = object
|param1text = A ghost object. Must be a ghost type that is one of "airport," "navaid," "runway," or "fix."
|param2 = flag
|param2text = Optional string that will tell FlightGear what type of waypoint it is. Must be one of "sid," "star," "approach," "missed," or "pseudo."
|example1text = Creates a new waypoint and appends it to the flight plan.
|example1 = var apt = airportinfo("KSFO");
var wp = createWPFrom(apt);
var fp = flightplan();
fp.appendWP(wp);
|example2text = Creates a new waypoint and appends it to the flight plan. This way point is then removed; the {{func link|print()}} statements prove this.
|example2 = var apt = airportinfo("KSFO");
var wp = createWPFrom(apt, "pseudo");
print(wp.wp_name);
var fp = flightplan();
fp.appendWP(wp);
print(fp.getPlanSize());
fp.clearWPType("pseudo");
print(fp.getPlanSize());
}}

===defined()===
{{Nasal doc
|syntax = defined(symbol);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns 1 (true) or 0 (false) depending on whether a variable exists.
|param1 = symbol
|param1text = A string that will be what the function searches for.
|example1 = var number = 12;
var check_exist = func {
print("Variable 'number' ", defined("number") == 1 ? "exists" : "does not exist"); # 'number' does exist
print("Variable 'number2' ", defined("number2") == 1 ? "exists" : "does not exist"); # 'number2' does not exist
}
check_exist();
}}

===directory()===
{{Nasal doc
|syntax = directory(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=572|t=Source}}
|text = Returns a vector containing a list of the folders and files in a given file path or <code>'''nil'''</code> if the path doesn't exist. Hidden folders and files are not added to the vector.
{{inote|The first two elements of the vector will be <code>'.'</code> and <code>'..'</code>. These are for navigating back up the file tree, but have no use in Nasal. They can be safely removed from the vector.}}
|param1 = path
|param1text = Absolute file path.
|example1text = Gets the folders and files in [[$FG_ROOT]], and then removes the extra first two elements (see note above).
|example1 = var dir = directory(getprop("/sim/fg-root")); # get directory
dir = subvec(dir, 2); # strips off the first two elements
debug.dump(dir); # dump the vector
}}

===fgcommand()===
{{Nasal doc
|syntax = fgcommand(cmd[, args]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=456|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|text = Runs an fgcommand. See also {{readme file|commands}} and [[Bindings]] for more information. See {{flightgear file|src/Main/fg_commands.cxx|l=1425}} for the full list of fgcommands. Note that fgcommands generated by {{func link|addcommand()}} can also be run using this function. Also, the full list of fgcommands depends on the version of FlightGear you have. Returns 1 (true) if the fgcommand succeeded or 0 (false) if it failed.
|param1 = cmd
|param1text = String that is the name of the command that is to be run.
|param2 = args
|param2text = If the fgcommand takes arguments, they are inputted using this argument. Can either be a <code>props.Node</code> object, or a hash (see examples below).
|example1 = fgcommand("null"); # does nothing
|example2 = var args = props.Node.new({'script': 'print("Running fgcommand");'});
if (fgcommand("nasal", args)) { # prints "Running fgcommand" and then one of these print statements
print("Fgcommand succeeded");
} else {
print("Fgcommand encountered a problem");
}
|example3 = var args = { 'dialog-name': 'about' };
fgcommand("dialog-show", args); # shows the 'about' dialog
}}

===findAirportsByICAO() ===
{{Nasal doc
|syntax = findAirportsByICAO(search[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1096|t=Source}}
|text = Returns a vector containing <code>airport</code> ghost objects which are (by default) airports whose ICAO code matches the search string. The results are sorted by range from closest to furthest.
|param1 = search
|param1text = Search string for the function. Can either be a partial or a full ICAO code.
:{{icaution|The more matches there are for the given code, the longer the function will take. Passing just one character (e.g., "K"), might make FlightGear hang for a certain amount of time.}}
|param2 = type
|param2text = This will narrow the search to airports of a certain type. By default, only airports are searched for. May be one of "airport," "heliport," or "seaport."
|example1 = var apts = findAirportsByICAO("KSF"); # finds all airports matching "KSF"
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")"); # prints them
}
|example2 = var apts = findAirportsByICAO("SP0", "seaport"); # finds all seaplane bases matching "SP0"
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")"); # prints them
}
|example3 = var apt = findAirportsByICAO("XBET"); # one way to check if an airport does exist"
if (size(apt) == 0) {
print("Airport does not exist"); # this one will be printed
} else {
print("Airport does exist");
<nowiki>}</nowiki>
}}

===findAirportsWithinRange()===
{{Nasal doc
|syntax = findAirportsWithinRange([pos, ]range[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1066|t=Source}}
|text = Returns a vector of <code>airport</code> ghost object which are (by default) airports that are within a given range of a given position, or the aircraft's current position. The results are sorted by range from closest to furthest.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findAirportsWithinRange(lat, lon, range, type);</code>.
|param2 = range
|param2text = Mandatory number giving the range in nautical miles within which to search for airports/heliports/seaplane bases.only airports are searched for.
|param3 = type
|param3text = This will narrow the search to airports of a certain type. By default, only airports are searched for. May be one of "airport," "heliport," or "seaport."
|example1text = Searches for airports within 10 nm of [[KSFO]].
|example1 = var pos = airportinfo("KSFO");
var apts = findAirportsWithinRange(pos, 10);
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
}
|example2text = Searches for seaplane bases within 15 nm of [[KSFO]].
|example2 = var pos = airportinfo("KSFO");
var apts = findAirportsWithinRange(pos, 15, "seaport");
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
}
|example3text = Searches for airports within 10 nm of your current position.
|example3 = var apts = findAirportsWithinRange(10);
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
<nowiki>}</nowiki>
}}

===findCommByFrequencyMHz()===
findCommByFrequencyMHz([pos, ]freq[, type]);
[[sourceforge:p/flightgear/flightgear/ci/next/tree/src/Scripting/NasalPositioned.cxx#l1547|source]]

Returns a <code>comm</code> ghost object for a station matching a given frequency. If there is more than one station with that frequency, the nearest station is returned.

'''pos'''

: Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findCommByFrequencyMHz(lat, lon, freq, type);</code>.
; freq
: Frequency, in megahertz, of the station to search for.
; type
: This will narrow the search to station of a certain type. Defaults to "all." For the full list of accepted type arguments, see flightgear/src/Navaids/positioned.cxx (line 160)
'''Example'''
var com = findCommByFrequencyMHz(123.6);
print("ID: ", com.id); # prints info about the comm station
print("Name: ", com.name);
print("Latitude: ", com.lat);
print("Longitude: ", com.lon);
print("Type: ", com.type);
print("Frequency: ", sprintf("%.3f", com.frequency), " Mhz");

=== findFixesByID() ===
{{Nasal doc
|syntax = findFixesByID([pos, ]id);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1627|t=Source}}
|text = Returns a vector containing <code>fix</code> ghost objects matching a given ID, sorted by range from a certain position.
{{inote|Fixes are (usually) also known as waypoints.}}
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findFixesByID(lat, lon, id);</code>.
|param2 = id
|param2text = Full or partial ID of the fix to search for.
:{{inote|1=Inputting a partial ID does not work correctly (see [http://forum.flightgear.org/viewtopic.php?f=30&t=28129 here]). It is best to just input a full ID.}}
|example1 = var fixes = findFixesByID("POGIC");
foreach(var fix; fixes){
print(fix.id, " - lat: ", fix.lat, " {{!}} lon: ", fix.lon); # prints information about POGIC
}
|example2 = var fix = findFixesByID("ZUNAP");
fix = fix[0];
var (course, dist) = courseAndDistance(fix);
print("Turn to heading ", math.round(course), ". You have ", sprintf("%.2f", dist), " nm to go to reach ", fixes[0].id);
}}

===findNavaidByFrequencyMHz()===
{{Nasal doc
|syntax = findNavaidByFrequencyMHz([pos, ]freq[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1547|t=Source}}
|text = Returns a <code>navaid</code> ghost object for a navaid matching a given frequency. If there is more than one navaid with that frequency, the nearest station is returned.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidByFrequencyMHz(lat, lon, freq, type);</code>.
|param2 = freq
|param2text = Frequency, in megahertz, of the navaid to search for.
|param3 = type
|param3text = This will narrow the search to navaids of a certain type. Defaults to "all." For the full list of accepted type arguments, see {{flightgear file|src/Navaids/positioned.cxx|l=127}}.
|example1 = var navaid = findNavaidByFrequencyMHz(109.55);
print("ID: ", navaid.id); # prints info about the navaid
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 100), " Mhz");
print("Range: ", navaid.range_nm, " nm");
if(navaid.course) print("Course: ", navaid.course);
}}

=== findNavaidsByFrequencyMHz()===
{{Nasal doc
|syntax = findNavaidsByFrequencyMHz([pos, ]freq[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1572|t=Source}}
|text = Returns a vector conatining <code>navaid</code> ghost objects for navaids that match a given frequency, sorted from nearest to furthest.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsByFrequencyMHz(lat, lon, freq, type);</code>.
|param2 = freq
|param2text = Frequency, in megahertz, of the navaid to search for.
|param3 = type
|param3text = This will narrow the search to navaids of a certain type. Defaults to "all." For the full list of accepted type arguments, see {{flightgear file|src/Navaids/positioned.cxx|l=127}}.
|example1 = var navaids = findNavaidsByFrequencyMHz(109.55);
foreach(var navaid; navaids){
print("--");
print("ID: ", navaid.id); # prints info about the navaid
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 100), " Mhz");
print("Range: ", navaid.range_nm, " nm");
if(navaid.course) print("Course: ", navaid.course);
print("--");
<nowiki>}</nowiki>
}}

===findNavaidsByID()===
{{Nasal doc
|syntax = findNavaidsByID([pos, ]id[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1600|t=Source}}
|text = Returns a vector containing <code>navaid</code> ghost objects matching a given ID, sorted by range from a certain position.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsByID(lat, lon, id, type);</code>.
|param2 = id
|param2text = Full or partial ID of the fix to search for.
:{{inote|1=Inputting a partial ID does not work correctly (see [http://forum.flightgear.org/viewtopic.php?f=30&t=28129 here]). It is best to just input a full ID.}}
|param3 = type
|param3text = This will narrow the search to navaids of a certain type. Defaults to "all." For the full list of accepted type arguments, see {{flightgear file|src/Navaids/positioned.cxx|l=127}}.
|example1 = var navaid = findNavaidsByID("MXW");
navaid = navaid[0];
print("ID: ", navaid.id); # prints info about 'MXW' (a VOR station)
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 1000), " Mhz");
print("Range: ", navaid.range_nm, " nm");
}}

===findNavaidsWithinRange()===
{{Nasal doc
|syntax = findNavaidsWithinRange([pos, ]range[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1518|t=Source}}
|text = Returns a vector of <code>navaid</code> ghost objects which are within a given range of a given position (by default the aircraft's current position). The results are sorted from closest to furthest.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsWithinRange(lat, lon, range, type);</code>.
|param2 = range
|param2text = Mandatory number giving the range in nautical miles within which to search for navaids.
|param3 = type
|param3text = This will narrow the search to navaids of a certain type. Defaults to "all." For the full list of accepted type arguments, see {{flightgear file|src/Navaids/positioned.cxx|l=127}}.
|example1text = Searches for navaids within 10 nm of [[KSFO]].
|example1 = var pos = airportinfo("KSFO");
var navs = findNavaidsWithinRange(pos, 10);
foreach(var nav; navs){
print(nav.name, " (ID: ", nav.id, ")");
}
|example2text = Searches for navaids within 10 nm of your current position.
|example2 = var navs = findNavaidsWithinRange(10);
foreach(var nav; navs){
print(nav.name, " (ID: ", nav.id, ")");
<nowiki>}</nowiki>
}}

===finddata()===
{{Nasal doc
|syntax = finddata(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=603|t=Source}}
|text = Takes a relative path and tries to return an absolute one. It works by appending the relative path to some paths and testing to see if they exist. As of FlightGear v3.7, these paths are the TerraSync directory (tested first) and [[$FG_ROOT]].
|param1 = path
|param1text = A relative path as a string.
|example1 = var path = finddata("Aircraft/Generic");
print(path); # prints the absolute path to $FG_ROOT/Aircraft/Generic
|example2 = var path = finddata("Airports");
print(path); # prints the absolute path to <TerraSync dir>/Airports
|example3 = var path = finddata("preferences.xml");
print(path); # prints the absolute path to $FG_ROOT/preferences.xml
}}

===flightplan()===
{{Nasal doc
|syntax = flightplan([path]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1738|t=Source}}
|text = {{see also|Nasal Flightplan}}
Returns a flight plan object, either one for the current flight plan, or one loaded from a given path.
|param1 = path
|param1text = Optional path to flight plan XML file.
|example1text = Gets the active flight plan and gets the ID of the current waypoint. Note that this example requires a flight plan to be set in the [[Route Manager]] first.
|example1 = var fp = flightplan();
print(fp.getWP(fp.current).id);
|example2text = Creates a new flight plan from an XML file and prints the IDs of the waypoints. Note that this example requires a flight plan to have been created and saved as <tt>''[[$FG_HOME]]/fp-demo.xml''</tt>.
|example2 = var path = getprop('/sim/fg-home') ~ '/fp-demo.xml';
var fp = flightplan(path);
for(var i = 0; i < fp.getPlanSize(); i += 1){
print(fp.getWP(i).id);
<nowiki>}</nowiki>
}}

===geodinfo()===
{{Nasal doc
|syntax = geodinfo(lat, lon[, max_alt]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=981|t=Source}}
|text = Returns a vector containing two entries or <code>'''nil'''</code> if no information could be obtained because the terrain tile wasn't loaded. The first entry in the vector is the elevation (in meters) for the given point, and the second is a hash with information about the assigned material (as defined in <tt>''[[$FG_ROOT]]/Materials''</tt>), or <code>'''nil'''</code> if there was no material information available (for example, because there is an untextured building at that location). The structure of the hash is as follows (see also {{readme file|materials}}):
* '''light_coverage:''' The coverage of a single point of light in m<sup>2</sup>.
* '''bumpiness:''' Normalized bumpiness factor for the material.
* '''load_resistance:''' The amount of pressure in N/m<sup>2</sup> the material can withstand without deformation.
* '''solid:''' 1 (true) or false (0) depending on whether the material is solid or not.
* '''names:''' Vector of scenery types (usually generated by [[TerraGear]]) that will use this material.
* '''friction_factor:''' Normalized friction factor of the material.
* '''rolling_friction:''' The rolling friction coefficient of the material.

Note that this function is a ''very'' CPU-intensive operation, particularly in FlightGear v2.4 and earlier. It is advised to use this function as little as possible.
|param1 = lat
|param1text = Latitude, inputted as a number.
|param2 = lon
|param2text = Longitude, inputted as a number.
|param3 = max_alt
|param3text = The altitude, in metres, from which the function will begin searching for the height of the terrain. Defaults to 10,000 metres. If the terrain is higher than this argument specifies, <code>'''nil'''</code> will be returned.
|example1text = Dumps information about ground underneath the aircraft.
|example1 = var pos = geo.aircraft_position();
var info = geodinfo(pos.lat(), pos.lon());
debug.dump(info);
|example2text = Prints whether the ground underneath the aircraft is solid or is water.
|example2 = var pos = geo.aircraft_position();
var info = geodinfo(pos.lat(), pos.lon());
if (info != nil and info[1] != nil) {
print("The ground underneath the aircraft is ", info[1].solid == 1 ? "solid." : "water.");
<nowiki>}</nowiki>
}}

=== geodtocart() ===
{{Nasal doc
|syntax = geodtocart(lat, lon, alt);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=962|t=Source}}
|text = Converts {{wikipedia|geodetic coordinates}} (latitude, longitude, and altitude) to {{wikipedia|ECEF|Earth-centered, Earth-fixed}} coordinates (x, y and z). A vector is returned containing x, y, and z in metres. The equatorial radius of earth used is that defined by the {{wikipedia|WGS 84}} (6,378,137 metres). All argument are mandatory.
|param1 = lat
|param1text = Latitude, in degrees.
|param2 = lon
|param2text = Longitude, in degrees.
|param3 = alt
|param3text = Altitude, in metres.
|example1 = var (x, y, z) = geodtocart(0, 0, 0); # point is the intersection of the prime meridian and equator.
print("x: ", x); # prints "x: 6378137"
print("y: ", y); # prints "y: 0"
print("z: ", z); # prints "y: 0"
}}

=== get_cart_ground_intersection()===
Introduced in 2017.2.1, see [[Terrain Detection]].

===getprop()===
{{Nasal doc
|syntax = <nowiki>getprop(path[, path[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=345|t=Source}}
|text = Returns the value of a node in the [[Property Tree]] or <code>'''nil'''</code> if the node does not exist or the value is not a number (NaN).
|param1 = path
|param1text = There needs to be at least one argument, but there is no limit to the maximum amount of arguments that can be given. The arguments will be concatenated together to form a property tree path. The arguments must be strings, but in FlightGear v3.2 onwards, there is also support (added by {{flightgear commit|34ed79}}) for numeric arguments as indices. See example 2 below.
|example1 = print("You have FlightGear v", getprop("/sim/version/flightgear")); # prints FlightGear version
|example2text = Note that the example below will only work in FlightGear 3.2 and above.
|example2 = for(var i = 0; i < 8; i += 1){
print("View #", i + 1, " is named ", getprop("/sim/view", i, "name"));
}
|example3text = Same as above, but is supported by all versions of FlightGear.
|example3 = for(var i = 0; i < 8; i += 1){
print("View #", i + 1, " is named ", getprop("/sim/view[" ~ i ~ "]/name"));
<nowiki>}</nowiki>
}}
==== See also====
{{note| If you have to read/write the same property multiple times (e.g. in an update loop), it is more efficient to use a node object:
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}

===greatCircleMove()===
{{Nasal doc
|syntax = greatCircleMove([pos, ]course, dist);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1681|t=Source}}
|text = Calculates a new set of geodetic coordinates using inputs of course and distance, either from the aircraft's current position (by default) or from another set of coordinates. Returns a hash containing two members, ''lat'' and ''lon'' (latitude and longitude respectively).
|param1 = pos
|param1text = Optional position to calculate from. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost object.
:* A hash with ''lat'' and ''lon'' members
:* A <code>geo.Coord</code> object
:* A lat/lon pair, that is, a pair of numbers (latitude followed by longitude) separated by a comma: <code>greatCircleMove(lat,lon, ...)</code>.
|param2 = course
|param2text = Course to new set of coordinates, in degrees (in the range 0–360).
|param3 = dist
|param3text = Distance in nautical miles to the new set of coordinates.
|example1 = var pos = greatCircleMove(0,0, 0, 1);
debug.dump(pos); # print hash with coordinates
|example2 = var fix = findFixesByID("POGIC");
fix = fix[0];
var pos = greatCircleMove(fix, 45, 10);
debug.dump(pos); # print hash with coordinates
}}

===interpolate()===
{{Nasal doc
|private = _interpolate()
|syntax = <nowiki>interpolate(prop, value1, time1[, value2, time2[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=522|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|text = Linearly interpolates a node in the property tree to a given value in a specified time. The value/time pairs will be run one after the other in the order that they are passed to the function. Note that the interpolation will continue even when the simulation is paused.
|param1 = prop
|param1text = String or <code>props.Node</code> object that indicates a node in the property tree to be used.
|param2 = value''n''
|param2text = Target value to change the property to in the set amount of time. This should be a number.
|param3 = time''n''
|param3text = Time in seconds, that will be taken for the interpolation.
|example1text = Paste the code below into the Nasal Console and execute. Then, open the Property Browser and look for the property. Finally, run the code again, and watch the value of the property change.
|example1 = setprop("/test", 0); # (re-)set property
interpolate("/test",
50, 5, # interpolate to 50 in 5 seconds
10, 2, # interpolate to 10 in 2 seconds
0, 5); # interpolate to 0 in 5 seconds
|example2 = # Apply the left brake at 20% per second
var prop = "controls/gear/brake-left";
var dist = 1 - getprop(prop);
if (dist == 1) {
interpolate(prop, 1, dist / 0.2);
<nowiki>}</nowiki>
}}

===isa()===
{{Nasal doc
|syntax = isa(object, class);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Checks if an object is an instance of, or inherits from, a second object (or class), returning 1 (true) if it is and 0 (false) if otherwise.
|param1 = object
|param1text = Object to check.
|param2 = class
|param2text = Class/object to check that '''object''' inherits from or is an instance of.
|example1 = var coord = geo.Coord.new();
if(isa(coord, geo.Coord)){
print("Variable 'coord' is an instance of class 'geo.Coord'"); # this one will be printed
} else {
print("Variable 'coord' is not an instance of class 'geo.Coord'");
}
|example2 = var coord = geo.Coord.new();
if(isa(coord, props.Node)){
print("Variable 'coord' is an instance of class 'props.Node'");
} else {
print("Variable 'coord' is not an instance of class 'props.Node'"); # this one will be printed
}
|example3text = The example below demonstrates checking of inheritance.
|example3 = var Const = {
constant: 2,
getConst: func {
return me.constant;
}
};

var Add = {
new: func {
return { parents: [Add, Const] };
},

addToConst: func(a){
return a * me.getConst();
}
};

var m = Add.new();
print(m.addToConst(4));

if(isa(m, Add)) print("Variable 'm' is an instance of class 'Add'"); # will be printed
if(isa(m, Const)) print("Variable 'm' is an instance of class 'Const'"); # will also be printed
}}

===logprint()===
{{Nasal doc
|syntax = <nowiki>logprint(priority[, msg[, msg[, ...]]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=431|t=Source}}
|text = Concatenates a message and logs it with a given priority level. Unlike {{func link|print()}} and {{func link|printlog()}}, message outputted by this function will be logged in your <code>[[Commonly used debugging tools#fgfs.log|fgfs.log]]</code> file as coming from the Nasal file itself rather than from {{flightgear file|src/Scripting/NasalSys.cxx}}.
|param1 = priority
|param1text = Number specifying the priority level of the outputted message:
:{{{!}} class="wikitable"
! Number !! Debug type
{{!-}}
{{!}} 1 {{!!}} Bulk
{{!-}}
{{!}} 2 {{!!}} Debug
{{!-}}
{{!}} 3 {{!!}} Info
{{!-}}
{{!}} 4 {{!!}} Warn
{{!-}}
{{!}} 5 {{!!}} Alert
{{!}}}
|param2 = msg
|param2text = The message. There is no limit to the arguments you give give. They will be concatenated together before logging.
|example1 = # logs the value of pi to three decimal places with log level 3
logprint(3, "pi = ", sprintf("%.3f", math.pi));
|example2 = logprint(5, "Alert! This is an important message!");
}}
{{note|
The following constants have been added to the development branch of FlightGear ("next") and will be releases with FG 2020.1 so you won't have to remember the numbers anymore:

LOG_BULK, LOG_WARN, LOG_DEBUG, LOG_INFO, LOG_ALERT, DEV_WARN, DEV_ALERT }}

===magvar() ===
{{Nasal doc
|syntax = magvar([pos]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1642|t=Source}}
|text = Returns the {{wikipedia|magnetic variation}} at a given set of coordinates. The table below gives the magnetic model used depending on the version of FlightGear.
{{{!}} class="wikitable"
! FlightGear versions !! Model !! Reference date
{{!-}}
{{!}} 3.6 and above {{!!}} {{wikipedia|World Magnetic Model}} (WMM) 2015 {{!!}} 1 January 2015
{{!-}}
{{!}} 0.9.11-pre1 to 3.4 {{!!}} WMM 2005 {{!!}} 1 January 2005
{{!-}}
{{!}} 0.7.3 to 0.9.10 {{!!}} WMM 2000 {{!!}} 1 January 2000
{{!}}}
|param1 = pos
|param1text = Optional position to calculate from. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost object.
:* A hash with ''lat'' and ''lon'' members
:* A <code>geo.Coord</code> object
:* A lat/lon pair, that is, a pair of numbers (latitude followed by longitude) separated by a comma: <code>magvar(lat,lon)</code>.
|example1 = print(magvar(0, 0)); # prints the magnetic variation at 0, 0
}}

===maketimer() ===
{{Nasal doc
|syntax = maketimer(interval[, self], function);
|source = ''Implemented using the {{API Link|flightgear|class|TimerObj}} class.''<br>{{flightgear file|src/Scripting/NasalSys.cxx|l=90|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=533|t=Part 2}}
|version = 2.12
|commit = {{flightgear commit|ab939f|t=commit}}
|text = Returns a timer object containing the following methods and members:
* '''start()''': Starts the timer.
* '''stop()''': Stops the timer.
* '''restart(interval)''': Restarts the timer with the given interval.
* '''singleShot''': Bool showing whether the timer is only to be run once, or continuously until told to stop. Can be both set and read from (see examples).
* '''isRunning''': Read-only bool telling whether the timer is currently running.
* '''simulatedTime''': (FG 2017.1+; {{flightgear commit|0af316|t=commit}}) Bool telling whether the timer is using simulated time (which accounts for pause, etc.). Defaults to false (use real time). Can be both read and set. This cannot be changed while the timer is running.
Unlike {{func link|settimer()}}, which it replaces, <code>maketimer()</code> provides more control over the timer. In addition, it can help reduce memory usage.
|param1 = interval
|param1text = Interval in seconds for the timer.
|param2 = self
|param2text = Optional parameter specifying what any <code>'''me'''</code> references in the function being called will refer to.
|param3 = function
|param3text = Function to be called at the given interval.
|example1 = var timer = maketimer(1, func(){
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)
});
timer.start();
|example2 = var timer = maketimer(1, math, func(){
print(me.math); # 'me' reference is the 'math' namespace
});
timer.singleShot = 1; # timer will only be run once
timer.start();
|example3 = var timer = maketimer(1, func(){
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)
});
timer.start();
print(timer.isRunning); # prints 1
|example4text = In the example below, "Hello, World!" will be printed after one second the first time, and after two seconds thereafter.
|example4 = var update = func(){
print("Hello, World!");
timer.restart(2); # restarts the timer with a two second interval
}

var timer = maketimer(1, update);
timer.singleShot = 1;
timer.start();
}}

===maketimestamp()===
{{Nasal doc
|syntax = maketimestamp()
|source = ''Implemented using the {{API Link|flightgear|class|TimeStampObj}} class.''<br>{{flightgear file|src/Scripting/NasalSys.cxx|l=214|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=589|t=Part 2}}
|version = 2019.2
|commit = {{flightgear commit|7db06300|t=commit}}
|text = Returns a time stamp object to allow high resolution timing of Nasal operations. When created the timer will automatically be stamped. The object has the following methods:
* '''stamp()''': Resets the timing operation. Call this first.
* '''elapsedMSec()''': returns number of milliseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.
* '''elapsedUSec()''': returns number of microseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.
|
|example1text = In the example below the number of milliseconds elapsed will be printed.
|example1 = var timestamp = maketimestamp();
timestamp.stamp();
print(timestamp.elapsedMSec(), "ms elapsed");
print(timestamp.elapsedMSec(), "ms elapsed");
}}

===md5()===
{{Nasal doc
|syntax = md5(string);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=758|t=Source}}
|version = 3.2
|commit = {{flightgear commit|cfbf9e|t=commit}}
|text = Returns a the {{wikipedia|MD5}} hash (as a string) of the inputted string.
|param1 = string
|param1text = String the generate the hash of. Mandatory.
|example1text = The below code should output <code>65a8e27d8879283831b664bd8b7f0ad4</code>.
|example1 = print(md5("Hello, World!"));
}}

===navinfo()===
{{Nasal doc
|syntax = navinfo(lat, lon, type, id);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1453|t=Source}}
|text = Returns vector <code>navaid</code> ghost objects matching the given '''type''' and '''id''' or <code>'''nil'''</code> on error.
|param1 = lat ''and'' lon
|param1text = If given, the returned navaids will be put into order of ascending distance from the location.
|param2 = type
|param2text = Narrows the search to the given type. Must be one of "any," "fix," "vor," "ndb," "ils," "dme," or "tacan." Defaults to the equivalent of "any."
|param3 = id
|param3text = ID to search for. Note that, although all the parameters are technically optional, this parameter must be given, otherwise an empty vector will be returned.
|example1 = navinfo("vor"); # returns all VORs
|example2 = navinfo("HAM"); # return all navaids whose names start with "HAM"
|example3 = navinfo("vor", "HAM"); # return all VORs whose names start with "HAM"
|example4 = navinfo(34,48,"vor","HAM"); # return all VORs whose names start with "HAM" and sorted by distance relative to 34°, 48°
}}

===parse_markdown()===
{{Nasal doc
|syntax = parse_markdown(markdown);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=745|t=Part 1}} {{!}} {{simgear file|simgear/misc/SimpleMarkdown.cxx|t=Part 2}}
|version = 3.2
|text = Parses a string containing {{wikipedia|Markdown}} and returns the result as a string. As of FlightGear 2016.1, it is just a simple parser, and does the following:
* It strips whitespace from the beginning of the string.
* It supports [http://daringfireball.net/projects/markdown/syntax#p paragraphs and line breaks].
* It collapses whitespace.
* It converts unordered [http://daringfireball.net/projects/markdown/syntax#list lists] to use a bullet character (•). Note that the bullet character is implemented in hexadecimal UTF-8 character bytes (<code>E2 80 A2</code>), as so may not work properly when the being displayed in an encoding other than UTF-8.
|param1 = markdown
|param1text = String containing Markdown to be parsed.
|example1text =
Save the below code as <tt>''[[$FG_ROOT]]/gui/dialogs/test.xml''</tt>, then run the Nasal code below it to open the dialog. To change the markdown to be parsed, simply change the code in the highlighted section, save it, and reload the GUI (<tt>Debug > Reload GUI</tt>).
<syntaxhighlight lang="xml" highlight="41-50">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>test</name>
<layout>vbox</layout>

<group>
<layout>hbox</layout>

<empty>
<stretch>true</stretch>
</empty>

<text>
<label>parse_markdown() test dialog</label>
</text>

<empty>
<stretch>true</stretch>
</empty>

<button>
<legend></legend>
<pref-width>16</pref-width>
<pref-height>16</pref-height>
<binding>
<command>dialog-close</command>
</binding>
</button>

</group>

<canvas>
<name>Canvas plot</name>
<stretch>true</stretch>
<pref-width>400</pref-width>
<pref-height>300</pref-height>
<nasal>
<load><![CDATA[
var text = 'Items:
* apples
* oranges
* pears

Some text.
Some more items:
* apples
* oranges
* pears';

var parsed = parse_markdown(text);

var root_canvas = canvas.get(cmdarg());
root_canvas.setColorBackground(255, 255, 255);
var root = root_canvas.createGroup();

var text_dis = root.createChild("text")
.setText(parsed)
.setTranslation(5, 5)
.setFont("LiberationFonts\LiberationSans-Regular.ttf")
.setFontSize(15)
.setColor(0, 0, 0)
.setDrawMode(canvas.Text.TEXT)
.setAlignment("left-top");
]]></load>
</nasal>
</canvas>

</PropertyList>
</syntaxhighlight>
|example1 = fgcommand("dialog-show", {"dialog-name": "test"});
|example2text = The example below parses Markdown and outputs it in a HTML document. The parsed text is placed in <syntaxhighlight lang="xml" inline><pre></pre></syntaxhighlight> tags. To change the Markdown to be parsed, simply edit the variable <tt>markdown</tt> at the top of the code.
|example2 = <nowiki>var markdown = 'Items:
* apples
* oranges
* pears

Some text.
Some more items:
* apples
* oranges
* pears';

var parsed = parse_markdown(markdown);

debug.dump(parsed);

var path = string.normpath(getprop("/sim/fg-home") ~ '/Export/parse_markdown()-test.html');

var file = io.open(path, "w");

var html = "<!DOCTYPE html>\n\n<html>\n\n<head>\n\t<meta charset=\"UTF-8\">\n\t<title>parse_markdown() test generated by Nasal</title>\n</head>\n\n<body>\n\t<pre>" ~ parsed ~ "</pre>\n</body>\n\n</html>";

io.write(file, html);
io.close(file);
print("Done, file ready for viewing (" ~ path ~ ")");</nowiki>
}}

===parsexml()===
{{Nasal doc
|syntax = <nowiki>parsexml(path[, start[, end[, data[, pro_ins]]]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=710|t=Source}}
|text = This function is an interface into the built-in [http://expat.sourceforge.net/ Expat XML parser]. The absolute path to the file is returned as string, or <code>'''nil'''</code> is returned on error.
|param1 = path
|param1text = Mandatory absolute path to the XML file to be parsed.
|param2 = start
|param2text = Optional callback function that will be called for every starting tag. The function should take two argument: the tag name and a hash containing attributes.
|param3 = end
|param3text = Optional callback function that will be called for every ending tag. The function should take one argument: the tag name.
|param4 = data
|param4text = Optional callback function that will be called for every piece of data within a set of tags. The function should take one argument: the data as a string.
|param5 = pro_ins
|param5text = Optional callback function that will be called for every {{wikipedia|Processing Instruction|processing instruction}}. The function should take two argument: the target and the data string.
|example1text = Save the below XML code in <tt>''[[$FG_HOME]]/Export/demo.xml''</tt>. Then, execute the Nasal code below in the Nasal Console. The XML will be parsed and each bit of the code will be printed.
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<?xml-stylesheet type="text/xsl" href="style.xsl"?>

<foo>
<blah type="string"><![CDATA[ <sender>John Smith</sender> ]]></blah>
<blah2 type="string">Orange & lemons</blah2>
</foo>
</syntaxhighlight>
|example1 = var start = func(name, attr){
print("Starting tag: '", name, "'");
foreach(var a; keys(attr)){
print("\twith attribute ", a, '="', attr[a], '"');
}
}

var end = func(name){
print("Ending tag: '", name, "'");
}

var data = func(data){
print("Data = '", data, "'");
}

var pro_instr = func(target, data){
print("Processing instruction: target = '", target, "', data = '", data, "'");
}

parsexml(getprop("/sim/fg-home") ~ '/Export/demo.xml', start, end, data, pro_instr);
}}

===print()===
{{Note|As of 07/2020, we are in the process of slowly deprecating and removing Nasal print() (in fgdata) where possible in favor of log [[#logprint()]] which takes a priority level.

This is part of the goal that we achieve zero output at log-level at alert, and everything shown at ‘warn; is really a warning, not just information.<ref>https://sourceforge.net/p/flightgear/mailman/message/37042224/</ref>}}

{{Nasal doc
|syntax = <nowiki>print(data[, data[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=415|t=Source}}
|text = Concatenates its arguments and then prints it to the terminal and the [[Commonly used debugging tools#fgfs.log|log]]. Note that a newline is automatically added.
|param1 = data
|param1text = Data to print. Only strings and numbers can be printed; other data types will not be. There many be any number of arguments; they will just be concatenated together.
|example1 = print("Just", " a ", "test"); # prints "Just a test"
|example2 = print("pi = ", math.pi); # prints "pi = 3.141592..."
}}

=== printf() ===
{{Nasal doc
|syntax = <nowiki>printf(format[, arg[, arg, [...]]]);</nowiki>
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Creates and prints a formatted string. For a description of its arguments, see {{func link|sprintf()}} (it is, in fact, implemented using <code>sprintf()</code>).
|example1 = printf("In hexadecimal, 100000 = %X", 186A0); # prints "In hexadecimal, 100000 = 186A0"
}}

===printlog()===
{{Nasal doc
|syntax = <nowiki>printlog(level, data[, data[, ...]]);</nowiki>
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Prints the given message with the given log level. If the log level is higher or equal to <code>/sim/logging/priority</code>, it is printed.
|param1 = level
|param1text = Mandatory log level as a string. Must be one of "none," "bulk," "debug," "info," "warn," or "alert." Note that "none" will mean that the message will never be printed.
|param2 = data
|param2text = Data to be printed. Only strings and numbers will be printed; others will not be. There may be any number of arguments; they will just be concatenated together.
|example1 = printlog("alert", "This is an alert"); # message will be printed
|example2 = printlog("info", "Just informing you about something"); # message will be printed only if log level is set to "info" or less
}}

===rand()===
{{Nasal doc
|syntax = rand();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=554|t=Source}}
|text = Returns a random floating point number between 0 (inclusive) and 1 (exclusive). It takes no arguments.
|example1 = print(rand()); # prints random number
}}

===registerFlightPlanDelegate()===
{{Nasal doc
|syntax = registerFlightPlanDelegate(init_func);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1879|t=Source}}
|text = Registers a flight plan delegate. See <tt>''{{fgdata file|Nasal/route_manager.nas|t=$FG_ROOT/Nasal/route_manager.nas}}''</tt> for examples.
|param1 = init_func
|param1text = Initialization function which will be called during FlightGear's startup.
}}
===removecommand()===
{{Nasal doc
|syntax = removecommand(cmd);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=668|t=Source}}
|text = Removes the given fgcommand. Returns <code>'''nil'''</code>.
{{caution|This will remove '''any''' [[fgcommands|fgcommand]], even those implemented in C++, so use with caution!}}
|param1 = cmd
|param1text = String specifying the name of the command to remove.
|example1 = addcommand("hello", func(){
print("Hello");
});
fgcommand("hello"); # "Hello" will be printed
removecommand("hello"); # removes it
}}

===removelistener()===
{{Nasal doc
|syntax = removelistener(id);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=1384|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=506|t=Part 2}}
|text = Removes and deactivates the given listener and returns the number of listeners left or <code>'''nil'''</code> on error.
{{note|It is good practice to remove listeners when they are not required anymore. This prevents the listeners reducing FlightGear's run performance.}}
|param1 = id
|param1text = ID of listener as returned by {{func link|setlistener()}}.
|example1 = var ls = setlistener("/sim/test", func(){
print("Property '/sim/test' has been changed");
});
setprop("/sim/test", "blah"); # trigger listener
var rem = removelistener(ls); # remove listener
print("There are ", rem, " listeners remaining");
}}

===resolvepath()===
{{Nasal doc
|syntax = resolvepath(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=604|t=Source}}
|text = Takes a relative path as a string and uses [[SimGear]]'s path-resolving framework to return an absolute path as a string. If the path could not be resolved, an empty string is returned. See [[Resolving Paths]] for a detailed description of the algorithm. This function can also be used to check if a file exists.
|param1 = path
|param1text = Relative path to be completed.
|example1 = print(resolvepath("Nasal/globals.nas")); # prints the equivalent of $FG_ROOT/Nasal/globals.nas
|example2 = print(resolvepath("blah")); # prints nothing; could not be resolved
|example3 = var file_path = resolvepath("Aircraft/SenecaII/some-file");
if (file_path != ""){
gui.popupTip("some-file found", 2);
} else {
gui.popupTip("some-file not found", 2);
<nowiki>}</nowiki>
}}

===setlistener()===
{{Nasal doc
|syntax = <nowiki>setlistener(node, code[, init[, type]]);</nowiki>
|private = _setlistener()
|source = {{flightgear file|src/Scripting/Nasal|l=499|t=Part 1}} {{!}} {{flightgear file|src/Scripting/Nasal|l=1350|t=Part 2}}<br>''Listener implemented using the {{API Link|flightgear|class|FGNasalListener}} class.''
|text = Creates a listener which will be triggered when the given property is changed (depending on the '''type'''). A unique integer ID is returned; this can later be used as the argument to {{func link|removelistener()}}.
{{note|Listeners are known to be a source of resource leaks. To avoid this, please take measures such as:
* Using {{func link|removelistener()}} when they are not needed any more.
* Using a single initialization listener.
* Avoiding tying listeners to properties that are rapidly updated (e.g., many times per frame).
}}
|param1 = node
|param1text = Mandatory string or <code>props.Node</code> object pointing to a property in the [[Property Tree]].
|param2 = code
|param2text = Mandatory callback function to execute when the listener is triggered. The function can take up to four arguments in the following order:
* '''changed''': a <code>props.Node</code> object pointing to the changed node.
* '''listen''': a <code>props.Node</code> object pointing to the listened-to node. Note that this argument maybe different depending on the '''type'''.
* '''mode''': an integer telling how the listener was triggered. 0 means that the value was changed. 1 means that a child property was added. -1 means that a child property was removed.
* '''is_child''': boolean telling whether '''changed''' is a child property of the listened-to '''node''' or not. 1 (true) if it is, 0 (false) otherwise.
|param3 = init
|param3text = If set to 1 (true), the listener will additionally be triggered when it is created. This argument is optional and defaults to 0 (false).
|param4 = type
|param4text = Integer specifying the listener's behavior. 0 means that the listener will only trigger when the property is changed. 1 means that the trigger will always be triggered when the property is written to. 2 will mean that the listener will be triggered even if child properties are modified. This argument is optional and defaults to 1.
|example1 = var prop = props.globals.initNode("/sim/test", "", "STRING"); # create property
var id = setlistener("/sim/test", func(n){ # create listener
print("Value: ", n.getValue());
});
setprop("/sim/test", "blah"); # trigger listener
removelistener(id); # remove listener
prop.remove(); # remove property
}}

===setprop()===
{{Nasal doc
|syntax = <nowiki>setprop(path[, path[, ...]], value);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=385|t=Source}}
|text = Sets the value of a property in the [[Property Tree]]. If the property does not exist, it will be created. Returns 1 (true) on success or 0 (false) if there was an error.
{{note|If you want to remove a property, you will have to use one of the <code>props</code> helpers:
<syntaxhighlight lang="nasal">
props.globals.getNode("foo/bar").remove(); # take out the complete node
props.globals.getNode("foo").removeChild("bar"); # take out a certain child node
</syntaxhighlight>
}}
|param1 = path
|param1text = There needs to be at least one '''path''' argument, but there is no limit to the maximum amount that can be given. They will be concatenated together to form a property tree path. The arguments must be strings, but in FlightGear v3.2 onwards, there also is support (added by {{flightgear commit|34ed79}}) for numeric arguments as indices. See example 2 below.
|param2 = value
|param2text = Value to write to the given property. Must be either a string or a number.
|example1 = setprop("/sim/demo", "This is a demo");
|example2text = Note that the example below will only work in FlightGear 3.2 and above.
|example2 = for(var i = 0; i < 3; i += 1){
setprop("/sim/demo", i, "Demo #" ~ i));
}
|example3text = Same as above, but is supported by all versions of FlightGear.
|example3 = for(var i = 0; i < 3; i += 1){
setprop("/sim/demo[" ~ i ~ "]", "Demo #" ~ i));
<nowiki>}</nowiki>
}}
====See also====
{{note| If you have to read/write the same property multiple times (e.g. in an update loop), it is more efficient to use a node object:
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}

===settimer() ===
{{Nasal doc
|syntax = settimer(function, delta[, realtime]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=499|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=1286|t=Part 2}}
|text = Runs the given function a specified amount of seconds after the current time. Returns <code>'''nil'''</code>.
{{note|Improper use of <code>settimer()</code> may cause resource leaks. It is also highly recommended that the newer {{func link|maketimer()}} should be used instead of this function.}}
|param1 = function
|param1text = Mandatory function that will be called. It may be necessary to enclose code in an anonymous function (see example).
|param2 = delta
|param2text = Mandatory amount of time in seconds after which the function will be called.
|param3 = realtime
|param3text = If 1 (true), "real time" will be used instead of "simulation time." Defaults to 0 (false). Note that if "simulation time" is used, the timer will not run while FlightGear is paused.
|example1 = var myFunc = func(){
print("Hello");
}

settimer(myFunc, 2); # runs myFunc after 2 seconds
|example2 = var sqr = func(a){
return a * a;
}

settimer(func(){
print(sqr(2)); # will print 4 after 2 seconds
}, 2);
}}

===srand() ===
{{Nasal doc
|syntax = srand();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=559|t=Source}}
|text = Makes the pseudorandom number generator (see {{func link|rand()}}) generate a new {{wikipedia|random seed|noicon=1}} based on time. Returns 0.
}}
===systime()===
{{Nasal doc
|syntax = systime();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=770|t=Source}}
|text = Returns the {{wikipedia|Unix time}} (seconds since since 00:00:00 UTC, 1/1/1970) as a floating point number with high resolution. This function is useful for benchmarking purposes (see example 2).
{{note|1=High resolution timers under Windows can produce inaccurate or fixed sub-millisecond results.<ref>{{cite web|url=http://forum.flightgear.org/viewtopic.php?f=30&t=29259|title=Nasal: systime() ??!?|author=Necolatis|date=Apr 2nd, 2016}}</ref> This is due to the underlying {{func link|GetSystemTimeAsFileTime()|link=https://msdn.microsoft.com/en-us/library/windows/desktop/ms724397(v=vs.85).aspx}} API call, which depends on hardware availability of suitable high resolution timers. See also [https://msdn.microsoft.com/en-us/library/windows/desktop/dn553408(v=vs.85).aspx Acquiring high-resolution time stamps]}}
|example1 = print("Unix time: ", systime()); # prints Unix time
|example2 = var myFunc = func(){
for(var i = 0; i <= 10; i += 1){
print("Interation #", i);
}
}
var t = systime(); # record time
myFunc(); # run function
var t2 = systime(); # record new time
print("myFunc() took ", t2 - t, " seconds"); # print result
}}

===thisfunc()===
{{Nasal doc
|syntax = thisfunc();
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns the function from which this function is called. This allows a function to reliably and safely call itself from within a closure.
|example1 = var stringify_vec = func(input){
if (typeof(input) == "scalar"){
return sprintf("%s", input);
} elsif (typeof(input) == "vector") {
if (size(input) == 0) return "[]";
var this = thisfunc();
var buffer = "[";
for(var i = 0; i < size(input); i += 1){
buffer ~= this(input[i]);
if (i == size(input) - 1) {
buffer ~= "]";
} else {
buffer ~= ", ";
}
}
return buffer;
} else {
die("stringify_vec(): Error! Invalid input. Must be a vector or scalar");
}
}

var test_vec = ["a", "b", "c", 1, 2, 3];
debug.dump(stringify_vec(test_vec)); # prints "[a, b, c, 1, 2, 3]"
test_vec = [];
debug.dump(stringify_vec(test_vec)); # prints "[]"
test_vec = {};
debug.dump(stringify_vec(test_vec)); # will throw an error
}}

===tileIndex() ===
{{Nasal doc
|syntax = tileIndex();
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1720|t=Source}}
|text = Returns the index of the tile at the aircraft's current position as a string. This corresponds to the name of the STG file of the tile. For example, at [[KSFO]], this would be <code>942050</code>, corresponding to <tt>''[[$FG_SCENERY]]/Terrain/w130n30/w123n3/942050.stg''</tt>.
|example1 = print(tileIndex()); # print index
}}

=== tilePath()===
{{Nasal doc
|syntax = tilePath();
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1712|t=Source}}
|text = Returns the base path of the tile at the aircraft's current position as a string. For example, at KSFO, this would be <code>w130n30/w123n3</code>, corresponding to <tt>''[[$FG_SCENERY]]/Terrain/w130n30/w123n3''</tt>.
|example1 = print(tilePath()); # print path
}}

=== values()===
{{Nasal doc
|syntax = values(hash);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns a vector containing the values of the given hash.
|param1 = hash
|param1text = Mandatory hash to get the values of.
|example1 = var hash = {
"a": 1,
"b": 2,
"c": 3
};

foreach(var val; values(hash)){
print(val);
}
|example2text = The below example does exactly the same thing as the above example, but does not use <code>values()</code>:
|example2 = var hash = {
"a": 1,
"b": 2,
"c": 3
};

foreach(var key; keys(hash)){
print(hash[key]);
<nowiki>}</nowiki>
}}

==Extension functions new in FG 2020.1 ==
The following functions have been added to the nasal core library and will be released with FlightGear version 2020.1.
Before the release they are available in the development branch "next".

===isfunc()===
Returns 1 if type or argument is a function, otherwise 0.

===isghost()===
Returns 1 if type or argument is a ghost, otherwise 0.

=== ishash()===
Returns 1 if type or argument is a hash, otherwise 0.

===isint()===
{{Nasal doc
|syntax = isint(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns 1 if argument has a numeric value and x == floor(x), e.g. integer.
}}

===isnum()===
{{Nasal doc
|syntax = isnum(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns 1 if typeof(x) is "scalar" and x has a numeric value otherwise 0.
}}

===isscalar()===
{{Nasal doc
|syntax = isscalar(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns 1 if type or argument is a scalar (string or numeric), otherwise (vector, hash, func, ...) it returns 0. This is useful to check if a variable can be converted to string e.g. when useing the string concat operator "~".
|example1 = var a = "foo";
var b=42;
if (isscalar(a) and isscalar(b)) print(a~b);
if (isstr(a)) print("a is a string");
if (isint(b)) print("b is an integer");
# if (isscalar(a))... is equivalent to if (typeof(a) == "scalar")...
}}

===isstr()===
Returns 1 if type or argument is a string, otherwise 0.

===isvec()===
Returns 1 if type or argument is a vector, otherwise 0.

===vecindex()===
{{Nasal doc
|syntax = vecindex(vector, value);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns the index of value or nil, if value is not found in vector.
|example1=
var myvector = ["apple", "bananna", "coconut"];
# to check if a vector contains a certain value compare vecindex to nil
if (vecindex(myvector, "apple") != nil) {
print("found apple");
}
# WARNING: this will not work as desired because index is 0
if (vecindex(myvector, "apple")) {
print("found apple");
<nowiki>}</nowiki>

}}

==Variables==
Various global constants (technically variables) are provided for use in converting between different units. They are all found in {{fgdata file|Nasal/globals.nas|text=$FG_ROOT/Nasal/globals.nas}}.

===D2R===
{{Nasal doc
|syntax = var radians = degrees * D2R;
|text = Converts an angle from degrees to radians when multiplied by the angle in degrees. Equal to <code>π / 180</code>.
}}
===FPS2KT===
{{Nasal doc
|syntax = var knots = feet_per_second * FPS2KT;
|text = Converts a velocity from feet per second to knots when multiplied by the velocity in feet per second. Approximately equal to 0.5925.
}}
===FT2M===
{{Nasal doc
|syntax = var metres = feet * FT2M;
|text = Converts a length from feet to metres when multiplied by the length in feet. Equal to 0.3048.
}}
===GAL2L ===
{{Nasal doc
|syntax = var litres = gallons * GAL2L;
|text = Converts a volume from US liquid gallons to litres when multiplied by the volume in gallons. Approximately equal to 3.7854.
}}
===IN2M===
{{Nasal doc
|syntax = var metres = inches * IN2M;
|text = Converts a length from inches to metres when multiplied by the length in inches. Equal to 0.0254.
}}
===KG2LB===
{{Nasal doc
|syntax = var pounds = kilograms * KG2LB;
|text = Converts a mass from kilograms to pounds when multiplied by the mass in kilograms. Approximately equal to 2.2046.
}}
===KT2FPS===
{{Nasal doc
|syntax = var feet_per_second = knots * KT2FPS;
|text = Converts a velocity from knots to feet per second when multiplied by the velocity in knots. Approximately equal to 1.6878.
}}
===KT2MPS===
{{Nasal doc
|syntax = var metres_per_second = knots * KT2MPS;
|text = Converts a velocity from knots to metres per second when multiplied by the velocity in knots. Approximately equal to 0.5144.
}}
===L2GAL===
{{Nasal doc
|syntax = var gallons = litres * L2GAL;
|text = Converts a volume from litres to US liquid gallons when multiplied by the volume in litres. Approximately equal to 0.2642.
}}
===LB2KG===
{{Nasal doc
|syntax = var kilograms = pounds * LB2KG;
|text = Converts a mass from pounds to kilograms when multiplied by the mass in pounds. Approximately equal to 0.4536.
}}
===M2FT ===
{{Nasal doc
|syntax = var feet = metres * M2FT;
|text = Converts a length from metres to feet when multiplied by the length in metres. Approximately equal to 3.2808.
}}
===M2IN===
{{Nasal doc
|syntax = var inches = metres * M2IN;
|text = Converts a length from metres to inches when multiplied by the length in metres. Approximately equal to 39.3701.
}}
===M2NM ===
{{Nasal doc
|syntax = var nautical_miles = metres * M2NM;
|text = Converts a length from metres to nautical miles when multiplied by the length in metres. Approximately equal to 0.00054.
}}
===MPS2KT ===
{{Nasal doc
|syntax = var knots = metres_per_second * MPS2KT;
|text = Converts a velocity from metres per second to knots when multiplied by the velocity in metres per second. Approximately equal to 1.9438.
}}
===NM2M ===
{{Nasal doc
|syntax = var metres = nautical_miles * NM2M;
|text = Converts a length from nautical miles to metres when multiplied by the length in nautical miles. Equal to 1,852.
}}
===R2D===
{{Nasal doc
|syntax = var degrees = radians * R2D;
|text = Converts an angle from radians to degrees when multiplied by the angle in radians. Equal to <code>180 / π</code>.
}}

{{Appendix}}

{{Nasal namespaces}}

Aircraft properties reference

2024-06-30T13:05:40Z

Jsb: /* Annunciators [draft] */

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

== Annunciators [draft] ==
!! This section is work in progress !!

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 $FGDATA/Aircraft/Generic/generic-annunciators.xml 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 should, and usually do correspond to how various cockpit controls are set. Consider these the pilot input.

=== 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]]

Property browser

2024-04-23T09:56:07Z

Jsb: Add availability note for new prop browser features

[[File:Property_Browser.jpg|thumb|270px|The property browser window]]
{{PropertyTree}}

The [[FlightGear]] '''property browser''' is a dialog used to browse, in-simulator, through all properties. Properties are internal, runtime state variables in FlightGear. The property browser cannot only be used to inspect all sorts of internal variables at runtime, but it can also be used to change the values of most properties easily (some being conceputally read-only, i.e. because they're exclusively written-to by a certain subsystem such as the FDM). For instance, you cannot change your frame rate by changing the frame counter obviously.

== Opening the property browser ==
The property browser can be opened while FlightGear is running either:
* By pressing the {{key press|/}} key (forward slash)
* Through the main [[menubar|menu]]: <tt>Debug > Browse Internal Properties</tt> (in older version: <tt>File > Browse Internal Properties</tt>).

Browse around to see the different data fields that are available. Just about everything interesting/useful is published in the property system. The browser allows you to inspect and even change values in the live running copy of FG.

=== Property Key Handler ===

The property key handler provides a better experience for developers when using the property tree and is suited to keyboard operations. See [[Property Key Handler]] for more information.

== Tied properties ==
{{Note|The origin of tied properties was largely to address
"hypothetical" performance concerns in the early days. Coders could
continue to use native compiled variables and simultaneously expose them to
the property system. Early property system skepticism included issues like
performance and use of global structures. Those have largely not proven
out to be actual issues. So without looking deep into how much
effort/change/impact this would require, I think for the most part the
whole tied property aspect of the api could go away and the property system
api would simplify quite a bit.<ref>https://sourceforge.net/p/flightgear/mailman/message/37280934/</ref>
}}
Some properties are so called ''tied'' properties which are directly mapped to internal C++ variables and they cannot be modified using the property browser, we are currently trying to get rid of tied properties, see [[Howto:Use_Property_Tree_Objects]] for details.

In addition, even some non-tied properties cannot be modified because they are by default constantly written/modified by another subsystem (in C++/Nasal space), possibly updating properties at frame rate, this applies for example to the frame rate counter, which is constantly updated by C++ code - so trying to set it from Nasal would be kind of pointless.

Also certain properties are only read/applied during initialization/re-initialization (startup/reset) of the sim, while others require the corresponding subsystems to be reinitialized.

== Tips and tricks ==
Apart from setting a property by clicking it and using the text field and Set button, there is many things that can be done through the property browser:
{| class="wikitable"
|+
!Mouse click while holding on keyboard
!Function
!Comment
|-
|ctrl
|on '.' toggle verbose mode
on '..' goto root
on any bool property: toggle true/false value
|Verbose mode is explained below
|-
|shift
|on '.' dump properties to console
display property in top left corner of the flightgear screen
|To ''remove the property'' ctrl-shift-click another property
|-
|alt
|toggle trace_write attribute of the selected property
|Since 04/2024 on 'next'; details below in 'verbose mode'
|-
|ctrl+alt
|toggle trace_read attribute of the selected property
|Since 04/2024 on 'next'; details below in 'verbose mode'
|}

== Verbose mode ==
In verbose mode, toggled by ctrl-clicking an "<tt>.</tt>" entry or toggling <code>/sim/gui/dialogs/property-browser/show-flags</code>, some additional information is shown as flags like this

<code>foo = '123.456' (double; AT)</code>.

{| class="wikitable" border="1" cellspacing="0"
! Flag
! Meaning
! Comment
|-
| r || Read protected || Showing that a property can not be read.
|-
| w || Write protected || Showing that a property can not be written to.
|-
| R || Trace read operations || rowspan="2" | In <code>--log-level=info</code> create log line with TRACE prefix on write/read operation; set with <code><foo trace-write="y"></code>.
Since 04/2024 on next R and W flag can be set on the fly via the property browser (see above)
|-
| W || Trace write operations
|-
| A || Archive bit set || Makes writeProperties() also save this property in restricted mode ("save flight"), while all others are only saved in full mode.
|-
| U || User archive bit set || Saved into ~/.fgfs/autosave.xml, and restored next time. 
|-
| T || Tied property || Only the C/C++ code that owns a tied property can write to it. Also, listeners will not be triggered.
|-
| L<N> || Number of listeners
|
|-
|=> <path>
|Alias target
|This prop is an alias for <path> (since 04/2024 on 'next')
|-
|}

{{FGCquote
|1= <pre>props.globals.getNode("/sim/aircraft").getAttribute("references")

does now return the reference counter -- the number of co-owners
of the shared pointer. This is really only useful for debugging.
And here's again a summary of all the attribute names:

children ... returns number of children (faster than size(n.getChildren()!)
listeners ... return number of attached listeners
references ... returns number of co-owners (+ 2 for own consumption)
tied ... returns whether a node is "tied" (in which case listeners
might not get triggered)
alias ... whether the node is an alias to another node
read ... whether the node is read-protected
write ... whether the node is write-protected
archive ... whether the "archive" flag is set, which makes the
node saved with "Save Flight" in the menu
trace-read ... whether the node is being traced for read operations
trace-write ... whether the node is being traced for write operations
userarchive ... whether the node will be saved to ~/.fgfs/autosave.xml
on exit
</pre>
|2= {{cite web
| url = http://sourceforge.net/p/flightgear/mailman/message/15645291/
| title = <nowiki>Re: [Flightgear-devel] FlightGear/Plib periodic stutter notes</nowiki>
| author = <nowiki>Melchior FRANZ</nowiki>
| date = Oct 21st, 2007
| added = Oct 21st, 2007
| script_version = 0.25
}}
}}

== Other ways to open the property browser ==
=== Forcing open the browser on startup ===
You can force the browser to open on startup, through the following command:
--prop:browser=/sim/path/that/you/want/to/show

More than one property browser can be opened like this.
--prop:browser=position --prop:browser[1]=orientation

=== Opening the property browser through nasal ===
Calling <code>gui.property_browser(<path>)</code> opens a property browser for <path>. While it can be called more than once, though all the dialogues will be drawn on top of each other in the centre of the screen. Example:

<syntaxhighlight lang="nasal">
settimer(func {
gui.property_browser("/position");
gui.property_browser("/orientation");
}, 0);
</syntaxhighlight>

=== Displaying On-Screen property values through nasal ===
Create a file (let's call it display-props.nas) with instructions such below

<syntaxhighlight lang="nasal">
# On-screen displays
var enableOSD = func {
var left = screen.display.new(20, 10);
var right = screen.display.new(-300, 10);

left.add("/orientation/heading-deg");
left.add("/environment/wind-from-heading-deg");
left.add("/environment/wind-speed-kt");
right.add("/controls/flight/rudder");
}
enableOSD();
</syntaxhighlight>

Add the path/to/display-props.nas in your aircraft -set.xml,

or in your $FG_HOME/ inside a Nasal/ folder.

== Related content ==
=== Wiki articles ===
* [[Property Key Handler]]

=== Source code ===
* {{fgdata source|path=gui/dialogs/property-browser.xml}}

[[Category:Menubar]]
[[Category:Property Tree]]

Property browser

2024-04-23T09:54:53Z

Jsb: Update property browser /* Tips and tricks */ and /* Verbose mode */

[[File:Property_Browser.jpg|thumb|270px|The property browser window]]
{{PropertyTree}}

The [[FlightGear]] '''property browser''' is a dialog used to browse, in-simulator, through all properties. Properties are internal, runtime state variables in FlightGear. The property browser cannot only be used to inspect all sorts of internal variables at runtime, but it can also be used to change the values of most properties easily (some being conceputally read-only, i.e. because they're exclusively written-to by a certain subsystem such as the FDM). For instance, you cannot change your frame rate by changing the frame counter obviously.

== Opening the property browser ==
The property browser can be opened while FlightGear is running either:
* By pressing the {{key press|/}} key (forward slash)
* Through the main [[menubar|menu]]: <tt>Debug > Browse Internal Properties</tt> (in older version: <tt>File > Browse Internal Properties</tt>).

Browse around to see the different data fields that are available. Just about everything interesting/useful is published in the property system. The browser allows you to inspect and even change values in the live running copy of FG.

=== Property Key Handler ===

The property key handler provides a better experience for developers when using the property tree and is suited to keyboard operations. See [[Property Key Handler]] for more information.

== Tied properties ==
{{Note|The origin of tied properties was largely to address
"hypothetical" performance concerns in the early days. Coders could
continue to use native compiled variables and simultaneously expose them to
the property system. Early property system skepticism included issues like
performance and use of global structures. Those have largely not proven
out to be actual issues. So without looking deep into how much
effort/change/impact this would require, I think for the most part the
whole tied property aspect of the api could go away and the property system
api would simplify quite a bit.<ref>https://sourceforge.net/p/flightgear/mailman/message/37280934/</ref>
}}
Some properties are so called ''tied'' properties which are directly mapped to internal C++ variables and they cannot be modified using the property browser, we are currently trying to get rid of tied properties, see [[Howto:Use_Property_Tree_Objects]] for details.

In addition, even some non-tied properties cannot be modified because they are by default constantly written/modified by another subsystem (in C++/Nasal space), possibly updating properties at frame rate, this applies for example to the frame rate counter, which is constantly updated by C++ code - so trying to set it from Nasal would be kind of pointless.

Also certain properties are only read/applied during initialization/re-initialization (startup/reset) of the sim, while others require the corresponding subsystems to be reinitialized.

== Tips and tricks ==
Apart from setting a property by clicking it and using the text field and Set button, there is many things that can be done through the property browser:
{| class="wikitable"
|+
!Mouse click while holding on keyboard
!Function
!Comment
|-
|ctrl
|on '.' toggle verbose mode
on '..' goto root
on any bool property: toggle true/false value
|Verbose mode is explained below
|-
|shift
|on '.' dump properties to console
display property in top left corner of the flightgear screen
|To ''remove the property'' ctrl-shift-click another property
|-
|alt
|toggle trace_write attribute of the selected property
|Since 04/2024 on next; details below in 'verbose mode'
|-
|ctrl+alt
|toggle trace_read attribute of the selected property
|Since 04/2024 on next; details below in 'verbose mode'
|}

== Verbose mode ==
In verbose mode, toggled by ctrl-clicking an "<tt>.</tt>" entry or toggling <code>/sim/gui/dialogs/property-browser/show-flags</code>, some additional information is shown as flags like this

<code>foo = '123.456' (double; AT)</code>.

{| class="wikitable" border="1" cellspacing="0"
! Flag
! Meaning
! Comment
|-
| r || Read protected || Showing that a property can not be read.
|-
| w || Write protected || Showing that a property can not be written to.
|-
| R || Trace read operations || rowspan="2" | In <code>--log-level=info</code> create log line with TRACE prefix on write/read operation; set with <code><foo trace-write="y"></code>.
Since 04/2024 on next R and W flag can be set on the fly via the property browser (see above)
|-
| W || Trace write operations
|-
| A || Archive bit set || Makes writeProperties() also save this property in restricted mode ("save flight"), while all others are only saved in full mode.
|-
| U || User archive bit set || Saved into ~/.fgfs/autosave.xml, and restored next time. 
|-
| T || Tied property || Only the C/C++ code that owns a tied property can write to it. Also, listeners will not be triggered.
|-
| L<N> || Number of listeners
|
|-
|=> <path>
|Alias target
|This prop is an alias for <path>
|-
|}

{{FGCquote
|1= <pre>props.globals.getNode("/sim/aircraft").getAttribute("references")

does now return the reference counter -- the number of co-owners
of the shared pointer. This is really only useful for debugging.
And here's again a summary of all the attribute names:

children ... returns number of children (faster than size(n.getChildren()!)
listeners ... return number of attached listeners
references ... returns number of co-owners (+ 2 for own consumption)
tied ... returns whether a node is "tied" (in which case listeners
might not get triggered)
alias ... whether the node is an alias to another node
read ... whether the node is read-protected
write ... whether the node is write-protected
archive ... whether the "archive" flag is set, which makes the
node saved with "Save Flight" in the menu
trace-read ... whether the node is being traced for read operations
trace-write ... whether the node is being traced for write operations
userarchive ... whether the node will be saved to ~/.fgfs/autosave.xml
on exit
</pre>
|2= {{cite web
| url = http://sourceforge.net/p/flightgear/mailman/message/15645291/
| title = <nowiki>Re: [Flightgear-devel] FlightGear/Plib periodic stutter notes</nowiki>
| author = <nowiki>Melchior FRANZ</nowiki>
| date = Oct 21st, 2007
| added = Oct 21st, 2007
| script_version = 0.25
}}
}}

== Other ways to open the property browser ==
=== Forcing open the browser on startup ===
You can force the browser to open on startup, through the following command:
--prop:browser=/sim/path/that/you/want/to/show

More than one property browser can be opened like this.
--prop:browser=position --prop:browser[1]=orientation

=== Opening the property browser through nasal ===
Calling <code>gui.property_browser(<path>)</code> opens a property browser for <path>. While it can be called more than once, though all the dialogues will be drawn on top of each other in the centre of the screen. Example:

<syntaxhighlight lang="nasal">
settimer(func {
gui.property_browser("/position");
gui.property_browser("/orientation");
}, 0);
</syntaxhighlight>

=== Displaying On-Screen property values through nasal ===
Create a file (let's call it display-props.nas) with instructions such below

<syntaxhighlight lang="nasal">
# On-screen displays
var enableOSD = func {
var left = screen.display.new(20, 10);
var right = screen.display.new(-300, 10);

left.add("/orientation/heading-deg");
left.add("/environment/wind-from-heading-deg");
left.add("/environment/wind-speed-kt");
right.add("/controls/flight/rudder");
}
enableOSD();
</syntaxhighlight>

Add the path/to/display-props.nas in your aircraft -set.xml,

or in your $FG_HOME/ inside a Nasal/ folder.

== Related content ==
=== Wiki articles ===
* [[Property Key Handler]]

=== Source code ===
* {{fgdata source|path=gui/dialogs/property-browser.xml}}

[[Category:Menubar]]
[[Category:Property Tree]]

Aircraft properties reference

2024-04-02T22:35:37Z

Jsb: /* Engine Common */ Add fire property

Aircraft properties reference

2024-04-02T10:17:13Z

Jsb: /* Annunciators [draft] */

Aircraft properties reference

2024-04-02T10:00:46Z

Jsb: /* Annunciators [draft] */

Aircraft properties reference

2024-03-30T13:59:24Z

Jsb: /* Annunciators [draft] */

Aircraft properties reference

2024-03-28T00:15:02Z

Jsb: annunciators: Add hint to aircraft.light