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

Properties
==========

The following tags can be defined in a model XML file.

General Properties
------------------

These tags can be used at the top level of a model XML file.
They must be children of the root ``<PropertyList>`` tag.

Main model
^^^^^^^^^^

These tags define the main 3D model loaded by this model XML file.

``<path>``
    .. code-block:: xml

      <path>path/to/model/file</path>

    Path to a model file to load. Can be a 3D model (AC3D or GlTF), or another model XML file.

.. _model-xml-offsets:

``<offsets>``
    .. code-block:: xml

      <offsets>
        <x-m>0</x-m>
        <y-m>0</y-m>
        <z-m>0</z-m>
        <heading-deg>0</heading-deg>
        <pitch-deg>0</pitch-deg>
        <roll-deg>0</roll-deg>
      </offsets>

    Translates and rotates the model.
    The coordinate system used is ``x`` backwards, ``y`` right, ``z`` up.

``<texture-path>``
    FlightGear will look for textures for this model in this directory.

Others
^^^^^^

``<nasal>``
    .. code-block:: xml

      <nasal>
        <load>
          ...
        </load>
        <unload>
          ...
        </unload>
      </nasal>

    Nasal code to be run when this model is loaded or unloaded respectively.

    Within this code, the ``cmdarg()`` function returns the model :doc:`property-root`

    .. hint::
       To stop nasal code from interfering with XML syntax, enclose it in a ``<![CDATA[ ]]>`` block:

       .. code-block:: xml

          <nasal>
            <load><![CDATA[
              ... nasal code here ...
            ]]></load>
          </nasal>

``<multiplay>``
    .. code-block:: xml

      <multiplay>
        <custom-property>value</custom-property>
      </multiplay>

    When this model is loaded for a multiplayer aircraft, everything under this tag will be added to FlightGear property tree under the model :doc:`property-root`.



.. _model-xml-model-tag:

Secondary models
----------------

The ``<model>`` tag is used to define a secondary model. There can be any number of them.

**Example:**

.. code-block:: xml

    <model>
      <path>path/to/model/file.xml</path>
      <name>pilot</name>
      <offsets><x-m>-3</x-m></offsets>
    </model>

It contains the following:

``<path>``
    Path to a model file to load. Can be a 3D model (AC3D or GlTF), or another model XML file.

``<name>``
    Name for this secondary model. It can be used to apply animations to the entire secondary model.

``<attach-to>``
    .. versionadded:: 2024.2

    Name of parent to which this secondary model will be attached.
    Any offsets or animation on the parent will affect this model.

``<offsets>``
    Offsets for this model only. Same syntax as for the :ref:`main model <model-xml-offsets>`.
    When a parent is specified with ``<attach-to>``, offsets are relative to the parent position.

``<overlay>``
    If the file specified by ``<path>`` is a model XML file, the content of ``<overlay>`` is added to this file.
    Combined with ``alias`` attributes, this can be used to make models with parameters:
    https://wiki.flightgear.org/Howto:Model_with_parameters

``<condition>``
    Only show this secondary model when this condition holds.
    See :doc:`../condition/index` for the syntax.

``<usage>interior</usage>``
    Only the value ``interior`` is recognised.
    Depending on settings, a model marked as ``interior`` may not be loaded for AI or multiplayer models, to help with performance.


Special objects
---------------

Tags ``<light>``, ``<text>``, and ``<particlesystem>`` each define a kind of special object.
See the following resources regarding their syntax:

``<light>``
    https://wiki.flightgear.org/Compositor#Lights

``<text>``
    https://wiki.flightgear.org/OSG_Text

``<particlesystem>``
    .. warning:: ``<particlesystem>`` is currently non-functional in FlightGear 2024.2

    `FGDATA/Docs/README.xmlparticles <https://gitlab.com/flightgear/fgdata/-/blob/next/Docs/README.xmlparticles>`__

They use following common tags:

``<name>``
    Name for this object. It can be used to apply animations.

``<attach-to>``
    .. versionadded:: 2024.2

    Name of parent to which this object will be attached, same as in secondary models.

``<offsets>``
    This tag is *only* used by ``<text>`` and ``<particlesystem>``.
    Translation and rotation offsets for this object. Same syntax as for the :ref:`main model <model-xml-offsets>`.
    When a parent is specified with ``<attach-to>``, offsets are relative to the parent position.

``<position>``
    This tag is *only* used by ``<light>``, as a substitute for ``<offsets>`` (for translations).

    .. code-block:: xml

      <position>
        <x-m>0</x-m>
        <y-m>0</y-m>
        <z-m>0</z-m>
      </position>

    The coordinate system used is ``x`` backwards, ``y`` right, ``z`` up.

``<direction>``
    This tag is *only* used by ``<light>``, as a substitute for ``<offsets>`` (for rotations).

    There are three possible ways to specify the light direction:

    * With angles (similar to ``<offsets>``):

      .. code-block:: xml

        <direction>
          <heading-deg>0</heading-deg>
          <pitch-deg>0</pitch-deg>
          <roll-deg>0</roll-deg>
        </direction>

    * As a vector:

      .. code-block:: xml

        <direction>
          <x>-1</x>
          <y>0</y>
          <z>0</z>
        </direction>

    * By pointing towards a specific position.

      .. code-block:: xml

        <direction>
          <lookat-x-m>-1</lookat-x-m>
          <lookat-y-m>0</lookat-y-m>
          <lookat-z-m>0</lookat-z-m>
        </direction>


Animations
----------

Objects can be animated with ``<animation>``, taking properties as input.

**Example:**

.. code-block:: xml

    <animation>
      <type>rotate</type>
      <object-name>Rudder</object-name>
      <property>surface-positions/rudder-pos-norm</property>
      <factor>30</factor>
      <axis>
        <z>1</z>
      </axis>
    </animation>

The following tags are shared by all animations:

``<type>``
    Type of animation, e.g. 'select', 'translate', 'rotate', etc.

``<object-name>``
    Name of the object to which this animation applies.
    Many ``<object-name>`` can be defined for a single animation.

``<condition>``
    When this is false, the animation will stop moving/updating.
    See :doc:`../condition/index` for the syntax.

    .. caution::
        When the condition is false, the animation does *not* return to its initial position.

The remaining parameters depend on the type of animation.
See https://wiki.flightgear.org/Howto:Animate_models
for a detailed list of animation types and their parameters.



Effects
-------

Effects can change the way an object is rendered.

**Example:**

.. code-block:: xml

    <effect>
      <inherits-from>Effects/model-transparent</inherits-from>
      <object-name>glass</object-name>
      <!-- Using model-transparent like this is no longer needed as of 2025,
           it is only here for the example. -->
    </effect>

The following tags are enough to apply an already existing effect to the model:

``<inherits-from>``
    Name of the effect to apply, as defined under ``<name>`` in the effect file.
    This is *not* the path to the effect file, although it is common to use the same name for the file and the effect.

``<object-name>``
    Name of the object to which to this effect applies.
    Many ``<object-name>`` can be defined for a single effect.

See `FGDATA/Docs/README.effects <https://gitlab.com/flightgear/fgdata/-/blob/next/Docs/README.effects>`__ for the full syntax of effects.

.. caution::
   Effects are disabled for GlTF models.