# API Reference - QUERY

All QUERY are listed below. Additionally, numbers, strings, null and arrays (pass-through) are valid as a query.

# `text`

text along with params can be used to build up any string. {N} is used as a replacement token in the string. N starts at 0 and increments, and it matches the elements in params.

Examples:

{"text":"object_name_{0}", "params":[ 99 ]}
{"text":"object_name_{0}", "params":[ {"var":["L:TEST","number"]} ]}

The result is a string which may be sent to another API, with a value like object_name_99.

Format specifiers:

{0}
{0:TIME}
{0:DMS}
{0:LOCATION}

# `var`

var is the primary way to read an L:Var or A:var from the simulator. A list of variables is Available here (opens new window)

All L:Vars will use the unit number.

Examples:

{"var": ["L:MY_SIM_VAR_HERE", "number"]}
{"var": ["A:PLANE ALTITUDE", "feet"]}

# `object/var`

Read a property on a mission object.

Property	Function
$INDEX	Correlate a mission object name to `L:MISSION OBJECT ...` vars
VAR 1	Generic data slot 1
VAR 2	Generic data slot 2
VAR 3	Generic data slot 3
MODE	Object mode
HEIGHT	Radio Altitude in feet (readonly)
ALT	Altitude in feet
AALT	Actual altitude in feet (readonly)
AHDG	Actual heading in feet (readonly)
CREATED	1: created, 0: not created, -1: failed creation (readonly)
COUPLED	Special obejct mode. See table below
VELOCITY X	Body Velocity X (meters per second)
VELOCITY Y	Body Velocity Y (meters per second)
VELOCITY Z	Body Velocity Z (meters per second)
WP INDEX	Waypoint navigation 0: inactive, >0: represents active waypoint index.
distance	calculate distance to object
distance:ft	calculate distance to object (unit converter)

Generic data slots have a meaning only to the specific object (such as setting an animation state, a common use for VAR 1).

These values are applicable to the MODE var:

Object Mode	Function
0	Default mode. You may set `VELOCITY Z`
1	Repositioning mode. You may set `LAT`, `LON` and `HDG`
2	3-axis velocity
3	Default MSFS physics
4	Same as 1 but pitch inverted 180 degrees
5	Stop when radio height is under 10ft
6	Flight object repositioning. Set `ALT` and `HDG`

These values are applicable to the COUPLED var:

Object Mode	Function
0	Default mode.
1	Coupled to hoist station
2	Coupled to sling station
3	Available to be coupled to sling station
4	Firefighting target `VAR 1`: quantity of fire
5	Firefighting water source `VAR 1`: radius in meters, `VAR 2`: height in feet

distance:ft (unit converter) is also supported

Examples:

{"object": "my_object", "var": "VELOCITY Z"}
{"object": "my_object", "var": "$INDEX"}
{"object": "my_object", "var": "distance"}

# `location/var`

You can get 3 things from a LOCATIONREF: distance in nautical miles, latitude and longitude.

distance:ft (unit converter) is also supported

Examples:

{"location": LOCATIONREF, "var":"distance"}
{"location": LOCATIONREF, "var":"lat"}
{"location": LOCATIONREF, "var":"lon"}

# `bearing`

bearing calculates the true heading between two LOCATIONREF.

Examples:

{"bearing": {"to":LOCATIONREF, "from":LOCATIONREF}}

# `has_location`

has_location will return 1 or 0 based on whether the location name exists already.

Examples:

{"has_location": QUERY}
{"has_location": "my_location_name"}

# `resolve_location`

resolve_location will return [lat, lon] from a LOCATIONREF.

Examples:

{"resolve_location": QUERY}
{"resolve_location": "my_location_name"}

# `has_object`

has_object will return 1 or 0 based on whether the object name exists already.

Examples:

{"has_object": QUERY}
{"has_object": "my_object_name"}

# `has_user_action`

has_user_action returns 1 or 0 depending on whether the user_action is currently active.

Examples:

{"has_user_action": QUERY}
{"has_user_action": "my_user_action_name"}

# `has_mission`

has_mission will return 1 or 0 based on whether the mission id exists in the index.

Examples:

{"has_mission": QUERY}
{"has_mission": "my_mission_id_"}

# `has_macro`

has_macro returns a boolean value indication whether the macro name exists or not.

Examples:

{"has_macro": QUERY}
{"has_macro": "my_macro"}

# `no_resolve`

no_resolve will just return the un-interpreted data.

Examples:


{"no_resolve": {"arbitrary_data_here":"my_data"}}

# `resolve_icon`

resolve_icon will look up an entry in the icons table.

Examples:

{"resolve_icon": "my_icon_name"}

# `static`

static enables getting keys under the data section of the mission (static data).

Examples:

"data": {
  "my_static_key": 99
}

{"static": "my_static_key"}

# `has_static`

has_static returns a boolean value indicating if the key exists on the mission data section.

Examples:

{"has_static":"my_static_key"}

# `has_global`

has_mission will return 1 or 0 based on whether the global name is defined.

Examples:

{"has_global": QUERY}
{"has_global": "my_global_name"}

# `global`

global enables query of a global variable by name.

Examples:

{"global": QUERY}
{"global": "my_global_name"}

# `has_route`

has_route will return a boolean value indicating if the specified route exists.

Examples:

{"has_route": QUERY}
{"has_route": "my_route_name"}

# `route`

route will return the route information for a given route name.

Examples:

{"route": QUERY}
{"route": "my_route_name"}

# `create_array`

create_array makes a new array of the specified size. Arrays grow automatically so 0 is fine.

Examples:

{"create_array": QUERY}
{"create_array": 10}

# `create_struct`

create_struct will create a complex object and each key will be evaluated as a QUERY

Examples:

{"create_struct": {
  "key1":QUERY, 
  "key2":QUERY
}}

# `struct`

struct is used to access a complex object.

path: access a property.
has_path: 1 or 0 based on whether the property exists.
function: call a function
index: access an array element

Examples:

{"struct": ...., "path": "length"}
{"struct": {"js:get":"JSON"}, "function": "stringify", "params": [ {"local": "my_local"}, null, 2]}
{"struct": ...., "index": 0}

# `js:get`

js:get retrieves an object from the window. Examples are Math or JSON.

Examples:

{"js:get": "Math"}

# `js:create_async_function`

js:create_async_function creates a JS async function which calls a COMMANDLIST with $args defined as a param.

Examples:

{"js:create_async_function": [
  {"set_message":{"text":"js called:{0}", "params": [
    {"struct": {"param": "$args"}, "index": 0}
  ]}}
]}

# `js:function`

js:function creates a JS function which calls a QUERY with $args defined as a param. Since it is a QUERY, you may return a value synchronously as well.

Examples:

{"js:create_callback": [
  {"set_message":{"text":"js called:{0}", "params": [
    {"struct": {"param": "$args"}, "index": 0}
  ]}}
]}

# `js:new`

js:new calls the constructor on an object, providing params if defined.

Examples:

{"js:new": "my_window_object", "params":[QUERY, QUERY, QUERY]}

# `json:stringify`

json:stringify will transform an object into a JSON string.

Examples:

{"json:stringify": {"param":"$RET"}}

# `json:parse`

json:parse will transform JSON string into an object.

Examples:

{"json:parse": {"param":"$RET"}}

# `json:copy`

json:copy will create a deep copy of the object. Changes to the new object will not impact the input object. Examples:

{"json:copy": {"param":"$RET"}}

# `object:keys`

object:keys will return an array containing the key names in the target object. Examples:

{"object:keys": {"param":"$RET"}}

# `string:split`

string:split will create an array from the parts of string, specified by the delimiter.

index: Optional. This will return only one index in the array, instead of all parts of the array. This is handy if you only want one part of the split string anyway.

Examples:

  {"string:split": {"struct": {"js:new": "Date"}, "function": "toISOString"}, "delimiter":"T", "index": 1}

# `string:join`

string:join will create a string by appending each item in the input array, along with a delimiter.

Examples:

{"string:join": ["one","two","three"], "delimiter":"_"}

# `create_number`

create_number will use the js Number() to convert a string to a number value.

Examples:

{"create_number":QUERY}
{"create_number":"99.5"}

# `has_local`

has_local will return 1 or 0 based on whether the key exists in the locals.

Examples:

{"has_local": "my_local_name"}

# `local`

local will retreive a local variable by name.

Examples:

{"local": "my_local_name"}
{"local": "my_local_name", "path": "key"}

# `gamevar`

gamevar works like var but lets you query SimVar.GetGameVarValue in MSFS.

Examples:

{"gamevar": ["my_game_var", "my_unit"]}

# `table`

table lets you read a key from a named table. (Table must be open first)

Examples:

{"table": "my_table", "key": "my_key"}

# `param`

param lets you read a parameter from the params collection. There is a params collection for each macro and one for the main thread. create_thread's take the same params as the calling context.

Examples:

{"param": "my_param"}
{"param": "my_param", "path": "my_key"}

# `has_param`

has_param tells you whether 1 or 0 for whether or not the parameter key exists.

Example:

{"has_param": "my_param"}

# `rand`

rand will create a random decimal value between QUERY (minimum) and QUERY2 (maximum) bounds.

Examples:

{"rand":[QUERY1, QUERY2]}
{"rand":[0, 60]}

# `add`

add will add a list of queries (2 or more).

Examples:

{"add":[QUERY1, QUERY2, ...]}
{"add":[2,2]}
{"add":[{"var":["L:TEST","number]}, 1]}

# `add360`

add360 is like add but the final result is normalized between 0 and 360.

Examples:

{"add360":[QUERY1, QUERY2, ...]}
{"add360":[{"var":["L:TEST","number]}, 90]}

# `compare360`

compare360 will provide absolute value between two values 0-360.

Examples:

{"compare360":[1, 359]} // -> 2

# `subtract`

subtract subtracts QUERY1 - QUERY2.

Examples:

{"subtract":[QUERY1, QUERY2]}

# `multiply`

multiply multiplies QUERY1 * QUERY2.

Examples:

{"multiply":[QUERY1, QUERY2]}

# `divide`

divide divides QUERY1 / QUERY2. if QUERY2 is zero, the result is 0.

Examples:

{"divide":[QUERY1, QUERY2]}

# `right_shift`

right_shift is the right bit shift operator >>.

QUERY >> QUERY2

Examples:

{"right_shift": [QUERY1, QUERY2]}
{"right_shift": [0xFFFF, 2]}

# `left_shift`

left_shift is the left bit shift operator <<.

QUERY << QUERY2

Examples:

{"left_shift": [QUERY1, QUERY2]}
{"left_shift": [0xFFFF, 2]}

# `xor`

xor is the exclusive-or operator.

Examples:

{"xor": [QUERY1, QUERY2]}

# `remainder`

remainder is the mod or remainder operator.

Examples:

{"remainder": [QUERY1, QUERY2]}

# `exponent`

exponent is power operator.

Examples:

{"exponent": [QUERY1, QUERY2]}

# `round`

round will round a number to the nearest integer (whole number) value.

Examples:

{"round":QUERY}
{"round": 3.5}

# `tofixed`

tofixed is like round, but lets you configure the number of digits to round to. digits=2 would result in numbers like 0.00

Examples:

{"tofixed":QUERY, "digits": QUERY}
{"tofixed":3.141592, "digits": 2}

# `floor`

floor returns the closest previous whole number.

Examples:

{"floor":QUERY}
{"floor":2.5}

# `ceil`

ceil (ceiling) returns the closest next whole number.

Examples:

{"ceil":QUERY}
{"ceil":2.5}

# `abs`

abs returns the absolute value of a number (removing negative sign).

Examples:

{"abs":QUERY}
{"abs": -300}

# `Math. ...` functions

These Math functions are also available:

Math.sign
Math.log
Math.log2
Math.log10
Math.sin
Math.sinh
Math.asinh
Math.cos
Math.cosh
Math.acosh
Math.atan
Math.atanh
Math.atan2

Examples:

{"Math.sign": -100}
{"Math.atan2": [QUERY, QUERY]}

# `clamp`

clamp will return a number which is between the range of QUERY_MIN to QUERY_MAX. If QUERY_VAL is between the min and max, it will be returned directly.

Examples:

{"clamp":[QUERY_VAL, QUERY_MIN, QUERY_MAX]}
{"clamp":[5.5, 0, 100]}

# `scale`

scale is transforms a value in range A to range B.

Examples:

{"scale":[QUERY_A_VAL, QUERY_A_MIN, QUERY_A_MAX, QUERY_B_MIN, QUERY_B_MAX]}
{"scale":[0.05, 0, 1, 0, 100]}

# `require`

require returns 1 or 0 depending on whether the QUERY1 op QUERY2 condition is true or false.

Examples:

{"require": QUERY1, "eq": QUERY2}
{"require": {"var":["L:TEST","number"]}, "eq", 0}

# `and`

and is the logical AND operator.

and returns 1 if each of the queries are 1. If any query isn't 1, the overall result is 0.

Examples:

{"and":[
  {"require": QUERY, "eq": QUERY},
  ...
]}

# `or`

or is the logical OR operator.

or will return 1 if any of the queries return 1. It will also short-circuit, in that further queries will not be checked if any subsequent query returns 1.

Examples:

{"or":[
  {"require": QUERY, "eq": QUERY},
  ...
]}

# `not`

not is the logical NOT operator.

not will invert (1 to 0 and 0 to 1) any query.

Examples:

{"not":QUERY}

# `typeof`

typeof returns a string which describes the type of input it was given.

Type	Type Name
structs	"object"
null	"object"
arrays	"array"
strings	"string"
numbers	"number"
undefined	"undefined"

# `isNaN`

isNaN indicates whether a number is NaN or not.

Examples:

{"isNaN": QUERY}

# `parseInt`

parseInt converts a string to an integer

Examples:

{"parseInt": QUERY}

# `parseFloat`

parseFloat converts a string to an decimal value.

Examples:

{"parseFloat": QUERY}

# `if`

if works as a QUERY or a COMMAND. The syntax is the same, except COMMANDLIST is a QUERY.

Examples:

{"if": QUERY, "then": QUERY, "else": QUERY}
{"if": QUERY, "then": QUERY}

# `switch`

switch works as a QUERY as well as a COMMAND. COMMANDLISTs are instead a QUERY in this form.

Examples:

{"switch": QUERY, "case":{
  "0": QUERY,
  "1": QUERY,
  "2": QUERY,
  "3": QUERY,
  "default": QUERY
}}

# `convert`

convert will do unit conversion.

Examples:

{"convert": QUERY, "from":"from_unit", "to":"to_unit"}
{"convert": QUERY, "from":"miles", "to":"meters"}
{"convert": QUERY, "from":"kg", "to":"lb"}

You can convert between these units:

Weight Unit	Monikers
Kilogram	kilogram, kg, kilo
Pound	pound, lb

Length Unit	Monikers
Feet	feet, foot, ft
Meter	meter, m
Mile	mile, mi
Nautical Mile	nauticalmile, nm, nmi

# `fn.HOIST_SEND_TO_GROUND`

HOIST_SEND_TO_GROUND will conditionally deploy and stow the hoist based on proximity to the target.

Examples:

{"HOIST_SEND_TO_GROUND", "params": {
  "target": LOCATIONREF,
  "after_deploy_commands": [
    ... commands after deploying the hoist
  ],
  "before_stow_commands": [
    ... commands before stow
  ]
}}

# `fn.HOIST_REEL_UP_AND_STOW`

HOIST_REEL_UP_AND_STOW will wait for the hoist to be reeled up, and run the commands once when it happens:

before_stow_commands will run once when the hoist is stowing.

Examples:

{"fn":"HOIST_REEL_UP_AND_STOW", "params": {
  "before_stow_commands": [
    .. commands here to run before stow (to swap the objects)
  ]
}}

# `fn.HOIST_REEL_UP`

HOIST_REEL_UP will return true when the hoist is up and stowed, and false until that happens.

Examples:

{"fn":"HOIST_REEL_UP"}

# `fn.hoist_get_reel_distance:ft`

Gets the distance which the cable is extended.

Examples:

{"fn":"hoist_get_reel_distance:ft"}
{"fn":"hoist_get_reel_distance:m"}

# `fn.hoist_get_distance_from_ground:ft`

Gets the distance from the hoist object to the ground.

Examples:

{"fn":"hoist_get_distance_from_ground:ft"}
{"fn":"hoist_get_distance_from_ground:m"}

# `fn.score_bambi_dump`

score_bambi_dump will return a score value, which is calculated from all of the objects which were created with COUPLED=4. The total score is the summation of VAR 2 from each of those objects.

Examples:

{"fn":"score_bambi_dump"}

# `fn.all_fires_extinguished`

all_fires_extinguished indicates if there are any objects with COUPLED=4 that are alive. Returns 1 if any fire is active.

Examples:

{"fn":"all_fires_extinguished"}

# `fn.has_remote_notify`

Returns 1 or 0 based on whether the mission is running from a server.

Examples:

{"fn":"has_remote_notify"}

# `fn.is_voice_server_connected`

fn:is_voice_server_connected indicates whether or not the voice server is currently connected.

Examples:

{"fn": "is_voice_server_connected"}

# `fn.create_guid`

fn:create_guid will generate a globally unique identifier string.

Examples:

{"fn": "create_guid"}

# `fn.create_date`

create_date will create a JS Date object.

Examples:

{"set_message":{"text":"{0}", "params":[ {"fn":"create_date"} ]}},

# `fn.get_time_string`

get_time_string will get a 24-hour UTC timestamp like 07:05:57

Examples:

{"set_message":{"text":"{0}", "params":[ 
  {"fn":"get_time_string"}
]}},

# `fn.get_mission_objects`

get_mission_objects will get the active mission objects (for enumeration).

Examples:

{"set_message":{"text":"{0}", "params":[ 
  {"json:stringify": {"fn":"get_mission_objects"}}
]}},

# `fn.get_aircraft_moniker`

fn.get_aircraft_moniker will get a string identifier for the aircraft, like H145 or H160.

Examples:

{"#comment":"copy either H145 or H160 into a string local named HXX"},
{"set":{"local":"HXX"},"value":{"fn":"get_aircraft_moniker"}},
{"#comment":"fire an event where the name is either H145 or H160 but otherwise is the same..."},
{"trigger":"H:{local:HXX}_SDK_DO_RANDOM_THING"},
{"#comment":"just show a message, but note that you can now use {local:HXX} in any string across the mission"},
{"set_message":"hello from {local:HXX}"},

# `fn.is_any_sling_object_coupled`

fn.is_any_sling_object_coupled returns a boolean value indicating whether an object is coupled right now.

# `fn.get_sling_object_type`

fn.get_sling_object_type returns a value from 1 to 10 indicating the type of sling object currently coupled.

# `fn.get_mission_icons`

fn.get_mission_icons gets the entire icons table.

# `fn.create_multiplayer_connection`

fn.create_multiplayer_connection creates an MPClient multiplayer connection.

← API Reference - COMMAND API Reference - LOCATION →

# API Reference - QUERY

# text

# var

# object/var

# location/var

# bearing

# has_location

# resolve_location

# has_object

# has_user_action

# has_mission

# has_macro

# no_resolve

# resolve_icon

# static

# has_static

# has_global

# global

# has_route

# route

# create_array

# create_struct

# struct

# js:get

# js:create_async_function

# js:function

# js:new

# json:stringify

# json:parse

# json:copy

# object:keys

# string:split

# string:join

# create_number

# has_local

# local

# gamevar

# table

# param

# has_param

# rand

# add

# add360

# compare360

# subtract

# multiply

# divide

# right_shift

# left_shift

# xor

# remainder

# exponent

# round

# tofixed

# floor

# ceil

# abs

# Math. ... functions

# clamp

# scale

# require

# and

# or

# not

# typeof

# isNaN

# parseInt

# parseFloat

# if

# switch

# convert

# fn.HOIST_SEND_TO_GROUND

# fn.HOIST_REEL_UP_AND_STOW

# fn.HOIST_REEL_UP

# fn.hoist_get_reel_distance:ft

# fn.hoist_get_distance_from_ground:ft

# fn.score_bambi_dump

# fn.all_fires_extinguished

# fn.has_remote_notify

# fn.is_voice_server_connected

# `text`

# `var`

# `object/var`

# `location/var`

# `bearing`

# `has_location`

# `resolve_location`

# `has_object`

# `has_user_action`

# `has_mission`

# `has_macro`

# `no_resolve`

# `resolve_icon`

# `static`

# `has_static`

# `has_global`

# `global`

# `has_route`

# `route`

# `create_array`

# `create_struct`

# `struct`

# `js:get`

# `js:create_async_function`

# `js:function`

# `js:new`

# `json:stringify`

# `json:parse`

# `json:copy`

# `object:keys`

# `string:split`

# `string:join`

# `create_number`

# `has_local`

# `local`

# `gamevar`

# `table`

# `param`

# `has_param`

# `rand`

# `add`

# `add360`

# `compare360`

# `subtract`

# `multiply`

# `divide`

# `right_shift`

# `left_shift`

# `xor`

# `remainder`

# `exponent`

# `round`

# `tofixed`

# `floor`

# `ceil`

# `abs`

# `Math. ...` functions

# `clamp`

# `scale`

# `require`

# `and`

# `or`

# `not`

# `typeof`

# `isNaN`

# `parseInt`

# `parseFloat`

# `if`

# `switch`

# `convert`

# `fn.HOIST_SEND_TO_GROUND`

# `fn.HOIST_REEL_UP_AND_STOW`

# `fn.HOIST_REEL_UP`

# `fn.hoist_get_reel_distance:ft`

# `fn.hoist_get_distance_from_ground:ft`

# `fn.score_bambi_dump`

# `fn.all_fires_extinguished`

# `fn.has_remote_notify`

# `fn.is_voice_server_connected`

# `fn.create_guid`