@simconnect.js/api NPM

SimConnect client implementation for NodeJS.

@simconnect.js/api

This package provides a more user-friendly wrapper with predefined simvars values.

Read our contribution guidelines.

Quick start

Install required libraries:

yarn add simconnect.js @simconnect.js/api

Import the module and create a new connection constructor:

import { SIMCONNECT_API } from "@simconnect.js/api";

const simconnect = new SIMCONNECT_API();

simconnect.connect({
    autoReconnect: true,
    retries: Infinity,
    retryInterval: 5,
    onConnect: connect,
    onRetry: (_retries, interval) =>
      console.log(`Connection failed: retrying in ${interval} seconds.`),
    onException: (e) => {
      console.log("exception", e);
    },
  });

async function connect(handle, recvOpen) {
  console.log(`Simulator connected`, recvOpen);

  const [start, stop] = simconnect.schedule(
    (data) => {
      console.log("data", data);
    },
    1000,
    ["PLANE ALTITUDE"],
    true
  );

  const unpauseOff = simconnect.on(SystemEvents.UNPAUSED, () => {
    console.log(`sim unpaused`);
    unpauseOff();
  });

  const unpauseOn = simconnect.on(SystemEvents.PAUSE, () => {
    console.log(`sim paused`);
    unpauseOn();
  });
}

Methods:

connect:

Opens a connection with a running simulator stream:

simconnect.connect({
  autoReconnect: true,
  retries: Infinity,
  retryInterval: 5,
  onConnect: connect,
  onRetry: (_retries, interval) =>
    console.log(`Connection failed: retrying in ${interval} seconds.`),
  onException: (e) => {
    console.log("exception", e);
  },
});

connect method takes several options:

autoReconnectboolean: Boolean indicator that performs an automatic reconnection when it is detected that the simulator is not connected or stopped being connected.
retriesnumber: Number of attempts it will make when making a reconnection.
retryIntervalnumber: Interval in seconds that it will do when it is making a reconnection, example: if you put 5, every 5 seconds it will try to reconnect.
onConnectfunction: Callback function that is executed when a succesfully connection is made.
onRetryfunction: Callback function that is executed when a retry is made.
onExceptionfunction: Callback function that is executed when an exception is made.

on:

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 SIMCONNECT_API:

import { SystemEvents, SIMCONNECT_API } from "@simconnect.js/api";

const simconnect = new SIMCONNECT_API();

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

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

off:

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:

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:

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:

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:

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)