XPLMInstance

Instanced 3-D object drawing — the recommended way to place OBJ models in the world without per-frame drawing callbacks.

Functions

XLuaCreateInstance(obj, { i })

Returns: XPLMInstanceRef

XPLMCreateInstance creates a new instance, managed by your plug-in, and returns a handle to the instance. A few important requirements: * The object passed in must be fully loaded and returned from the XPLM before you can create your instance; you cannot pass a null obj ref, nor can you change the ref later. * If you use any custom datarefs in your object, they must be registered before the object is loaded. This is true even if their data will be provided via the instance dataref list. * The instance dataref array must be a valid pointer to a null-terminated array. That is, if you do not want any datarefs, you must pass a pointer to a one-element array containing a null item. You cannot pass null for the array itself.

Argument Type Notes
obj XPLMObjectRef Enum — use a constant from XPLMObjectRef
datarefs { i } Array table — { val1, val2, ... }
XLuaInstanceSetAutoShift(instance)

Returns: (returns nothing)

XPLMInstanceSetAutoShift tells X-Plane to move the location of your instance every time the sim\'s local coordinate sytem changes, so that a static instance does not have to be moved. Without this, a plugin is responsible for updating an instance's local position when the coordinate system shifts. Use this for static instances that you would not otherwise have to move.

Argument Type Notes
instance XPLMInstanceRef Enum — use a constant from XPLMInstanceRef
XLuaDestroyInstance(instance)

Returns: (returns nothing)

XPLMDestroyInstance destroys and deallocates your instance; once called, you are still responsible for releasing the OBJ ref. Tip: you can release your OBJ ref after you call XPLMCreateInstance as long as you never use it again; the instance will maintain its own reference to the OBJ and the object OBJ be deallocated when the instance is destroyed.

Argument Type Notes
instance XPLMInstanceRef Enum — use a constant from XPLMInstanceRef
XLuaInstanceSetPosition(instance, {k}, { i })

Returns: (returns nothing)

Updates both the position of the instance and all datarefs you registered for it. Call this from a flight loop callback or UI callback. DO_NOT call XPLMInstanceSetPosition from a drawing callback; the whole point of instancing is that you do not need any drawing callbacks. Setting instance data from a drawing callback may have undefined consequences, and the drawing callback hurts FPS unnecessarily. The memory pointed to by the data pointer must be large enough to hold one float for every dataref you have registered, and must contain valid floating point data. BUG: before X-Plane 11.50, if you have no dataref registered, you must still pass a valid pointer for data and not null.

Argument Type Notes
instance XPLMInstanceRef Enum — use a constant from XPLMInstanceRef
new_position {k} Hash table — {{ field = value, ... }} (see SDK docs for fields)
data { i } Array table — { val1, val2, ... }
XLuaInstanceSetPositionDouble(instance, {k}, { i })

Returns: (returns nothing)

Updates both the position of the instance and all datarefs you registered for it. Call this from a flight loop callback or UI callback. DO_NOT call XPLMInstanceSetPositionDouble from a drawing callback; the whole point of instancing is that you do not need any drawing callbacks. Setting instance data from a drawing callback may have undefined consequences, and the drawing callback hurts FPS unnecessarily. The memory pointed to by the data pointer must be large enough to hold one float for every dataref you have registered, and must contain valid floating point data.

Argument Type Notes
instance XPLMInstanceRef Enum — use a constant from XPLMInstanceRef
new_position {k} Hash table — {{ field = value, ... }} (see SDK docs for fields)
data { i } Array table — { val1, val2, ... }

Examples

Examples coming soon.