MODEL DEFINITIONS

The <model_filename>.xml file goes in the Model folder beside the other folders for the object and should be formatted as follows:

<?xml version="1.0" encoding="UTF-8"?>
<ModelInfo version="1.0" guid="<!-- GUID HERE -->">
    <LODS>
        <!-- LOD DATA HERE -->
    </LODS>
    <!-- MODEL ANIMATION DATA HERE -->
    <AnimGraph>
        <!-- ANIMATION GRAPH AND BLENDTREE DATA HERE -->
    <AnimGraph>
    <Behaviors>
        <!-- MODEL BEHAVIOR DATA HERE -->
    </Behaviors>
</ModelInfo>
 
<ModelBehaviors>
    <!-- DEPRECATED -->
</ModelBehaviors>

Here you must include the <ModelInfo> element, and some older files may have the <ModelBehaviors> element. However that has since been deprecated in favor of the <Behaviors> element, and it should not be used except if it already exists as part of a legacy SimObject, or if you are creating additional Template, Input Event or Parameter Function files. The rest of the XML is comprised of the elements listed on this page as well as the elements listed on the Model Animation Definitions page (since animation can be embedded in the model XML or included as a separate animation.xml file, elements related to animation are listed on a separate page). You can find multiple examples of the model file in the various samples that come with the SDK, and some short example snippets on the Model Examples page.

 

 

<ModelInfo>

This element is a container element for all the model details. This element can contain the following:

<LODS>, <Behaviors>, <Animation>, <NodeAnimation>, <AnimationEvent>, <AnimGraph>, <IKChain>, <IKConstraint>, <ModelAttachments>.

 

Note that not all the elements listed above are required for every model type - some are specific to aircraft while others are more suited to ground vehicle or scenery SimObjects, and still others will depend on the sub-elements included within other elements.

 

This element has the following attributes:

 

Attribute Description Type Required
Version The version of this ModelInfo definition. Default is "1.0". Currently not important. Float No
GUID The unique GUID of the model this XML accompanies. Must be in the format "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx}", all lower case, e.g: "{12f06ee8-11ce-4e7b-a715-a9c5deb5352f}". This is currently only required for scenery objects.   No
(Unless model is for a Scenery Object)

 

 

<LODS>

This is a container element that takes no attributes and contains one or more <LOD /> sub-elements. See the LOD Example for more information on how this element works.

IMPORTANT! Please ensure that you have read and understood the LOD limits for models in Microsoft Flight Simulator.

 

<LOD />

This sub-element of <LODS> is used to describe a single LOD model. It can be self closing, or it can contain the (deprecated) <AnimationFileList> container element, one or more <MergeModel> elements, and/or one or more <AttachModel> elements. It has the following attributes:

 

Attribute Description Type Required
modelFile Defines the model file to use (from a relative path) for this LOD.

String

 Yes
minSize This is the minimum size on screen before this LOD model is considered for display, as a percentage. Note that the value can be greater than 100%. Please see LOD Minsize Rules for more information. Float No

 

<MergeModel>

This element is used to define the different animation and/or submodel gLTF files that should be used for the SimObject over the different <LOD /> elements. Paths for this element are relative to the model XML file location. If you are using both submodels and animations then you would have at least two of these elements, although you can have more as required. You can find an example for this element here: . You can also find out more information about submodel merging here: Submodel Merging.

 

<AttachModel>

This element is used to define a unique ID string for a glTF file that is going to be attached to the main model (as defined in the main <LOD /> element) when the main model is on the given LOD. If you include this element then you will also need to add a <ModelAttachments> element where you will define the path and other details relevant to the model being attached. Note too that you may have multiple <AttachModel> elements if required.

You can find an example for this element here: Model Attachments.

 

Attribute Description Type Required
id The unique ID of the model that is being attached.

String

 Yes

 

You can also find out more information about setting up and using attachments here: Model Attachments.

 

 

<AnimationFileList>

This is a container sub-element that is used to hold one or more <AnimationFile> elements, and it has no attributes. Note that this is a deprecated feature that - while still supported - should not be used for new SimObjects created for Microsoft Flight Simulator. Instead, you should be using the <MergeModel> elements.

 

<AnimationFile>

This element is a sub-element of the <AnimationFileList> and holds the name (including the extension) of the gLTF file that has the animations that the LOD requires. This file should be in the "animation" folder, beside the "model" and "texture" folder for the SimObject.

 

 

<AnimationInclude>

When you have an object that has variations, you may wish each variation to reference the same set of animations. In these cases, you would not include the different animation elements in the individual [model].xml but instead create a separate animation.xml file that contains only contains the animation elements to be shared. This file would then be referenced using the <AnimationInclude> element. This element has no parameters and requires the <Include /> sub-element to define the path to the animation file to use.

 

<Include />

This is a self closing element and is a sub-element of <AnimationInclude>. The element has a single attribute:

 

Attribute Description Type Required
File The path to the animation.xml, relative to the [model].xml directory.

String

 Yes

 

 

<IKChain>

This element describes an Inverse Kinematic (IK) chain, most commonly used with Jetways. You can see an example of this element being used in the sample Jetway project and also on the XML examples page: Jetway Example. It must have one each of the sub-elements <Start>, <End>, <TranslationSpeed> and <RotationSpeed>, and takes the following attributes:

 

Attribute Description Type Required
Name The name of the event of the IK Chain.

String:

IK_MainHandle - for both jetways and jetway links
IK_SecondaryHandle - For Jetways
IK_WheelsGroundLock - For Jetways

Yes

 

NOTE: The hierarchy of Nodes in the object is crucial to define an IK chain. The chain will be composed of the line of descendants from the Start Node to the End Node, and each of these nodes (except End) will move within its constraints, aiming the End Node towards a target. Each of these nodes move relative to its parent, and any other descendants (in the hierarchy) of these nodes will follow.

 

<Start>

This sub-element of <IKChain> contains the name of the Node at the start of the chain, which can move within its constraints. This should not be the root Node of the object.

 

<End>

This sub-element of <IKChain> contains the name of the Node at the end of the chain, aiming for a target position. Must be a descendant of the Start Node in the hierarchy, and it will not move relative to its parent as part of this IK chain.

 

<TranslationSpeed>

This sub-element of <IKChain> contains the maximal translation speed of each Node of the chain (relative to its parent), in meters per second.

 

<RotationSpeed>

This sub-element of <IKChain> contains the maximal rotation speed of each Node of the chain (relative to its parent), in degrees per second.

 

 

<IKConstraint>

This element takes no parameters and defines the constraints of a Node for inverse kinematic (IK) purposes. It will only have an effect if the Node is part of an IK chain (excluding the End node). You can see an example of this element being used in the sample Jetway project and also on the examples page: Jetway Example. It must have <Node> sub-element, and can have also have the following optional sub-elements: <X>, <Y>, <Z>, <Pitch />, <Bank />, <Heading />.

NOTE: A Node part of an IK Chain that has no defined <IKConstraint> will not move at all (relative to its parent) during IK movements.

Each of the sub elements except <Node> can have the following attributes:

 

Attribute Description Type Required
Min Minimal position/angle relative to its parent Node Float No
Max Maximal position/angle relative to its parent Node Float No

 

If neither Min nor Max are defined, this means the Node has no limits to translating or rotating along the direction for the sub-element direction, relative to its parent. If both Min and Max are defined, the Node will always stay within the given range relative to its parent. Note that the default position/angle (relative to parent) should be in this range.

 

<Node>

This sub-element of the <IKConstraint> element contains the name of the Node that can move within constraints during IK.

 

<X>, <Y>, <Z>

These sub-elements of the <IKConstraint> element are used to define a translation for the node along the X, Y or Z axis.

 

<Pitch />

This self closing sub-element of the <IKConstraint> element takes no parameters and has no sub-elements. When added to the main constraint container element, it indicates that the node can be rotated by changing pitch.

 

<Bank />

This self closing sub-element of the <IKConstraint> element takes no parameters and has no sub-elements. When added to the main constraint container element, it indicates that the node can be rotated by changing bank.

 

<Heading />

This self closing sub-element of the <IKConstraint> element takes no parameters and has no sub-elements. When added to the main constraint container element, it indicates that the node can be rotated by changing heading.

 

 

<ModelAttachments>

This element is required when you have specified that an attachment is being used in the <LOD /> section of the XML file using the <AttachModel> element. It acts as a container element that will hold one or more <ModelAttachment> element (one for each of the <AttachModel> IDs that have been defined). For more information, please see the page on Model Attachments.

 

<ModelAttachment>

This element is a container for the <AttachToNode> and <Model> elements. Each of these elements should be linked with an <AttachModel> element using the ID attribute.

 

Attribute Description Type Required
id The ID that the model glTF being defined should be linked to. Float Yes

 

<AttachToNode>

This sub-element of the <ModelAttachment> element is used to define the node on the "main" model (as defined in the main <LOD /> element) that the model attachment should be attached to.

 

<Model>

This sub-element of the <ModelAttachment> element is used to give the path to the model XML file of the model being attached. Note that the path is relative to the XML file path where you are defining it.

 

 

<Behaviors>

This element is for defining the different behaviors of the SimObject model using a flexible components system that permits you to use and create templates. This template system relies on a number of "base" templates that have predefined values for different things within a SimObject, with the idea being that you call a template for a specific behavior then use additional XML elements to override only the parts of the template that you require to change for the model being referenced. You can find full details of how this system works from the following page: Model Behaviors

 

 

<ModelBehaviors>

This element was previously used exactly the same as the current <Behaviors> element when used within a [model].xml file, but has since been deprecated in that capacity, and is now exclusively used when defining library files for model behaviors. In this capacity it is used as the root element when creating independent library files for Templates, Input Events and Parameter Functions. These independent files can be referenced using the <Include /> element within the other files and should be formatted like this:

<?xml version="1.0" encoding="utf-8"?>
<ModelBehaviors>
    <!-- Any Further File Includes -->
    <Include ModelBehaviorFile="FILE_PATH" />
    <!-- Templates -->
    <Template Name = "TEMPLATE_NAME">
        <!-- Define Template -->
    </Template>
    <!-- Input Events -->
    <InputEvent ID="INPUT_EVENT_NAME">
        <Presets>
            <!-- Event Presets -->
        </Presets>
    </InputEvent>
    <!-- Parameter Functions -->
    <ParametersFn ID="FUNCTION_NAME">
        <!-- Define Function -->
        <ReturnParameters>
            <!-- Return Parameters-->
        </ReturnParameters>
    </ParametersFn>
</ModelBehaviors>

When creating library files in this way, you can have unique files for each of the types (Templates, Inputs and Fucntions), or you can have them all in a single file, or any combination that you require, as long as the general formatting shown above is maintained.