Instance script interface

The IInstance script interface represents a single instance of an object type (represented by IObjectClass). Instances that appear in the layout have a IWorldInstance interface instead, but it derives from IInstance, so these methods and properties are available for any type of instance.

Many objects return a more specific class deriving from IInstance or IWorldInstance to add APIs specific to the plugin. See the Plugin interfaces reference for more information.

Getting an IInstance

Instances are typically accessed through IObjectClass methods like getFirstInstance(). For example, runtime.objects.Sprite.getFirstInstance() will return the first instance of the Sprite object type.

Instance events

The following events can be listened for on any instance using the addEventListener method. See instance event for standard event properties. Note many more kinds of addon-specific events can be fired. See the documentation on each addon's script interfaces for more information.

Fired when the instance is destroyed. After this event, all references to the instance are now invalid, so any remaining references to the instance should be removed or cleared to null in this event. Accessing an instance after it is destroyed will throw exceptions or return invalid data. The event object also has an isEndingLayout property to indicate if the object is being destroyed because it's the end of a layout, or destroyed for other reasons.

Instance APIs

addEventListener(type, func, capture)
removeEventListener(type, func, capture)
Add or remove an event handler for a particular type of event fired by an addon's script interface. An event object is passed as a parameter to the handler function. See instance event for standard event object properties. For information on which events are fired by specific addons and which additional event object properties are available, see the documentation on each addon's script interfaces.
Dispatch an event, firing any handler functions that have been added for the event type. You can use new C3.Event(eventName, isCancellable) to create an event object that can be dispatched (e.g. new C3.Event("click", true)), and add any extra properties relevant to your event to that object. This can also be used by the addon SDK to cause your addon to fire an event in the script interface, e.g.:

const e = new C3.Event("click", true);

A reference back to the IRuntime interface. (This is particularly useful when subclassing instances, since in a custom class's methods you can always refer to the runtime with this.runtime.)
The IObjectClass interface for this instance's object type.
If the object has any instance variables, they can be accessed by named properties under this property. For example if an object has an instance variable named health, it can be set and retrieved using Note if the object has no instance variables, the instance won't have an instVars property at all.

If the object has any behaviors, they can be accessed by named properties under this property. For example if an object has a behavior named Bullet, it can be accessed using instance.behaviors.Bullet. Each behavior has its own properties and methods, which can be found in the Behavior interfaces reference section. Note if the object has no behaviors, the instance won't have a behaviors property at all.

The unique ID of this instance, as a number. Note instances can be looked up by their UID using the runtime getInstanceByUid() method.
Destroy the instance, removing it and releasing any memory associated with it.
Construct 3 Manual 2021-12-14