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 2024 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.
  • MSFS_AirportContext.h - This is the "base" file that should be included in all projects that are wanting to support WebAssembly modules in airports.
  • MSFS_CommBus.h - This file corresponds to the Communication API.
  • MSFS_Event.h - This file corresponds to the Event API.
  • MSFS_GaugeContext.h - This is the "base" file that should be included in all projects that are creating WASM gauges using the MSFS 2024 callbacks.
  • MSFS_IO.h - This file corresponds to the IO AP.
  • MSFS_MapView.h - This corresponds to the MapView API.
  • MSFS_Network.h - This corresponds to the Network API.
  • MSFS_PlannedRoute.h - This corresponds to the Planned Route API.
  • MSFS_Render.h - This corresponds to the NanoVG API.
  • MSFS_Utils.h - This is a small library of functions used by several API.
  • MSFS_Vars.h - This file corresponds to the Vars 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.
  • 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. Note that thisAPI is now considered a legacy API and instead you should be using the Vars API for Microsoft Flight Simulator 2024 aircraft.

 

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

 

 

Upgrade a WebAssembly module from MSFS 2020 to MSFS 2024

Unlike Microsoft Flight Simulator 2020 where all WebAssembly modules were run on the main thread, Microsoft Flight Simulator 2024 runs WebAssemly modules on different threads (however, each module is still single threaded). Thanks to that improvement, the entire frame can be used to run updates, callbacks... which increases overall performance. Standalone modules will automatically benefit from this improvement, but gauge modules will not benefit from the entire feature without changes. Things to note about the updated WASM modules are as follows:

 

 

  • The Gauge API has been deprecated and is now considered a legacy API, mainly because its architecture is not compatible with the Microsoft Flight Simulator 2024 simulation architecture anymore. However the features provided by this API are still available through the Vars API and Event API.

 

  • Standalone modules now have an update callback to avoid having a SimConnect connection used only for this purpose.

 

  • Microsoft Flight Simulator 2024 streams a lot of content, including WebAssembly packages of all types. Because of this, dependency files (data, assets...) might not have been downloaded yet when referenced. If a WebAssembly module tries to read a file which has not been downloaded yet (using synchronous libc functions to read the file), the module will be "paused" for few frames until the file is ready to be used that in way. To avoid this behavior, we strongly advise you to use the new IO API for read purposes.

 

  • Some SimConnect functions will send a different structure than the one sent from Microsoft Flight Simulator 2020 (ie: members are the same but the size of some of them has been changed). Because of this change, some logic will need to be reviewed to be sure that every thing works correctly, especially if the module uses short static buffers with those functions. More information here: SimConnect SDK.

 

  • A new library has been added - MSFS_WasmVersions.a - that must be linked with your WASM project for it to be detected as a MSFS 2024 module (SimConnect for instance). Without this, those features will behave as if they were from a MSFS 2020 module. If you are using the Microsoft Flight Simulator 2024 platform toolset to compile your WebAssembly module, then this library is linked automatically, otherwise you will have to integrate it in your pipeline yourself.

 

 

WebAssembly Modules Usage

A WebAssembly module can be used by Microsoft Flight Simulator 2024 in 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 or more gauge callbacks, see Creating WASM Gauges.
  • As an airport module if it is linked to a scenery, in which case it will be automatically loaded (and unloaded) according to the scenery spawn and de-spawn.
  • As a system module which can contain system callbacks, see Creating WASM Systems.

 

In all 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 2024 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 un-encrypted (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.

 

 

Known Issues and Limitations

With the current releases of the game and SDK, the following limitations exist:

  • The Windows API is not supported.
  • C++ exceptions are not supported.
  • C++ threads are not supported.
  • The GDI+ wrapper is very incomplete.
  • The WebAssembly module must be compiled in Debug mode for C/C++ code for symbols to be visible while debugging.

 

Related Topics

  1. Creating WASM Gauges
  2. Debugging WASM Gauges
  3. Platform Toolset
  4. GDI+
  5. WASM Debug