node-simconnect

node-simconnect

A SimConnect client library for Node.JS, written in TypeScript. Integrates directly with the SimConnect protocol and runs on Windows, Linux and Mac.

Credits

This project is a rewrite of the Java client library jsimconnect, originally written by lc0277. Details about the protocol can be found on lc0277's old website.

Instructions

Please refer to the /samples folder for help.

The API works similar to the SimConnect API described in the official documentation.

Quick start

import { open, Protocol } from 'node-simconnect';

const EVENT_ID_PAUSE = 1;

open('My SimConnect client', Protocol.FSX_SP2)
    .then(function ({ recvOpen, handle }) {
        // recvOpen: object containing simulator information
        // handle: the SimConnect handle
        console.log('Connected to', recvOpen.applicationName);
        handle.subscribeToSystemEvent(EVENT_ID_PAUSE, 'Pause');
        handle.on('event', function (recvEvent) {
            switch (recvEvent.clientEventId) {
                case EVENT_ID_PAUSE:
                    console.log(recvEvent.data === 1 ? 'Sim paused' : 'Sim unpaused');
                    break;
            }
        });
        handle.on('quit', function () {
            console.log('Simulator quit');
        });
        handle.on('close', function () {
            console.log('Connection closed unexpectedly (simulator CTD?)');
        });
    })
    .catch(function (error) {
        console.log('Connection failed:', error);
    });

Running over network?

1. Open SimConnect.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.Document Type="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>
   

3. Provide the IP address of the simulator PC and the port number when calling open:

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

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

1. Look for a SimConnect.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 a SimConnect.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 to localhost:<port>.

Functionality

node-simconnect is supposed to behave more or less in the same way as the offical SDK. Please refer to the official SimConnect documentation for a description of the methods below and how to use them.

The new Microsoft Flight Simulator has introduced some new features to the SimConnect ("KittyHawk") API, and more features are likely to come. Most of these will only be implemented on demand if there are specific requests. Feel free to open a new issue or create a pull request.

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

⚠️ = deprecated and will not work, according to the official documentation.

Events and data

Method	Implemented	Tested FSX	Tested P3D	Tested MSFS
addClientEventToNotificationGroup	✅
addToClientDataDefinition	✅
addToDataDefinition	✅	✅
clearClientDataDefinition	✅
clearDataDefinition	✅	✅
clearInputGroup	✅
clearNotificationGroup	✅
createClientData	✅
mapClientDataNameToID	✅
mapClientEventToSimEvent	✅
mapInputEventToClientEvent	✅
removeClientEvent	✅
removeInputEvent	✅
requestClientData	✅
requestDataOnSimObject	✅	✅
requestDataOnSimObjectType	✅	✅
requestNotificationGroup	✅
requestReservedKey	✅
subscribeToSystemEvent	✅	✅
setClientData	✅
setDataOnSimObject	✅	✅
setInputGroupPriority	✅
setInputGroupState	✅
setSystemEventState	✅
setSystemState	✅
unsubscribeFromSystemEvent	✅	✅

AI Objects

Method	Implemented	Tested FSX	Tested P3D	Tested MSFS
aICreateParkedATCAircraft	✅
aICreateEnrouteATCAircraft	✅
aICreateNonATCAircraft	✅
aICreateSimulatedObject	✅
aIReleaseControl	✅
aIRemoveObject	✅
aISetAircraftFlightPlan	✅

Flights

Method	Implemented	Tested FSX	Tested P3D	Tested MSFS
flightLoad	✅
flightPlanLoad	✅
flightSave	✅

Facility

Method	Implemented	Tested FSX	Tested P3D	Tested MSFS
addToFacilityDefinition	✅	n/a	n/a	✅
requestFacilitiesList (including Ex1)	✅
requestFacilityData (including Ex1)	✅	n/a	n/a	✅
subscribeToFacilities	✅	✅
unSubscribeToFacilities	✅	✅

Menu

Method	Implemented	Tested FSX	Tested P3D	Tested MSFS
menu	✅	✅		⚠️
menuAddItem	✅			⚠️
menuAddSubItem	✅			⚠️
menuDeleteItem	✅			⚠️
menuDeleteSubItem	✅			⚠️

Weather

Method	Implemented	Tested FSX	Tested P3D	Tested MSFS
weatherRequestObservationAtNearestStation	✅	✅		⚠️
weatherRequestCloudState	✅	✅		⚠️
weatherRequestInterpolatedObservation	✅			⚠️
weatherRequestObservationAtStation	✅			⚠️
weatherCreateStation	✅			⚠️
weatherSetObservation	✅			⚠️
weatherSetModeServer	✅			⚠️
weatherSetModeTheme	✅			⚠️
weatherSetModeGlobal	✅			⚠️
weatherSetModeCustom	✅			⚠️
weatherSetDynamicUpdateRate	✅			⚠️
weatherCreateThermal	✅			⚠️
weatherRemoveThermal	✅			⚠️

Misc

Method	Implemented	Tested FSX	Tested P3D	Tested MSFS
cameraSetRelative6DOF	✅
completeCustomMissionAction	✅
executeMissionAction	✅
requestSystemState	✅	✅
setNotificationGroupPriority	✅
text	✅	✅		⚠️