ANIMATION XML PROPERTIES
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 version="1.0" encoding="UTF-8"?>
<ModelInfo version="1.1" guid="<!-- GUID HERE -->">
<Animation>
<Event time="1" name="Event_Name"/>
</Animation>
<!-- FURTHER ANIMATION EVENT DATA HERE -->
<AnimGraph>
<DefaultState name="Default_State_Name"/>
<BlendTreeState name="Idle">
<Animations>
<Animation guid="<!-- GUID HERE -->" loop ="True/False" speed="1"/>
</Animations>
<Events>
<Event time="1" name="Event_Name"/>
</Events>
</BlendTreeState>
<!-- FURTHER BLENDTREE STATES HERE -->
<Transition start="Start_Animation" end ="End_Animation">
<Condition> <!-- RPN CONDITION HERE --> </Condition>
</Transition>
<!-- FURTHER TRANSITIONS HERE -->
<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:
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, or as part of a <Component>
definition.
<Animation>
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:
Attribute | Description | Type | Required |
---|---|---|---|
name |
A unique name for the new animation. It should not contain any spaces or punctuation, but can contain underscores and numeric digits. | String | Yes |
guid |
The unique GUID for the animation. This is the reference the simulation will use to identify the animation, and must be in the format "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx} ", all lower case, e.g: "{12f06ee8-11ce-4e7b-a715-a9c5deb5352f} ". |
String | Yes |
length |
This is used only for "Sim" animations, and exists for backwards compatibility. It is not necessary to specify this if you specify the <AnimLength> element of a <PartInfo> animation. |
Float | No |
type |
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 <PartInfo> below for more information. |
Enum: "Standard" |
Yes |
typeParam |
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: typeParam = "Autoplay" |
String : "AutoPlay" - the animation will run when the object is rendered "Random" - the animation will be started at a random point along its timeline "FrameRate" - The FrameRate reference 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. |
No |
<NodeAnimation>
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:
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 |
The element has the sub-element <Node />
and takes the following attribute:
Attribute | Description | Type | Required |
---|---|---|---|
type |
The type of node animation to use (currently only 1 type is available) |
Enum: "WingFlex" |
Yes |
<Node />
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).
<AnimationEvent>
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:
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 |
<Time>
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.
<IsNormalPlayback>
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).
<AnimGraph>
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:
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 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.
<DefaultState />
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:
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 Percent Over 100. 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 |
<BlendTreeState>
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:
This element is used within the main <AnimGraph>
container or within a <Layer>
and has the following attribute:
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 |
<Value>
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, for example:
<Value>(A:GROUND VELOCITY, METERS PER SECOND)</Value>
<Animations>
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.
<Animation>
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:
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 |
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 |
<Transition>
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 anExitTime
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 definedend
state of the transition, and the currently playing animation matches thestart
state animation. - The following are all considered as "automatic" transitions:
- A transition with a
<Condition>
but without anExitTime
attribute will be automatically executed if the<Condition>
resolves as true and thestart
state is the current one. - A transition with an
ExitTime
attribute and no<Condition>
will be automatically executed when the animation from thestart
state reaches a certain ratio of the animation. For example, anExitTime
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 theExitTime
value has been reached.
- A transition with a
NOTE: "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.
Some notes on triggering transitions:
- when using the
<Condition>
element, if the current state is thestart
one from the transition, the code in the<Condition>
is evaluated every frame, and if it resolves as true, then the transition triggers. - 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). - When using an
ExitTime
greater than 0, you are setting a "ratio" that will trigger the transition automatically once the animation from thestart
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.
- if you set
The element has the following attributes:
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 |
<Condition>
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, for example:
<Condition>(A:SURFACE RELATIVE GROUND SPEED, METERS PER SECOND) 0.1 ></Condition>
<Layer>
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:
The element has the following attributes:
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 |
<Events>
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.
<Event />
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:
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 |
<PartInfo>
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:
Please see the page model.cfg Examples for examples of how this element is used.
IMPORTANT! 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.
<Name>
This is a sub-element of <PartInfo>
and is the name of the animation from the <Animation>
element. This element has no attributes.
<Copy>
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.
<AnimLength>
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.
<Animation>
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.
<Parameter>
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.
<Lag>
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.
<Code>
This sub element of <Parameter>
can contain a reference to a script for evaluation.
<Sim>
This sub-element of <Parameter>
must contain a <Variable>
entry for the animation to reference, along with <Units>
, <Scale>
, and <Bias>
entries.
NOTE: Simvar scale and bias is applied as follows - Value = SimvarValue * Scale + Bias
<Variable>
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
.
<Units>
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
<Scale>
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.
<Bias>
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.
<MouseRect>
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:
<Cursor>
<IMCursorsInstances>
<IMMouseFlagsInstances>
<IMTooltipsInstances>
<Disabled>
<DisabledInVr>
<Lock>
<LockFlagsTemporary>
<HighlightNodeId>
<HelpID>
<TooltipID>
<MouseFlags>
<IgnoreZTest>
Note that you may also have one, and only one, of the following sub-elements in the <MouseRect>
(they are mutually exclusive):
<Cursor>
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:
None
Normal
UpArrow
DownArrow
LeftArrow
RightArrow
Hand
Crosshair
Grab
GrabOpen
TurnLeft
TurnRight
TurnLeft_Small
TurnRight_Small
TurnLeft_UpSideDown
TurnRight_UpSideDown
UpDownArrows
LeftRightArrows
DiagonalArrows
Lock
Dynamic
AnimTip
<IMCursorsInstances>
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.
<IMMouseFlagsInstances>
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.
<IMTooltipsInstances>
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.
<IMDefault>
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+
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<Animated>
- Define an animated tooltip using RPN and Program Template XML Properties.
<IMCodeInstances>
- The content of the<IMDefault>
element will be an RPN code node used to define the callback.
<IMDrag>
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+
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 code node used to define the callback.
<CursorLeft>
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.
<CursorRight>
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.
<CursorUp>
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.
<CursorDown>
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.
<CursorCenter>
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.
<Cursor>
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.
<CursorCenterRadius>
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 Percent Over 100 of the screen size.
<Animated>
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 and RPN.
<Disabled>
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.
<DisabledInVr>
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.
<Lock>
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).
<LockFlagsTemporary>
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 +
character. For a full list of flags, please see here: <MouseFlags>
.
<HighlightNodeId>
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.
<HelpID>
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
<TooltipID>
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.
<TooltipEntries>
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:
Attribute | Description | Type | Required |
---|---|---|---|
Disabled |
If set to "True", then no tooltip will be shown. Default is "False". |
Bool | No |
<TTTitle>
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:
Attribute | Description | Type | Required |
---|---|---|---|
RPN |
If set to "True", then the supplied string contains RPN which should be evaluated. Default is "False". |
Bool | No |
<TooltipEntry />
This self closing sub-element of <TooltipEntries>
requires no data other than the following attribute:
Attribute | Description | Type | Required |
---|---|---|---|
ID |
The ID of the InputEvent to retrieve the tooltip data from. | String | Yes |
<MouseFlags>
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):
LEFTALL
RIGHTALL
MIDDLEALL
RIGHTSINGLE
MIDDLESINGLE
LEFTSINGLE
RIGHTDOUBLE
MIDDLEDOUBLE
LEFTDOUBLE
RIGHTDRAG
MIDDLEDRAG
LEFTDRAG
MOVE
RIGHTRELEASE
MIDDLERELEASE
LEFTRELEASE
WHEELUP
WHEELDOWN
WHEEL
DOWNREPEAT
MOVEREPEAT
LEAVE
LOCK
UNLOCK
ENTER
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
andWHEELDOWN
respectively. LOCK
andUNLOCK
are self explicit.
<IgnoreZTest>
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.
<CallbackCode>
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:
<IMCodeInstances>
<DragAnimName>
<DragNodeId>
<DragAnimSynced>
<DragUseAnimLag>
<DragAnimLagTarget>
<DragMode>
<DragAxis>
<DragScalar>
<DragFlagsLockable>
<IMCodeInstances>
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 code which will be executed any time a mouseflag matches with a user interaction. This event can be checked using (M:Event)
in RPN.
<DragAnimName>
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
.
<DragNodeId>
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
.
<DragAnimSynced>
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
.
<DragUseAnimLag>
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.
<DragAnimLagTarget>
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 << 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:
<DragAnimLagTarget>509</DragAnimLagTarget>
<DragMode>
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:
Trajectory
- uses animation to screen space projectionDefault
- uses the screen space coordinates relative position
<DragAxis>
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:
X
Y
Any
(Screen Coordinates)
<DragScalar>
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).
<DragFlagsLockable>
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 +
character. For a full list of flags, please see here: <MouseFlags>
.
<CallbackDragging>
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:
<IMCodeInstances>
<DragAnimName>
<DragNodeId>
<DragAnimSynced>
<DragUseAnimLag>
<DragAnimLagTarget>
<DragMode>
<DragAxis>
<DragScalar>
<DragFlagsLockable>
<XScale> / <YScale> / <ZScale>
<Scale>
<MinValue> / <MaxValue>
<EventID>
<IsRelative>
<XScale> / <YScale> / <ZScale>
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.
<Scale>
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.
<MinValue> / <MaxValue>
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.
<IsRelative>
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.
<CallbackJumpDragging>
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:
<XMovement> / <YMovement>
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:
<EventIdInc> / <EventIdDec>
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.
<Delta>
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.
<EventID>
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.