.. include:: ../../../_includes/_warning_banner.rst

Property Root
=============

Each model has a *property root*. When the model refers to a property, e.g.

.. code-block:: xml

  <animation>
    ...
    <property>path/to/property</property>
    ...
  </animation>

the ``path/to/property`` is relative to the model property root.

The model property root is usually part of FlightGear's global property tree.
For example:

* For the main aircraft model, the property root is the root ``/`` of the property tree itself.
* For an AI or multiplayer model, the property root is ``/ai/models/<model_name>/``.

Be careful not to confuse the property root with the model XML file.
Both are property trees, but with very different roles:

* The model property root usually lives in the global property tree. Properties from the model XML file never do.
* Any ``<property>`` tag or similar in the model file refers to a property path relative to the property root.
* Any ``alias="path"`` attribute refers to a property path in the model XML file.



Be also careful of relative vs absolute property paths.
This is a relative path (relative to the model property root):

.. code-block:: xml

  <property>path/to/property</property>

This is an absolute path (due to the leading ``/``), it refers to the global property tree:

.. code-block:: xml

  <property>/path/to/property</property>

If you have any doubt, use only relative paths in XML model files.
Absolute paths are rarely correct: the model property root exists for a reason, and you should use properties in it.


Example
-------

This is a typical animation for the elevator in an aircraft model:

.. code-block:: xml

  <animation>
    <type>rotate</type>
    <object-name>elevator</object-name>
    <property>surface-positions/elevator-pos-norm</property>
    <factor>30</factor>
  </animation>

When flying this aircraft, the model is loaded with property root ``/``,
so the elevator is animated by the property ``/surface-positions/elevator-pos-norm``.
In this case, there is no difference between relative and absolute paths.

When this aircraft is loaded as multiplayer,
the model is loaded with property root e.g. ``/ai/models/multiplayer[0]/``,
so the elevator is animated by the property ``/ai/models/multiplayer[0]/surface-positions/elevator-pos-norm``.
This property is transmitted over multiplayer, and the animation will work correctly.

If an absolute path had been used instead, then it is still ``/surface-positions/elevator-pos-norm``
which would have been used for the multiplayer aircraft animation.
This is the elevator position for the main aircraft, not the multiplayer one!