WorldInfo

Addon SDK v1 retirement

The WorldInfo class represents the state of an instance in the "world" (i.e. the Layout it is in). This includes information like its position, size, angle, Z order, layer and so on.

Only "world" type plugin instances have an associated WorldInfo. It is typically obtained by using the Instance GetWorldInfo() method.

Modifying geometric properties

For performance reasons, changing the X, Y, angle, width, height or origin does not update the corresponding bounding box, which is stored separately. If any of these properties are changed, you must call SetBboxChanged() afterwards to ensure the runtime re-calculates the bounding box.

General methods

GetInstance()

Return the associated Instance that this WorldInfo represents state for.

SetX(x)

SetY(y)

SetXY(x, y)

GetX()

GetY()

Set and get the position of the instance in layout co-ordinates.

OffsetX(x)

OffsetY(y)

OffsetXY(x, y)

Add to the X and Y components of the instance's position. For example OffsetX(5) is equivalent to SetX(GetX() + 5).

SetWidth(w)

SetHeight(h)

SetSize(w, h)

GetWidth()

GetHeight()

Set and get the width and height of the instance in layout co-ordinates.

SetAngle(a)

GetAngle()

Set and get the angle of the instance in radians. Use C3.toDegrees() and C3.toRadians() to convert from degrees to radians.

SetOriginX(x)

SetOriginY(y)

GetOriginX()

GetOriginY()

Set and get the origin of the instance as a normalized position in the [0,1] range, i.e. 0.5 is the middle.

SetBboxChanged()

Mark the instance's bounding box as having been changed. Call this after altering the position, size, angle or origin of the instance.

GetBoundingBox()

Return a C3.Rect representing the axis-aligned bounding box of the instance in layout co-ordinates.

GetBoundingQuad()

Return a C3.Quad representing the bounding quad of the instance in layout co-ordinates, which is essentially the rotated bounding box.

SetOpacity(o)

GetOpacity()

Set and get the opacity of the instance in the [0,1] range. 0 is fully transparent and 1 is opaque. This changes the alpha component of the instance color.

SetUnpremultipliedColor(c)

Set the RGB components of the instance color. This applies a built-in color multiply effect which appears like a tint. As with opacity, color values are in the [0,1] range. The default is RGB 1,1,1 (white) which means the instance appears with normal colors. Pass a C3.Color as the parameter. The runtime internally uses premultiplied alpha for best rendering quality; in this method the RGB values do not need to be premultiplied with the alpha (opacity) value, since it will apply the premultiplication for you.

GetUnpremultipliedColor()

GetPremultipliedColor()

Get the instance color as a read-only C3.Color, either without or with premultiplied alpha (respectively). The instance color includes the opacity in the alpha channel.

HasDefaultColor()

Returns true if the instance color RGBA value equals (1,1,1,1), else false.

SetBlendMode(bm)

GetBlendMode()

Set and get the instance blend mode, as an index in to the dropdown list used in Construct's Blend mode property. E.g. 0 is "normal", 1 is "additive", etc.

GetLayer()

Get the Layer the instance is currently on.

GetLayout()

Get the Layout the instance currently belongs to.

SetVisible(v)

IsVisible()
Set and get the visible state for the instance. This is a boolean that hides the instance when set to false.

Collision methods

SetCollisionEnabled(e)

IsCollisionEnabled()

Set and get a boolean indicating whether collisions are enabled for this instance.

ContainsPoint(x, y)

Test if a point in layout co-ordinates intersects this instance, respecting its collision polygon and collisions enabled flag.

Mesh distortion methods

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.

ReleaseMesh()

Releases any mesh that has been created, reverting back to default rendering of the object with no mesh distortion. Ignored if no mesh created.

HasMesh()

Return a boolean indicating whether a mesh has been created for this object.

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 x, y, uand v options.


• x and 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.


• u and 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.

Note: this method returns a boolean indicating whether you must subsequently call SetBboxChanged() to apply the change. This allows all points in the mesh to be efficiently updated without unnecessarily repeatedly calling SetBboxChanged().

Z order methods

ZOrderMoveToTop()

ZOrderMoveToBottom()

Move the instance to the top or bottom of the Z order on its current layer.

ZOrderMoveToLayer(layer)

Move the instance in the Z order to the given Layer. If the same layer it is currently on is specified, the call is ignored. If the instance is moved to a new layer, it is inserted to the top of the Z order on that layer.

ZOrderMoveAdjacentToInstance(otherInst, isOnTop)

Move the instance in the Z order to be adjacent to the Instance otherInst (note this is passed as an Instance, not a WorldInfo). If isOnTop is true, this instance will be moved directly on top of otherInst in the Z order; otherwise it will be directly beneath. This method may move the instance to a different layer, since it will move it to the same layer as otherInst is on.