GENERAL TEMPLATE XML PROPERTIES

On this page you can find a list of the general model behavior XML that is used within the <CompileBehaviors> or <Behaviors> element of the principle [model].xml file associated with a SimObject (or within the <ModelBehaviors> of an additional model file). For an overview of the contents of this page please see the following section:

 

 

<Macro>

This element creates a global-scope macro that can be used to name values, strings and code which will then be substituted in at runtime wherever the macro is called. The macro has a "name" attribute, which is the name that should be called in the rest of the model behavior XML to use the macro, and the contents of the element are what will be substituted in instead. Note that when calling a macro name it should be preceded by an @.

 

Macros are usually defined at the top of the XML, directly under one of the following parent elements (see File Structure for information on which top-level element to use where):

  1. <Behaviors>
  2. <ModelBehaviors>
  3. <CompileBehaviors>

 

Macro definitions look something like this:

<Macro Name="IsUsingRelativePos">(M:InputType) 1 ==</Macro>
<Macro Name="DragLockResetTimer">0.05 0.10 @IsUsingRelativePos ?</Macro>
<Macro Name="MyCompany">'TT_COMPANY_NAME_LOCALISED'</Macro>

 

Attribute Description Type Required
Name

The name of the macro, which will be used to call the macro in the rest of the XML. Use the @ symbol before the macro to use it, eg: @on_off_condition

This string must be alpha-numeric, and can only contain the _ or - symbols.

 String Yes

 

 

<Include />

This element is used to read and register the <InputEvent>, <Macro>, <Template> and <ParametersFn> elements included within the file given in the chosen attribute (but not components). This is a self-closing element that is used within the following elements (see File Structure for information on which top-level element to use where):

  1. <Behaviors>
  2. <ModelBehaviors>
  3. <CompileBehaviors>

 

This element must have one of the following attributes, and should always be listed at the top of the XML file, or directly after the parent element:

 

Attribute Description Type Required
ModelBehaviorFile

This tells the models.xml to include one of the Microsoft Flight Simulator 2024 core model behavior definition files. The path will be relative to the ModelBehaviorDefs folder. For example, to include the "Engine.xml" file, then the path supplied to this attribute would be: "Asobo_EX1\Common\Exterior\Templates\Engine.xml". Please see Including Template Files for more information on using this attribute and compiled behaviors.

NOTE: All the core behaviour files for Microsoft Flight Simulator 2024 are in the Asobo_EX1 folder. The core files for Microsoft Flight Simulator 2020 are in the Asobo folder. You should not mix and match templates from both folders. They may work together, but future updates may break this and in general all aircraft for MSFS 2024 should use the Asobo_EX1 templates.

 String No
Path This is an alias for the ModelBehaviorFile attribute. String No
RelativeFile This is for including a file from a path relative to the [model].xml file location. String No
File This is an alias for the RelativeFile attribute. String No

 

 

<IncludeBase />

This element is used to include the components from another [model].xml file, and optionally override them on an individual basis. For example, this is often used when creating presets for aircraft variations as it lets you take a "base" file from a different location (for example the common folder), use all the same components but override the components that are not applicable to the current preset with a different component definition.

 

A simple example is an aircraft that has unique landing gear in a preset, but the rest of the aircraft is the exact same. In this case you would include the base XML and then override the component in the preset model XML, eg: in the base model XML file you would have:

<Component ID="LANDING_GEAR">
    <Component ID="LandingGear_LEFT">
    ...
    </Component>
</Component>

In the preset model XML file you can then overwrite specific components something like this:

<Component OverrideID="LANDING_GEAR:LandingGear_LEFT">
    ...
</Component>

 

This is a self-closing element and should be defined at the top level of the XML file, directly after the any of the following parent elements (see File Structure for information on which top-level element to use where):

  1. <Behaviors>
  2. <ModelBehaviors>
  3. <CompileBehaviors>

 

It has the following attribute:

 

Attribute Description Type Required
RelativeFile This is for including a file from a path relative to the [model].xml file location. String Yes

 

Optionally you may use these attributes instead of the RelativeFile attribute, although these are not generally required:

 

Attribute Description Type Required
ModelBehaviorFile

This tells the models.xml to include one of the Microsoft Flight Simulator 2024 core model behavior definition files. The path will be relative to the ModelBehaviorDefs folder. For example, to include the "Engine.xml" file, then the path supplied to this attribute would be: "Asobo_EX1\Common\Exterior\Templates\Engine.xml". Please see Including Template Files for more information on using this attribute and compiled behaviors.

NOTE: All the core behaviour files for Microsoft Flight Simulator 2024 are in the Asobo_EX1 folder. The core files for Microsoft Flight Simulator 2020 are in the Asobo folder. You should not mix and match templates from both folders. They may work together, but future updates may break this and in general all aircraft for MSFS 2024 should use the Asobo_EX1 templates.

 String No
Path This is an alias for the ModelBehaviorFile attribute. String No
File This is an alias for the RelativeFile attribute. String No

 

For example:

<!-- in BaseFolder -->
<IncludeBase RelativeFile="SubFolder/A.xml"/>
<!-- in BaseFolder/SubFolder -->
<IncludeBase RelativeFile="B.xml"/> <!-- includes BaseFolder/SubFolder/B.xml -->

 

 

<Component>

With this element you can define a component behavior. The contents of this element will depend on the component being defined and the purpose that it is being created for. The main component elements that can be defined are as follows:

  1. <PartID>
  2. <CameraTitle>
  3. <FX>
  4. <AnimationTriggers>
  5. <Visibility>
  6. <EmissiveFactor>
  7. <Update>
  8. <Animation>
  9. <MouseRect>
  10. <UseInputEvent>

 

 

Additionally you can use the <Parameters>, <UseTemplate>, <Condition> and other elements (like the ones that are custom to the template, as explained in the Templates section of the Model Behaviors page). Note that you can create hierarchies of components since you can nest one or more <Component> elements within other <Component>s.

 

This element has the following attributes:

 

Attribute Description Type Required
ID The unique ID for the component. This string must be alpha-numeric, and can only contain the _ or - symbols. String Yes
Node This is the name of the model node (part) that the component should affect. String No
CameraTitle This is the name of a camera to use to highlight an instrument when evaluating a checklist. String No
OverrideID When using an <IncludeBase /> as part of the XML, this lets you create a component that overrides a previously defined component with a a given ID, redefining everything it used to define. String No

 

Note that you may see in some of the XML templates the element <RootComponent>. This is a deprecated element that is now considered an alias for the <component> element as such should not be used for new model behaviors.

 

<PartID>

This node defines an ID used in a checklist for highlighting instruments, and has no attributes. Essentially this creates a link between a name (the PartID) and a node (the component node ID), but note that you can only have a <PartId> element when the component it belongs to has an assigned Node as well. You may have multiple part IDs for a single component ID, and you may also use the same part ID name in multiple components, in which case when an element is highlighted from the part ID (for a checklist, for example), all the components associated with this id - therefore their node and their children in the gltf hierarchy - will be highlighted too.

 

<Update>

This element describes how an animation should be updated based on the given attributes and the RPN that the element contains. This node is used extensively as part of the Model Behaviors templates, in particular the ASOBO_GT_Update template where it is called using the <UPDATE_CODE> custom element. It is usually part of a <Component> definition and can have the following attributes:

 

Attribute Description Type Required
InteractionModel

This specifies whether the update should run during a specific interaction model or not.

Enum:

"Default"

"Drag"

"All"

 Yes
Once This can be used to set whether the update happens only once (set to "true"), or happens repeatedly (set to "false"). Bool No
Frequency This attribute specifies the update frequency in updates per second (Hz).

Float

 No

 

<UpdateFrequencyPreset>

This element permits you to change which update frequency preset a component should be using and is a sub-element of the <Component> element. These presets define how often an animation, VFX, etc... should be updated based on the size on screen of the model (calculated as a Percent Over 100). The frequency itself will be 1 update per game frame for the maximum and 1 update every 30 game frames for the minimum, and the update frequency for models between the min and max size will have an interpolated frequency between 1:1 and 1:30.


The default preset for the update frequency is "Asobo_Default", which will be used if this sub-element is omitted. The presets available by default to you are:

 

Name Size On Screen For
Max Update Frequency		 Size On Screen For
Min Update Frequency		 Size On Screen
To Stop Update
Asobo_Default 1.0 0.01 0.01
Asobo_FrequentWhenSmall 0.01 0.001 0.001
Asobo_RareWhenSmall 1.0 0.1 0.1
Asobo_Default_NeverStop 0.1 0.01 0.0

 

You can find information on how to create your own presets from the following section:

 

<CameraTitle>

This element simply takes a the name of a camera (as a string) to use to highlight an instrument when evaluating a checklist. The element should be included as part of a <Component> and has no attributes.

 

<FX>

This element is used as part of a <Component> definition to create a VFX. It can have the following sub-elements:

  1. <Offset>
  2. <ContactPoint>
  3. <Code>
  4. <EnableEntries>
  5. <DisableEntries>
  6. <OverrideEntries>
  7. <GraphParameters>

 

This element has the following attribute:

 

Attribute Description Type Required
GUID

The GUID of the effect that is being used by the component.

String

 Yes

 

<Offset>

This sub-element of the <FX> element defines the offset in the coordinate system defined by the VFX (in meters). As such it requires the following sub-elements:

Element Description Type Required
<X> Offset on the X axis (meters)

Float

 Yes
<Y> Offset on the Y axis (meters)
<Z> Offset on the Z axis (meters)
<P> Rotation offset of the pitch (degrees)
<B> Rotation offset of the bank (degrees)
<H> Rotation offset of the heading (degrees)

 

<ContactPoint>

This sub-element of the <FX> element defines the contact point to attach the effect to, and you can use -1 for none.

 

<Code>

This sub-element of the <FX> element defines the RPN code to use to spawn the effect. The result of the code will be interpreted as boolean, where if the result is "True" the visual effect is spawned and if it is "False" then it is destroyed.

 

<EnableEntries>

This sub-element of the <FX> element is used to enumerate surface types over which this effect may spawn. This element requires one or more <SurfaceTypeEntry /> sub-elements, and may contain Program Template Definitions to generate dynamic changes.

 

<DisableEntries>

This sub-element of the <FX> element is used to enumerate surface types over which this effect may not spawn. This element requires one or more <SurfaceTypeEntry /> sub-elements, and may contain Program Template Definitions to generate dynamic changes.

 

<OverrideEntries>

This sub-element of the <FX> element is used to define which VFX will replace the one defined by the GUID for the given surface type. This element requires one or more <SurfaceTypeFXEntry /> sub-elements, and may contain Program Template Definitions to generate dynamic changes.

 

<GraphParameters>

This sub-element of the <FX> element is used to define custom parameters with some RPN code and Program Template Definitions which can then be used in the VFX graph (with the VFX editor GraphParameter element).

 

<SurfaceTypeEntry />

This self-closing element is a sub element of <EnableEntries> and <DisableEntries>, and <OverrideEntries>. It defines a surface type, which is set using the following attribute:

Attribute Description Type Required
SurfaceType

A surface type string.

String:

  1. CONCRETE
  2. GRASS
  3. WATER_FSX
  4. GRASS_BUMPY
  5. ASPHALT
  6. SHORT_GRASS
  7. LONG_GRASS
  8. HARD_TURF
  9. SNOW
  10. ICE
  11. URBAN
  12. FOREST
  13. DIRT
  14. CORAL
  15. GRAVEL
  16. OIL_TREATED
  17. STEEL_MATS
  18. BITUMINUS
  19. BRICK
  20. MACADAM
  21. PLANKS
  22. SAND
  23. SHALE
  24. TARMAC
  25. WRIGHT_FLYER_TRACK
  26. OCEAN
  27. WATER
  28. POND
  29. LAKE
  30. RIVER
  31. WASTE_WATER
  32. PAINT
 Yes

 

<SurfaceTypeFXEntry />

This self-closing element is a sub element of <OverrideEntries>. It defines a surface type, which is set using the following attribute:

Attribute Description Type Required
SurfaceType

A surface type string.

String:

  1. CONCRETE
  2. GRASS
  3. WATER_FSX
  4. GRASS_BUMPY
  5. ASPHALT
  6. SHORT_GRASS
  7. LONG_GRASS
  8. HARD_TURF
  9. SNOW
  10. ICE
  11. URBAN
  12. FOREST
  13. DIRT
  14. CORAL
  15. GRAVEL
  16. OIL_TREATED
  17. STEEL_MATS
  18. BITUMINUS
  19. BRICK
  20. MACADAM
  21. PLANKS
  22. SAND
  23. SHALE
  24. TARMAC
  25. WRIGHT_FLYER_TRACK
  26. OCEAN
  27. WATER
  28. POND
  29. LAKE
  30. RIVER
  31. WASTE_WATER
  32. PAINT
 Yes
FXGuid A visual effect GUID to use for this surface type String Yes

 

<Visibility>

This element is usually found as part of a <Component> definition and is used to control the visibility of a Node (and its children) programmatically. As such it requires a <Parameter> sub-element to control the visibility toggle. The Parameter tag can have the following sub-elements:

  • <Code> - If the resulting value of any RPN code supplied is 0, then the target node will be hidden
  • <Sim> - If the value of the SimVar is 0, then the target node will be hidden

 

<EmissiveFactor>

This element is used as part of a <Component> element and sets the component as the target of a material component. A material component is used to control the intensity of an emissive programmatically. As such it requires a <Parameter> sub-element to control the emissive toggle. To turn off an emissive, the resulting value of the parameter code should be 0. The Parameter tag can have the following sub-elements:

  • <Code> - The resulting value of any RPN code supplied will be multiplied with the emissive texture
  • <Sim> - The SimVar value will be multiplied with the emissive texture

 

<UseInputEvent>

This element will call an input event that has been defined already from a template or from the [model].xml using the <InputEvent> element, and is used as part of a <Component>. It has the following attributes:

 

Attribute Description Type Required
ID The ID (name) of the Input Event to use, as defined by the ID attribute of the <InputEvent> element. String Yes

 

For more information on input events, please see the following page:

 

 

<Template>

With this element we initialise a template definition and give it a name. This can then be called using the <UseTemplate> element elsewhere in the XML. The element is used as a container for the template data, which can include:

  1. <Component>
  2. <Parameters>
  3. <UseParametersFn>
  4. <UseTemplate>
  5. <Condition>

 

Other elements (like the ones that are custom to the template, as explained in the Templates section of the Model Behaviors page) may also be included. This element has the following attributes:

 

Attribute Description Type Required
Name This is the name of the template, and is what will be used when calling the <UseTemplate> element. This string must be alpha-numeric, and can only contain the _ or - symbols. String Yes

 

<TemplateAlias>

You can use this element as a sub-element of <Template> and is used to define an alias for the template that is using it. This element has no attributes, and requires a string to be used correctly, for example:

<Template Name="DEPRECATED_Propeller_Anim_Rotation_Template">
    <TemplateAlias>Propeller_Anim_Rotation_Template</TemplateAlias>
</Template>

 

 

<UseTemplate>

This element is used to reference another template. This element has no fixed sub-elements and will generally require the use of the parameters that are created in the template being referenced, some of which may be optional. It has the following attributes:

 

Attribute Description Type Required
Name This is for including a file from a path relative to the [model].xml file location. String Yes

 

 

<InputEvent>

This element is used to retrieve input from the user. The element is used as a container element for <Presets> that will be used to create the the different inputs. It has the following attributes:

 

Attribute Description Type Required
ID The ID (name) of the Input Event being defined. This ID is then used in the <UseInputEvent> element to call the event. This string must be alpha-numeric, and can only contain the _ or - symbols. String Yes

 

This contents of this element are explained in full on the following page:

 

 

<Parameters>

This sub-element is essentially a container for any number of parameters required by other elements - like <Template>, <Component>, or within <Presets> - and it can also be used when working with the XML Programs elements. The element does not require any additional attributes, although it does have the following optional attributes:

 

Attribute Description Type Required
Type

When this attribute is included, you are saying that the parameter sub-elements contained in this element will either be used as default parameters or will override existing parameters.

If not included, the default type is "Default".

String:

  1. "Default"
  2. "Override"
 No
Lifetime This attribute establishes the lifetime of the parameters, and is only relevant when the element is used within a <Loop>. When the attribute is set to "Iteration", the parameters will be created and discarded on each iteration of the loop, while setting it to "Loop" the parameter will be created at the start of the loop, and discarded at the end of all iterations.

String:

  1. "Loop"
  2. "Iteration"
 No

 

It should be noted that in older iterations of the model behavior files and templates the elements <DefaultTemplateParameters> and <OverrideTemplateParameters> were used to contain default and override parameters. However these two elements are now deprecated and you should use the <Parameters> element with the appropriate Type attribute.

 

Any user created parameters called within this element can also have a special Process attribute added to them. This attribute is explained here:

 

<SaveParameters>

This element can be defined anywhere a <Parameters> element can be defined and is used to save the parameters and values it contains to a file. It has the following attributes:

 

Attribute Description Type Required
ID Unique identifier given to the saved parameters. This string must be alpha-numeric, and can only contain the _ or - symbols. String Yes
Append

When this attribute is used, saved parameters will be appened onto the save file. When this attribute is not included, the save file will be wiped before saving. The attribute has two ways to save, identified using the following values:

  • "Default" - When you supply this value, if any parameters have been saved previously, the values will NOT be overwritten by the new value in the save.
  • "Override" - When you supply this value, if any parameter has been saved previously, then it's value will be overwritten by the new value.

In either case, if any parameter is not included in the save file already, it will be appended onto the save.

String

 No

 

For example:

<SaveParameters ID="MySave">
    <A>A_VALUE</A>
</SaveParameters>
<SaveParameters ID="MySave" Append="Override">
    <A>AN_OTHER_VALUE</A>
</SaveParameters>
<!-- MySave contains : -->
<!-- <A>AN_OTHER_VALUE</A> -->

 

<LoadParameters />

This sub element of <Parameters> can be used to load in previously saved parameters and their values (parameters are saved using the <SaveParameters> element). This element is self closing and has the following attribute:

 

Attribute Description Type Required
ID The unique identifier that was given to the saved parameters when they were saved. String Yes

 

<RemoveSavedParameters />

This element can be defined anywhere a <Parameters> element can be defined and is used to wipe previously saved parameters and their associated values (parameters are saved using the <SaveParameters> element). This element is self closing and has the following attribute:

 

Attribute Description Type Required
ID The unique identifier that was given to the saved parameters when they were saved. String Yes

 

 

<ParametersFn>

This element is similar to the <Template> element, in that it permits you to create a reusable XML for use in your model behaviors. The element can takes a list of parameters as the input, perform operations on these inputs using XML Programs, and then return one or more parameters as the ouput. This is a container element for <Parameters>, <ReturnParameters>, and XML Programing elements, and requires a unique name, and you can have multiple parameter functions defined. This name is what would be used to reference the function in other parts of the model behavior XML.

 

Attribute Description Type Required
Name This is the name of the parameter function, and is what will be used when calling the <UseParametersFn> element. This string must be alpha-numeric, and can only contain the _ or - symbols. String Yes

 

For more information on how to use this element please see the following section:

And for examples of use, please see here:

 

<ReturnParameters>

This element is used to define one or more return parameters from a <ParametersFn> element. This element can also contain further parameter function calls using the <UseParametersFn> as well as XML Programing elements.

 

 

<UseParametersFn>

This element is used to call a previously defined parameter function, and can itself serve as a container for parameters. The function named by this element should have been created already using the <ParametersFn> element.

 

Attribute Description Type Required
Name This is the name of the previously defined parameter function that is being used. String Yes

 

 

<DynamicParameters>

This container element is used to define one or more fallback dynamic parameters for substitution within the XML and will be used as part of the merge process for a modular aircraft. The element has no attributes, and is used to define dynamic parameter elements as follows:

<DynamicParameters>
    <PARAM_NAME>'string'_n</PARAM_NAME>
    <PARAM_NAME><value></PARAM_NAME>
</DynamicParameters>

Each element in the <DynamicParameter> container is a new parameter that can then be used as a reference to the "alias" contained within. Note that the alias must always be supplied in single quotes '' followed by _n. For example:

<DynamicParameters>
    <CIRCUIT_NAME>'Screen'_n</CIRCUIT_NAME>
    <VOLTAGE>200</VOLTAGE>
</DynamicParameters>

You can then use this dynamic parameter elsewhere in the XML by referencing it between [], eg:

(A:CIRCUIT ON:[CIRCUIT_NAME]) // Get the state of the circuit called Screen

For more information, please see the following section:

 

 

<AnimationTriggers>

This element is used within the model behaviors to react to an animation change either by sending a simple event or a sound event, as explained in the Animation Sounds Example. It will contain one or more <EventTrigger> elements and requires one attribute:

 

Attribute Description Type Required
Animation The target animation name for the event. String Yes

 

<EventTrigger>

This is a sub-element of <AnimationTriggers> and is a container for the <SoundEvent /> element (which plays a sound) or the <EffectEvent /> element (which is a simple event, like changing the camera). This element has the following attributes:

 

Attribute Description Type Required
NormalizedTime This is the normalized time of the animation from which the sound will play. It's going from 0 to 1. This attribute must be used alone, without a Count or Frame attribute. Float No
Count

This attribute divides the animation timeline in equal segments by the value given. Sounds will play at the middle of each segment. e.g:

  • If the value is 2 the sound will play when the animation timeline reaches 25% and 75%.
  • If the value is 5 the sound will play when the animation timeline reaches 10%, 30%, 50%, 70% and 90%.

This attribute must be used alone, without a NormalizedTime or Frame attribute.

 Integer No
Frame This is the frame of the animation where the sound will be played. This attribute must be used alone, without a Count or NormalizedTime attribute. Integer No
Direction This attribute determines the direction of the animation timeline in which the sound will be played.

String:

  1. "Forward"
  2. "Backward"
  3. "Both"
 Yes

 

<SoundEvent />

This is a self-closing sub-element of <EventTrigger> and is what sets the sound to be triggered. This element has the following attributes:

 

Attribute Description Type Required
WwiseEvent This is the event that the sound is triggered on and should be the same as that defined for the sound in the sound.xml. String Yes
Action Whether to play or stop the sound. The stop value is useful when dealing with looping sounds.

String:

  1. "Play"
  2. "Stop"
 Yes

 

<EffectEvent />

This is a self-closing sub-element of <EventTrigger> and is used to trigger a camera event. This element has the following attribute:

 

Attribute Description Type Required
Name The name of the simple event to trigger. String Yes

 

Related Topics

  1. Aircraft XML and Model CFG
  2. Model Behaviors
  3. Using Model Behaviors
  4. Template Explorer