WorldInstance script interface
IWorldInstance script interface represents a single instance of an object type (represented by IObjectClass) that appears in a layout. It derives from the IInstance script interface.
Many objects return a more specific class deriving from
IWorldInstance to add APIs specific to the plugin. See the Plugin interfaces reference for more information.
- An ILayout interface representing the layout the instance is on.
- An ILayer interface representing the layer the instance is on.
- The position of this instance, in layout co-ordinates.
- The Z elevation of the instance, relative to the layer it is on.
- A read-only value indicating the Z elevation of the instance including its layer's Z elevation.
- The size of this instance, in layout co-ordinates.
- The angle of the instance in radians. If this is changed,
angleDegrees updates accordingly.
- The angle of the instance in degrees. If this is changed,
angle updates accordingly.
- Return a DOMRect representing the axis-aligned bounding box of the instance in layout co-ordinates.
- Return a DOMQuad representing the bounding quad of the instance in layout co-ordinates. This is always a rectangle, but unlike the bounding box can represent rotation.
- A boolean indicating whether the instance is visible in the layout.
- The opacity of the instance, as a floating point number in the range [0, 1], where 0 is fully transparent and 1 is fully opaque.
- An array with 3 elements specifying the red, green and blue color filter of the instance, with color values as floats in the 0-1 range.
- A string indicating the current blend mode of the instance, controlling how it draws over the background. This must be one of
- An array of IEffectInstance representing the effect parameters for each effect on the instance.
Z order APIs
- Move the instance to the top or the bottom of its current layer in the Z order.
- Move the instance to the top of a different layer given by its ILayer.
- moveAdjacentToInstance(other, isAfter)
- Move the instance adjacent to
IWorldInstance) in the Z order. If necessary this also moves the instance to the same layer as
isAfter is true, it moves it just above the given instance, else just below.
- containsPoint(x, y)
- Test if a point intersects this instance, using its collision polygon if any, and return a boolean indicating if the point is inside the instance's collision area.
- Test if this instance overlaps another world instance given by an
true if they overlap, else
false. This uses the object's collision polygons if any. If either instance has collisions disabled, this will always return
- Test if this instance overlaps any instance with the Solid behavior. This returns the instance interface class for the first instance with the solid behavior that was found to overlap this instance, or
null if none. This uses the object's collision polygons if any and respects solid collision filtering.
Mesh distortion APIs
- createMesh(hsize, vsize)
- Create a mesh for deforming the appearance of the object with the given number of mesh points horizontally and vertically. The minimum size is 2.
- Releases any mesh that has been created, reverting back to default rendering of the object with no mesh distortion. Ignored if no mesh created.
- setMeshPoint(col, row, opts)
- Alter a given point in a created mesh given by its zero-based column and row.
opts is an object that may specify the following properties:
mode: a string of
"absolute" (default) or
"relative", determining how to interpret the
y: the mesh point position offset, in normalized co-ordinates [0, 1] across the object size. These are allowed to go outside the object bounds. In relative mode these are added to the mesh point's current position.
v: the texture co-ordinate for the mesh point, in normalized co-ordinates [0, 1]. These are not allowed to go outside the object bounds. These can be omitted, or in absolute mode be set to -1, to indicate not to change the texture co-ordinate from the default.
- Return the size of the mesh as
[hsize, vsize] (corresponding to the size passed to
createMesh()) if one is created. If no mesh has been created, returns
Scene graph APIs
- Return the parent
IWorldInstance of this instance in the scene graph hierarchy if any, else
- Return the top parent of this instance in the scene graph hierarchy (which by definition has no parent itself) if any, else
- A generator method that can be used to iterate all the instance's parents, up to the top parent.
- Returns the number of children that have been added to this instance in the scene graph hierarchy.
- Of the children that have been added to this instance, return the child instance at the given zero-based index. If the index is out of bounds, returns
- A generator method that can be used to iterate all the instance's added children.
- A generator method that can be used to iterate all the instance's children recursively, i.e. including children of children, down to the bottom of the scene graph hierarchy.
- addChild(wi, opts)
- Add another world instance given by an
IWorldInstance as a child of this instance in the scene graph hierarchy. This instance becomes its parent in the scene graph hierarchy. 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:
Each option is a boolean which defaults to
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
false if omitted, so only
true properties need to be specified.
- Remove an existing child given by an
IWorldInstance that was previously added with
addChild(). The child is detached from the scene graph hierarchy and this instance will no longer act as its parent. The removed child still keeps its own children, if it has any.
- Shorthand method for
wi.getParent().removeChild(wi), i.e. removes this instance from its parent if it has any. If the instance has no parent, the method has no effect.
Construct 3 Manual
You are here:
Search this manual:
This manual entry was last updated on 23 Mar, 2021 at 18:21