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

Introduction
============

3D models for FlightGear are loaded from AC3D or GlTF files.
However, only the shape of the model is loaded from this file.
Animations and effects are instead defined in an XML file.

XML model files typically define the following:

* A main 3D model file (in AC3D or GlTF format).
* Any number of child models. These can be 3D models (AC3D or GlTF), or other XML model files.
* Special objects, such as lights, particles, text.
* Animations and effects for all these objects.


General Syntax
--------------

A model XML file is a `PropertyList XML`_ file, where properties have a special meaning.
As a result:

.. _PropertyList XML: https://wiki.flightgear.org/PropertyList_XML_files

* Everything must be contained in a root ``<PropertyList>`` tag.

* ``<tag include="other-file.xml"/>`` can be used to include a different file.

  .. note::
    In most cases, you want to use :ref:`model-xml-model-tag` tags rather than ``include`` attributes.
    ``<model>`` allows to add animations, offsets, etc. while the ``include`` attribute does not.



* ``<tag alias="path"/>`` can be used to reference a property defined elsewhere in this file.

  .. note::
    Attribute ``alias="path"`` refers to a node in this XML file, not a node in the global property tree. See :doc:`property-root`.

Almost all tags and attributes in a model XML file are optional.