Instance Creation And Destruction

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.

-- returns XPLMInstanceRef -> assign to local/var
local my_instanceRef = XPLMCreateInstance(
    obj,         -- XPLMObjectRef
    datarefs     -- char const
)

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.

XPLMInstanceSetAutoShift(
    instance     -- XPLMInstanceRef
)

See associated types:

• XPLMInstanceRef

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.

XPLMDestroyInstance(
    instance     -- XPLMInstanceRef
)

See associated types:

• XPLMInstanceRef