Python SDK Modules

We’ve attempted to fully document the API here, noting changes from the official C-Language SDK. (Don’t forget to use the Search field in the header of each of these documentation web pages to find what you’re looking for!)

Most of the APIs in this documentation include example source code which can be cut and pasted into the Mini Python Interpreter.

Additionally:

• Change Log. Lists recent changes to this SDK.

• X-Plane Developer Documentation @ developer.x-plane.com. The official X-Plane SDK documentation is for C-language, and most of that has been translated to python and documented with XPPython3. However, when in doubt, check the Laminar docs.

Note we use a Simplified Python Interface as described in xp. This makes all interfaces available from:

import xp

You’ll find it much faster and easier to write new code using this interface and it won’t wear out your X-P-L-M keys. You can use the older style, but you’ll have to import each module separately:

import XPLMMenus

Not sure which modules contain what you want? Here’s an overview arranged by features:

• Accessing dataRefs (internal X-Plane data), and creating your own dataRefs. XPLMDataAccess

  • with a simpler lua-like access using easy datarefs Easy Datarefs

• Command creation and execution, also allows you to augment (or replace) existing defined commands XPLMUtilities

  • with a simpler lua-like access using easy commands Easy Commands

• Creating Menus to execute code or existing commands XPLMMenus

• Creating flight loops, which can execute your code at specific points in time, including every frame. XPLMProcessing

  • Timers: really just simple flight loops Easy Timers

• Drawing:

  • Drawing within a window Window API

  • Drawing within an avionics device window Avionics API

  • Drawing on the screen using old-style, and largely deprecated draw callbacks Direct Drawing

  • Using pre-defined 3d object for Instance drawing: XPLMInstance. And access to existing library of objects XPLMScenery.

  • OpenGL interactions, state, textures (including weather radar): XPLMGraphics

  • Python OpenGL drawing primitives (lines, polygons, text, transformations, etc.: xpgl

  • Simple (non-OpenGL) drawing primitives XPLMGraphics, and graphical elements XPUIGraphics

  • Widgets Old style buttons, textboxes, checkboxes, etc. useful for basic user interaction. XPWidgets, doc:widgetutils, doc:standardwidgets

  • IMGUI integration for newer-style buttons, etc. xp_imgui

  • Cursor manipulation XPCursor

• Querying and controlling the weather XPLMWeather

• Accessing the NavAid database XPLMNavigation

• Interacting with Flight Management Systems (FMS) and flight plans XPLMNavigation

• Replay and situation files loading and saving XPLMUtilities

• Aircraft: setting and moving the user plane, changing aircraft type, disabling AI aircraft. XPLMPlanes

• Drawing on the pop-up Map. Adding labels and icons. XPLMMap

• Controlling the Camera, changing the position and location of the camera XPLMCamera

• Keyboard shortcuts:

  • Hot Keys: Higher level keystroke intercept to execute code. Hot keys “listen” for a specific keystroke, and are only called when that stroke is made. Hot Keys.

  • Key Sniffing: Intercept a keystroke and execute code. Lowest level and can “consume” the key blocking other usage. Sniffer are called on every keystroke and are passed the current keystroke, which they can opt to ignore: Key Sniffing

• Coordinate systems:

  • OpenGL (“local”) and Lat/Lng (“world”) XPLMGraphics

  • Elapsed time, and cycle number XPLMProcessing

  • Mesh probes (vertical distance to terrain) XPLMScenery

  • Magnetic variation XPLMScenery

• FMOD Sound, playing audio clips and positioning them in 3d space XPLMSound, or simple “speak string” for alerts XPLMUtilities.

• Working with other plugins, messages your plugin will receive (PLANE_LOADED, PLANE_CRASHED, etc.) and finding and messaging other plugins : XPLMPlugin

• System information: paths, version, language XPLMUtilities

• Python infrastructure: version, executable, paths. XPPython.

  • Python package management using pip xp_pip.

  • Performance Statistics: XPPython

  • Access to internal XPPython Datastructures to aid debugging: XPPython

• Logging to Log.txt and to XPPython3Log.txt XPPython.

For compatibility with Laminar documentation, this documentation splits the SDK along the same divisions:

XPLMCamera	Control camera angle.
XPLMDataAccess	Read/Write DataRefs, also create your own.
XPLMDefs	Enumerations for Keycodes, primarily.
XPLMDisplay	Direct drawing, using “draw callbacks”. Avionics drawing, using “avionics callbacks”. Window creation and interaction (visibility, geometry, drawing, clicks, key handling). Monitor / Screen size query functions. Key-sniffing and hot keys.
XPLMGraphics	Basic OpenGL interface. Local / World Coordinate system conversion. Basic drawing functions (drawString, measureString), of limited utility.
XPLMInstance	Preferred drawing routines using “objects” loaded by XPLMScenery. Create, destroy and set position of instances.
XPLMMap	Create new layer and draw on X-Plane map.
XPLMMenus	Create menus & menu items and provide handlers.
XPLMNavigation	Query NavAid database. Get/Set Flight Management Systems (FMS) entries. (This includes basic systems such as G530 and more advanced systems found in airliners.)
XPLMPlanes	Get/Set user’s aircraft and initial location. Disable AI aircraft.
XPLMPlugin	Find, enable / disable other plugins. Send messages to other plugins
XPLMProcessing	Get current elapsed time and cycle number. Create, schedule, and destroy Flight Loops.
XPLMScenery	Terrain testing (height, slope, relative movement) using probes. Magnetic variation (declination) at a point. Lookup and loading of scenery objects. (Used with XPLMInstance.)
XPUIGraphics	Draw Windows, to be executed within XPLMDisplay draw callbacks. Draw pre-defined decorative elements such as Checkbox, Waypoint, CoolingTower: you’ll have to manage clicks if you want interaction. Draw Tracks (“scroll bars”). Again, you have to manage interaction.
XPLMUtilities	Execute X-Plane Commands, also create your own. Save & Load situations and replays. Speak String, reload scenery, get virtual key description and current language. Get paths, directory contents utilities. Find internal X-Plane function symbol, for access to code not directly supported by the SDK.
XPLMSound	Play sound, at a specific location, in a particular direction, with fading. (Uses FMOD).
XPLMWeather	Get METAR for given airport Get Weather Information for given location (latitude, longitude, altitude).

X-Planes’s Widget modules:

XPWidgets	Create, destroy and otherwise manipulated pre-defined (“standard”) widgets. Send (widget) messages, and handle messages through callbacks.
XPStandardWidgets	Pre-defined widgets, with their properties and messages. Including Window Button Text Field Scroll Bar Caption Progress Indicator
XPWidgetDefs	Enumerations related to widgets – mostly message and property IDs.
XPWidgetUtils	Mostly useless functions.

Some “helper” pure-python modules, built on top of the others, making basic functionality easier to implement.

Easy Timers	Create and schedule one-shot and interval timers. Easier than working with flight loops.
Easy Commands	Create and execute X-Plane commands. Alter existing commands.
Easy Datarefs	Create and access datarefs.
EasyPython	Optional parent class for required PythonInterface class. Provides a number of well-defined callback points, making it easier for you to code a plugin.
Xlua Variables	Convenience code with pre-defined global parameters, also commonly used in xlua programs.

More pure-python modules useful for graphics:

xpgl	Convenience wrapper around common OpenGL routines allowing you to quickly draw shapes, load images, and fonts.

And three XPPython-specific additions (also accessible with simple import xp.)

xp	The only python modules you really need. This page also describes the pythonic, simplified API mapping with optional and keyword parameters.
xp_imgui	API to the Dear ImGui graphics library, with examples.
XPPython	Logging functions Access internal XPPython3 data structures, perhaps useful for debugging new plugins.