Repository files navigation

A non-official SimConnect client library written in TypeScript. Lets you write Node.js applications that communicates directly with Microsoft Flight Simulator, FSX and Prepar3D without need for additional SDK files. Runs on Windows, Linux and Mac.

This project is a port of the Java client libraryjsimconnect, originally written bylc0277. Details about the protocol can be found onlc0277's old website. A huge thanks to everyone involved in that project! 🙏

💡 Tip: check out themsfs-simconnect-api-wrapper which provides a more user-friendly wrapper around some of thenode-simconnect APIs.

1. npm install node-simconnect
2. Check out the/samples folder for example scripts.
3. Refer to theofficial SimConnect documentation for comprehensive details on SimConnect APIs and usage.

There are alsoauto generated API-docs.

You always start by callingopen(...) which will attempt to open a connection with the SimConnect server (your flight simulator). If this succeeds you will get access to:

• recvOpen: contains simulator information
• handle: used for accessing the SimConnect APIs

Example:

import{open,Protocol}from'node-simconnect';constEVENT_ID_PAUSE=1;open('My SimConnect client',Protocol.FSX_SP2).then(function({ recvOpen, handle}){console.log('Connected to',recvOpen.applicationName);handle.on('event',function(recvEvent){switch(recvEvent.clientEventId){caseEVENT_ID_PAUSE:console.log(recvEvent.data===1 ?'Sim paused' :'Sim unpaused');break;}});handle.on('exception',function(recvException){console.log(recvException);});handle.on('quit',function(){console.log('Simulator quit');});handle.on('close',function(){console.log('Connection closed unexpectedly (simulator CTD?)');});handle.subscribeToSystemEvent(EVENT_ID_PAUSE,'Pause');}).catch(function(error){console.log('Connection failed:',error);});

Most of the APIs described in theofficial SimConnect documentation are implemented innode-simconnect. For information on how each feature works, please refer to the official documentation.

Several new features have been added to the SimConnect API after the new Microsoft Flight Simulator was released, and more features are likely to come. Most of these will only be implemented on request. If you are missing any features innode-simconnect feel free toopen a new issue or create a pull request.

Prepar3D support and Prepar3D-only-features will not be prioritized.

For a complete list of available API methods, please refer to theSimConnectConnection class.

A major feature used by C/C++/C# implementation of SimConnect client libraries is the ability to directly cast a memory block to a user-defined structure. This is technically impossible to do in JavaScript or TypeScript since memory layout of classes and types are not accessible. Consequently, the wrapping/unwrapping steps must be done by the user.

Example using the official SimConnect SDK (C++):

// C++ code ////////////////////structStruct1 {double  kohlsmann;double  altitude;double  latitude;double  longitude;int     verticalSpeed;};// ....    hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1,"Kohlsman setting hg","inHg");    hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1,"Indicated Altitude","feet");    hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1,"Plane Latitude","degrees");    hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1,"Plane Longitude","degrees");    hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1,"VERTICAL SPEED","Feet per second", SimConnectDataType.INT32);SimConnect_RequestDataOnSimObject(hSimConnect, REQUEST_1, DEFINITION_1, SIMCONNECT_OBJECT_ID_USER, SIMCONNECT_PERIOD_SECOND);// ....void CALLBACKMyDispatchProc(SIMCONNECT_RECV* pData, DWORD cbData) {switch(pData->dwID) {case SIMCONNECT_RECV_ID_SIMOBJECT_DATA: {            SIMCONNECT_RECV_SIMOBJECT_DATA *pObjData = (SIMCONNECT_RECV_SIMOBJECT_DATA*) pData;switch(pObjData->dwRequestID) {case REQUEST_1:                    Struct1 *pS = (Struct1*)&pObjData->dwData;break;                }break;        }    }}

The code below demonstrates how the same is achieved withnode-simconnect:

// TypeScript code ////////////////////constREQUEST_1=0;constDEFINITION_1=0;// ....handle.addToDataDefinition(DEFINITION_1,'Kohlsman setting hg','inHg',SimConnectDataType.FLOAT64);handle.addToDataDefinition(DEFINITION_1,'Indicated Altitude','feet',SimConnectDataType.FLOAT64);handle.addToDataDefinition(DEFINITION_1,'Plane Latitude','degrees',SimConnectDataType.FLOAT64);handle.addToDataDefinition(DEFINITION_1,'Plane Longitude','degrees',SimConnectDataType.FLOAT64);handle.addToDataDefinition(DEFINITION_1,'VERTICAL SPEED','Feet per second',SimConnectDataType.INT32);handle.requestDataOnSimObject(REQUEST_1,DEFINITION_1,SimConnectConstants.OBJECT_ID_USER,SimConnectPeriod.SIM_FRAME);// ....handle.on('simObjectData',recvSimObjectData=>{switch(recvSimObjectData.requestID){caseREQUEST_1:{constreceivedData={// Read order is important!kohlsmann:recvSimObjectData.data.readFloat64(),altitude:recvSimObjectData.data.readFloat64(),latitude:recvSimObjectData.data.readFloat64(),longitude:recvSimObjectData.data.readFloat64(),verticalSpeed:recvSimObjectData.data.readInt32(),}break;}}});

When thesimObjectData callback is triggered, therecvSimObjectData.data is used to extract the requested simulation variables. These values are stored as a single continuous binary data chunk/buffer, maintaining the order in which the simulation variables were added to the data definition. In this case, the buffer is 288 bits long (64 + 64 + 64 + 64 + 32), or 36 bytes.

Theread...() functions are used to extract each value individually. When the correct function is used, the reading "cursor" (offset) automatically moves after each read, positioning it at the beginning of the next value in the buffer. Consequently, it is crucial to ensure that the values are read in the same order and using the same data type as initially requested.

If the Node.js application runs on the same computer as the flight simulator you don't need to worry about this part.

To connect from an external computer you must configure SimConnect to accept connections from other hosts. This procedure is also described in the official docs, but here is the short version:

1. OpenSimConnect.xml.

   • FSX:X:\Users\<USER>\AppData\Roaming\Microsoft\FSX
   • MSFS:X:\Users\<USER>\AppData\Local\Packages\Microsoft.FlightSimulator_**********\LocalCache.

2. Set property<Address>0.0.0.0</Address>. Example of a working SimConnect.xml file:

   <?xml version="1.0" encoding="Windows-1252"?><SimBase.DocumentType="SimConnect"version="1,0">    <Filename>SimConnect.xml</Filename>    <SimConnect.Comm>        <Protocol>IPv4</Protocol>        <Scope>local</Scope>        <Port>5111</Port>        <MaxClients>64</MaxClients>        <MaxRecvSize>41088</MaxRecvSize>        <Address>0.0.0.0</Address>    </SimConnect.Comm></SimBase.Document>

Connecting from a remote script can be done by providing the IP address of the flight simulator PC and the port number when callingopen:

constoptions={remote:{host:'localhost',port:5111}};open('My SimConnect client',Protocol.FSX_SP2,options).then(/* ... */).catch(/* try again? */);

Note that if no connection options are specified,node-simconnect will auto-discover connection details in the following order:

1. Look for aSimConnect.cfg in the folder where Node.js is located. If the script is running in Electron, this will be the folder where the Electron executable is installed.
2. Look for aSimConnect.cfg in the user's home directory (%USERPROFILE%, eg.C:\Users\<username>)
3. Look for a named pipe in the Windows registry, automatically set by the simulator
4. Look for a port number in the Windows registry, automatically set by the simulator. node-simconnect will then connect tolocalhost:<port>.