# Animation XML Properties<no value>
This section is dedicated to the XML elements related to model animation. These elements can be used as part of the `[model].xml` file, or as a separate `animations.xml` file. If any animations are being defined for a single model then you would normally include these elements within the actual `[model].xml`, but if you wish to share animations across multiple models, then you would set up an `animations.xml` file, formatted as follows:

``` xml
<?xml version="1.0" encoding="UTF-8"?>
<ModelInfo version="1.1" guid="">
    <Animation>
        <Event time="1" name="Event_Name"/>
    </Animation>
    
    <AnimGraph>
        <DefaultState name="Default_State_Name"/>
        <BlendTreeState name="Idle">
          <Animations>
            <Animation guid="" loop ="True/False" speed="1"/>
          </Animations>
          <Events>
            <Event time="1" name="Event_Name"/>
          </Events>      
        </BlendTreeState>
        
        <Transition start="Start_Animation" end ="End_Animation">
          <Condition>  </Condition>
        </Transition>
        
    <AnimGraph>
</ModelInfo>
```

This file would be placed in the same location as the `sim.cfg` file or `aircraft.cfg` that will be using the animations, and there should be an "animations" folder in the same directory, for example:  
![Files And Folders Required For Shared Model Animations](images/5_Content_Config/Models/model_anim_folders.png) Note that the elements listed here can also be used within the `<Behaviors>` element of the `[model].xml` to define animations as part of the [Model Behaviors](modelbehaviors/model-behaviors/), or as part of a `<Component>` definition.

 

 

### &lt;Animation&gt;

This element is the root entry of any behavior. It defines the name the of the model animation and the behavior it should be linked to. It can contain the `<Event />` sub-element and has the following parameters:

 

<table><thead><tr class="header"><th>Attribute</th><th>Description</th><th>Type</th><th>Required</th></tr></thead><tbody><tr class="odd"><td><code>name</code></td><td>A unique name for the new animation. It should not contain any spaces or punctuation, but can contain underscores and numeric digits.</td><td>String</td><td>Yes</td></tr><tr class="even"><td><code>guid</code></td><td>The unique <a href="#" class="glossterm">GUID</a> for the animation. This is the reference the simulation will use to identify the animation, and must be in the format "<code>{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx}</code>", all lower case, e.g: "<code>{12f06ee8-11ce-4e7b-a715-a9c5deb5352f}</code>".</td><td>String</td><td>Yes</td></tr><tr class="odd"><td><code>length</code></td><td>This is used only for "Sim" animations, and exists for backwards compatibility. It is not necessary to specify this if you specify the <code>&lt;AnimLength&gt;</code> element of a <code>&lt;PartInfo&gt;</code> animation.</td><td>Float</td><td>No</td></tr><tr class="even"><td><code>type</code></td><td>Defines the type of animation. Standard animations are simpler to define and not typically driven by aircraft controls. Sim animations are usually linked to Simulation Variables, see the section on <code>&lt;PartInfo&gt;</code> below for more information.</td><td><p>Enum:</p><ol><li>"<strong>Standard</strong>"</li><li>"<strong>Sim</strong>"</li></ol></td><td>Yes</td></tr><tr class="odd"><td><code>typeParam</code></td><td><p>This is used to set the animation play property for the different animation types. You can uses either or both of the available options, eg:</p><pre class="language-cpp"><code>typeParam = &quot;Autoplay&quot;
typeParam = &quot;Autoplay,Random&quot;</code></pre></td><td><p>String :</p><ol><li>"<strong>AutoPlay</strong>" - the animation will run when the object is rendered</li><li>"<strong>Random</strong>" - the animation will be started at a random point along its timeline</li><li><p>"<strong>FrameRate</strong>" - The FrameRate <em>reference</em> value, where the default value is 18fps. This is essentially a scalar of 1, so if you set the FrameRate to 36fps the animation would be played at double the speed, or at 9fps to play at half speed. Note that if you use this type, then you <em>must</em> also use the <code>length</code> attribute, for example:</p><pre class="language-xml"><code>&lt;Animation length=&quot;100&quot; name=&quot;CubeAction&quot; guid=&quot;16DEA026-A609-42EA-B820-211C951CA8CB&quot; type=&quot;Standard&quot; typeParam=&quot;AutoPlay,FrameRate=36&quot; /&gt;</code></pre></li></ol></td><td>No</td></tr></tbody></table>

 

 

### &lt;NodeAnimation&gt;

This element is currently used for advanced "wingflex" bone animation. It animates the positions of several nodes in three dimensions. For this to have the desired effect, the nodes should be the joints of a skeleton that skins the wings and the nodes are hard-coded to a limit of 12 with the following order:

 

{{< table-wrapper >}}

| Order | Node Position                                             |
|:-----:|-----------------------------------------------------------|
|   0   | the left wing bone closest to the center                  |
|   1   | in between                                                |
|   2   | in between                                                |
|   3   | the left wing bone furthest from the center               |
|   4   | the right wing bone closest to the center                 |
|   5   | in between                                                |
|   6   | in between                                                |
|   7   | the right wing bone furthest from the center              |
|   8   | the left wing engine pivot node closest to the center     |
|   9   | the left wing engine pivot node furthest from the center  |
|   10  | the right wing engine pivot node closest to the center    |
|   11  | the right wing engine pivot node furthest from the center |

{{< /table-wrapper >}}


 

The element has the sub-element `<Node />` and takes the following attribute:

 

<table><thead><tr class="header"><th>Attribute</th><th>Description</th><th>Type</th><th>Required</th></tr></thead><tbody><tr class="odd"><td><code>type</code></td><td>The type of node animation to use (currently only 1 type is available)</td><td><p>Enum:</p><p>"WingFlex"</p></td><td>Yes</td></tr></tbody></table>

 

 

#### &lt;Node /&gt;

This self-closing element is a sub-element of `<NodeAnimation>` and is used to define the 12 different wingflex nodes on the model for the aircraft (one `<Node />` element per wingflex node).

 

 

### &lt;AnimationEvent&gt;

This element describes a moment in time when the animation reaches a certain point. Note that it is sensitive to the direction in which the animation changes, and by default an event only fires when an animation value *increases*. It can have `<Time>` and `<IsNormalPlayback>` sub-elements, and takes the following attributes:

 

{{< table-wrapper >}}

| Attribute       | Description                                                                                                                                | Type   | Required |
|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------|--------|:--------:|
| `EventName`     | The name of the event, which can be used by other parts of Microsoft Flight Simulator 2024, like missions. | String |    Yes   |
| `AnimationName` | The name of the animation this event links to.                                                                                             | String |    Yes   |

{{< /table-wrapper >}}


 

 

#### &lt;Time&gt;

This is a sub-event of `<AnimationEvent>` and is used for setting the time - as a percentage of the animation duration - at which this event should trigger. An animation can have several `<Time>` elements, in which case the event will fire on all those occasions. Note that some animations contain several parts. For example, the gear animations have the retraction in the first half and the suspension in the second half. This element has no attributes.

 

 

#### &lt;IsNormalPlayback&gt;

This is a sub-event of `<AnimationEvent>`. If this is set to False (0), the animation event will trigger when the animation value *decreases* instead. The default value is True (1).

 

 

### &lt;AnimGraph&gt;

This element is a container element that is used to hold the various elements used to define one or more animations for a model, as well as how those animations should transition together based on specific conditions. It can contain the following sub-elements:

1.  `<DefaultState />`
2.  `<BlendTreeState>`
3.  `<Transition>`

 

Alternatively you may also provide one or more `<Layer>` elements, to create multiple layers of blend-trees.

 

The AnimGraph system is mostly used by [Living Thing](../modular-simobjects/simobjects/living-things/) SimObjects: a complex example would the airport Marshaller, while a more simple example would be an animal walking around. The `<AnimGraph>` will contain at least two or more `<BlendTreeState>` elements, each with a unique name. It will also contain a `<DefaultState />` (that references a `<BlendTreeState>`), and one or more `<Transition>` elements to control the change between two blendtree states.

 

Each `<BlendTreeState>` has at least one animation - but can have more - and these animations can be used by several `<BlendTreeState>` elements if required. A `<BlendTreeState>` element also specifies whether an animation should loop or not, which means you can have two `<BlendTreeState>` elements for the same animation, with one looping while the other does not. Switching between these blendtree states is done using the `<Transition>` element, which **must** be specified for it to be possible to go from one blendtree state animation to another.

 

 

### &lt;DefaultState /&gt;

This is a self closing element that sets a default model animation state. The element should be included as part of an `<AnimGraph>` or a `<Layer>` and has the following attributes:

 

{{< table-wrapper >}}

| Attribute | Description                                                                                                                                                                                                                                                                                                                                                                 | Type   | Required |
|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------|:--------:|
| `name`    | The name of the blend-tree state that should be used as the default animation state for the model.                                                                                                                                                                                                                                                                          | String |    Yes   |
| `weight`  | This attribute is only used when the default state is part of a `<Layer>`. It sets the weighted chance of this layer default state being used over any other, and is expressed as a {{< glossterm >}}percent_over_100{{< /glossterm >}}. If you have two layers and one has a weight of 0.75 and the other 0.25, then the chances of getting the first default state is 3:4. | Float  |    No    |

{{< /table-wrapper >}}


 

 

### &lt;BlendTreeState&gt;

This element is used to define one or more animation states that can be used for animating the model. These states can be blended together using the `<Transition>` element, and can have the following elements used as sub-elements to further control how and when the animation will be played:

1.  `<Animations>`
2.  `<Events>`
3.  `<Value>`

 

This element is used within the main `<AnimGraph>` container or within a `<Layer>` and has the following attribute:

 

{{< table-wrapper >}}

| Attribute | Description                                                                                                                                                                                                                                                                                                                                                                                                                                | Type    | Required |
|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|:--------:|
| `Name`    | The name of the animation state that is being defined.                                                                                                                                                                                                                                                                                                                                                                                     | String  |    Yes   |
| `doBlend` | When set to "TRUE", the `<Value>` element should be included to tell the simulation to use the value to decide which animations to blend (based on the `threshold` attribute in the listed `<Animation>` elements). If this is set to "FALSE", then animations will only change when the current one is finished playing, and the subsequent animation to use will be chosen at random, based on the `weight` attribute for the animation. | Boolean |    No    |

{{< /table-wrapper >}}


 

 

#### &lt;Value&gt;

This element is used to set a value which will be used to switch between the different animations in the blend state. Values are calculated using [Reverse Polish Notation](../../programming-apis/reverse-polish-notation/), for example:

``` xml
<Value>(A:GROUND VELOCITY, METERS PER SECOND)</Value>
```

 

 

### &lt;Animations&gt;

This is a container element for one or more of the `<Animation>` sub-elements and is used inside a `<BlendTreeState>` element. It has no attributes.

 

 

#### &lt;Animation&gt;

This sub-element defines how a single animation - based on the supplied animation GUID - should be performed. The attributes that control the animation within this element are:

 

{{< table-wrapper >}}

| Attribute        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Type   | Required |
|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------|:--------:|
| `guid`           | The animation GUID to reference (as defined by the main `<Animation>` element).                                                                                                                                                                                                                                                                                                                                                                               | String |    Yes   |
| `loop`           | Whether the animation should loop (True) or not (False).                                                                                                                                                                                                                                                                                                                                                                                                      | Bool   |    Yes   |
| `speed`          | The animation speed scalar. When set to 1 the animation will play at the original speed. Lower values will slow the animation and higher values will speed it up, eg: 0.5 would play it at half speed and 2.0 would play it at double speed.                                                                                                                                                                                                                  | Float  |    Yes   |
| `weight`         | This sets the "weight" of the animation for when the `<BlendTreeState>` element has set the `doBlend` attribute to "FALSE". When an animation has ended, this value is used to choose the next random animation to play, "weighted" towards the ones with the higher value. This value should be between 0 and 1, where the higher the value, the more likely the animation is to be chosen.                                                                  | Float  |    No    |
| `threshold`      | This is the threshold value for choosing an animation based on the returned `<Value>` for the `<BlendTreeState>` element. If the value is between 2 consecutive thresholds, the 2 corresponding animations are blended together with weight depending on how close the value is to each threshold. If the value is more than the last threshold, the last animation is used. See the [&lt;BlendTreeState&gt; Example](model-xml-examples/#BlendTreeState). | Float  |    No    |
| `FireEventOnEnd` | This is used to notify the end of an animation for a `<SimMission.PlayBlendTreeStateAction>` to become "complete". This means that if the `<SimMission.PlayBlendTreeStateAction>` is set with `<Immediate>False</Immediate>`, it will wait until the end of the animations from the `<BlendTreeState>` element that do have this set to "True", before continuing to the next action.                                                                         | Bool   |    No    |

{{< /table-wrapper >}}


 

 

### &lt;Transition&gt;

The `<Transition>` element is a container element for the `<Condition>` sub-element and is designed to create a transition between two different `<BlendTreeState>` animations. This element is a child of the main `<AnimGraph>` or `<Layer>` elements.

 

When creating transitions between states, you can have them work in four different ways depending on the attributes and elements that are set for it:

-   A transition *without* any `<Condition>` element *nor* an `ExitTime` attribute will be considered as "**manual**". This means that it will *only* be executed when some code or script requests a different `<BlendTreeState>` and the following conditions are met: the requested state is the defined `end` state of the transition, and the currently playing animation matches the `start` state animation.
-   The following are all considered as "**automatic**" transitions:
    -   A transition *with* a `<Condition>` but *without* an `ExitTime` attribute will be automatically executed if the `<Condition>` resolves as true and the `start` state is the current one.
    -   A transition *with* an `ExitTime` attribute and *no* `<Condition>` will be automatically executed when the animation from the `start` state reaches a certain ratio of the animation. For example, an `ExitTime` of 1.0 will start the transition immediately at the end of the current animation. A value of 0.5 will start at half the duration of the current animation. A value of 2.5 will start after two and a half (looped) iterations of the current animation.
    -   A transition with *both* an `ExitTime` *and* a `<Condition>` will be automatically executed when both the `<Condition>` resolves as true and the `ExitTime` value has been reached.

 

{{< callout context="note" title="NOTE" icon="outline/bulb" >}}

"Automatic" transitions cannot be controlled by code or script, and should only be used when the transition is expected to **always** happen after some time/condition, no matter what the circumstances.

{{< /callout >}}

 

Some notes on triggering transitions:

1.  when using the `<Condition>` element, if the current state is the `start` one from the transition, the code in the `<Condition>` is evaluated every frame, and if it resolves as true, then the transition triggers.
2.  using a `<SimMission.PlayBlendTreeStateAction>` in a mission/script file to ask an animation to go to state *X*. This will search for a transition going from the current state to state *X*, and will trigger that transition if it is found (if no such transition exists, the action will do nothing).
3.  When using an `ExitTime` greater than 0, you are setting a "ratio" that will trigger the transition automatically once the animation from the `start` state has reached that far in the animation. For example:
    -   if you set `ExitTime="0.5"`, the transition will trigger when the animation is halfway through, and the animation keeps going - blended with the new one - during the transition duration as usual.
    -   if you set `ExitTime="3.0"` - and the animation is set to loop - then the transition will automatically trigger after 3 loops.

 

The element has the following attributes:

 

{{< table-wrapper >}}

| Attribute  | Description                                                                                                            | Type   | Required |
|------------|------------------------------------------------------------------------------------------------------------------------|--------|:--------:|
| `start`    | The name of the start animation (the one to transition *from*), as defined by the `<BlendTreeState>` "Name" attribute. | String |    Yes   |
| `end`      | The name of the end animation (the one to transition *to*), as defined by the `<BlendTreeState>` "Name" attribute.     | String |    Yes   |
| `duration` | The duration of the transition, in seconds.                                                                            | Float  |    No    |
| `ExitTime` | The time ratio for when the transition should trigger (see the information given above for more details)               | Float  |    No    |

{{< /table-wrapper >}}


 

 

#### &lt;Condition&gt;

This element is for defining a conditional expression that will be evaluated every frame to see if the parent `<Transition>` should be triggered or not. The condition should be written using [Reverse Polish Notation](../../programming-apis/reverse-polish-notation/), for example:

``` xml
<Condition>(A:SURFACE RELATIVE GROUND SPEED, METERS PER SECOND) 0.1 &gt;</Condition>
```

 

 

### &lt;Layer&gt;

This is an advanced feature that can be used to assign different blend-tree states to different layers within the model and as such have various animations playing independently of each other. The intended use of the layers system is to have each layer corresponding to an independent part of the model, so that their animations do not conflict. For example, you could have a layer controlling the legs and lower body of a Human model, another layer for the arms and upper body, and a third layer for the head. Each layer could then be in a different state : legs walking or not, arms idle or doing some animation, face looking happy or sad or talking, etc...

 

This element can contain the following sub-elements:

1.  `<DefaultState />`
2.  `<BlendTreeState>`
3.  `<Transition>`

 

The element has the following attributes:

 

{{< table-wrapper >}}

| Attribute | Description                                                                                                                                                               | Type   | Required |
|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------|:--------:|
| `name`    | The name of the layer.                                                                                                                                                    | String |    Yes   |
| `weight`  | This can can be used to determine how to blend several layers together if they happen to conflict with one another or with Model Behavior animations. Default value is 1. | Float  |    No    |

{{< /table-wrapper >}}


 

 

### &lt;Events&gt;

This is a container element for the `<Event />` sub-element which is used to define animation events within a `<BlendTreeState>` element. It has no attributes.

 

 

#### &lt;Event /&gt;

This is a sub-element of the `<Events>` container element - and also the `<Animation>` element - and is used to set the timing of specific animation events that are used in world scripts (usually for flora/fauna SimObjects in the world), or as events to be performed when an animation has ended (as used in `<BlendTreeState>` elements). It is a self-closing element that has the following attributes:

 

{{< table-wrapper >}}

| Attribute | Description                                                                                  | Type    | Required |
|-----------|----------------------------------------------------------------------------------------------|---------|:--------:|
| `time`    | The time that the event should trigger. This is a **frame number**, and should start from 0. | Integer |    Yes   |
| `name`    | The name of the animation this event links to.                                               | String  |    Yes   |

{{< /table-wrapper >}}


 

 

### &lt;PartInfo&gt;

This element is used to link animations and there should be one of these elements for every `<Animation>` of the type "`Sim`". The element takes no parameters, and is a container for multiple sub-elements:

1.  `<Name>`
2.  `<Copy>`
3.  `<AnimLength>`
4.  `<Animation>`
5.  `<Parameter>`
6.  `<MouseRect>`

 

Please see the page [model.cfg Examples](model-cfg-examples/) for examples of how this element is used.

{{< callout context="caution" title="IMPORTANT!" icon="outline/alert-triangle" >}}

This - and the sub-elements it contains - is a **legacy** element and should not be used, nor is it required, for custom SimObjects made for Microsoft Flight Simulator 2024.

{{< /callout >}}

 

 

#### &lt;Name&gt;

This is a sub-element of `<PartInfo>` and is the name of the animation from the `<Animation>` element. This element has no attributes.

 

 

#### &lt;Copy&gt;

This is a sub-element of `<PartInfo>`. One `<PartInfo>` entry can serve as a template for another. For example if the two have very similar animations but reference a different variable, the second can copy the first, but a new `<Variable>` entry will override the first. This element has no attributes.

 

 

#### &lt;AnimLength&gt;

This is a sub-element of `<PartInfo>`. In FSX, this was the length of the animation in frames. In Microsoft Flight Simulator 2024, this variable is only used to scale the output of `<Parameter>` blocks that contain either `<Code>` or `<Sim>` sub-elements. The output divided by the `<AnimLength>` should be a value between 0 and 1, which is then multiplied with the length of the model animation to get the correct animation position. If the divided output value is not between 0 and 1, it will be clamped. This element has no attributes.

 

 

#### &lt;Animation&gt;

This is a sub-element of `<PartInfo>` and describes how the part will animate. It can contain the `<Parameter>` sub-element and has no attributes.

 

 

### &lt;Parameter&gt;

This is a sub-element of either the `<Animation>` or `<Component>` elements and is a container element for `<Code>` or `<Sim>` sub-elements, with the optional `<Lag>` elements being available too. It has no attributes.

 

 

#### &lt;Lag&gt;

This sub-element of `<Parameter>` can be used to introduce a lag amount. A lag can be used so that a part will not jump instantaneously from one state to the next. Lag is measured in the maximum number of keyframes per second. So, for example: if the animation frame length is 50, and the lag is set to 400, the animation will take a minimum of 50/400 or one eighth of a second to complete.

 

 

#### &lt;Code&gt;

This sub element of `<Parameter>` can contain a reference to a script for evaluation.

 

 

#### &lt;Sim&gt;

This sub-element of `<Parameter>` must contain a `<Variable>` entry for the animation to reference, along with `<Units>`, `<Scale>`, and `<Bias>` entries.

{{< callout context="note" title="NOTE" icon="outline/bulb" >}}

Simvar scale and bias is applied as follows - `Value = SimvarValue * Scale + Bias`

{{< /callout >}}

 

 

##### &lt;Variable&gt;

This is a sub-element of `<Sim>` (and also `<CallbackDragging>`) and takes the name of the simulation variable being referenced. Note that the usual notation (`A:SimVarName`) is simplified to just the variable name for this entry. If the variable has an index value that you wish to pass through as well, then the format would be: `SimVarName:INDEX`.

 

 

##### &lt;Units&gt;

This is a sub-element of `<Sim>` (and also `<CallbackDragging>`) and sets the units of the variable. The page on Simulation Variables lists all the available units: [Simulation Variable Units](../../programming-apis/simvars/simulation-variable-units/)

 

 

##### &lt;Scale&gt;

This is a sub-element of `<Sim>` (and also `<CallbackDragging>`) and is used to scale the value returned by the variable. When dealing with animation, the result is the offset into the keyframes, for example: a boolean value of 0 or 1 scaled by 50, will result in keyframe 0 being used for the `FALSE` state, and keyframe 50 for the `TRUE` state.

 

 

##### &lt;Bias&gt;

This is a sub-element of `<Sim>` (and also `<CallbackDragging>`). When dealing with animation, if the value returned and scaled does not fall into the desired range for the keyframes (for example, the range -50 to +50), then a bias can be added to all values to indicate which keyframe to use. A bias of 50 in this example will adjust the range to 0 - 100.

 

 

### &lt;MouseRect&gt;

This is used within the model behavior `<Template>` and `<Component>` elements, and can also be seen as a sub-element of the deprecated `<PartInfo>`. It is a container element used to define how the user interacts with an animated part. It has no attributes and can contain the following elements:

1.  `<Cursor>`
2.  `<IMCursorsInstances>`
3.  `<IMMouseFlagsInstances>`
4.  `<IMTooltipsInstances>`
5.  `<Disabled>`
6.  `<DisabledInVr>`
7.  `<Lock>`
8.  `<LockFlagsTemporary>`
9.  `<HighlightNodeId>`
10. `<HelpID>`
11. `<TooltipID>`
12. `<MouseFlags>`
13. `<IgnoreZTest>`
14. `<PrioritizeVCockpits>`

 

Note that you may also have one, and *only* one, of the following sub-elements in the `<MouseRect>` (they are mutually exclusive):

1.  `<CallbackCode>`
2.  `<CallbackDragging>`
3.  `<CallbackJumpDragging>`
4.  `<EventID>`

 

 

#### &lt;Cursor&gt;

This is a sub-element of the `<MouseRect>` element, and has no attributes. It is used to define the shape of the cursor when the mouse is over the rectangle. The contents of this element should be one of the following strings:

1.  
2.  `None`
3.  `Normal`
4.  `UpArrow`
5.  `DownArrow`
6.  `LeftArrow`
7.  `RightArrow`
8.  `Hand`
9.  `Crosshair`
10. `Grab`
11. `GrabOpen`
12. `TurnLeft`
13. `TurnRight`
14. `TurnLeft_Small`
15. `TurnRight_Small`
16. `TurnLeft_UpSideDown`
17. `TurnRight_UpSideDown`
18. `UpDownArrows`
19. `LeftRightArrows`
20. `DiagonalArrows`
21. `Lock`
22. `Dynamic`
23. `AnimTip`

 

 

#### &lt;IMCursorsInstances&gt;

This is a sub-element of the `<MouseRect>` element and has no attributes. It is a container element for the sub-elements listed below. It is used to specify different cursor setups depending on whether the active interaction model is **legacy** or **modern**. The element can have either or both of the two following sub nodes:

-   `<IMDefault>` - The cursor definitions for the legacy interaction model
-   `<IMDrag>` - The cursor definitions for the modern interaction model

 

If no `<IMDrag>` is specified but an `<IMDefault>` is, the `<IMDefault>` specification will be used for both the legacy and modern interactions.

 

 

#### &lt;IMMouseFlagsInstances&gt;

This is a sub-element of the `<MouseRect>` element and has no attributes. It is a container element for the sub-elements listed below. It is used to specify different mouse flags depending on whether the active interaction model is **legacy** or **modern**. The element can have either or both of the two following sub nodes:

-   `<IMDefault>` - The mouse flags for the legacy interaction model
-   `<IMDrag>` - The mouse flags for the modern interaction model

 

If no `<IMDrag>` is specified but an `<IMDefault>` is, the `<IMDefault>` specification will be used for both the legacy and modern interactions.

 

 

#### &lt;IMTooltipsInstances&gt;

This is a sub-element of the `<MouseRect>` element and has no attributes. It is a container element for the sub-elements listed below. It is used to specify different tooltip setups depending on whether the active interaction model is **legacy** or **modern**. The element can have either or both of the two following sub nodes:

-   `<IMDefault>` - The tooltip definitions are for the legacy interaction model
-   `<IMDrag>` - The tooltip definitions are for the modern interaction model

 

If no `<IMDrag>` is specified but an `<IMDefault>` is, the `<IMDefault>` specification will be used for both the legacy and modern interactions.

 

 

##### &lt;IMDefault&gt;

This sub-element has no attributes and is used to define certain **legacy interaction ** behaviours, and it's contents will depend on the parent element:

 

-   `<IMCursorsInstances>` - When this is the parent, `<IMDefault>` will be a container for the `<CursorLeft>`, `<CursorRight>`, `<CursorUp>`, `<CursorDown>`, `<CursorCenter>`, `<Cursor>`, and `<CursorCenterRadius>`, elements.

 

-   `<IMMouseFlagsInstances>` - The content of the `<IMDefault>` element is a combination of mouse flags separated by the {{< button "+" />}} character. Mouse flags listed will be registered as valid events from all legacy user interactions. For a full list of flags, please see here: `<MouseFlags>`.

 

-   `<IMTooltipsInstances>` - The content of the `<IMDefault>` element will be one of the following:
    -   `<HelpID>` - An ID linked to a localization string or Help string.
    -   `<TooltipID>` - Tooltip RPN sample defining a tooltip string. For the included strings please see here: [ToolTip Text IDs](modelbehaviors/tooltip-text-ids/)
    -   `<Animated>` - Define an animated tooltip using [RPN](../../programming-apis/reverse-polish-notation/) and [Program Template XML Properties](modelbehaviors/program-template-xml-properties/).

 

-   `<IMCodeInstances>` - The content of the `<IMDefault>` element will be an [RPN](../../programming-apis/reverse-polish-notation/) code node used to define the callback.

 

##### &lt;IMDrag&gt;

This sub-element has no attributes and is used to define certain **modern interaction** behaviours, and it's contents will depend on the parent element:

 

-   `<IMCursorsInstances>` - When this is the parent, `<IMDrag>` will be a container for the `<CursorLeft>`, `<CursorRight>`, `<CursorUp>`, `<CursorDown>`, `<CursorCenter>`, `<Cursor>`, and `<CursorCenterRadius>`, elements.

 

-   `<IMMouseFlagsInstances>` - The content of the `<IMDrag>` element is a combination of mouse flags separated by the {{< button "+" />}} character. Mouse flags listed will be registered as valid events from all modern user interactions. For a full list of flags, please see here: `<MouseFlags>`.

 

-   `<IMTooltipsInstances>` - The content of the `<IMDrag>` element will be the following:
    -   `<TooltipEntries>` - Defines which information should be displayed when the cursor is hovering over the interaction box.

 

-   `<IMCodeInstances>` - The content of the `<IMDrag>` element will be an [RPN](../../programming-apis/reverse-polish-notation/) code node used to define the callback.

 

 

##### &lt;CursorLeft&gt;

This is a sub-element of `<IMDefault>` or `<IMDrag>` (when those elements are children of `<IMCursorsInstances>`) and it has no attributes. It defines the cursor type displayed when the cursor is hovering over the left side of the interaction box. See the `<Cursor>` element for the list of cursor types that can be used.

 

 

##### &lt;CursorRight&gt;

This is a sub-element of `<IMDefault>` or `<IMDrag>` (when those elements are children of `<IMCursorsInstances>`) and it has no attributes. It defines the cursor type displayed when the cursor is hovering over the right side of the interaction box. See the `<Cursor>` element for the list of cursor types that can be used.

 

 

##### &lt;CursorUp&gt;

This is a sub-element of `<IMDefault>` or `<IMDrag>` (when those elements are children of `<IMCursorsInstances>`) and it has no attributes. It defines the cursor type displayed when the cursor is hovering over the top side of the interaction box. See the `<Cursor>` element for the list of cursor types that can be used.

 

 

##### &lt;CursorDown&gt;

This is a sub-element of `<IMDefault>` or `<IMDrag>` (when those elements are children of `<IMCursorsInstances>`) and it has no attributes. It defines the cursor type displayed when the cursor is hovering over the bottom side of the interaction box. See the `<Cursor>` element for the list of cursor types that can be used.

 

 

##### &lt;CursorCenter&gt;

This is a sub-element of `<IMDefault>` or `<IMDrag>` (when those elements are children of `<IMCursorsInstances>`) and it has no attributes. It defines the cursor type displayed when the cursor is hovering in the middle of the interaction box. See the `<Cursor>` element for the list of cursor types that can be used.

 

 

##### &lt;Cursor&gt;

This is a sub-element of `<IMDefault>` or `<IMDrag>` (when those elements are children of `<IMCursorsInstances>`) and it has no attributes. It defines the cursor type displayed when the cursor is hovering over any part of the interaction box. See the `<Cursor>` element for the list of cursor types that can be used.

 

 

##### &lt;CursorCenterRadius&gt;

This is a sub-element of `<IMDefault>` or `<IMDrag>` (when those elements are children of `<IMCursorsInstances>`) and it has no attributes. It defines the radius of the cursor detection area. This is a value between 0 and 1, essentially calculated as the {{< glossterm >}}percent_over_100{{< /glossterm >}} of the screen size.

 

 

##### &lt;Animated&gt;

This sub-element is only used by the `<IMDefault>` element, and is used to define an animated cursor and/or tooltip. This is done using the [Program Template XML Properties](modelbehaviors/program-template-xml-properties/) and [RPN](../../programming-apis/reverse-polish-notation/).

 

 

#### &lt;Disabled&gt;

This is a sub-element of the `<MouseRect>` element, and has no attributes. If this element is included and set to `True`, then the mouserect will not be instantiated.

 

 

#### &lt;DisabledInVr&gt;

This is a sub-element of the `<MouseRect>` element, and has no attributes. If this element is included and set to `True`, then the mouserect will not be available when the simulation is in VR mode.

 

 

#### &lt;Lock&gt;

This is a sub-element of the `<MouseRect>` element, and has no attributes. If this element is included and set to `True`, then the mouserect will prompt for a lock (note that this is mandatory for gamepad compatibility of drag interactions).

 

 

#### &lt;LockFlagsTemporary&gt;

This is a sub-element of the `<MouseRect>` element, and has no attributes. It is used to set the Mouse Flags that will be used to lock the mousrect when using a pointer device. Multiple mouse flags may be supplied, separated by the {{< button "+" />}} character. For a full list of flags, please see here: `<MouseFlags>`.

 

#### &lt;HighlightNodeId&gt;

This is a sub-element of the `<MouseRect>` element, and has no attributes. When not using a legacy interaction, this is the node highlighted when hovering over the target mouserect. If this element is not included in the mousrect definition, then it will default to the Component node the mouserect was created in.

 

 

#### &lt;HelpID&gt;

This is a sub-element of the `<MouseRect>` element, and has no attributes. It takes the ID of the help string to display when the cursor is over the mouse rectangle. See the Help IDs document for more information: [Help Text IDs](modelbehaviors/help-text-ids/)

 

 

#### &lt;TooltipID&gt;

This is a sub-element of the `<MouseRect>` element, and has no attributes. It takes the ID of the tooltip string to display when the cursor is over the mouse rectangle, or a custom RPN string. See here for a list of all included strings: [ToolTip Text IDs](modelbehaviors/tooltip-text-ids/).

 

#### &lt;TooltipEntries&gt;

This is a sub-element of the `<IMDrag>` element and is used to define which information should be displayed when the cursor is hovering over the interaction box. The element requires the `<TTTitle>` and `<TooltipEntry />` sub-elements and has the following attribute:

 

<table><thead><tr class="header"><th>Attribute</th><th>Description</th><th>Type</th><th>Required</th></tr></thead><tbody><tr class="odd"><td><code>Disabled</code></td><td><p>If set to "True", then no tooltip will be shown.</p><p>Default is "False".</p></td><td>Bool</td><td>No</td></tr></tbody></table>

 

 

##### &lt;TTTitle&gt;

This sub element of `<TooltipEntries>` is used to define a String ID or give an RPN sample that returns a string to be used as the tooltip title. The element has the following attribute:

 

<table><thead><tr class="header"><th>Attribute</th><th>Description</th><th>Type</th><th>Required</th></tr></thead><tbody><tr class="odd"><td><code>RPN</code></td><td><p>If set to "True", then the supplied string contains RPN which should be evaluated.</p><p>Default is "False".</p></td><td>Bool</td><td>No</td></tr></tbody></table>

 

 

##### &lt;TooltipEntry /&gt;

This self closing sub-element of `<TooltipEntries>` requires no data other than the following attribute:

 

{{< table-wrapper >}}

| Attribute | Description                                                 | Type   | Required |
|-----------|-------------------------------------------------------------|--------|:--------:|
| `ID`      | The ID of the InputEvent to retrieve the tooltip data from. | String |    Yes   |

{{< /table-wrapper >}}


 

 

#### &lt;MouseFlags&gt;

This is a sub-element of the `<MouseRect>` element and holds one or more case-insensitive mouse flags that indicate when the `<Behaviors>` is to be triggered. The element has no attributes and will take one or more of the following strings (these strings can be concatenated using the "+" symbol):

1.  `LEFTALL`
2.  `RIGHTALL`
3.  `MIDDLEALL`
4.  `RIGHTSINGLE`
5.  `MIDDLESINGLE`
6.  `LEFTSINGLE`
7.  `RIGHTDOUBLE`
8.  `MIDDLEDOUBLE`
9.  `LEFTDOUBLE`
10. `RIGHTDRAG`
11. `MIDDLEDRAG`
12. `LEFTDRAG`
13. `MOVE`
14. `RIGHTRELEASE`
15. `MIDDLERELEASE`
16. `LEFTRELEASE`
17. `WHEELUP`
18. `WHEELDOWN`
19. `WHEEL`
20. `DOWNREPEAT`
21. `MOVEREPEAT`
22. `LEAVE`
23. `LOCK`
24. `UNLOCK`
25. {{< input "Enter" />}}
26. `EXIT`

 

Please note that these flags *partially* link to the inputs you can rebind from Microsoft Flight Simulator 2024:

-   Primary interactions correspond to `LEFT` flags.
-   Secondary interactions correspond to `RIGHT` flags.
-   Tertiary interactions correspond to `MIDDLE` flags.
-   Increase & Decrease correspond to `WHEELUP` and `WHEELDOWN` respectively.
-   `LOCK` and `UNLOCK` are self explicit.

 

 

#### &lt;IgnoreZTest&gt;

This is a sub-element of the `<MouseRect>` element and is used to tell the simulation that the element should ignore the Z-Test when the user hovers the cursor over it. This means that the highlight will be drawn above everything else, even if the associated model should actually be behind other things. Set to "True" to ignore Z-testing or set to "False" (or ommit) to use Z-testing.

 

 

#### &lt;PrioritizeVCockpits&gt;

This is a sub-element of the `<MouseRect>` element and - when set to "True" - it will attempt to give priority to any VCockpit display when the mouserect is very close, avoiding interference from other objects. This is mostly meant to be used for backdrops of screens which block clicks to the Vcockpit from affecting other mouserects behind them.

 

 

### &lt;CallbackCode&gt;

This is a sub-element of the `<MouseRect>` element and allows for a range of calculations, assignments and the sending of key events to take place. The element has no attributes, and will require the following sub-elements:

1.  `<IMCodeInstances>`
2.  `<DragAnimName>`
3.  `<DragNodeId>`
4.  `<DragAnimSynced>`
5.  `<DragUseAnimLag>`
6.  `<DragAnimLagTarget>`
7.  `<DragMode>`
8.  `<DragAxis>`
9.  `<DragScalar>`
10. `<DragFlagsLockable>`

 

 

#### &lt;IMCodeInstances&gt;

This is a sub-element of both the `<CallbackCode>` and `<CallbackCode>` elements and has no attributes. It should contain the `<IMDefault>` and `<IMDrag>` sub-elements, which will in turn contain a sample of [RPN](../../programming-apis/reverse-polish-notation/) code which will be executed any time a mouseflag matches with a user interaction. This event can be checked using `(M:Event)` in [RPN](../../programming-apis/reverse-polish-notation/).

 

 

#### &lt;DragAnimName&gt;

This is a sub-element of both the `<CallbackDragging>` and `<CallbackCode>` elements and has no attributes. It is used to give the name of the animation to sample the drag data from. This element is only required when the `<DragMode>` is set to `Trajectory`.

 

 

#### &lt;DragNodeId&gt;

This is a sub-element of the `<CallbackCode>` element and has no attributes. This is used to give the name of the node to sample drag data from. If not included then it will default to the component node. Note that this is only useful if the mouserect node pivot point location moves with the animation, and is only required when the `<DragMode>` is set to `Trajectory`.

 

 

#### &lt;DragAnimSynced&gt;

This is a sub-element of both the `<CallbackDragging>` and `<CallbackCode>` elements and has no attributes. This is used to set whether the saved drag position `(M:DragPercent)` will be synced with the animation percent value (set to "True") or not (set to "False"). This element is only required when the `<DragMode>` is set to `Trajectory`.

 

 

#### &lt;DragUseAnimLag&gt;

This is a sub-element of the `<CallbackDragging>`, `<CallbackCode>`, and `<CallbackJumpDragging>` elements and has no attributes. If set to "True" the animation lag will be applied while interacting with the mouserect.

 

 

#### &lt;DragAnimLagTarget&gt;

This is a sub-element of the `<CallbackDragging>`, `<CallbackCode>`, and `<CallbackJumpDragging>` elements and has no attributes. If `<DragUseAnimLag>` is false then this element permits you to add a bitflag to override the targets that should be skipping lag when interacting with a mouserect. The value is stored as an 8bit value, with 1 bit for each animation. If this element is not included, then it will default to 511 in decimal (all bits sets, ie: 111111111 in binary). The check is done as follows:

BitFlag & (1 &lt;&lt; AnimIndex )

Here the `AnimIndex` corresponds to the order the animation has been created in within a component, starting at 0. For example: if you have 2 animations and only the first one should be skipping lag then the bitflag should look like this in binary - 111111101 - which translates to 509 in decimal. In this case the XML would look like this:

``` xml
<DragAnimLagTarget>509</DragAnimLagTarget>
```

 

 

#### &lt;DragMode&gt;

This is a sub-element of both the `<CallbackDragging>` and `<CallbackCode>` elements and has no attributes. It sets the screen space mode that will be used for drag calculations, which will be one of the following:

1.  `Trajectory` - uses animation to screen space projection
2.  `Default` - uses the screen space coordinates relative position

 

 

#### &lt;DragAxis&gt;

This is a sub-element of both the `<CallbackDragging>` and `<CallbackCode>` elements and has no attributes. This element defines which axis to take into account to update the drag value. Can be one of the following:

1.  {{< button "X" />}}
2.  `Y`
3.  `Any` (Screen Coordinates)

 

 

#### &lt;DragScalar&gt;

This is a sub-element of the `<CallbackDragging>`, `<CallbackCode>`, and `<CallbackJumpDragging>` elements and has no attributes. This defines the scalar that will be applied to the drag value update when using relative coordinate (ie: with a gamepad).

 

 

#### &lt;DragFlagsLockable&gt;

This is a sub-element of the `<CallbackDragging>`, `<CallbackCode>`, and `<CallbackJumpDragging>` elements and has no attributes. This defines the mouse flags events that will be triggered when moving an axis using relative coordinates (ie: with a gamepad). Multiple mouse flags may be supplied, separated by the {{< button "+" />}} character. For a full list of flags, please see here: `<MouseFlags>`.

 

 

### &lt;CallbackDragging&gt;

This is a sub-element of the `<MouseRect>` element and adding this entry allows for a more complex interaction with the part. The location where the user clicked and the current simulation value related to this part are captured, then when the user drags the mouse a set key event is triggered. The value passed with this key event is determined by the simulation `<Variable>`, and the `<Scale>` and `<Bias>` values.

 

This element can contain the following sub-elements and has no attributes:

1.  `<IMCodeInstances>`
2.  `<DragAnimName>`
3.  `<DragNodeId>`
4.  `<DragAnimSynced>`
5.  `<DragUseAnimLag>`
6.  `<DragAnimLagTarget>`
7.  `<DragMode>`
8.  `<DragAxis>`
9.  `<DragScalar>`
10. `<DragFlagsLockable>`
11. `<XScale> / <YScale> / <ZScale>`
12. `<Scale>`
13. `<MinValue> / <MaxValue>`
14. `<EventID>`
15. `<IsRelative>`

 

 

#### &lt;XScale&gt; / &lt;YScale&gt; / &lt;ZScale&gt;

This is a sub-element of the `<CallbackDragging>` element, and has no attributes. It sets the drag scale delta for each axis (X, y and Z) individually, and these values will be applied to the appropriate SimVar value offset. The delta is the difference in screen co-ordinates between the current position of the mouse and the position when the dragging started along the given axis.

 

 

#### &lt;Scale&gt;

This is a sub-element of the `<CallbackDragging>` element, and has no attributes. It sets the drag scale delta which will be applied to the SimVar value offset. The delta is the difference in screen co-ordinates between the current position of the mouse and the position when the dragging started.

 

 

#### &lt;MinValue&gt; / &lt;MaxValue&gt;

These are sub-elements of the `<CallbackDragging>` element and can be used to set the lower and upper limits of the value that will actually be sent with the key event.

 

 

#### &lt;IsRelative&gt;

This is a sub-element of the `<CallbackDragging>` element and has no attributes. If True will use a different coordinate system centered around the node pivot point to compute the offset.

 

 

### &lt;CallbackJumpDragging&gt;

This is a sub-element of the `<MouseRect>` element and adding this entry allows for mouse interactions when an increment and decrement key event are required. It has the following sub-elements and takes no parameters:

1.  `<XMovement> / <YMovement>`
2.  `<DragUseAnimLag>`
3.  `<DragAnimLagTarget>`
4.  `<DragScalar>`
5.  `<DragFlagsLockable>`

 

 

#### &lt;XMovement&gt; / &lt;YMovement&gt;

These are sub-elements of the `<CallbackJumpDragging>` element and have no attributes. These elements contain the definition of the required mouse movement (in the X and Y directions), and can also contain the following sub-elements:

1.  `<EventIdInc> / <EventIdDec>`
2.  `<Delta>`

 

 

##### &lt;EventIdInc&gt; / &lt;EventIdDec&gt;

These are sub-elements of the `<XMovement> / <YMovement>` elements and have no attributes. They can be used to define the value to be sent as the increment or decrement.

 

 

##### &lt;Delta&gt;

This is a sub-elements of the `<XMovement> / <YMovement>` elements and has no attributes. It takes a value which is the mouse movement in screen co-ordinates required for one increment or one decrement key event to be triggered. By default movement to the *right* or *up* increments, but this can be reversed by entering a negative delta.

 

 

### &lt;EventID&gt;

This is a sub-element of the `<MouseRect>` element and can also be a sub-element of the `<CallbackDragging>` element.

 

When used with the `<MouseRect>` element, it stores the ID of the event that will be triggered if the mouse is clicked over the mouse rectangle. Alternatively a custom numeric event can be defined (in the range 0x11000 to 0x1FFFF), to be picked up by a gauge handler written in C++. The element has no attributes.

 

When used with the `<CallbackDragging>` element, this should be a set key event and not a key event that toggles or increments or decrements.