Reverse Polish Notation

The Microsoft Flight Simulator 2024 SDK has full support for the PostFix notation also known as Reverse Polish Notation (RPN). This is used in various places, such as Gauges and Model Behaviors.

In Reverse Polish Notation, the operators follow their operands - for instance, to add 3 and 4, one would write:

3 4 +

rather than:

3 + 4

If there are multiple operations, operators are given immediately after their second operands, so the conventional expression:

3 - 4 + 5

would be written like this in reverse Polish notation:

3 4 - 5 +

Essentially this means that 4 is first subtracted from 3, then 5 is added to it. An advantage of reverse Polish notation is that it removes the need for the parentheses () that are required by InFix notation (InFix notation is simply the name given to conventional notation for expressions such as these). Using the example above it could possibly have the following two interpretations:

3 - (4 * 5)
(3 - 4) * 5

Both those expressions will give quite different results, yet use the same values and operands. In Reverse Polish Notation this ambiguity is removed. The former example 3 - (4 * 5) of could be written:

3 4 5 * -

which unambiguously means 3 (4 5 *) - which in turn reduces to 3 20 - , which finally gives -17. On the other hand the second “version” could be written

3 4 - 5 *

which unambiguously means (3 4 -) 5 * which gives -5. This can be thought of as a series of stack operations, ie:

• When the RPN script parser comes across a value, it pushes it onto the top of the stack.
• When the script parser comes across an operator, it pops from the stack the number of operands that the operator works on (usually one or two values).
• Whatever value is left on top of the stack at the end of the execution is the result of the calculated expression.

RPN In Microsoft Flight Simulator 2024#

Reverse Polish Notation is not a programming language, it is simply a compiler-friendly way of creating complex logical expressions. However, it is used along with some built-in sim functions and variables to create short scripts that are then used to do different things within the sim. Typically these a scripts will use one or more expressions to define what a gauge or model does, and - in their simplest form - the expressions are the names of simulation parameters along with the units in which the element should be expressed - both enclosed in parentheses - followed by operands.

In the following example the expression returns the value of the NAV1 OBS parameter:

(A:NAV1 OBS, degrees)

The A before the colon indicates that this parameter is an Aircraft parameter. NAV1 OBS is a simulation variable (see the Simulation Variable document for a full list of variables) and degrees are the units of measure in which the aircraft parameter will display. Let’s look at how this would be used along with Reverse Polish Notation to write a small script:

(A:NAV1 OBS, degrees) d (A:PARTIAL PANEL HEADING, bool) (A:PARTIAL PANEL ELECTRICAL, bool) or 0 == if{ (A:PLANE HEADING DEGREES GYRO, degrees) 90 - - } dgrd

This would translate as:

“If the PARTIAL PANEL HEADING is false and the PARTIAL PANEL ELECTRICAL is false, then this expression returns the NAV1 OBS reading minus the ( PLANE HEADING DEGREES GYRO reading minus 90), converted to radians.”

Here is a full example of how Reverse Polish Notation is used along with the available parameters and operands within the XML for model behaviors:

<UseTemplate Name="Push_Button_With_Indicator_Template">
    <ANIM_NAME>MID_Push_Isolate_Copilot#SUFFIX_ID#</ANIM_NAME>
    <NODE_ID>MID_Push_Isolate_Copilot#SUFFIX_ID#</NODE_ID>
    <INDICATOR_NODE_ID>MID_Push_Isolate_Copilot_Active#SUFFIX_ID#</INDICATOR_NODE_ID>
    <SIMVAR_TO_WATCH_0>INTERCOM MODE</SIMVAR_TO_WATCH_0>
    <SIMVAR_TO_WATCH_1>INTERCOM SYSTEM ACTIVE</SIMVAR_TO_WATCH_1>
    <GET_STATE_EXTERNAL>(A:INTERCOM MODE, Enum) 0 &gt; (A:INTERCOM SYSTEM ACTIVE, Bool) and sp0</GET_STATE_EXTERNAL>
    <SIM_STATE_IS_ON_EXTERNAL>l0</SIM_STATE_IS_ON_EXTERNAL>
    <CHECK_STATE_HAS_CHANGED>True</CHECK_STATE_HAS_CHANGED>
    <SET_STATE_EXTERNAL>
        (&gt;H:#KEY_PREFIX#_Isolate_Copilot_Push)
        (A:INTERCOM MODE, Enum) 2 == (A:INTERCOM SYSTEM ACTIVE, Bool) and if{ (&gt;K:TOGGLE_ICS) } els{
            (A:INTERCOM SYSTEM ACTIVE, Bool) ! if{ 
                (&gt;K:TOGGLE_ICS)
                2 (&gt;K:INTERCOM_MODE_SET)
            } els{
                2 0 1 3 (A:INTERCOM MODE, Enum) case (&gt;K:INTERCOM_MODE_SET)
            }
        }
    </SET_STATE_EXTERNAL>
    <COND_INDICATOR_ACTIVE>(B:AS1000_MID_Isolate_Copilot, Bool)</COND_INDICATOR_ACTIVE>
    <TT_DESCRIPTION_ID>@TT_Package.AS1000_MID_PUSH_ISOLATECO_ACTION</TT_DESCRIPTION_ID>
    <TOOLTIP_TITLE>@TT_Package.AS1000_MID_PUSH_ISOLATECO_TITLE</TOOLTIP_TITLE>
    <BTN_ID>MID_Isolate_Copilot</BTN_ID>
</UseTemplate>

Variable Types#

When using RPN to create expressions, you can use different variables, and these will require a prefix so the simulation can correctly identify their type and where they come from. The table below shows the different variable prefixes available to you.

Variable Prefix	System Name	Description	Units
A	Simulation Variable	Gets a specified SimVar from a simulation object.	Yes
B	Input Events	Gets the value of the specified input event (see Input Event Definitions for more information).	No
C	Callback Variables	This variable prefix is only used when dealing with GPS Variables.	Yes
E	Environment Variable	This is an environment variable. See the section on Environment Variables.	Yes
F	Function Library	This denotes a built in function from the function library. See the Function Library section below for more details.	No
G	Gauge Variables	Gets a variable that can be used to transfer unitless data between gauges.	No
H	HTML Event	An HTML event sent to JavaScript. These are defined in cockpit panel Model Behaviors, and only go in one direction: from the panel to the JavaScript / HTML code. H: events are not required to be defined ahead of time (similar to L: vars) and can be named with any contiguous string of alphanumeric characters. Each cockpit panel in Microsoft Flight Simulator 2024 sends a number of cockpit specific H: events that have no analogous key event, such as pressing individual buttons on an FMS computer. These individual panel specific events can be received by JavaScript instruments.	No
I	Instrument Variable	Used for instrument variables, where the variable scope is the instrument itself, meaning it will be available to all components in the instrument hierarchy. For example, consider the following instrument schematic:An IVar created in the A:B component (or first referenced in RPN in the A:B) will be accessible in A:B, A:B:C, and also in A and A:D. The value of this IVar will be the same at all time in all components, since the variable is registered in A (the root component of the instrument).	No
K	Key Event ID	This is a specific variable for a key Event ID for user input.(>K:TOGGLE_ICS)	No
L	Local Variable	Retrieves and/or creates a user defined local variable. If the local variable has not been defined in any of the associated files then it will be created and set to 0 the very first time it is referenced (and will not persist between runs). You can, however, define a default value for local variables using the following files:- using the [LocalVars.N] section of the FLT file you can define a non-persistent local variable- using the [LocalVars] section of the Systems Config file you can create a persistent local variableThis variable can be read and set within the scope of the user aircraft, and can be read by AI Aircraft. This variable is shared between aircraft if multiple instances of the aircraft are spawned using the variable. In general this is not what you want and you should use the scoped L:1 variable type instead.IMPORTANT! L: vars can only hold numeric data and nothing else, eg: no strings, no binary values, no structs, etc…	No
L:1	Local Variable (Scoped)	Retrieves and/or creates a user defined local variable. If the local variable has not been defined in any of the associated files then it will be created and set to 0 the very first time it is referenced (and will not persist between runs). You can, however, define a default value for local variables using the following files:- using the [LocalVars_EX1.N] section of the FLT file you can define a non-persistent local variable- using the [LocalVars_EX1] section of the Systems Config file you can create a persistent local variableThis variable can be read and set within the scope of the user aircraft, and can be read by AI Aircraft. This variable is scoped to each instance of the aircraft that uses it, so each instance will have a unique version of the local variable (unlike the un-scoped L var type).IMPORTANT! L:1 vars can only hold numeric data and nothing else, eg: no strings, no binary values, no structs, etc…
M	Mouse Variable	Gets the state of the mouse for use in mouse click handlers. Please see the Mouse Variables section below.NOTE: This identifier cannot be used when working with Input Events.	No
O	Component Variable	Used for variables within components, where the variable scope is the component itself.	No
P	Program Variable	Same as the Environment Variable E:	Yes
R	Resource Variable	This is used to retrieve a value from an external resource, which can either be a legacy Help ID or Tooltip ID, or something from a custom localization file. See Resource Variables for more details.
X	Calculator Variable	This variable is used exclusively when creating Mission Definitions and is for referencing parameters created in the <CalculatorParameterList> element within an RPN calculation (inside a <CalculatorFormula>.	No
W	Wwise Event	This is a Wwise Event ID and allows you to trigger a Wwise event based on logic driven by the XML. This makes it more flexible than the sounds defined in sound.cfg and the AnimSoundEvents, although more complex to use.	No
Z	Custom SimVar	These are user-defined variables which are stored in an object’s sim. The variable name is not one that has been predefined in the Microsoft Flight Simulator 2024 engine code, so anyone can create one with the name they want, as long as it doesn’t conflict with an existing SimVar.	No

Data Types#

The current version of RPN that is used by Microsoft Flight Simulator 2024 can work with the following data types:

• Double - A double is a floating point data type used to hold decimal values.
• Int - An integer is a “whole number” data type for values with with no decimal points.
• String - A string is a special data type that is meant to hold characters.
• Vec3X - A vec is a data type comprised of 3 independent floating point values, with no specific utility.
• PBH - Similar to a vec, this data type holds 3 independent floating point values that specifically represent the values of pitch, bank, and heading.
• ProxyOffset -

Function Library#

The RPN variable prefix F: can be used to access specific RPN functions. To give a very simple example of how to use these F: functions, let’s start by first creating an O: var, defined as:

(O:MyValue)

Now, to alter this value using the F: functions you would use the following to set the variable:

#A_VALUE# MyValue (>F:VarO)

And to get the variable:

MyValue (F:VarO)

The table below shows the full range of functions currently available:

To use F:Format to create dynamic runtime variables you would flag the value(s) to substitute using % (along with a stack operator, s in the following example):

'replacement' '1st' 'My %s string with a %s' (F:Format)

which would give:

"My 1st string with a replacement" (F:Format)

Note On AnimPos, EmissivePos, And VisibilityPos#

The functions AnimPos, EmissivePos, And VisibilityPos all work in the exact same way and are used to get the value of the position driving an animation, an emissive element, or a visibility element. These functions use the following format:

'name(@target)' (F:AnimPos\|EmissivePos\|VisibilityPos(, unit)

For example:

'my_animation' (F:AnimPos)

This returns the position of the animation called 'my_animation', which - if the animation was 3/4 completed, for example - would be 75, since the default return value when no unit is supplied is a percentage. However, the value can be requested in a different unit, and the automatic conversion will be based on the value over the value range in Percent Over 100 converted to the requested unit. For example:

'my_node' (F:EmissivePos, percent)

In this example, if the emissive value is a value of 0.5 and falls within the range of 0-1, then the returned value will be 0.5 / 1 (in Percent Over 100) converted to percent which is 50.

For the AnimPos an animation name must be provided, and for the EmissivePos and VisibilityPos a node name is expected. If the component is not part of the same behavior (in another Sim-Sttachment, for example) a target must be added. This target correspond to the alias given to the Sim-Attachment, for example:

'ANNUNCIATORS_LOWFUEL@Annunciators_Panel' (F:EmissivePos, position 16k)

Mouse Variables#

When using the M: identifier, you can check for any one of the following variables:

Resource Variables#

The resource variable R: can be used to retrieve a value from a resource file, and has two separate “modes”:

• R:0 - This is to be used with localization IDs to extract a simple localized string from a file. It also supports legacy projects and systems that use the ToolTip ID(opens in a new tab) (or Help ID)(opens in a new tab) variables that don’t require any dynamic elements, although these should not be used in new projects. For example:

  (R:0:HELPID_EXTR_LOW_VOLT)

• R:1 - This is the way that all new projects should use the R: variable and is designed to permit you to extract a localized ID from a file, and can also create a dynamic tooltip based on an RPN stack expression. For example:

  1 (R:1:@TT_Package.AUDIOPANEL_KNOB_COM_VOLUME_ACTION) (F:Format)

  In this example the <Macro>@TT_Package would be the path to the localization file, while AUDIOPANEL_KNOB_COM_VOLUME_ACTION is the value in the file to retrieve, which in this case would be the string "Adjust COM %d volume". The expression then uses the F: variable to perform a substitution which will finally output the string “Adjust COM 1 volume”.

Expression Operators#

There is a long list of operators that can be used within RPN stacks, all of which are given in the tables below.

General Operators#

Comparison Operators#

Bit Operators#

Logical Operators#

Numerical Operators#

Special Operators#

String Operators#

Stack Operators#

Operator Notes:#

• Formatted strings use a similar but slightly different syntax.

• All strings should be written using single quotes, for example: ‘abcxyz’.

• Hexadecimal numbers can be entered using the 0x convention (the hex value can use upper or lower case, for example: 0xff or 0xFF00AA00)

• Octal numbers can be entered by using a leading zero. For example, 022 is octal 18. This means you must be careful not to have leading zeros on decimal numbers.

• Scientific notation can be used to represent values, for example: 5E2 represents 5 x (10 to the power of 2) and 5E-2 represents 5 x (10 to the power of -2), giving 500 and 0.005 respectively.

• For vectors made using the xyz, pbh, or agl, you can retrieve the individual components using the “&” accessor, eg: &x, &y, &z, &p, &b, &h.

Strings#

The following sections contain information specific to the output of strings and how the RPN should be formatted for this.

Formatting Numbers#

If you wish any numbers to be formatted in a specific way then you need to use the exclamation mark symbol along with a designated letter, eg: !x!. This letter must be lowercase, and can only be one of the following:

• s: the number should be formatted as a string.
• d: the number should be formatted as an integer. Note that if the number is not already an integer, it will be rounded (not truncated) to the nearest integer.
• f: the number should be formatted as a float.

When setting up number formatting in this way, you can (optionally) choose to preceed the formatting letter by a number. This number specifies the minimum number of digits to display.

When working with decimal numbers, the following rules will be applied:

• If d is preceded by the digit “0”, then leading zeros are added if necessary.
• If d is preceded by “-”, text is left-aligned.
• If d is preceded by “+, a “+” symbol is indicated in front of the number when the number is greater than 0 (a “-” is always used to indicate numbers less than 0).
• If d is preceded by "” (space), leading spaces are added if necessary.

For floating point numbers, the following rule applies:

• If a decimal point is used in the formatting number, the digit after the decimal point specifies the number of digits to display after the decimal point.

Below you can find some examples of number formatting using various letters and values:

Conditional Gauge Strings#

The format of conditions (if, then, else, and case statements) in gauge strings is different from that in other scripts. In gauge strings use the %{if}, %{else}, and %{end} constructs to choose which text to display. Note that these keywords are case-sensitive and must be typed in lowercase. Also, there must not be a space between the “%” and the “{”. An if statement can be used without a corresponding else, in which case nothing is displayed if the result of the condition is false. The syntax for usage is one of the following:

%(CONDITIONAL)%{if}TEXT TO DISPLAY IF TRUE%{else}TEXT TO DISPLAY IF FALSE%{end}
%(CONDITIONAL)%{if}TEXT TO DISPLAY IF TRUE%{end}  

For example:

%( 1 )%{if}ON%{else}OFF%{end}

would give the output ON, whereas:

%( 0 )%{if}The value is true%{else}The value is false%{end}

would give the output: The value is false.

Escape Codes#

It is also possible to insert escape code sequences into gauge strings.

Examples#

Converting InFix To PostFix#

Unfortunately there is no easy way to automatically convert InFix expressions into RPN (PostFix) expressions, especially with the use of SimVars and things specific to the Microsoft Flight Simulator 2024 SDK. However, there are third-party tools that may be of some use to you and that can work quite well, although they are not perfect. One in particular may be worth looking at which you can find from the link below:

• RNP (a language which compiles to RPN)(opens in a new tab)