XPLMInstance

To use:

import xp

This API provides instanced drawing of X-Plane objects (.obj files). In contrast to old drawing APIs, (XPLMGraphics) which required you to draw your own objects per-frame, the instancing API allows you to simply register an OBJ for drawing, then move or manipulate it later (as needed).

This provides one tremendous benefit: it keeps all dataRef operations for your object in one place. Because datarefs are main thread only, allowing dataRef access anywhere is a serious performance bottleneck for the simulator—the whole simulator has to pause and wait for each dataRef access. This performance penalty will only grow worse as X-Plane moves toward an ever more heavily multi-threaded engine.

The instancing API allows X-Plane to isolate all dataRef manipulations for all plugin object drawing to one place, potentially providing huge performance gains.

Here’s how it works:

When an instance is created using createInstance(), it provides a list of all datarefs you want to manipulate in for the OBJ in the future. This list of datarefs replaces the ad-hoc collections of dataRef objects previously used by art assets. Then, per-frame, you can manipulate the instance by passing in a “block” of packed floats representing the current values of the datarefs for your instance using instanceSetPosition(). (Note that the ordering of this set of packed floats must exactly match the ordering of the datarefs when you created your instance.)

Functions

createInstance(obj, dataRefs=None)

Registers an instance of an X-Plane object, with an optional list of dataRefs.

obj is an object handle, as returned by loadObject() or loadObjectAsync(). Returns an object instance, which you’ll pass to instanceSetPosition() and destroyInstance().

The following example loads an XP standard object using lookupObjects(), and creates an instance of it, with two datarefs:

>>> paths = []
>>> xp.lookupObjects('lib/airport/vehicles/pushback/tug.obj', 0, 0, lambda path, refCon: paths.append(path), None)
1
>>> paths
['Resources/default scenery/sim objects/apt_vehicles/pushback/Tug_GT110.obj']
>>> obj = xp.loadObject(paths[0])
>>> drefs = ['sim/graphics/animation/ground_traffic/tire_steer_deg', 'foo/bar/ground']
>>> instance = xp.createInstance(obj, drefs)
>>> instance
<capsule object "XPLMInstanceRef" at 0x7f8946a4a9f0>

(With the above code, you’ve found, loaded and created the Instance, but you still need to instanceSetPosition() in order to actually see it.)

Official SDK XPLMCreateInstance

destroyInstance(instance)

Unregisters an instance (as returned from createInstance().)

>>> xp.destroyInstance(instance)

Official SDK XPLMDestroyInstance

instanceSetPosition(instance, position, data=None)

Updates both the position of the instance and all datarefs you registered for it.

instance is as returned by createInstance(). You must always provide a six-float tuple for position: (x, y, z, pitch, heading, roll), and data may be None. Otherwise data should be a list of floats in the same order as the dataRefs provided during instance creation. (If you don’t provide data, it effectively sets each registered dataRef to 0.0.)

The following example builds on the example in createInstance(), and sets the position of the instance, and sets values for each of the (two) datarefs. You’ll likely call this in your flight loop callback (not a draw callback):

>>> # get current aircraft position
>>> x = xp.getDatad(xp.findDataRef('sim/flightmodel/position/local_x'))
>>> y = xp.getDatad(xp.findDataRef('sim/flightmodel/position/local_y'))
>>> z = xp.getDatad(xp.findDataRef('sim/flightmodel/position/local_z'))
>>> pitch, heading, roll = (0, 0, 0)
>>> # Place the tug in front of the aircraft (just so you can see it)
>>> position = (x, y-1, z+10, pitch, heading+90, roll)
>>> # Set wheel steer degrees to 0, then 20, 40, pausing in between.
>>> xp.instanceSetPosition(instance, position, [0, 0.0])
>>> xp.instanceSetPosition(instance, position, [20, 0.0])
>>> xp.instanceSetPosition(instance, position, [40, 0.0])

Official SDK XPLMInstanceSetPosition