Property tree: Difference between revisions

The so called '''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 model, 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 & for external input/output.  

For example, a left banking joystick input is exposed in the property tree where it is read by the FG FDM sub-system.  The FG 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.

There are several subsystems that implement a full API on top of the property tree, such as the AI traffic system, the multiplayer mode, but also Canvas - basically, setting certain properties (e.g. 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 tree ==

Naming a property is very much like naming a file in a file system, with levels of hierarchy, e.g.:  

Some of these variables are "calculated" within the sim (i.e. updated regularly, e.g. at frame rate), whilst others can be manipulated. Writing a variable is as easy as

What makes FG 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 within the property tree.

== Customizing and manipulating the property tree ==

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.

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, i.e. using a telnet client or a conventional web browser, at run time.

=== Protocol Options ===

By what was said above, the property tree is not consistent with fixed variables, they are created dynamically, to represent a propeller plane vs 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.