GENERAL TEMPLATE DEFINITIONS
On this page you can find a list of the general model behavior XML that is used within the <Behaviors>
element of the [model].xml
file associated with a SimObject. 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 the <Behaviors>
element, and would 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 |
String | Yes |
<Include />
This element is used to read and register the InputEvents, Macros, Templates and Parameter Functions included within the file given in the chosen attribute. This is a self-closing element that is used within the <Behaviors>
element or - for library files - within the <ModelBehaviors>
element. It must have one of the following attributes, and should always be listed at the top of the XML file, or directly after the <Behaviors>
or <ModelBehaviors>
element:
Attribute | Description | Type | Required |
---|---|---|---|
ModelBehaviorFile |
This tells the models.xml to include one of the Microsoft Flight Simulator 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\Common\Engine.xml ". |
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 <Behaviors>
from another [model].xml
file. For example, if you have an aircraft already defined that is very similar to the one you are currently working on, then you can use this element to include the <Behaviors>
from the first aircraft and then modify only those model behaviors that differ in the current aircraft [model].xml
. This is a self-closing element and should be defined at the top of the XML file, or directly after the <Behaviors>
element. 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 RelativeFil
e 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 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\Common\Engine.xml ". |
String | No |
Path |
This is an alias for the ModelBehaviorFile attribute. |
String | No |
File |
This is an alias for the RelativeFile attribute. |
String | No |
<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:
<PartID>
<CameraTitle>
<FX>
<AnimationTriggers>
<Visibility>
<EmissiveFactor>
<Update>
<Animation>
<MouseRect>
<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. | 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: <Offset>
, <ContactPoint>
, <Code>
, <EnableEntries>
, <DisableEntries>
, <OverrideEntries>
, and <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 <SurfaceTypeEntry />
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>
, <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:
|
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.
<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 <Component>
, <Parameters>
, <UseParametersFn>
, <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). 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. |
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. |
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. |
String:
|
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:
|
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 | 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:
In either case, if any parameter is not included in the save file already, it will be appended onto the save. |
String |
No |
<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. |
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 |
<AnimationTriggers>
This element is used within the model behaviors as a trigger for generating a sound effect, es explained in the Animation Sounds Example. It will contain one or more <EventTrigger>
elements and requires one attribute:
Attribute | Description | Type | Required |
---|---|---|---|
Animation | The name of the animation that the sound should play on. | 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 changes 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:
This attribute must be used alone, without a |
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:
|
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:
|
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 camera event to trigger. | String | Yes |