How To

Create Set Shapes


Set Shapes

These are shapes that usually already have names in everyday use and their form is well known. They are a box (or cuboid), a sphere, a cylinder, a cone, regular polygons, a plane and a specialist horizontal plane called the ground. Slightly less well know but also included in set shapes are ground from height map, tiled ground, a torus, a torus knot and the polyhedra.

The MeshBuilder method uses a number of options that you can set or you can just settle for the default values. Whilst some options such as size or diameter have an obvious meaning others such as updatable or faceUV require Further Reading to fully understand what they are and how to use them.

How To Create Set Shapes using MeshBuilder

To create all the set shapes you just follow the pattern

var mesh = BABYLON.MeshBuilder.Create<Shape Name>("name", options, scene);

Box

Example :

var box = BABYLON.MeshBuilder.CreateBox("box", {height: 5}, scene);
option value default value
size (number) size of each box side 1
height (number) height size, overwrites size option size
width (number) width size, overwrites size option size
depth (number) depth size, overwrites size option size
faceColors (Color4[]) array of 6 Color4, one per box face Color4(1, 1, 1, 1) for each side
faceUV (Vector4[]) array of 6 Vector4, one per box face UVs(0, 0, 1, 1) for each side
updatable (boolean) true if the mesh is updatable false
sideOrientation (number) side orientation DEFAULTSIDE
frontUVs (Vector4[]) array of Vector4, ONLY WHEN sideOrientation:BABYLON.Mesh.DOUBLESIDE set Vector4(0,0, 1,1)
backUVs (Vector4[]) array of Vector4, ONLY WHEN sideOrientation:BABYLON.Mesh.DOUBLESIDE set Vector4(0,0, 1,1)

Playground Example of a Box -


Sphere

Different values for diameterX, diameterY and diameterZ_ lead to an ellipsoid. Example :

var sphere = BABYLON.MeshBuilder.CreateSphere("sphere", {diameter: 2, diameterX: 3}, scene);
option value default value
segments (number) number of horizontal segments 32
diameter (number) diameter of the sphere 1
diameterX (number) diameter on X axis, overwrites diameter option diameter
diameterY (number) diameter on Y axis, overwrites diameter option diameter
diameterZ (number) diameter on Z axis, overwrites diameter option diameter
arc (number) ratio of the circumference (latitude) between 0 and 1 1
slice (number) ratio of the height (longitude) between 0 and 1 1
updatable (boolean) true if the mesh is updatable false
sideOrientation (number) side orientation DEFAULTSIDE
frontUVs (Vector4[]) array of Vector4, ONLY WHEN sideOrientation:BABYLON.Mesh.DOUBLESIDE set Vector4(0, 0, 1,1)
backUVs (Vector4[]) array of Vector4, ONLY WHEN sideOrientation:BABYLON.Mesh.DOUBLESIDE set Vector4(0, 0, 1,1)

Playground Example of a Sphere -


Cylinder or Cone

If you set diameterTop to zero, you get a cone instead of a cylinder, with different values for diameterTop and diameterBottom you get a truncated cone.

Example :

var cone = BABYLON.MeshBuilder.CreateCylinder("cone", {diameterTop: 0, tessellation: 4}, scene);
option value default value
height (number) height of the cylinder 2
diameterTop (number) diameter of the top cap, can be zero to create a cone, overwrites the diameter option 1
diameterBottom (number) diameter of the bottom cap, can't be zero, overwrites the diameter option 1
diameter (number) diameter of both caps 1
tessellation (number) number of radial sides 24
subdivisions (number) number of rings 1
faceColors (Color4[]) array of 3 Color4, 0 : bottom cap, 1 : cylinder tube, 2 : top cap Color4(1, 1, 1, 1) for each face
faceUV (Vector4[]) array of 3 Vector4, 0 : bottom cap, 1 : cylinder tube, 2 : top cap UVs(0, 0, 1, 1) for each face
arc (number) ratio of the circumference between 0 and 1 1
updatable (boolean) true if the mesh is updatable false
sideOrientation (number) side orientation DEFAULTSIDE
frontUVs (Vector4[]) array of Vector4, ONLY WHEN sideOrientation:BABYLON.Mesh.DOUBLESIDE set Vector4(0,0, 1,1)
backUVs (Vector4[]) array of Vector4, ONLY WHEN sideOrientation:BABYLON.Mesh.DOUBLESIDE set Vector4(0,0, 1,1)

Playground Example of a Cone -


Plane

A flat surface parallel to XoY plane.

Example :

var plane = BABYLON.MeshBuilder.CreatePlane("plane", {width: 5}, scene);
option value default value
size (number) side size of the plane 1
width (number) size of the width size
height (number) size of the height size
updatable (boolean) true if the mesh is updatable false
sideOrientation (number) side orientation DEFAULTSIDE
sourcePlane (Plane) source plane (math) the mesh will be transformed to null
frontUVs (Vector4[]) array of Vector4, ONLY WHEN sideOrientation:BABYLON.Mesh.DOUBLESIDE set Vector4(0,0, 1,1)
backUVs (Vector4[]) array of Vector4, ONLY WHEN sideOrientation:BABYLON.Mesh.DOUBLESIDE set Vector4(0,0, 1,1)

Playground Example of a DOUBLESIDE Plane -


Disc or Regular Polygon

You can create any kind of regular polygon with CreateDisc(), the number of sides is dependent on the value given to tessellation. The larger this value the closer to an actual disc. Using the arc option you can create a sector.

Example :

var disc = BABYLON.MeshBuilder.CreateDisc("disc", {tessellation: 3}, scene); // makes a triangle
option value default value
radius (number) the radius of the disc or polygon 0.5
tessellation (number) the number of disc/polygon sides 64
arc (number) ratio of the circumference between 0 and 1 1
updatable (boolean) true if the mesh is updatable false
sideOrientation (number) side orientation DEFAULTSIDE

Playground Example of a Sector of Dodecagon -


Torus

Example :

var torus = BABYLON.MeshBuilder.CreateTorus("torus", {thickness: 0.2}, scene);
option value default value
diameter (number) diameter of the torus 1
thickness (number) thickness of its tube 0.5
tessellation (number) number of segments along the circle 16
updatable (boolean) true if the mesh is updatable false
sideOrientation (number) side orientation DEFAULTSIDE
frontUVs (Vector4[]) array of Vector4, ONLY WHEN sideOrientation:BABYLON.Mesh.DOUBLESIDE set Vector4(0,0, 1,1)
backUVs (Vector4[]) array of Vector4, ONLY WHEN sideOrientation:BABYLON.Mesh.DOUBLESIDE set Vector4(0,0, 1,1)

Playground Example Using Thickness to Create a Hoop and a Donut -


Torus Knot

Example :

var torus = BABYLON.MeshBuilder.CreateTorusKnot("tk", {}, scene);
option value default value
radius (number) radius of the torus knot 2
tube (number) thickness of its tube 0.5
radialSegments (number) number of radial segments 32
tubularSegments (number) number of tubular segments 32
p (number) number of windings 2
q (number) number of windings 3
updatable (boolean) true if the mesh is updatable false
sideOrientation (number) side orientation DEFAULTSIDE
frontUVs (Vector4[]) array of Vector4, ONLY WHEN sideOrientation:BABYLON.Mesh.DOUBLESIDE set Vector4(0,0, 1,1)
backUVs (Vector4[]) array of Vector4, ONLY WHEN sideOrientation:BABYLON.Mesh.DOUBLESIDE set Vector4(0,0, 1,1)

A Playground Example of a Torus Knot -


Ground

A flat horizontal surface parallel to the plane XoZ subdivided into sections. Example :

var ground = BABYLON.MeshBuilder.CreateGround("gd", {width: 6, subdivsions: 4}, scene);
option value default value
width (number) size of the width 1
height (number) size of the height 1
updatable (boolean) true if the mesh is updatable false
subdivisions (number) number of square subdivisions 1

Playground Example of Ground -


Ground From a Height Map

Example :

var ground = BABYLON.MeshBuilder.CreateGroundFromHeightMap("gdhm", url, {width: 6, subdivisions: 4}, scene);

Don't forget the url parameter, which is the link to the heightmap file, a greyscale file where lighter areas will be displayed higher than darker areas.

option value default value
width (number) size of the map width 10
height (number) size of the map height 10
subdivisions (number) number of map subdivisions 1
minHeight (number) minimum altitude 0
maxHeigth (number) maximum altitude 1
onReady (function) a callback js function that is called and passed the just built mesh (mesh) => {return;}
updatable (boolean) true if the mesh is updatable false

Playground Example Ground From Height Map -


Tiled Ground

Example :

var tiledGround = BABYLON.MeshBuilder.CreateTiledGround("tgd", {subdivsions: {w:4, h:6} }, scene);
option value default value
xmin (number) map min x coordinate value -1
zmin (number) map min z coordinate value -1
xmax (number) map max x coordinate value 1
zmin (number) map max z coordinate value 1
subdivisions ( {w: number, h: number} ) number of subdivisions (tiles) on the height and the width of the map {w: 6, h: 6}
precision ( {w: number, h: number} ) number of subdivisions on the height and the width of each tile {w: 2, h: 2}
updatable (boolean) true if the mesh is updatable false

Playground Example of Tiled Ground -


.

Full explanation of creating a tiled ground by its original code writer here.

Further Reading

How To Make the Most of Options

Side Orientation
Updatable
Face UV and Face Colors
Front and Back UV

Basic - L1

Mesh Overview
Set Shapes 101
Parametric Shapes 101
Parametric Shapes
Polyhedra Shapes
Decals

Mid Level - L2

Ribbons In Detail

More Advanced - L3

Maths Makes Ribbons