Token Variables

TOKEN VARIABLES

IMPORTANT! Token Variables - along with the Gauge API - have been deprecated in Microsoft Flight Simulator 2024 in favour of the new Vars API and Event API, which work with the more extensive and supported Simulation Variables and Key Events.

WASM/C++ Gauges have access to information about the Microsoft Flight Simulator 2020 simulation state through a set of token variables (see the Token Variable Index for all available). The state information provided to the token variables depends on the various aricraft *.cfg files, since each aircraft will have access to different token variables depending on its capabilities. For example: the Cessna 182 provides access to GROUND_ALTITUDE, as does every other aircraft. The Cessna 182, however, doesn't provide access to the TURB_ENGINE_1_VIBRATION variable because the Cessna 182 has a reciprocating engine, not a turbine engine. Therefore, it's important to make sure that the *.cfg files you're using for your aircraft and gauges support the token variables those gauges require.

NOTE: Token variables are not the same as SimVars, and are specific to the Gauge API. Some of them are associated with SimVars (and may even have the same name as the associated SimVar), however many have no SimVar associations.

The following pages contain the different token variables, grouped into categories, although you may find it easier to use the Search function or check the Token Variable Index (below) to find the variable you are looking for:

`UNIVERSAL_VAR` Types

Each token variable returns a specific type of data. The following structure shows how the UNIVERSAL_VAR variable is defined and the types that could be returned:

typedef union UNIVERSAL_VAR {
    FLOAT64 n; // any number.
    BOOL b; // any boolean
    ENUM e; // any enumerated value
    FLAGS f;// any flags field
    PVOID p;// any pointer
    VAR32 d;// any binary coded decimal
    VAR32 o;// any binary coded octal
} UNIVERSAL_VAR, *PUNIVERSAL_VAR, **PPUNIVERSAL_VAR;

The tables on the various Token Variable pages list the module variable name and specifies which UNIVERSAL_VAR union member to use with each variable.

Accessing A Tokenized Variable Through The Gauge API:

Instantiate a MODULE_VAR variable initializing the GAUGE_TOKEN ID structure member. You can set the ID to one of the token variables provided in the Token Variable Index. For example:

typedef struct MODULE_VAR
		{
		    GAUGE_TOKEN id;
		    PVOID var_ptr;
		    VAR_TYPE var_type;
		    UNIVERSAL_VAR var_value;
		    UNIVERSAL_VAR var_old;
		} MODULE_VAR, *PMODULE_VAR, **PPMODULE_VAR;

To update the contents of the variable from Flight Simulator state information, use lookup_var:

lookup_var(PMODULE_VAR module_var)

After the lookup_var function is called, the value of a MODULE_VAR variable is stored in the var_value member of the structure.

IMPORTANT! Token variables are read-only. Any attempt to set these variables through the var_ptr variable may result in program crashes and incompatibility with future versions of Microsoft Flight Simulator 2024.

The following code example shows how the MODULE_VAR variable is used. Note that this is a callback function and, in this specific example, it is for a sprite element:

MODULE_VAR attitude_bank = { ATTITUDE_INDICATOR_BANK_DEGREES };
FLOAT64 flight_director_bank_cb(PELEMENT_SPRITE pelement)
{
    lookup_var(&attitude_bank);
    // Offset by attitude card's bank
    return attitude_bank.var_value.n - pelement->source_var_0.var_value.n;
}

Token Variable Index

Below you can find indexed all the Token Variables available, presented this way to facilitate finding the required variable at a glance or through the search system: