Skip to content

ShapeVector Guide

Jump to bottom
Peter Robinson edited this page Jul 5, 2020 · 2 revisions

Introduction

All scene objects are known engine types that allow instances to be created at runtime. The "ShapeVector", like all other objects, is derived from a base type of "SceneObject". That means it includes all the fields from that type as well as adding its own fields specific to itself.

A ShapeVector is an object that displays vector graphics of simple polygons or circles. These shapes can be shown either as an outline or filled in with a solid color. Rendering points and lines are also possible using ShapeVector.

TorqueScript Bindings

Exposed Fields

The ShapeVector type exposes the following fields in addition to those it inherits. Shown are the equivalent methods available that perform the same action in setting and getting the respective field:

  • PolyList
  • setPolyCustom(int, string)
  • getPoly()
  • LineColor
  • setLineColor(float or string)
  • setLineAlpha(float)
  • getLineColor()
  • FillColor
  • setFillColor(float or string)
  • setFillAlpha(float)
  • getFillColor()
  • FillMode
  • setFillMode(bool)
  • getFillMode()
  • IsCircle
  • setIsCircle(bool)
  • getIsCircle()
  • CircleRadius
  • setCircleRadius(float)
  • getCircleRadius()

The following is a complete description of each of these fields.

PolyList (int)

This field contains a list of X/Y coordinate pairs that define the location of each polygon shape's verticies. The coordinates are defined in local space. For example, a square would have the following:

%object = new ShapeVector();
%object.PolyList = "-0.500 -0.500 0.500 -0.500 0.500 0.500 -0.500 0.500";

A triangle would have:

%object.PolyList = "-1.000 -0.000 0.500 -0.866 0.500 0.866";

If you do not wish to manually define coordinate pairs, you can simply specify the number of verticies the shape should have with ShapeVecor.setPolyPrimitive(vertexCount). That method only defines shapes as equiangular, a more complex shape where the interior angles are not identical will need to be defined manually through PolyList. Also remember that a circle would not be defined through this field, that instead uses the IsCircle and CircleRadius fields.

LineColor (float)

Sets the color (float red, float green, float blue, float alpha) of the shape's outline. The default is white (1.0, 1.0, 1.0, 1.0).

%object.LineColor = "0.0 0.0 0.0 1.0";

Replacing the numeric values in the example above with a stock color name like "CornflowerBlue" is also valid.

FillColor (float)

Sets the color (float red, float green, float blue, float alpha) of the shape's filled in texture. This color can be different to the line color. The default is (0.5, 0.5, 0.5, 1.0).

%object.FillColor = "0.0 1.0 0.0 1.0";

Replacing the numeric values in the example above with a stock color name like "CornflowerBlue" is also valid.

FillMode (bool)

This field is used to specify whether the shape is rendered as an outline or filled in with a solid color. The default is false, which means an outline is rendered.

%object.FillMode = "true";

IsCircle (bool)

Specify whether the ShapeVector is a circle or not. The default is false.

%object.IsCircle = "true";

CircleRadius (float)

Sets the radius of the circle in meters. The IsCircle field needs to be set to true for this field to work. The default is 1.0.

%object.CircleRadius = 10;

TAML Format

Using TorqueScript and the exposed fields or methods described in the previous section, you can programmatically create and configure a ShapeVector. You can then export this type to a TAML file or even create a TAML file manually and read it into your game at an appropriate time.

Here is an example ShapeVector TAML file in XML format:

<ShapeVector
    PolyList="-1.000 -0.000 0.500 -0.866 0.500 0.866"
    LineColor="0.5 1 1 1"
    fillColor="0.5 1 1 0.5"
    FillMode="1"
    Size="20 20" />

The same example in JSON format:

{
    "ShapeVector": {
        "PolyList": "-1.000 -0.000 0.500 -0.866 0.500 0.866",
        "LineColor": "0.5 1 1 1",
        "fillColor": "0.5 1 1 0.5",
        "FillMode": "1",
        "Size": "20 20"
    }
}

Additional API

The following methods are available to further configure and control a ShapeVector.

setPolyScale(widthScale / [heightScale])

This method scales the values of the polygon. If no height is specified, the width value is used for the height as well.

setPolyPrimitive(vertexCount)

This is perhaps the easiest way to create a polygon shape. Simply specify how many verticies the shape should have, and an equiangular polygon is created.

getWorldPoly()

While a polygon's verticies are defined in local space, this method gets the coordinates of those points in world space.

getVertexCount()

Returns the number of verticies on a polygon shape.

getBoxFromPoints()

Gets the width and height of a box where all polygon verticies of the shape are contained within it.

setFlip(bool flipX, bool flipY)

Sets whether to flip the shape along either the X or Y axis (or both).

getFlip()

Returns the flip status of each axis for a shape.

setFlipX(bool)

Sets whether to flip the shape along the X axis.

getFlipX()

Gets whether the shape is flipped along the X axis.

setFlipY(bool)

Sets whether to flip the shape along the Y axis.

getFlipY()

Gets whether to flip the shape along the Y axis.

Additional Information

ShapeVector Properties

As a child of SceneObject, a ShapeVector has all the properties available from its parent class. In order to not be affected by gravity or other forces, a ShapeVector has the "static" body-type by default. If you wish to have a moving or rotating shape, remember to set its body-type to "dynamic".

Clone this wiki locally