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.
To create all the set shapes you just follow the pattern
var mesh = BABYLON.MeshBuilder.Create<Shape Name>("name", options, scene);
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) |
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) |
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) |
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) |
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 |
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) |
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 -
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 |
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 |
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 |
Full explanation of creating a tiled ground by its original code writer here.
Side Orientation
Updatable
Face UV and Face Colors
Front and Back UV
Mesh Overview
Set Shapes 101
Parametric Shapes 101
Parametric Shapes
Polyhedra Shapes
Decals