<img src="docs/static/img/logo.svg" width=48 align="top"> fsmapper

NOTE:| :-| The fsmapper User's Guide is available here. Please refer to this guide for instructions on how to use fsmapper

fsmapper is a Windows application designed to connect a variety of input and output devices to flight simulators. Originally, the development of fsmapper began to connect my DIY controller device, SimHID G1000, to Microsoft Flight Simulator 2020. However, it has now evolved to encompass functionalities that allow the creation of a home cockpit using a wide range of devices. fsmapper targets not only home cockpit builders aiming for an exact replica of a specific aircraft's cockpit, but also general flight simulator players who have limited equipment and space but want to efficiently operate a wide range of aircraft (The truth is, I fall into the latter category as well).

Although fsmapper offers a multitude of functions, it can be summarized into following three main aspects when viewed from the perspective of improving device and space utilization efficiency, as mentioned earlier.

Interaction between devices and Flight Simulators You can reflect the operation of various devices, including custom-made ones, in the operation of various cockpit systems within the flight simulator. Conversely, you can also retrieve the state of instruments and the position of switches in the flight simulator and reflect them on physical devices. fsmapper supports the following flight simulators.
Changes to Input Device Characteristics You can flexibly modify the characteristics and behaviors of input devices, such as altering the linearity of analog axes, changing polarity for alternate switch, generating events that account for the position and hysteresis of analog axes, and so on. This allows for consistent handling of the same throttle device across aircraft with and without afterburners, or enables adjustments for actions like fuel cut-off and thrust reversal.
Virtual instrument panel utilizing Touchscreen Monitors In a multi-monitor environment, you can construct virtual instrument panels on the screen. Particularly when using a touchscreen monitor, intuitive actions like tapping or flicking can be used to manipulate switches and knobs displayed on the screen. By configuring popped-out windows, such as the PFD, as elements of the virtual instrument panel, you can effectively build a glass cockpit. fsmapper excels in handling pop-out windows, allowing you to hide title bars and window frames to seamlessly integrate them as part of the instrument panel. It also provides a workaround for the well-known issue where pop-out windows in MSFS2020 cannot be touch-operated.

If you watch this video, you'll get a better understanding of what can be achieved with fsmapper as described above. In this video, A320's virtual instrument panels are assembled on a 10.5-inch touchscreen by combining six popup windows (FCU, PFD, ND, ECAM x 2, MCDU) and user-defined instruments and switches. Additionally, by dynamically switching and displaying the instrument panels, it enables diverse information representation and manipulation even on a small screen.

All the functionalities mentioned earlier are accessed through Lua 5.4 scripts. Although fsmapper is implemented as a Windows GUI application, it actually only features a dashboard to display operational status and a console function to show messages during script execution,　particularly error messages. If there wasn't a necessity to allow users to select pop-out windows in Microsoft Flight Simulator 2020,　I believe it would have been implemented as a command-line interface (CLI).

The diagram above illustrates how fsmapper works. fsmapper patiently waits for events (green arrows) such as operations from various input devices, touchscreen interactions, and changes in the aircraft's status within a flight simulator. Upon detecting an event, fsmapper executes the corresponding action. These actions are Lua function objects that allow interaction (orange arrows) with various objects such as aircraft controls within a flight simulator, graphical representation on the screen, and data output to devices, facilitated through Lua functions and Lua objects provided by fsmapper.

The 'Configuration File' specified by the user during fsmapper execution refers to the definition of the correspondence between these events and actions as a Lua script.

How to build and install

It’s easier to download and install the pre-compiled package from here. However, you can also build it yourself　by follow the steps below.

Requirements Make sure that the following softwares are installed in advance.
- Visual Studio 2026 whilch is instaled with folowing workloads:
 - Universal Windows Platform development
 - C++ desktop development
 - C++ game development
- Microsoft Flight Simulator 2024 SDK
- nuget.exe should be placed at the folder which is indicated by PATH environment variable.
Running a console Run cmd.exe or PowerShell.exe on any console. Note that environment variables must be set to complie x64 binaries. The one of easiest way is using the following shortcut made when Visual Studio was installed.
- x64 Native Tools Command Prompt for VS

Downloading source codes

$ git clone --recursive https://github.com/opiopan/fsmapper.git

Preparing dependent modules Downloading and compiling Lua source codes and downloading vJoySDK will be done by following step. 
```
$ cd fsmapper\modules
$ .\prepare_modules.bat
```

Compiling

$ cd ..\src
$ nuget restore fsmapper.sln
$ msbuild /p:Configuration=Release

Making deployable package
```
$ cd ..\deploy
$ .\deploy.bat
```
Installing Copy fsmmapper folder to any folder you want.
```
$ xcopy fsmapper <DESTINATION_FOLDER_PATH>
```

Additional softwares

While not mandatory for running fsmapper, it's highly recommended to additionally install the following two pieces of software. fsmapper provides users with more convenient features by integrating with these softwares.

vJoy (Dwonload) vJoy is a device driver that functions as a virtual joystick. fsmapper offers multiple functions to alter button status, axis positions, and POV settings of the vJoy device. Through the use of the vJoy device, fsmapper provides highly flexible configurability for human interface devices.
MobiFlight WASM Module (GitHub) This WASM module, functioning as an add-on for FS2020, enables an external-process utility to execute arbitrary RPN script and monitor changes in the aircraft's internal state stored in local variables like LVARs. fsmapper gains unrestricted access to retrieve and modify aircraft states by communicating with the MobiFlight WASM Module operating within the FS2020 process. The easiest way to install the MobiFlight WASM Module is by downloading and installing the MobiFlight Connector from here.

The vanilla fsmapper communicates with FS2020 through the SimConnect API, which allows an external process to access only SimVars and Event IDs. However, this access isn't sufficient to control all operable objects in a cockpit or retrieve all gauge statuses to display on another DIY gauge or virtual instrument panel. To control and access all cockpit gauges, accessing local variables within an aircraft module is necessary, and the Gauge API serves this purpose. Regrettably, this API can only be used within the WASM module. The MobiFlight WASM Module addresses this limitation, enabling fsmapper to access all local variables by communicating with this WASM module.

How to use fsmapper

Please refer the Tutrial and the Configuration Guide.

Supporting custom devices

fsmapper only supports Direct Input gaming devices and SimHID devices, but it provides a plugin API to support other devices.
For details, please refer to the Plugin SDK Reference.　

Sample Scripts

This repository includes several configuration scritps for practical use of SimHID G1000 at here. To use these scripts, vJoy driver and [MobiFligh

Fsmapper

Install / Use

README