=====AddShape=====

====Summary====

The **AddShape** function will allow you to create a predefined asset shape such as a Cube, Sphere, Capsule, Cylinder or Custom Polygon.

Custom Polygon's can be defined as multiple [[XY Coordinates]] to create a flat shape using the points and then an //Extrude// parameter value can be applied to convert it into a 3D shape.

====Parameters====

===Shape===
//Type: [[Primitive]]
Default: None//

Specifies the type of 3D shape that the new asset will be. Any one of the following 3D primitaves may be specified:

^3D Shape^Description^
|**cube**|Creates an asset with a Cube shaped mesh.|
|**cylinder**|Creates an asset with a Cylinder shaped mesh.|
|**sphere**|Creates an asset with a Sphere shaped mesh.|
|**capsule**|Creates an asset Capsule shaped mesh.|
|**empty**|Creates an asset with no mesh attached.|
|**polygon**|Creates an asset from a set of [[XY Coordinates]] which will form a customized polygon.|

===Polygon===

In order to crates a shape of the type //polygon//, multiple [[XY Coordinates]] must be specified using the //points// parameter. See //points// for more information.

===Points===

//Type: Multiple [[XY Coordinates]]
Default: None//

Each coordinate must be specified and formatted as "X1 Y1,X2 Y2,X3 Y3". At least 3 sets of coordinates must be specified.

//Must only be used if the shape type **Polygon** was specified.//

===Extrude===

//Type: [[Float]]
Default: None//

The amount to extrude from the specified //Polygon// //Points// to convert a flat shape into a 3D shape.

//Must only be used if the shape type **Polygon** was specified.//

===TopAndBottom===

//Type: [[Bool]]
Default: **True**//

Used when the shape type is defined as a //Polygon// type. If true, it will generate ceiling and floor polygons to create a completely solid shape. If false, there will be no ceiling or floor and only the walls of the mesh will be generated.

//Must only be used if the shape type **Polygon** was specified.//

===Name===

//Type: Text
Default: None//

Specifies the name from which to view label the asset. This name can be referred to by later other scripts in order to modify and/or interact with it.

===Position===
//Type: [[XYZ Coordinates]]
Default: **0,0,0**//

The co-ordinates in which to place the asset within the 3D world. Co-ordinates are defined as "x,y,z", separated by a ',' and no spaces.

===AttachTo===
//Type: Text
Default: None//

Specifies the //name// or ARDI ID of another asset for which this asset is to be parented to. If using an asset ID, begin the target with the '#' character. //This parameter is optional//

If defined, this asset will be parented to the specified asset and it's //position// will be converted to local co-ordinates around the parent asset.

===CopyRotation===

//Type: [[Bool]]
Default: **True**//

Only used when an //AttachTo// parameter is defined. If true, the asset will attempt to copy the rotation of it's parent.

===Color===
//Type: [[RGB]] or [[RGBA]]
Default: **1,1,1,1**//

This parameter sets the color of the new asset. Color must be defined as "r,g,b" or "r,g,b,a" using normalized values (values ranging from 0.0 to 1.0)

^Parameter^Meaning^
|**r**|The value for the amount of red to be applied. Must be a value ranging from 0.0 to 1.0|
|**g**|The value for the amount of green to be applied. Must be a value ranging from 0.0 to 1.0|
|**b**|The value for the amount of blue to be applied. Must be a value ranging from 0.0 to 1.0|
|**a**|The value for the amount of alpha transparency to be applied. Must be a value ranging from 0.0 to 1.0. //This parameter is optional//|

===Texture===
//Type: [[Path]]
Default: None//

Specifies the path to the texture file to be used. Standard bitmap file formats are supported such as **.png**,**.jpg**,**.bmp**.

This applies textures to the new asset, allowing more graphical detail to be added.

===Transparent===
//Type: [[Bool]]
Default: **False**//

Specifies whether or not to add an additional transparency effect to the new asset. If true, the object will become transparent.

====See Also====
[[addmesh]] [[addbeacon]] [[addparticle]] [[addlinkedpoints]] [[remove]] [[duplicateobject]]

====Examples====

<code>
<addshape Shape="Cylinder" Position="67,25,160" Name="TestCylinder" />
</code>

> This will create a new asset of the primitave shape type **Cylinder** at the x,y,z coordinates "67,25,160" respectively and give the asset the name **TestCylinder**.

<code>
<addshape Shape="Cube" Position="30,25,100" Name="TestCube" Texture="GlowingEdges.png" Transparent="true"/>
</code>

> This will create a new asset of the primitave shape type **Cube** at the respective x,y,z coordinates "30,25,100" . It will have the name **TestCube**, have a texture imported from the file **GlowingEdges.png** and be set to //Transparent//.

<code>
<addshape Shape="Polygon" Points="10 10,10 20,20 10" Extrude="10" Position="15,15,60" Name="TestShape" Texture="Texture.png" Transparent="true" Color="0.4,1,0.4" />
</code>

> This will add an asset called **TestShape** to the 3D world of type //polygon//. The //polygon// will have the 3 points 10 10, 10 20, 20 10 respectively and an //extrude// height of 10.

> It will be created and positioned at the x,y,z co-ordinates: 15,16,60 respectively. It will also have a texture imported from the file **Texture.png**, be set to //Transparent// and have a color of 0.4,1,0.4 which should create a shade of light green.