msfs-simconnect-api-wrapper

msfs-simconnect-api-wrapper

A JavaScripty wrapper around EvenAR's excellent node-simconnect with a simplified API.

See test.js for the basics, which you can run (with MSFS open and sitting on the apron with a plane =) using npm test.

Installation and use

Install with npm install msfs-simconnect-api-wrapper.

For examples on how to use this, see the examples dir.

API

This API manager has an argless constructor that does nothing other than allocate internal values. In order to work with MSFS, you need to call the connect function first, which can take an options object of the following form:

{
  retries:  positive number or Infinity
  retryInterval: positive number, representing number of seconds (not milliseconds) between retries,
  onConnect: callback function with the node-simconnect handle as its only argument.
  onRetry: callback function with (retries left, retry interval) as its two arguments. This triggers _before_ the next attempt is scheduled.
}

For example, we can set up an API object and have it start trying to connect, eventually dropping us into the code that knows it has an MSFS connection using the following boilerplate:

import { MSFS_API } from "./msfs-api.js";

const api = new MSFS_API();

api.connect({
  retries: Infinity,
  retryInterval: 5,
  onConnect: () => run(),
  onRetry: (_, interval) => {
    console.log(`Connection failed: retrying in ${interval} seconds.`);
  },
});

function run() {
  console.log(`We have an API connection to MSFS!`);
  //
  // ...your code here...
  //
}

Properties

The API has a single property .connected which is either undefined or true and can be used to determine whether the API has a connection to MSFS outside of code that relies on the onConnect callback.

Methods

connect(opts?)

Sets up a connection to MSFS, see above for an explanation of opts. If let unspecified, no retries will be attempted.

on(evtDefinition, handler)

Starts listening for a specific simconnect event with a specific handler. Returns a corresponding arg-less off() function to clean up the listener. See the "System events" section below for details on the event definition.

System events (used for on/off handling):

All event names in https://docs.flightsimulator.com/html/Programming_Tools/SimConnect/API_Reference/Events_And_Data/SimConnect_SubscribeToSystemEvent.htm are supported as constants on the SystemEvents object, importable alongside MSFS_API:

import { SystemEvents, MSFS_API } from "./msfs-api.js";

const api = new MSFS_API();

api.connect({
  retries: 2Infinity,
  retryInterval: 5,
  onConnect: () => {
    api.on(SystemEvents.PAUSED, () => {
      // ...
    });
  },
});

Note that the event names are keys from the SystemEvents object, using UPPER_SNAKE_CASE, not strings.

Special Events

There is currently a single "not-official" event that can be listened to:

• AIRPORTS, registers a listener for which airports are nearby (or rather, "in the current Sim bubble", which is all world tiles currently loaded and active in the sim), which triggers every time an airport comes into range, as well as when airports go out of range.

off(evtDefinition, handler)

Stop listening for a specific simconnect event with a specific handler. You'll typically not need to call this function directly, as you can just use the function that on returns. See the "System events" section above for more details on the event definition.

get(...propNames)

Accepts a list of simvars (with spaces or underscores) and async-returns a key/value pair object with each simvar as key (with spaces replaced by underscores).

schedule(handler, interval, ...propNames)

Sets up a periodic call to handler every interval milliseconds with the result of get(...propNames). Returns an arg-less off() to end the scheduled call.

set(propName, value)

Accepts a single simvar and the value its should be set to. This will throw "SimVar ... is not settable" when attempting to set the value for a read-only variable.

trigger(triggerName, value?)

Triggers a simconnect event, with optional value.

Supported Simvars:

All simvars are supported, barring several simvars with data types for which I need to figure out how to actually deference then, such as LatLonAlt structs, or the (super rare) bool/string combination, as well a any simvar that is officially deprecated, or marked as "legacy, do not use these going forward". If you get an error about an unknown Simvar, look up that variable on the SimConnect variables list and see if it's either deprecated, or part of a collection that is considered legacy.

• Camera Variables (not verified)
• Services Variables (not verified)
• Miscellaneous Variables (not verified)
• Aircraft SimVars:
  • Aircraft Autopilot/Assistant Variables (not verified)
  • Aircraft Brake/Landing Gear Variables (not verified)
  • Aircraft Control Variables (not verified)
  • Aircraft Electrics Variables (not verified)
  • Aircraft Engine Variables (not verified)
  • Aircraft Flight Model Variables (not verified)
  • Aircraft Fuel Variables (not verified)
  • Aircraft Misc. Variables (not verified)
  • Aircraft Radio Navigation Variables (not verified)
  • Aircraft System Variables (not verified)
  • Helicopter Variables (not verified)

"not verified" means that they've been ported, marked settable where appropriate, pass the test run, but they've not been individually confirmed to be correct with respect to the documentation yet.

Supported SimEvents:

SimEvents are resolved by key name, so as long as you use a valid key name, you can trigger it.

See https://docs.flightsimulator.com/html/Programming_Tools/Event_IDs/Event_IDs.htm for the full list (there are... a lot).

Helping out

File an issue if you want to help get this wrapper to 100% simvar and event support! Even if you just want to help verify a few variables, that's a few variables fewer that I'll need to run through =)