Panel XML Logic Elements
The following elements can all be used within the <Condition>, <[CUSTOM]>, and <Electric> panel XML elements as a way to create logical expressions that will control in some way the event being defined. For more information on the Panel XML file, please see here:
When using these logic elements, you are not just limited to a single operation, but can instead nest multiple logic elements within each other to create complex operations, where the results of one element will be passed to the container element that is above it in the element hierarchy, as shown in the following example:
<Max>
<Min>
<Multiply>
<Divide>
<Multiply>
<Simvar name="ENG TORQUE:1" unit="Foot pounds"/>
<Divide>
<SimVar name="GENERAL ENG RPM:1" unit="rpm"/>
<Constant>5252</Constant>
</Divide>
<Constant>550</Constant>
</Multiply>
<Divide>
<SimVar name="AIRCRAFT MAX RATED HP" unit="ft lb per second"/>
<SimVar name="NUMBER OF ENGINES" unit="number"/>
</Divide>
</Divide>
<Constant>100</Constant>
</Multiply>
<Constant>100</Constant>
</Min>
<Constant>0</Constant>
</Max>The above XML logic would be translated as the following mathematical expression:
result = max(min(((ENG_TORQUE * (ENG_RPM / 5252) * 550) / (MAX_HP / ENGINE_NUM)) * 100), 100), 0);
<Function>
This element has two modes of use:
- as a direct child of the
<EngineDisplay>container element, where it is used to define a named function. - within one of the components of a
<Gauge>element, where it is used like a<Simvar />or a<Condition>to return a value by calling the named function.
The idea here is that you can create a function with a single block of XML logic to return a value, and then call this function multiple times elsewhere in the XML, cutting down on repetitive elements and making debugging easier.
The element has the following required attribute:
| Attribute | Description | Type | Required |
|---|---|---|---|
name |
The name of the function. This is the name that will be used both to define the function and to call the function (depending on context). | String | Yes |
The XML example below shows both a function being defined and then later called:
<EngineDisplay>
<Function Name="ShowTorqueRedLine">
<If>
<Condition>
<Lower>
<Simvar name="PROP RPM:1" unit="rpm"/>
<Constant>1800</Constant>
</Lower>
</Condition>
<Then>
<Constant>"True"</Constant>
</Then>
<Else>
<Constant>"False"</Constant>
</Else>
</If>
</Function>
<Gauge>
<ReferenceBug>
<Style>
<Color>#00ccff</Color>
</Style>
<DisplayLogic>
<And>
<GreaterEqual>
<Simvar name="PROP RPM:1" unit="rpm"/>
<Constant>1600</Constant>
</GreaterEqual>
<LowerEqual>
<Simvar name="PROP RPM:1" unit="rpm"/>
<Constant>1900</Constant>
</LowerEqual>
</And>
</DisplayLogic>
<Position>
<Function Name="MaximumCruiseTorqueBug"/>
</Position>
</ReferenceBug>
</Gauge>
<EngineDisplay>
<If>
This element can be used to create a sub-condition to return different values depending on whether the initial <If> condition is evaluated as true or false (if true, the <Then> value will be returned: if false, the <Else> value will be returned). These elements are most commonly used with the <Function> element. For example:
<Function Name="MyFunction">
<If>
<Condition>
<!-- Condition to check -->
</Condition>
<Then>
<!-- True Value -->
</Then>
<Else>
<!-- False value -->
</Else>
</If>
</Function>
<Then>
This is a sub-element of <If>. It will contain the value (or an evaluation that creates a value) to be returned when the parent <If> condition evaluates as true. See above for more information.
<Else>
This is a sub-element of <If>. It will contain the value (or an evaluation that creates a value) to be returned when the parent <If> condition evaluates as false. See above for more information.
<And>
This element acts as a logical "and" which will compare the results of two expressions and return "True" if they are both evaluating as "True", or "False" otherwise. Note that you cannot compare more than two expressions in a single <And>, but you can nest an <And> within an <And> and so compare more than the default 2 expression results in that way.
<And>
<Not>
<Simvar name="GENERAL ENG MASTER ALTERNATOR:1" unit="Bool"/>
</Not>
<Simvar name="GENERAL ENG MASTER ALTERNATOR:2" unit="Bool"/>
</And>
<Or>
This element acts as a logical "or" which will compare the results of two expressions and return "True" if either of them are evaluating as "True", or "False" otherwise. Note that you cannot compare more than two expressions in a single <or>, but you can nest an <or> within an <or> and so compare more than the default 2 expression results in that way.
<Or>
<Simvar name="GENERAL ENG FUEL PUMP ON:1" unit="Bool"/>
<Simvar name="GENERAL ENG FUEL PUMP ON:2" unit="Bool"/>
</Or>
<Not>
This element will check if an expression (either <Constant> or <Simvar />, or nested expression) is not "True" and return "True" if it's not, or "False" otherwise. For example:
<Not>
<Simvar name="L:XMLVAR_Pitot_1" unit="Bool"/>
</Not>
<Greater>
This element will check whether the result of one expression (the first one listed within the element) is greater than the result of another expression (the second one listed in the element). Expressions can be <Constant>, <Simvar />, or nested expression(s). For example:
<Greater>
<Simvar name="EXIT OPEN:0" unit="percent"/>
<Constant>0</Constant>
</Greater>
<Lower>
This element will check whether the result of one expression (the first one listed within the element) is lower than the result of another expression (the second one listed in the element). Expressions can be <Constant>, <Simvar />, or nested expression(s). For example:
<Lower>
<Simvar name="GENERAL ENG THROTTLE LEVER POSITION:1" unit="percent"/>
<Constant>70</Constant>
</Lower>
<GreaterEqual>
This element will check whether the result of one expression (the first one listed within the element) is greater than or equal to the result of another expression (the second one listed in the element). Expressions can be <Constant>, <Simvar />, or nested expression(s). For example:
<GreaterEqual>
<Value>CUR_ID</Value>
<Number>4</Number>
</GreaterEqual>
<LowerEqual>
This element will check whether the result of one expression (the first one listed within the element) is lower than or equal to the result of another expression (the second one listed in the element). Expressions can be <Constant>, <Simvar />, or nested expression(s). For example:
<LowerEqual>
<Simvar name="PRESSURIZATION CABIN ALTITUDE" unit="feet"/>
<Constant>10000</Constant>
</LowerEqual>
<Equal>
This element will check whether the result of one expression (the first one listed within the element) is equal to the result of another expression (the second one listed in the element). Expressions can be <Constant>, <Simvar />, or nested expression(s). For example:
<Equal>
<Simvar name="PARTIAL PANEL VACUUM" unit="Enum"/>
<Constant>1</Constant>
</Equal>
<Inequal>
This element will check whether the result of one expression (the first one listed within the element) is not equal to the result of another expression (the second one listed in the element). Expressions can be <Constant>, <Simvar />, or nested expression(s). For example:
<Inequal>
<Simvar name="GENERAL ENG STARTER ACTIVE:1" unit="Bool"/>
<Simvar name="GENERAL ENG STARTER ACTIVE:2" unit="Bool"/>
</Inequal>
<Multiply>
This element will multiply the results of two items, either <Constant>, <Simvar />, or nested expression(s). For example:
<Multiply>
<Simvar name="VERTICAL SPEED" unit="feet per minute"/>
<Constant>-1</Constant>
</Multiply>
<Divide>
This element will divide the results of two items, either <Constant>, <Simvar />, or nested expression(s). For example:
<Divide>
<Simvar name="GENERAL ENG RPM:1" unit="rpm"/>
<Constant>5252</Constant>
</Divide>
<Subtract>
This element will subtract the results of two items, either <Constant>, <Simvar />, or nested expression(s). For example:
<Subtract>
<Simvar name="NUMBER OF ENGINES" unit="number"/>
<Constant>1</Constant>
</Subtract>
<Min>
This element return the minimum value of two elements, either <Constant>, <Simvar />, or nested expression(s). For example:
<Min>
<Simvar name="RECIP ENG RADIATOR TEMPERATURE:1" unit="celsius"/>
<Constant>0</Constant>
</Min>
<Max>
This element return the maximum value of two elements, either <Constant>, <Simvar />, or nested expression(s). For example:
<Max>
<Simvar name="FUEL RIGHT QUANTITY" unit="gallons"/>
<Simvar name="FUEL LEFT QUANTITY" unit="gallons"/>
</Max>
<Clamp>
This element can be used to clamp a value - either <Constant>, <Simvar />, or generated from a nested expression - between a minimum and a maximum, which are given as attributes of the element.
| Attribute | Description | Type | Required |
|---|---|---|---|
min |
The minimum value to be returned if the input is lower. | String | Yes |
max |
The maximum value to be returned if the input is higher. | String | Yes |
For example:
<Clamp min="4" max="54">
<Simvar name="FUEL TOTAL QUANTITY" unit="gallons"/>
</Clamp>
<Timer>
This element can be used to specify a time after which the <Constant>, <Simvar />, or nested expression will be calculated. When you add a timer element, it will count up by 1 every second, and when the internal count reaches the time value given the expression or SimVar contained within will be evaluated. Note that this element may also contain the <ResetCondition> element which will reset the timer to 0 if the contained condition evaluates as true.
| Attribute | Description | Type | Required |
|---|---|---|---|
time |
The time - in seconds - after which the nested condition or SimVar will be evaluated. | String | Yes |
For example:
<Timer time="10">
<Greater>
<Simvar name="ELECTRICAL BATTERY LOAD:2" unit="amps"/>
<Constant>0.5</Constant>
</Greater>
</Timer>
<LinearMultiPoint>
This element can be used to test whether the given inputs, when plotted on a graph, fall within a given minimum and/or maximum range. If it does, then the result is true and if not then the result is false. The element itself has no attributes and requires a single <Table> sub-element (which itself must contain a single <ReferencePoints> as well as a <Minimums> and/or <Maximums> sub-element), and two <Param> sub-elements.
To help you better visualise how this graphing element works, you can visualise the graph itself as comprised of an X/Y axis where the X axis is the first <Param> defined, and the Y axis is the second <Param> defined. You would then define a series of <ReferencePoints> along the X axis, and finally supply the <Minimums> and/or <Maximums> along the Y axis. The following image helps illustrate this:
And a sample of the XML that the image above represents would look like this:
<LinearMultiPoint>
<Table>
<ReferencePoints>1160,2320,4930,11800</ReferencePoints>
<Minimums>0,1070,2380,4285</Minimums>
<Maximums>0,1460,2980,5360</Maximums>
</Table>
<Param>
<Multiply>
<Simvar name="VERTICAL SPEED" unit="feet per minute"/>
<Constant>-1</Constant>
</Multiply>
</Param>
<Param>
<Simvar name="PLANE ALT ABOVE GROUND" unit="feet"/>
</Param>
</LinearMultiPoint>Note that if you supply only a <Minimum> dataset, then the element will resolve as true if the input falls above the minimum values, and if you supply only a <Maximum> dataset, then it will return true only if the input falls below the maximum values. You must supply one or the other, although - as shown in the example - you can also supply both.
<Table>
This is a sub-element of <LinearMultiPoint> and is a container for one <ReferencePoints> element, and the <Minimums> and/or <Maximums> elements. See the <LinearMultiPoint> description for more information.
<ReferencePoints>
This is a sub-element of <Table> and is used to define the reference points that will be used as the positions along the "X" axis of the table/graph at which the minimums and maximums will be interpreted. Values are given as a comma separated list, and the <Minimums> and/or <Maximums> elements must also have the same number of values in their list.
<Minimums>
This is a sub-element of <Table> and is used to define the minimum values at each of the defined <ReferencePoints> (essentially the min value along the "Y" axis for each "X" axis reference point). Values are given as a comma separated list, and there must be an equal number of values as there are in the <ReferencePoints> element.
<Maximums>
This is a sub-element of <Table> and is used to define the maximum values at each of the defined <ReferencePoints> (essentially the max value along the "Y" axis for each "X" axis reference point). Values are given as a comma separated list, and there must be an equal number of values as there are in the <ReferencePoints> element.
<Param>
This is a sub-element of <LinearMultiPoint> and <MultiDimensionsTable> elements, and it has no attributes.
For the <LinearMultiPoint> element it is used to generate the value that will be used for checking against the <Table> element. There must be two <Param> elements defined, where the first one defines the value that is to be used for the X-axis and the second <Param> defines the value that is to be used for the Y-Axis. See the <LinearMultiPoint> description for more information.
For the <MultiDimensionsTable> element it is used to generate a value which will then be used to retrieve an index value from a <References> array. See the <MultiDimensionsTable> description for more information.
Within this element you can use the <Constant>, <Simvar />, or nested expression(s) to generate the value to be used.
<MultiDimensionsTable>
This element has no attributes and can be used to return a single value based on 2 or more <Input> values. The input values are used to get an index value, and then the combined indices are used to retrieve a specific value from a table within the <Output> element.
IMPORTANT! You can have a maximum of 5 inputs in a multi-dension table, however we do not recommend that you use that many if it can be avoided. 2 or 3 is optimal, since more may degrade performance.
Consider the following example:
<MultiDimensionsTable>
<Input>
<!-- Altitude Indexes -->
<!-- 0 1 2 3 4 5 6 7 8 -->
<References> 0,2000,4000,6000,8000,10000,12000,14000,16000</References>
<Param>
<Simvar name="PLANE ALTITUDE" unit="feet"/>
</Param>
</Input>
<Input>
<!-- Temperature Indexes -->
<!-- 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 -->
<References>-54,-40,-36,-22,-20,-18,-10,-8,-4, 0, 2, 4, 14, 18, 22, 26, 30, 32, 34, 38, 42, 46, 50</References>
<Param>
<Simvar name="AMBIENT TEMPERATURE" unit="celsius"/>
</Param>
</Input>
<!-- AltitudeIndex, TemperatureIndex : Value; -->
<Output>
0,0:2397;0,17:2397;0,22:2020;
1,0:2397;1,14:2397;1,21:1940;
2,0:2397;2,12:2397;2,20:1860;
3,0:2397;3,10:2397;3,19:1780;
4,0:2397;4,7 :2397;4,9: 2240;4,18:1700;
5,0:2397;5,3 :2397;5,8: 2120;5,11:2000;5,16:1620;
6,0:2397;6,1 :2397;6,4: 2170;6,15:1540;
7,0:2360;7,2 :2140;7,5: 1960;7,6: 1880;7,14:1440;
8,0:2160;8,1 :2000;8,5: 1800;8,6: 1720;8,13:1360;
</Output>
</MultiDimensionsTable>
In this example we have two inputs: altitude and ambient temperature. The first input gets the altitude and then checks the <References> array to find the index value. Note that values will be rounded down to the nearest reference value, for example, if the altitude in the XML above was 11,250ft, then that would be rounded down to the nearest reference value which is 10,000. Therefor, the index returned for that input would be 5. This process is repeated for all further inputs.
NOTE: If the param value falls below the value of index 0 in the reference array, the input will return 0.
Once the inputs have been processed, the indices returned are used to retrieve a corresponding output value. The <Output> element contains a list of mapped values with the format:
[input_index_1], [input_index_2], etc, : [output_value]
It will return the output value that has the same input indices as those retrieved from the corresponding inputs. For example, using the XML shown above, if input index 1 is 6 and input index 2 is 15, the output will be 1540.
<Input>
This is a sub-element of <MultiDimensionsTable>, has no attributes, and is used to generate an input value and use that to retrieve an index into a reference array for a corresponding value. As such the element acts as a container for a single <References> element (which will hold tha array of comparison values) and a single <Param> element (which will generate the value to be compared in the array to get the index)
<References>
This is a sub-element of <Input> and has no attributes. It takes a comma separated list of values against which the <Param> value will be compared (rounded down) to return an index.
<Output>
This is a sub-element of <MultiDimensionsTable>, has no attributes, and is used to create an output lookup table. This table is used to return specific values based on the input indices into the table. The table is is created as a comma separted list of values, where each value has the following format:
[input_index_1], [input_index_2], etc, : [output_value]
For example (shown with aditional spacing and fomatting to make it clearer:
<Output>
0,0:100; 0,1:1456; 0,2:1993;
1,0:255; 1,1:2410; 1,2:2900;
2,0:380; 2,1:3009; 2,2:3850;
3,0:500; 3,1:4500; 3,2:4999;
</Output>
See the <MultiDimensionsTable> description for more information.
<ResetCondition>
This element can be used to reset the parent element if the contained condition - which can be a <Simvar /> or nested expression - evaluates as true. <ResetCondition> can be used by the following elements: <Timer>, <MaxSinceStart>, <MinSinceStart>, <LinearMultiPoint>, <StateMachine>, <If>.
<MaxSinceStart>
<ResetCondition>
<Simvar name="SIM ON GROUND" unit="bool"/>
</ResetCondition>
<Simvar name="PLANE ALTITUDE" unit="feet"/>
</MaxSinceStart>
<StateMachine>
This container element has no attributes and is used to create a type of "finite state machine" that will switch between different defined states based on an expression. The states are defined using the <State> sub-element, and each state machine should have at least two of these to function correctly. The following example shows a typical state machine setup being used in an <Alert>:
<Alert>
<Type>SoundOnly</Type>
<SoundEvent>aural_500ft</SoundEvent>
<Condition>
<StateMachine>
<State id="Under" value="0">
<Transition to="Over">
<GreaterEqual>
<Simvar name="PLANE ALT ABOVE GROUND MINUS CG" unit="feet"/>
<Constant>510</Constant>
</GreaterEqual>
</Transition>
</State>
<State id="Over" value="0">
<Transition to="Alerting">
<LowerEqual>
<Simvar name="PLANE ALT ABOVE GROUND MINUS CG" unit="feet"/>
<Constant>500</Constant>
</LowerEqual>
</Transition>
</State>
<State id="Alerting" value="1">
<Transition to="Under">
<Constant>1</Constant>
</Transition>
</State>
</StateMachine>
</Condition>
</Alert>
<State>
This sub-element is used within the <StateMachine> container element to define the different "states" that can be chosen, and you will have at least two of these, although you can have many more. The element requires a <Transition> sub-element (to tell the state machine which state to transition to next) and a <Condition> element (to decide whether the state should change or not) and has the following attributes:
| Attribute | Description | Type | Required |
|---|---|---|---|
id |
This is the state ID string and will be used in the <Transition> element to switch between states. |
String | Yes |
value |
The value given here will be sent to the parent element that called the state machine when the state is first transitioned into. | String / Float | Yes |
<Transition>
This element is a sub-element of <State> and is used to tell the state machine which state to transition to next should the accompanying <Condition> or <Constant> evaluate as true. Each state should only ever have one transition, and the element has the following attribute:
| Attribute | Description | Type | Required |
|---|---|---|---|
to |
This string is the id of the <State> element that should be transitioned to next when the conditional expression evaluates to "True". |
String | Yes |
Unique Logic Elements
The following elements can be used as part of the XML logic anywhere where you would use a <Simvar /> or a <Constant>. They are (generally) self closing elements that require no attributes and are designed to signify a single specific value, related to the simulation as it runs.
<TimeSinceStart />
This element can be used to retrieve the time (in milliseconds) since the flight was started.
<MaxSinceStart>
This element can be used to retrieve the maximum value that a particular <Simvar /> has reached since the flight was started. Note that you may use the <ResetCondition> sub-element here to reset the maximum value based on a specific condition.
<MaxSinceStart>
<Simvar name="PLANE ALTITUDE" unit="feet"/>
</MaxSinceStart>
<MinSinceStart>
This element can be used to retrieve the minimum value that a particular <Simvar /> has reached since the flight was started. Note that you may use the <ResetCondition> sub-element here to reset the minimum value based on a specific condition.
<MinSinceStart>
<Simvar name="BAROMETER PRESSURE" unit="Millibars"/>
</MinSinceStart>
<DistanceFromOrigin />
This element can be used to retrieve the distance that the aircraft is from the origin waypoint (in nautical miles) as defined in the flightplan.
<DistanceToDestination />
This element can be used to retrieve the distance that the aircraft is from the destination waypoint (in nautical miles) as defined in the flightplan.
<HeadingChangeFromDeparture />
This element can be used to retrieve the difference between the current aircraft heading and the aircraft heading at takeoff (in degrees). Value will be between -180° and 180°.
<InstrumentWasOff />
This element will return true if the instrument has been switch off, or false if it has been switched on.