Simvar.js

An important part of creating instruments for Microsoft Flight Simulator is the ability to communicate with the simulation using Simulation Variables. These can be used to retrieve information about many aspects of the simulation, and some of them can also be set to update the simulation based on - for example - user input. When working with HTML/JS/CSS instruments, the simvar.js file is what contains the methods that you'll be using when working with SimVars.

The most important methods available to you from this file are as follows:

GetSimVarValue(name, unit, dataSource = "")

This method is used to get the value of a simulation variable and has the following parameters:

let ident = SimVar.GetSimVarValue("C:fs9gps:IcaoSearchCurrentIdent", "string", this.gps.instrumentIdentifier);

For example:

switch (this.mapRotationMode) {
    case EMapRotationMode.DTKUp:
        compass = SimVar.GetSimVarValue("GPS WP DESIRED TRACK", "degrees");
        break;
    case EMapRotationMode.HDGUp:
        compass = Simplane.getHeadingTrue();
        break;
    case EMapRotationMode.TrackUp:
        compass = SimVar.GetSimVarValue("GPS GROUND TRUE TRACK", "degrees");
        break;
    default:
        compass = 0;
        break;
}

SetSimVarValue(name, unit, value, dataSource = "")

This method is used to set the value of a simulation variable and has the following parameters:

SimVar.SetSimVarValue("L:isCompassDisplayed", "Bool", this.isCompassDisplayed)

For example:

checkEvent(eventName, onChanged) {
    const value = SimVar.GetSimVarValue(eventName, "number");
    if (value > 0) {
        SimVar.SetSimVarValue(eventName, "number", 0);
        onChanged();
    }
}

It is important to note that setting SimVars using JavaScript is an asynchronous operation meaning that there is no guarantee it will finish before the next line of code runs. To deal with this, the method returns a Promise<void> which permits you to write code that will only run once this promise as been returned. Here are two examples of how this can be implemented:

• Using .then:

  SimVar.SetSimVarValue("LIGHT NAV", "bool", true)
            .then(() => console.log("Nav light is on!"));

• Using await:

  await SimVar.SetSimVarValue("LIGHT NAV", "bool", true);
        console.log("Nav light is on!");

You should realise too that for some SimVars, awaiting the Promise will not guarantee the update is complete. This is because SimVar function calls into the simulation are cached and run at frame end for performance reasons and not all the simulation systems are synchronous. This does not mean you should not use the promise format for these kinds of operations, however, as it's still the most reliable and consistent way to set SimVars and the one that we recommend that you use.

Var Types

When using JavaScript for your instruments, you'll be able to use different types of SimVar. These will all broadly fall into the following categories:

NOTE: There are other non-SimVar variable types that can also be used in your instruments. These are listed here: Variable Types

A Vars

The most common type of variable you'll be working with in Microsoft Flight Simulator are "A" Vars. An "A" var is simply a way of talking about any simulation variable (as listed here) that you can get the value of, and sometimes set as well. We call these "A" vars because in legacy versions of the simulation like FSX you had to prefix the variable with the text "A:", however this is not required when querying or setting these variables using JavaScript.

To query a SimVar, supply the SimVar name and the units you would like to return the value in:

const indicatedAirspeed = SimVar.GetSimVarValue("INDICATED AIRSPEED", "knots");

Note that you may need to use an index value along with a simvar - for example to target a specific engine, or a circuit, etc... - in which case you would append the index onto the SimVar using a ":" as shown below:

const engineN1 = SimVar.GetSimVarValue("TURB ENG N1:1", "percent");

L Vars

When we talk of "L" vars we are talking about user settable variables that can have any name. When referring to them using JavaScript, these variables need to be prefixed with the text "L:". If the local variable has not been defined in any of the associated files for the aircraft, then it will be created and set to 0 the very first time it is referenced (and it will not persist between runs). You can, however, define a default value for local variables using the following:

• the [LocalVars.N] section of the FLT file permits you to define a non-persistent local variable
• the [LocalVars] section of the Systems Config file permits you to create a persistent local variable

This variable can be read and set within the scope of the user aircraft, and can be read by AI Aircraft. Note that "L" vars must always be properly prefixed and that their name must be a contiguous string with no spaces. 

IMPORTANT! "L:" vars can only hold numeric data and nothing else, eg: no strings, no binary values, no structs, etc...

Now, these are not exactly SimVars, but they still use the simvar.js methods to access them and set them, for example:

const isInMenuMode = SimVar.GetSimVarValue("L:IS_MENU_ACTIVE", "bool");

C Vars (GPS Vars)

As a developer you can also use "C" vars with the JavaScript API. These are a legacy variable type that is still supported, but only for GPS Variables. As such they require the addition of an additional prefix: "fs9gps". These variables can be used to get information about the position in the world of any number of things, like an airport, a waypoint, etc... as well as a number of other pieces of data used when querying or creating flight plans, for example:

const isApproachActive = SimVar.GetSimVarValue("C:fs9gps:FlightPlanIsActiveApproach", "bool");

Input Events

While not exactly SimVars, key events can also be initiated using the simvar.js methods. Key events are the way that Microsoft Flight Simulator binds input from the user to an action within the simulation, for example autopilot controls, setting the tim axis, turning on the engine starter, etc... (you can find a full list of available key events here). To use a key event you would invoke them as "K" vars, prefixing the input event name with K:, for example:

SimVar.SetSimVarValue("K:FLAPS_INCR", "number", 0);

Note that some key events will take a value which is used as an additional parameter used by the key, for example some events may require an axis value to be supplied:

SimVar.SetSimVarValue("K:AXIS_ELEVATOR_SET", "number", -8225);