Search this manual

Object class script interface

The IObjectClass script interface represents an object class in the project, e.g. a Sprite object type. An ObjectClass can have multiple instances created, which are represented by the IWorldInstance script interface if it appears in a layout, otherwise the IInstance interface.

Getting an IObjectClass

References to the project's object classes are typically accessed through the IRuntime interface objects property. For example runtime.objects.Sprite would refer to the IObjectclass interface for the Sprite object type, assuming one was added to the project.

Examples

The following examples demonstrate using some features of IObjectClass:

Object class events

The following events can be listened for using the addEventListener method.

"instancecreate"
Fired whenever a new instance belonging to this object type (or family) is created. The event object has an instance property referring to the IInstance (or derivative) that was created.
"instancedestroy"
Fired whenever any instance belonging to this object type (or family) 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 has an instance property referring to the IInstance (or derivative) that was destroyed. It 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.

Object class APIs

runtime
A reference back to the IRuntime interface.
plugin
A reference to the IPlugin interface (or derivative) this object class was created from.
name
A read-only string of the object class's name.
addEventListener(eventName, callback)
removeEventListener(eventName, callback)
Add or remove a callback function for an event. See Object class events above for more information.
setInstanceClass(Class)
Set a custom class to be used to represent instances of this object type. The class must derive from the default class. This can only be called in runOnStartup, before any instances have been created. For more information see the guide on subclassing instances.
getAllInstances()
Return an array of all instances of this object class.
getFirstInstance()
Return the first instance in the array returned by getAllInstances(), or null if no instances exist.
*instances()
Iterates over all the object class's instances.
getPickedInstances()
Return an array of instances that have been picked by the event's conditions. This is only useful with scripts in event sheets.
getFirstPickedInstance()
Return the first instance that has been picked by the event's conditions, or null if none. This is only useful with scripts in event sheets.
*pickedInstances()
Iterates over the instances that have been picked by the event's conditions. This is only useful with scripts in event sheets.
getPairedInstance(inst)
Get an instance of this object class at the same index (IID) as the given instance. If there are fewer instances of this object class than the given instance's object class, the index is allowed to wrap around. This allows identifying the same instance that the event system would pair with the given instance.
createInstance(layerNameOrIndex, x, y, createHierarchy, template)
Create a new instance of the object type at a position. The layer to create on is specified either by a case-insensitive string of the layer name or its zero-based index. The position is given in layout co-ordinates. If createHierarchy is true, all children of the created instance in the scene-graph hierarchy will also be created automatically with their connections in place. If template is a valid template name then the new instance will be based on the template rather than an arbitrary instance.
Returns an instance class representing the created instance.

Construct 3 Manual 2024-09-17