WEBASSEMBLY (WASM)

In order to provide both security and portability, it was decided to move away from add-ons distributed as DLLs in favour of add-ons distributed as WebAssembly modules. In order to do so without requiring a full rewrite of existing add-ons, a new platform toolset was designed for Visual Studio with the following capabilities:

  • Direct compilation of C/C++ projects into WebAssembly (WASM).
  • Debugging of WebAssembly modules by attaching to the game executable.
  • Full support for the standard C library.
  • Large support for the standard C++ library (see below).
  • GDI+ wrapper based on the NanoVG API to facilitate porting existing add-ons.


While WebAssembly itself is well documented, there seems to be some confusion as to how WebAssembly modules can be run outside of a web environment. To clear a few misconceptions:

  • The add-ons developed in WebAssembly for Microsoft Flight Simulator are not interpreted but rather converted to native code ahead of time (as DLLs).
  • WebAssembly itself doesn't offer API "X", "Y" or "Z" - it is up to its implementation to grant access to these APIs.

 

You can also find a complete tutorial to get you started using WASM for your gauges on the following page (including information on Debugging):

 

 

SDK APIs

The API's supplied with the SDK for use in Visual Studio are as follows:

Location Of The MSFS.h File

  • MSFS.h and MSFS_Core.h - These are the "base" files that should be included in all projects that are creating WASM gauges.
  • Legacy/gauges.h and Legacy/gps_info.h - These files are the main gauge API and they have multiple functions related to getting and setting data, rendering, etc... You can find full details here: Gauge API.
  • MSFS_CommBus.h - This file corresponds to the Communication API.
  • MSFS_MapView.h - This corresponds to the MapView API.
  • MSFS_Network.h - This corresponds to the Network API.
  • MSFS_Render.h - This corresponds to the NanoVG API.
  • MSFS_Vector.h - This is a small library of helper functions for vector maths.
  • MSFS_Vfx.h - This corresponds to the VFX API. 
  • MSFS_WindowsTypes.h - This is a library of type definitions for that defines some types used by windows/rendering with their equivalent in WASM.

These API's are supplied as part of the SDK Platform Toolset.

 

 

WebAssembly Modules Usage

A WebAssembly module can be used by Microsoft Flight Simulator in two different ways:

  • As a standalone module if it is placed in the modules subfolder of a package - it is then automatically loaded when the package is mounted into the VFS.
  • As a gauge module which can contain one more gauge callbacks.

 

In both cases the game will look for and execute the following module functions if they exist:

  • extern "C" MSFS_CALLBACK void module_init(void): upon loading or after sign-in.
  • extern "C" MSFS_CALLBACK void module_deinit(void): upon closing the game or after sign-out.

 

 

File Access

In order to access files from within an add-on, filenames can be prefixed in two ways:

  • " .\": to access the files from within the add-on package. This has a read-only access.
  • " \work": to access a persistent storage that the add-on can use. This is a read/write access.

 

It is important to note that when publishing your packages to the Microsoft Flight Simulator Marketplace for PC (this does not apply for Xbox), an encryption system is applied to protect the package contents. This encryption system means that your WASM modules can no longer access certain files within the package, meaning the module will not be able to retrieve the information it requests. It is because of this that you should never rely on parsing the files listed below when designing your code.

 

For SimObjects, you shouldn't try to access any file that ends with the following:

  • *engines.cfg
  • *flight_model.cfg
  • *systems.cfg
  • *.xml
  • *LOD0.bin
  • *LOD0.gltf


For Liveries, you shouldn't try to access any file that ends with:

  • *aircraft.cfg
  • *sim.cfg
  • *LOD0.bin
  • *LOD0.gltf
  • *LOD00.bin
  • *LOD00.gltf
  • *.dds

 

For scenery, you shouldn't try to access any files with the following extension:

  • *.bgl

 

If there is information within these files that is required by your WASM module, we advise you to copy this information to a different file that is known to remain unencrypted (ie: a file that is not of the type listed above), and include that file with your package.

NOTE: This system may be reviewed, updated, and improved upon in future releases.

 

 

Visual Studio Project Properties

The VS Properties Window For A WASM Module

When creating your WASM projects, most of the project settings will be the same as for a standard C++ project, however there are some things that should be set up with specific values, which we'll outline here:

 

  • Configuration Properties: These can be left with their default values.
  • C/C++: In this section you have the following properties which may need editing:
    • General - Debug Information Format: This must be set as //clang:-g. It should be set automatically, but it is worth checking.
    • General - Warning Level: Set this field to Level 3, and check your warning regularly, as clang will tell you if you do something wrong.
    • General - Multi-processor Compilation: Use this field to speed up your compilation time.
      Multi-Processor Compilation Options
    • Optimization: When debugging you should set everything to false/disabled/no. For release, we recomend that you set Optimization at Maximum Optimization (Favor Speed) (/O2). Note that with the latest SDK update, we automatically optimize modules which have a value in Optimization field (/clang:-O3), and no optimization means it is debuggable. The others fields can also be set as you require.
  • Linker: In the Debugging section you want to set it to "Generate Debug Info (/DEBUG)" when you are testing and debugging the module, but then for release, set it to "No".

 

Edit And Continue

It is possible to recompile some parts of your project while it is executing (and it will keep the same memory). To be able to do this, you must use Edit And Continue compatible WASM in Debug mode. In this case "compatible" means the most up-to-date version supplied with the most recent SDK release.

 

The general workflow for Edit And Continue is as follows:

  • Make some changes to your C++ code.
  • Open the WASM Debug Window and select your package.
  • Click on the "Experimental" node with the Recompile button and press it.
  • Your new code will be compiled, and the WASM will be patched. Note that some logs and popups will tell you exactly what has happened (ie: success, failure, descriptions...).

 

Keep in mind that there are some limitations:

  • You can't update an existing type.
  • You can't add a new member to a class, for example, but you can add functions/methods.
  • If you want to make a lot of changes, it is safer to make a clean new WASM.

 

 

Debugging

For help with debugging WASM gauges, please see the following page: