Instance

Addon SDK v1 retirement

The Instance class represents an object instance in the runtime.

General methods

GetWorldInfo()

For "world" type plugins, get the instance's associated WorldInfo. This allows modification of the position, size, angle etc.

GetRuntime()

Get the Runtime for this instance.

GetSdkInstance()

Get the plugin-specific instance class for this instance, which derives from SDKInstanceBase. See also Addon interfaces for the public APIs exposed by some of the built-in addons in Construct.

GetObjectClass()

Get the ObjectClass representing the object type this instance belongs to.

GetPlugin()

Return the plugin class for this instance, which derives from SDKPluginBase.

BelongsToObjectClass(objectClass)

Returns true if this instance's object class is the given object class, or the given object class is a family and this instance's object class is a member of that family.

GetImagePoint(nameOrIndex)

Get an image point from the instance by either its index or a string of its name. Note image points are returned in a [0,1] range, such that 0.5 represents the middle.

IsInContainer()

Returns true if the instance is in a container.

GetSiblings()

Return a read-only array of sibling instances for this instance, i.e. its associated other instances in its container. This is only applicable if the instance is in a container.

GetUID()

Get the unique identifier (UID) for this instance. UIDs are unique integer numbers assigned to every instance, and never change during the lifetime of the instance.

GetIID()

Get the instance identifier (IID) for this instance. IIDs are the zero-based index of this instance in its object type's instance list. Note IIDs can change during the lifetime of the instance; if an instance with a lower IID is destroyed, all instances with higher IIDs are renumbered so the IIDs are contiguous from 0.

GetBehaviorInstances()

Return a read-only array of BehaviorInstance for this instance.

GetBehaviorInstanceFromCtor(ctor)

Look up a behavior instance by its behavior constructor. For example GetBehaviorInstanceFromCtor(C3.Behaviors.Platform) will return the first BehaviorInstance for the Platform behavior if the instance has one, else null.

GetBehaviorSdkInstanceFromCtor(ctor)

As with GetBehaviorInstanceFromCtor(ctor), but returns the behavior-specific behavior instance class (which derives from SDKBehaviorInstanceBase) instead.

GetInstanceVariableCount()

Return the number of instance variables for this instance.

SetInstanceVariableValue(index, value)

GetInstanceVariableValue(index)

Set or get an instance variable value by its index. Note the type of the instance variable will be preserved.

GetSavedDataMap()

GetUnsavedDataMap()

Return a Map to store additional data to associate with this instance. Use string keys only, and ensure keys are unique. The saved data map is written to savegame files so should be used for persistent state. The unsaved data map is not written to savegame files so should be used for transient storage or caching.

Scene graph methods

GetParent()

Return the parent instance in the hierarchy, or null if none.

GetTopParent()

Return the top parent of this instance in the hierarchy (which by definition has no parent itself), or null if none.

*parents()

A generator method that can be used to iterate all the instance's parents, up to the top parent.

GetChildren()

Return an array of all the children that have been added to this instance. The array may be empty if no children have been added.

*children()

*allChildren()

Generator methods that can be used to iterate all the instance's children. The allChildren() variant is recursive, so will also iterate children-of-children.

AddChild(childInst, opts)

Add another instance as a child of this instance in the hierarchy. This instance becomes its parent. The child will move, scale and rotate with this instance according to the provided options specified in the object opts, which supports the following properties:

• transformX: move the child with this instance's X position


• transformY: move the child with this instance's Y position


• transformWidth: scale the child with this instance's width


• transformHeight: scale the child with this instance's height


• transformAngle: rotate the child with this instance's angle


• transformZElevation: move the child with this instance's Z elevation


• destroyWithParent: automatically destroy the child if this instance is destroyed

Each option is a boolean which defaults to false if omitted, so only true properties need to be specified.

RemoveChild(childInst)

Remove an existing child that was previously added with AddChild(). The child is detached from the hierarchy and this instance will no longer act as its parent. The removed child still keeps its own children, if it has any.