XLua2 API Ref XPLMInstance Latest - 4.4.0-d4

Multi-Object Instance Creation

Create an instance out of one or more objects with a single extensible call.

XPLMCoordinateSpace_t

enum XPLM440

This enum defines the coordinate space used to interpret the positions of an instance created with XPLMCreateInstanceEx(). By default, instances are in world space (the sim's global cartesian coordinate system). You can instead place an instance relative to an aircraft - either its interior or its exterior - or relative to the camera. Interior and exterior aircraft spaces use the same transform today; the distinction lets X-Plane light the objects correctly in a future release.

Name	Value	Description
xplm_CoordSpace_World	0	Position is in global OGL/tangent-plane coordinates (default).
xplm_CoordSpace_AircraftInterior	1	Position is relative to an aircraft's CG and body axes (+X right wing, +Y up, +Z tail), for objects inside the cockpit/cabin.
xplm_CoordSpace_AircraftExterior	2	Position is relative to an aircraft's CG and body axes (+X right wing, +Y up, +Z tail), for objects mounted on the exterior.
xplm_CoordSpace_Camera	3	Position is relative to the camera/view position and orientation.

Used by:

XPLMInstanceSetCoordinateSpace

XPLMInstanceObject_t

struct XPLM440

XPLMInstanceObject_t describes a single object within a multi-object instance: the object itself plus a fixed offset from the instance's origin. Every object in an instance moves rigidly together when you reposition the instance with XPLMInstanceSetPosition; this offset places each object relative to that shared origin and never changes after the instance is created.

local My_InstanceObject_t = {
    object   = nil,     -- XPLMObjectRef
    x        = 0.0,     -- float
    y        = 0.0,     -- float
    z        = 0.0,     -- float
    pitch    = 0.0,     -- float
    heading  = 0.0,     -- float
    roll     = 0.0,     -- float
}

XPLMCreateInstance_t

struct XPLM440

XPLMCreateInstance_t defines all of the parameters used to create an instance via XPLMCreateInstanceEx(). It is a strict superset of the older XPLMCreateInstance() call: it lets you build an instance out of more than one object, choose the coordinate space, and enable auto-shift, all in a single call. The structure will be expanded in future SDK versions to include more features. Always set the structSize member to the size of your struct in bytes!

local My_CreateInstance_t = {
    structSize       = 0,       -- int
    objects          = nil,     -- see XPLMInstanceObject_t
    objectCount      = 0,       -- int
    datarefs         = nil,     -- char
    coordinateSpace  = nil,     -- see XPLMCoordinateSpace_t
    aircraftIndex    = 0,       -- int
    autoShift        = 0,       -- int
}

XPLMCreateInstanceEx

function XPLM440

XPLMCreateInstanceEx creates a new instance from one or more objects and returns a handle to it. It is a strict superset of XPLMCreateInstance(): in addition to a single object, you can register several objects that draw and move together as one rigid group, and you can choose the coordinate space and auto-shift behavior up front in the same call.

The same requirements as XPLMCreateInstance() apply: every object must be fully loaded before you create the instance, any custom datarefs your objects use must be registered before the objects are loaded, and the dataref list must be a valid pointer to a NULL-terminated array. The dataref list is shared by all objects in the instance.

The set of objects is fixed when the instance is created; you cannot add or remove objects later. Destroy the instance with XPLMDestroyInstance() exactly as for an instance made with XPLMCreateInstance().

-- returns XPLMInstanceRef -> assign to local/var
local my_instanceRef = XPLMCreateInstanceEx(
    inParams     -- see XPLMCreateInstance_t
)

See associated types:

XPLMCreateInstance_t