MSFS2020 User Defined WASM Module Events Best Practices - MobiFlight/MobiFlight-Connector GitHub Wiki

Prepared by Jaime Leon - 8-Jun-21

Version 0.24

GENERAL DOS AND DON’TS

  1. Do learn RPN scripting. You will need to learn a little about this topic to understand the scripts used in MSFS. The scripting language used by MSFS is called RPN (“Reverse Polish Notation”). It is the way old HP engineering calculators worked, where numbers (or variables) are entered first and then the operand to be executed is entered last. The evaluation of RPN scripts is done using a stack operation analogy. For more information, see the RPN scripting reference down below. Just to get a feel, the following example reads a variable value in feet and adds 100.

    (A:PLANE ALTITUDE, feet) 100 +

*** EVENTX.TXT USE IS DEPRECATED *** All code can be input directly to the newer Input and Output code boxes in Mobiflight.

  1. Variables and in-sim events (not wasm module events) names are enclosed in parenthesis. No space after the opening, nor space before the closing parenthesis. A variable will have a type (like A:, L:, H:, I:, M:, O:, etc), followed by the variable name, followed by an optional index (:1), followed by a comma, and followed by the optional units (percent, percent over 100, second, feet, mhz, khz, number, enum, bool, etc.). As an example:

    (A:ENGINE ANTI ICE:1, Bool)

    is an A type variable (or “Avar”), whose name is ENGINE ANTI ICE, it is being accessed with an index of 1, and the variable is a Boolean (only takes 0 and 1 values). The space after the comma is optional.

  2. Do note that event and script names are not case sensitive. The event names may contain any combination of letters and numbers, including spaces and underscores. The letters in the name are not case sensitive, but the variable types are required to be in upper case. So, for example:

    MY_EVENT_NAME#0 (>L:MYVARIABLE_NAME)

    is the same name and code as the following:

    my_evenT_name#0 (>L:myVaRiaBle_Name)

    Note the upper case “L” in the variable type is required. The rest is not case sensitive. Although not strictly necessary, we follow the case use (upper or lower) in the same way a variable is presented in MSFS. For example:

    (L:XMLVAR_Pitot_1, bool)

    will normally be shown the same way in our documented scripts. Also, the units are not case sensitive: bool, Bool, and BOOL are all equivalent.

  3. Do note that some variables and event names have a > sign after the opening parenthesis. This means to write a value to this variable or in the case of events, execute this event. Be careful when transcribing code, as it is very easy to miss entering the > and later it is very hard to spot the error. Examples follow:

    (L:my_var) ++ (>L:my_var) read my_var, increase value by 1, store in same variable

    1 (>L:ASCRJ_FCP_APPR) set the variable to a value of 1

    (>K:AP_AIRSPEED_ON) execute the autopilot air speed on event

    1000 (>K:AP_ALT_VAR_INC) use parameter 1000 to execute autopilot altitude increase

  4. Do use unique names. Each event name to be used by the wasm module must be unique within the context of the events.txt list of events. Bear in mind that there are already over 2,200 documented event names. When duplicate names exist, the latter definition will always overwrite the earlier definition, leading to potentially undesirable results. To prevent unintended duplicate names, it is suggested to prefix all your events with the target airplane, for example

    WT_CJ4_AUTOPILOT_MASTER_ON or TBM930_PULSE_SWITCH_ON

  5. Do use names that can be understood by others. The computer doesn’t care, but we do. Using "A32NX_AP_MASTER_ON" is much better than "A32NX_B2355", although both are valid names. Use shorter names and abbreviations when reasonable, without becoming too cryptic. Don’t include unnecessary words in your names. Nobody likes very long event names. Assume other people will need to understand and use your event.

  6. Do build each event definition statement entirely in one single line. This is a requirement in both events.txt and events.user.txt. You will notice that event code in MSFS is presented with linefeeds that make reading easier. When transcribing code from MSFS, you will need to replace all the linefeeds with spaces and condense everything into one line. Lines can be any length, so don't worry about everything being bunched in one line. Use of a code editor app like Notepad++ is recommended for your event editing.

  7. Do pay close attention to the spaces in the code. The code parser is very unforgiving. There is no space after the if and els clauses. There is no space after the opening and before the closing parenthesis in a variable name. There MUST be at least one space between two variables or between any other elements in a script.

  8. New InputEvents tab in Model Behaviors. Since MSFS2020 version 1.18.13, a redesign of the Model Behaviors window was made. Among the new features, there is a tab called "InputEvents" that shows all the registered events for a particular airplane, with the code related to each event. When selecting one event in this page, there is an option to "Add to control panel" which opens a new box to the right with the event details. Variations of the same event are presented in tabs: Init, Value, Inc, Dec and Set. The code presented in these boxes can be selected with the mouse and copy/pasted to a code editor. This makes it far easier to extract, edit and test events. Many more functions are available from this tab, but are beyond the scope of this writing.

  9. Do mind how events.user.txt is processed. The WASM module will always merge events.user.txt over events.txt when starting up. Please note that this process implies that any new names in events.user.txt will be added, and any duplicate names will be overwritten. Also please note that the contents of events.user.txt WILL ALWAYS PREVAIL over the contents of events.txt. This means you can change an existing event code by putting its name with the new code for it in events.user.txt. Do be careful and mind what you are doing. You have to remember that your code in events.user.txt is the one being executed. When in doubt, it is safer to use new names for your tests.

  10. Do put your event names in msfs2020_eventids_user.cip. In addition to putting your new and test events in events.user.txt you will also need to include these event names (just the name, not the code) in the file "msfs2020_eventids_user.cip". This file is located inside the Mobiflight application folder under the subfolder "Presets". Mobiflight uses the list of events in msfs2020_eventids_user.cip files to display the available events under the User group in the config wizard window user interface. The new and test event names stored in the events.user.txt file MUST match the names used in the msfs2020_eventids_user.cip file.

    One exception to this rule is only if you are testing changing the code for an existing event. Since the event name is already contained in events.txt, there is no need to include it in msfs2020_eventids_user.cip. As mentioned in #15, you use the same name of the event and the code substitution occurs automatically when the two txt files are merged. Again, when in doubt it is safer to use unique names. If your MF configuration already uses the event name, then there is no need to change anything in MF in order to test the new code assigned to the existing event name.

  11. Do choose your event names wisely to save some work later. Once your events are published to the community in an events.txt update, you can safely delete those events from your events.user.txt file. If the new events names in the online spreadsheet match the same event names you used in your testing, then you don’t need to change your MF configuration. MF will recognize the name and correctly show its new group within events.txt.

    It is good practice to delete your already published events from your events.user.txt file. If you keep them, this is the code that will always prevail, which means that any later updates to any of these events, maybe not initiated by you, would not be recognized, even after updating events.txt.

  12. Do update your events.txt file. As new events are entered into the online spreadsheet, updates are published so that all users of MF can have the latest events. This is currently updated every weekend by the community member @rofl-er.

  13. Do restart MSFS2020 or use the “touch” command. You have created new events in event.user.txt. Now, in order for the MF WASM module to recognize any changes made to your events.user.txt, it must be reloaded by the simulator. This is done by restarting the game, a process that can easily take 10 minutes.

    After Sim Update 5, unfortunately, the touch command does not work any more.

    TOUCH COMMAND IS OBSOLETE AFTER SU5. Alternatively, we have found a workaround to force MSFS to reload the MF wasm module without restarting the simulator. This method involves running a batch file that changes the date/time stamp on the wasm module StandaloneModule.wasm and layout.json files. You can get this “touch.cmd” script file from the MSFS2020 WASM MODULE channel in the Discord server or you can copy and paste the following lines:

    @echo off

    copy /b "F:\Microsoft Flight Simulator\Community\mobiflight-event-module\layout.json"+,,"F:\Microsoft Flight Simulator\Community\mobiflight-event-module\layout.json"

    copy /b "F:\Microsoft Flight Simulator\Community\mobiflight-event-module\modules\StandaloneModule.wasm"+,,"F:\Microsoft Flight Simulator\Community\mobiflight-event-module\modules\StandaloneModule.wasm"

    Please note that you will need to change the path shown in quotes to the path where your installation has those specific files. You can store this windows script file anywhere in your disk. For example, on your Desktop. Run this batch file every time you need to test a new or modified script. Once the script is run, MSFS2020 will freeze for about 30-40 seconds while reloading the wasm module.

  14. Do contribute to our community. Once you have successfully tested an event, you are encouraged to contribute to the community by posting your events to the "Hubhop online events and variables presets database". The address is shown down below in the Online References. Hubhop replaces our old online spreadsheet repository to store all MSFS2020 events. Events can be searched by Vendor, Airplane, or System. You can search any event or enter your new events to the database, it is very easy to use.

CONCLUSION

This search, testing and recording of simulator events is an ongoing effort of the Mobiflight community, so that other members can benefit from our previous accumulated experiences and be able to build panels or home cockpits for flight simulation more easily.

If you have questions or comments, be sure to join us in the Mobiflight forum and the Mobiflight Discord server, where you will be able to find help from more experienced members and the latest news about this excellent piece of software.

 

GLOSSARY OF TERMS

Boolean, bool A type of variable that represents one bit of information and therefore only takes values of 1 or 0. Also interpreted as True or False, or as ON or OFF. Extensively used to represent the state of switches, LEDs, or even entire systems. It is the building block of binary logic.

LVAR “Local Variables” created by the mod airplane designers, often used to provide support for functions not included in the simulator

RPN “Reverse Polish Notation” Scripting language used in MSFS to program events, characterized by its reverse order notation, where numbers are entered first and the operands last

WASM “WebAssembly” is a new type of code that can be run in modern web browsers — it is a low-level assembly-like language with a compact binary format that runs with near-native performance

ONLINE RESOURCES REFERENCE

MSFS SDK Documentation: https://docs.flightsimulator.com/html/index.htm#t=Introduction%2FIntroduction.htm&rhsearch=status&ux=search

RPN Scripting: https://docs.flightsimulator.com/html/Additional_Information/Reverse_Polish_Notation.htm

https://www.prepar3d.com/SDKv5/sdk/scripting/rpn_scripting.html

Hubhop online events and variables presets database: https://hubhop.mobiflight.com/#/

Mobiflight web page: https://www.mobiflight.com/en/index.html

Mobiflight Github: https://github.com/Mobiflight/MobiFlight-Connector

Mobiflight Discord server: https://discord.gg/99vHbK7

Youtube Video: https://www.youtube.com/watch?v=PKBjEl9E5A4