MODEL XML PROPERTIES
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 XML Examples page.
For an explanation of how this file should be referenced for aircraft, please see here:
And for Scenery, please see here:
<ModelInfo>
This element is a container element for all the model details. This element can contain the following:
<LODS>
<CompileBehaviors>
<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 "
This is only required when the model is for a scenery object. See here for more information: Model XML For Scenery Setup |
String | No |
<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 2024.
If you are in possession of a licensed copy of the Simplygon SDK, then you can make use of the Microsoft Flight Simulator 2024 AutoLod feature for scenery. To use this feature you can add the following attribute to the <LODS>
element, and simply omit the <LOD />
sub-element.
Attribute | Description | Type | Required |
---|---|---|---|
autoGenerate |
When set to "true", the LODs for the scenery object ModelLib will be auto-generated when the package is compiled. By default this is set to "false". |
String |
No |
For more information, please see the following page:
<LOD />
This sub-element of <LODS>
is used to describe a single LOD model. It can be self closing, or it can contain 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 |
No |
minSize |
This is the minimum vertical screen size - expressed as a percentage - of the projected bounding sphere that is required for the LOD to be displayed. Note that the value can be greater than 100%. Please see the LOD Selection System page for more information on this property. Default value is 0. |
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: Submodels And Animations. 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.
<CompileBehaviors>
This element is similar to the <Behaviors>
element and is used 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:
IMPORTANT! This XML element is only for use with the Microsoft Flight Simulator 2024 Asobo_EX1 templates.
The fundamental difference between this element and the <Behaviors>
element is that the XML within will be compiled when the package is built (ie: a non-human readable binary XML file will be created). Compiled XML gives a performance boost, as everything within is pre-processed down to the simplest possible components, mouserects, animations, etc... As such this is the recommended top level element for your XML files. You should only be using <Behaviors>
or <ModelBehaviors>
when there are un-resolvable errors on building the package (this is a possibility with particularly complex templates where the compiler can't reduce the contents down to the simplest level).
NOTE: For information on how compiled behaviors affects the use of the core behavior templates, please see here: Including Template Files
This element has the following attributes:
Attribute | Description | Type | Required |
---|---|---|---|
version |
The version of the simulation for which the file was created, which can be one of the following:
|
Integer / String | Yes |
Revision |
The revision number. | Float | No |
<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:
This element has the following attributes:
Attribute | Description | Type | Required |
---|---|---|---|
version |
The version of the simulation for which the file was created, which can be one of the following:
|
Integer / String | Yes |
Revision |
The revision number. | Float | No |
<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 . 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 Functions), 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.
This element has the following attributes:
Attribute | Description | Type | Required |
---|---|---|---|
version |
The version of the simulation for which the file was created, which can be one of the following:
|
Integer / String | Yes |
Revision |
The revision number. | Float | No |
<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 following sub-elements:
The element takes the following attributes:
Attribute | Description | Type | Required |
---|---|---|---|
Name |
The name of the event of the IK Chain. |
String:
|
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:
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.