XPLMNavigation

Query the X-Plane navigation database (airports, VORs, NDBs, fixes, etc.) and program the FMS/GPS flight plan.

Enumerations

XPLMNavType

These enumerations define the different types of navaids. They are each defined with a separate bit so that they may be bit-wise added together to form sets of nav-aid types. NOTE: xplm_Nav_LatLon is a specific lat-lon coordinate entered into the FMS. It will not exist in the database, and cannot be programmed into the FMS. Querying the FMS for navaids will return it. Use XPLMSetFMSEntryLatLon to set a lat/lon waypoint.

Constant	Value	Description
`xplm_Nav_Unknown`	`0`
`xplm_Nav_Airport`	`1`
`xplm_Nav_NDB`	`2`
`xplm_Nav_VOR`	`4`
`xplm_Nav_ILS`	`8`
`xplm_Nav_Localizer`	`16`
`xplm_Nav_GlideSlope`	`32`
`xplm_Nav_OuterMarker`	`64`
`xplm_Nav_MiddleMarker`	`128`
`xplm_Nav_InnerMarker`	`256`
`xplm_Nav_Fix`	`512`
`xplm_Nav_DME`	`1024`
`xplm_Nav_LatLon`	`2048`
`xplm_Nav_TACAN`	`4096`

XPLMNavFlightPlan

These enumerations defines the flightplan you are accesing using the FMSFlightPlan functions. An airplane can have up to two navigation devices (GPS or FMS) and each device can have two flightplans. A GPS has an enroute and an approach flightplan. An FMS has an active and a temporary flightplan. If you are trying to access a flightplan that doesn't exist in your aircraft, e.g. asking a GPS for a temp flightplan, FMSFlighPlan functions have no effect and will return no information.

Constant	Value	Description
`xplm_Fpl_Pilot_Primary`	`0`
`xplm_Fpl_CoPilot_Primary`	`1`
`xplm_Fpl_Pilot_Approach`	`2`
`xplm_Fpl_CoPilot_Approach`	`3`
`xplm_Fpl_Pilot_Temporary`	`4`
`xplm_Fpl_CoPilot_Temporary`	`5`

Functions

XLuaGetFirstNavAid()

Returns: XPLMNavRef

This returns the very first navaid in the database. Use this to traverse the entire database. Returns XPLM_NAV_NOT_FOUND if the nav database is empty.

XLuaGetNextNavAid(navAidRef)

Returns: XPLMNavRef

Given a valid navaid ref, this routine returns the next navaid. It returns XPLM_NAV_NOT_FOUND if the navaid passed in was invalid or if the navaid passed in was the last one in the database. Use this routine to iterate across all like-typed navaids or the entire database.

Argument	Type	Notes
`navAidRef`	`XPLMNavRef`	Enum — use a constant from `XPLMNavRef`

XLuaFindFirstNavAidOfType(type)

Returns: XPLMNavRef

This routine returns the ref of the first navaid of the given type in the database or XPLM_NAV_NOT_FOUND if there are no navaids of that type in the database. You must pass exactly one navaid type to this routine.

Argument	Type	Notes
`type`	`XPLMNavType`	Enum — use a constant from `XPLMNavType`

XLuaFindLastNavAidOfType(type)

Returns: XPLMNavRef

This routine returns the ref of the last navaid of the given type in the database or XPLM_NAV_NOT_FOUND if there are no navaids of that type in the database. You must pass exactly one navaid type to this routine.

Argument	Type	Notes
`type`	`XPLMNavType`	Enum — use a constant from `XPLMNavType`

XLuaFindNavAid(nameFragment, iDFragment, lat, lon, frequency, type)

Returns: XPLMNavRef

This routine provides a number of searching capabilities for the nav database. XPLMFindNavAid will search through every navaid whose type is within inType (multiple types may be added together) and return any navaids found based on the following rules: * If inLat and inLon are not NULL, the navaid nearest to that lat/lon will be returned, otherwise the last navaid found will be returned. * If inFrequency is not NULL, then any navaids considered must match this frequency. Note that this will screen out radio beacons that do not have frequency data published (like inner markers) but not fixes and airports. * If inNameFragment is not NULL, only navaids that contain the fragment in their name will be returned. * If inIDFragment is not NULL, only navaids that contain the fragment in their IDs will be returned. This routine provides a simple way to do a number of useful searches: * Find the nearest navaid on this frequency. * Find the nearest airport. * Find the VOR whose ID is "BOS". * Find the nearest airport whose name contains "Chicago".

Argument	Type	Notes
`nameFragment`	`string`
`iDFragment`	`string`
`lat`	`number`
`lon`	`number`
`frequency`	`number`
`type`	`XPLMNavType`	Enum — use a constant from `XPLMNavType`

XLuaGetNavAidInfo(ref)

Returns: {k} with keys: type, latitude, longitude, height, frequency, heading, iD, name, reg

This routine returns information about a navaid. Any non-null field is filled out with information if it is available. Frequencies are in the nav.dat convention as described in the X-Plane nav database FAQ: NDB frequencies are exact, all others are multiplied by 100. The buffer for IDs should be at least 6 chars and the buffer for names should be at least 41 chars, but since these values are likely to go up, I recommend passing at least 32 chars for IDs and 256 chars for names when possible. The outReg parameter tells if the navaid is within the local "region" of loaded DSFs. (This information may not be particularly useful to plugins.) The parameter is a single byte value 1 for true or 0 for false, not a C string.

Argument	Type	Notes
`ref`	`XPLMNavRef`	Enum — use a constant from `XPLMNavRef`

Output table keys:

Key	Type
`type`	`number`
`latitude`	`number`
`longitude`	`number`
`height`	`number`
`frequency`	`number`
`heading`	`number`
`iD`	`{ i }`
`name`	`{ i }`
`reg`	`{ i }`

XLuaCountFMSEntries()

Returns: integer

This routine returns the number of entries in the FMS.

XLuaGetDisplayedFMSEntry()

Returns: integer

This routine returns the index of the entry the pilot is viewing.

XLuaGetDestinationFMSEntry()

Returns: integer

This routine returns the index of the entry the FMS is flying to.

XLuaSetDisplayedFMSEntry(index)

Returns: (returns nothing)

This routine changes which entry the FMS is showing to the index specified.

Argument	Type	Notes
`index`	`integer`

XLuaSetDestinationFMSEntry(index)

Returns: (returns nothing)

This routine changes which entry the FMS is flying the aircraft toward. The track is from the n-1'th point to the n'th point.

Argument	Type	Notes
`index`	`integer`

XLuaGetFMSEntryInfo(index)

Returns: {k} with keys: type, iD, ref, altitude, lat, lon

This routine returns information about a given FMS entry. If the entry is an airport or navaid, a reference to a nav entry can be returned allowing you to find additional information (such as a frequency, ILS heading, name, etc.). Note that this reference can be XPLM_NAV_NOT_FOUND until the information has been looked up asynchronously, so after flightplan changes, it might take up to a second for this field to become populated. The other information is available immediately. For a lat/lon entry, the lat/lon is returned by this routine but the navaid cannot be looked up (and the reference will be XPLM_NAV_NOT_FOUND). FMS name entry buffers should be at least 256 chars in length. WARNING: Due to a bug in X-Plane prior to 11.31, the navaid reference will not be set to XPLM_NAV_NOT_FOUND while no data is available, and instead just remain the value of the variable that you passed the pointer to. Therefore, always initialize the variable to XPLM_NAV_NOT_FOUND before passing the pointer to this function.

Argument	Type	Notes
`index`	`integer`

Output table keys:

Key	Type
`type`	`number`
`iD`	`{ i }`
`ref`	`XPLMNavRef`
`altitude`	`number`
`lat`	`number`
`lon`	`number`

XLuaSetFMSEntryInfo(index, ref, altitudeFt)

Returns: (returns nothing)

This routine changes an entry in the FMS to have the destination navaid passed in and the altitude specified. Use this only for airports, fixes, and radio-beacon navaids. Currently of radio beacons, the FMS can only support VORs and NDBs. Use the routines below to clear or fly to a lat/lon.

Argument	Type	Notes
`index`	`integer`
`ref`	`XPLMNavRef`	Enum — use a constant from `XPLMNavRef`
`altitudeFt`	`integer`

XLuaSetFMSEntryLatLon(index, lat, lon, altitudeFt)

Returns: (returns nothing)

This routine changes the entry in the FMS to a lat/lon entry with the given coordinates.

Argument	Type	Notes
`index`	`integer`
`lat`	`number`
`lon`	`number`
`altitudeFt`	`integer`

XLuaClearFMSEntry(index)

Returns: (returns nothing)

This routine clears the given entry, potentially shortening the flight plan.

Argument	Type	Notes
`index`	`integer`

XLuaCountFMSFlightPlanEntries(flightPlan)

Returns: integer

This routine returns the number of entries in the FMS.

Argument	Type	Notes
`flightPlan`	`XPLMNavFlightPlan`	Enum — use a constant from `XPLMNavFlightPlan`

XLuaGetDisplayedFMSFlightPlanEntry(flightPlan)

Returns: integer

This routine returns the index of the entry the pilot is viewing.

Argument	Type	Notes
`flightPlan`	`XPLMNavFlightPlan`	Enum — use a constant from `XPLMNavFlightPlan`

XLuaGetDestinationFMSFlightPlanEntry(flightPlan)

Returns: integer

This routine returns the index of the entry the FMS is flying to.

Argument	Type	Notes
`flightPlan`	`XPLMNavFlightPlan`	Enum — use a constant from `XPLMNavFlightPlan`

XLuaSetDisplayedFMSFlightPlanEntry(flightPlan, index)

Returns: (returns nothing)

This routine changes which entry the FMS is showing to the index specified.

Argument	Type	Notes
`flightPlan`	`XPLMNavFlightPlan`	Enum — use a constant from `XPLMNavFlightPlan`
`index`	`integer`

XLuaSetDestinationFMSFlightPlanEntry(flightPlan, index)

Returns: (returns nothing)

This routine changes which entry the FMS is flying the aircraft toward. The track is from the n-1'th point to the n'th point.

Argument	Type	Notes
`flightPlan`	`XPLMNavFlightPlan`	Enum — use a constant from `XPLMNavFlightPlan`
`index`	`integer`

XLuaSetDirectToFMSFlightPlanEntry(flightPlan, index)

Returns: (returns nothing)

This routine changes which entry the FMS is flying the aircraft toward. The track is from the current position of the aircraft directly to the n'th point, ignoring the point before it.

Argument	Type	Notes
`flightPlan`	`XPLMNavFlightPlan`	Enum — use a constant from `XPLMNavFlightPlan`
`index`	`integer`

XLuaGetFMSFlightPlanEntryInfo(flightPlan, index)

Returns: {k} with keys: type, iD, ref, altitude, lat, lon

Argument	Type	Notes
`flightPlan`	`XPLMNavFlightPlan`	Enum — use a constant from `XPLMNavFlightPlan`
`index`	`integer`

Output table keys:

Key	Type
`type`	`number`
`iD`	`{ i }`
`ref`	`XPLMNavRef`
`altitude`	`number`
`lat`	`number`
`lon`	`number`

XLuaSetFMSFlightPlanEntryInfo(flightPlan, index, ref, altitudeFt)

Returns: (returns nothing)

This routine changes an entry in the FMS to have the destination navaid passed in and the altitude specified. Use this only for airports, fixes, and radio-beacon navaids. Currently of radio beacons, the FMS can only support VORs, NDBs and TACANs. Use the routines below to clear or fly to a lat/lon.

Argument	Type	Notes
`flightPlan`	`XPLMNavFlightPlan`	Enum — use a constant from `XPLMNavFlightPlan`
`index`	`integer`
`ref`	`XPLMNavRef`	Enum — use a constant from `XPLMNavRef`
`altitudeFt`	`integer`

XLuaSetFMSFlightPlanEntryLatLon(flightPlan, index, lat, lon, altitudeFt)

Returns: (returns nothing)

This routine changes the entry in the FMS to a lat/lon entry with the given coordinates.

Argument	Type	Notes
`flightPlan`	`XPLMNavFlightPlan`	Enum — use a constant from `XPLMNavFlightPlan`
`index`	`integer`
`lat`	`number`
`lon`	`number`
`altitudeFt`	`integer`

XLuaSetFMSFlightPlanEntryLatLonWithId(flightPlan, index, lat, lon, altitudeFt, id, idLength)

Returns: (returns nothing)

This routine changes the entry in the FMS to a lat/lon entry with the given coordinates. You can specify the display ID of the waypoint.

Argument	Type	Notes
`flightPlan`	`XPLMNavFlightPlan`	Enum — use a constant from `XPLMNavFlightPlan`
`index`	`integer`
`lat`	`number`
`lon`	`number`
`altitudeFt`	`integer`
`id`	`string`
`idLength`	`integer`

XLuaClearFMSFlightPlanEntry(flightPlan, index)

Returns: (returns nothing)

This routine clears the given entry, potentially shortening the flight plan.

Argument	Type	Notes
`flightPlan`	`XPLMNavFlightPlan`	Enum — use a constant from `XPLMNavFlightPlan`
`index`	`integer`

XLuaLoadFMSFlightPlan(device, buffer, bufferLen)

Returns: (returns nothing)

Loads an X-Plane 11 and later formatted flightplan from the buffer into the FMS or GPS, including instrument procedures. Use device index 0 for the pilot-side and device index 1 for the co-pilot side unit.

Argument	Type	Notes
`device`	`integer`
`buffer`	`string`
`bufferLen`	`integer`

XLuaGetGPSDestinationType()

Returns: integer

This routine returns the type of the currently selected GPS destination, one of fix, airport, VOR or NDB.

XLuaGetGPSDestination()

Returns: XPLMNavRef

This routine returns the current GPS destination.

Examples

Examples coming soon.