XPLMPlanes

To use:

import xp

The XPLMPlanes APIs allow you to control the various aircraft in X-Plane, both the user’s and the sim’s.

Functions

setUsersAircraft(path)

This routine changes the user’s aircraft. Note that this will reinitialize the user to be on the nearest airport’s first runway with its engines running.

path is either relative to X-Plane root, or fully qualified path, including the .acf extension.

If the acf file cannot be found the user will be notified and their aircraft will be re-initialized.

>>> xp.setUsersAircraft("Aircraft/Laminar Research/Cessna 172SP/Cessna_172SP_G1000.acf")
>>> xp.setUsersAircraft("/Volumes/SSD1/X-Plane/Aircraft/Laminar Research/Cessna 172SP/Cessna_172SP_G1000.acf")

Official SDK XPLMSetUsersAircraft

placeUserAtAirport(code)

This routine places the user at a given airport. Specify the airport by its ICAO code (e.g. ‘KBOS’).

Warning

Using an invalid airport code will crash the sim, this includes using something other than ICAO. For example, ‘JFK’ does not work.

Note

You cannot call placeUserAtAirport() in your Start or Enable callback as the (initial) user aircraft has not yet been placed (you will crash the sim). You may create a flight loop callback and then execute placeUserAtAirport() within the callback, or in response to a menu or command.

>>> xp.placeUserAtAirport('KBOS')

Official SDK XPLMPlaceUserAtAirport

placeUserAtLocation(latitude, longitude, elevation, heading, speed)

Places the user at a specific location after performing any necessary scenery loads.

As with in-air starts initiated from the X-Plane user interface, the aircraft will always start with its engines running, regardless of the user’s preferences (i.e., regardless of what the dataref sim/operation/prefs/startup_running says).

elevation is meters MSL (1 meter = 3.28084 feet),
heading is degrees True, (use getMagneticVariation() to convert.)
speed is meters per second (1 meter per second = 1.94384 knots).
>>> xp.placeUserAtLocation(35, -122.5, 2000 / 3.28084, 90, 110 / 1.94384)

Official SDK XPLMPlaceUserAtLocation

countAircraft()

Return three integers representing:

  • the number of aircraft X-Plane is capable of having,

  • the number of aircraft that are currently active.

  • The pluginID of the plugin currently controlling the aircraft. (-1 for none)

These numbers count the user’s aircraft plus the number of AI Aircraft.

>>> xp.countAircraft()
(4, 4, -1)

Official SDK XPLMCountAircraft

getNthAircraftModel(int: index) → (model, path):

Return two strings based on the aircraft index. User’s aircraft is always 0.

  • filename of aircraft

  • path to the model filename

>>> xp.getNthAircraftModel(0)
('Cessna_172SP.acf', '/Volumes/SSD1/X-Plane/Aircraft/Laminar Research/Cessna 172SP/Cessna_172SP.acf')

Official SDK XPLMGetNthAircraftModel

acquirePlanes(aircraft=None, callable=None, refCon=none)

Grants your plugin exclusive access to the aircraft. It returns 1 if you gain access, 0 if you do not.

In the simplest form, attempt to acquire all the aircraft:

>>> xp.acquirePlanes()
1

If you provide a callback, and do not immediately get access, acquirePlanes() will return 0, and call you callback when able. Your callback() is passed the refCon. If you are able to acquire immediately, you callback will not be called.

>>> def MyCallback(refCon):
...    xp.log("Acquired airplanes")
...
>>> xp.acquirePlanes(callback=MyCallback)
1

aircraft is supposed to be a list of strings, specifying the planes you want to load, this does not appear to do anything in X-Plane 11, so keep it set to None. (Laminar has confirmed this does nothing in 11.5, and they suggest the parameter is deprecated and will not be fixed.)

Official SDK XPLMAcquirePlanes

releasePlanes()

Call this function to release access to the planes (acquirePlanes()). Note that if your plugin is disabled, access to planes is released for you and you must reacquire it.

Official SDK XPLMReleasePlanes

setActiveAircraftCount(count)

This routine sets the number of active planes. If you pass in a number higher than the total number of planes available, only the total number of planes available is actually used.

You must have exclusive access to planes first (acquirePlanes())

>>> xp.countAircraft()
(4, 4, -1)
>>> xp.acquirePlanes()
1
>>> xp.setActiveAircraftCount(6)
>>> xp.countAircraft()
(4, 4, 3)  # '3' being my plugin ID
>>> xp.setActiveAircraftCount(2)
>>> xp.countAircraft()
(4, 2, 3)  # '3' being my plugin ID
>>> xp.releasePlanes()

Official SDK XPLMSetActiveAircraftCount

setAircraftModel(index, path)

This routine loads an aircraft model. It may only be called if you have exclusive access to the airplane APIs (acquirePlanes()). Pass in the path of the model with the .acf extension. Path may be relative X-Plane Root. The index is zero based, but you may not pass in 0 (use setUsersAircraft() to load the user’s aircraft).

This does not add a new AI aircraft, if you use an index greater than current aircraft count. (It will do nothing.)

If the aircraft path is invalid, the user will be notified.

>>> xp.acquirePlanes()
1
>>> xp.setAircraftModel(2, 'Aircraft/Laminar Research/Boeing B737-800/b738.acf')
>>> xp.releasePlanes()

Official SDK XPLMSetAircraftModel

disableAIForPlane(index)

This routine turns off X-Plane’s AI for a given plane. The plane will continue to draw and be a real plane in X-Plane, but will not move itself.

Note

There is no enableAIForPlane() function: you cannot simple re-enable AI. However, if you acquire all planes, set the active count to 1 (User aircraft only) and then reset the count to something larger than 1, all of the added aircraft will have their AI re-enabled once you call xp.releasePlanes()

It seems this is likely an unintended side-effect, but works for XP11 and XP12.

Official SDK XPLMDisableAIForPlane

Constants

USER_AIRCRAFT = 0

User’s Aircraft