tutorials

Mesh CreateXXX Methods With Options Parameter


MeshBuilder CreateXXX() Methods With Options Parameter

In this tutorial, we will learn how to use the classical CreateXXX() methods with the options parameter instead of the full list of parameters. Indeed, as of BJS 2.3+, all the CreateXXX() methods can be called either by

var mesh = BABYLON.Mesh.CreateMesh(name, param1, param2, param3, ..., scene);

either by

var mesh = BABYLON.MeshBuilder.CreateMesh(name, {param1 : val1, param2: val2}, scene);

Then why use the options parameter if it does the same as the parameter list?

Because it doesn't do EXACTLY the same thing. Depending on the shape type, it allows making some (or all) parameters optional, and it can provide access to more available features on the created mesh. (What one might call 'advanced parameters'.)

Fixed Shapes

We call fixed shapes all the mesh types that are not parametric. This is to say... all the mesh types what have an expected final shape. For instance, if we create a Sphere or a Box mesh, we expect to get a spherical or a cubic shape, whereas if we create a Ribbon mesh, it depends upon a data set to be created (the pathArray). We can't predict its final shape.

All fixed shapes can be created by default... by using a blank options parameter :

var cylinder = BABYLON.MeshBuilder.CreateCylinder("cyl", {}, scene);

This means all the options properties are simply optional.

Box

Example :

var box = BABYLON.MeshBuilder.CreateBox("box", {height: 5, faceColors: myColors}, scene);

Properties, all optional :

property value default value
size (number) size of each box side 1
height (number) height size, overwrites size property size
width (number) width size, overwrites size property size
depth (number) depth size, overwrites size property 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

To understand how to set faceUV or faceColors, please read this : http://doc.babylonjs.com/tutorials/CreateBox_Per_Face_Textures_And_Colors

Sphere

Example :

var sphere = BABYLON.MeshBuilder.CreateSphere("sphere", {diameter: 2, diameterX: 3}, scene);

Properties, all optional :

property 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 property diameter
diameterY (number) diameter on Y axis, overwrites diameter property diameter
diameterZ (number) diameter on Z axis, overwrites diameter property 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

Cylinder or Cone

If you set diameterTop to zero, you get a cone instead of a cylinder. Example :

var cone = BABYLON.MeshBuilder.CreateCylinder("cone", {diameterTop: 0, tessellation: 4}, scene);

Properties, all optional :

property 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 property 1
diameterBottom (number) diameter of the bottom cap, can't be zero, overwrites the diameter property 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

To understand how to set faceUV or faceColors, please read this by considering 3 faces only : http://doc.babylonjs.com/tutorials/CreateBox_Per_Face_Textures_And_Colors

Plane

Example :

var plane = BABYLON.MeshBuilder.CreatePlane("plane", {width: 5}, scene);

Properties, all optional :

property 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

Ground

Example :

var ground = BABYLON.MeshBuilder.CreateGround("gd", {width: 6, subdivisions: 4}, scene);

Properties, all optional :

property 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

Ground From a Height Map

Example :

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

Don't forget the url parameter.

Properties, all optional :

property 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

Tiled Ground

Example :

var tiledGround = BABYLON.MeshBuilder.CreateTiledGround("tgd", {subdivisions: {w:4, h:6} }, scene);

Properties, all optional :

property 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

Disc

Remembe you can create any kind of regular plane polygon with CreateDisc() Example :

var disc = BABYLON.MeshBuilder.CreateDisc("disc", {tessellation: 3}, scene); // makes a triangle

Properties, all optional :

property 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

Torus

Example :

var torus = BABYLON.MeshBuilder.CreateTorus("torus", {thickness: 0.2}, scene);

Properties, all optional :

property 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

Torus Knot

Example :

var torus = BABYLON.MeshBuilder.CreateTorusKnot("tk", {}, scene);

Properties, all optional :

property 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

Polyhedron

Example :

var octahedron = BABYLON.MeshBuilder.CreatePolyhedron("oct", {type: 1, size: 3}, scene);

Properties, all optional :

property value default value
type (number) polyhedron type in the range [0,14] 0
size (number) polyhedron size 1
sizeX (number) X polyhedron size, overwrites the size property 1
sizeY (number) Y polyhedron size, overwrites the size property 1
sizeZ (number) Z polyhedron size, overwrites the size property 1
custom (polygonObjectReference) a polyhedron object, overwrites the type property null
faceColors (Color4[]) array of Color4, one per face Color4(1, 1, 1, 1) for each side
faceUV (Vector4[]) array of Vector4, one per face UVs(0, 0, 1, 1) for each side
flat (boolean) if false, a polyhedron has a single global face, faceUV and faceColors are ignored true
updatable (boolean) true if the mesh is updatable false
sideOrientation (number) side orientation DEFAULTSIDE

To understand how to set faceUV or faceColors, please read this by considering the right number of faces of your polyhedron, instead of only 6 for the box : http://doc.babylonjs.com/tutorials/CreateBox_Per_Face_Textures_And_Colors

Provided polyhedron types :
type name side number
0 Tetrahedron 4
1 Octahedron 8
2 Dodecahedron 12
3 Icosahedron 20
4 Rhombicuboctahedron 26
5 Triangular Prism 5
6 Pentagonal Prism 7
7 Hexagonal Prism 8
8 Square Pyramid (J1) 5
9 Pentagonal Pyramid (J2) 6
10 Triangular Dipyramid (J12) 6
11 Pentagonal Dipyramid (J13) 10
12 Elongated Square Dipyramid (J15) 12
13 Elongated Pentagonal Dipyramid (J16) 15
14 Elongated Pentagonal Cupola (J20) 22

If you need to use a custom polyhedron (http://www.babylonjs-playground.com/#21QRSK#1 -


: minimize the code editor with the button "EDITOR-" to see polyhedron names under the mouse pointer) instead of the provided ones, you will find the full sample file here : https://github.com/BabylonJS/Extensions/tree/master/Polyhedron Just copy/paste the wanted polyhedron object in your code like this :

var heptagonalPrism = { "name":"Heptagonal Prism", "category":["Prism"], "vertex":[[0,0,1.090071],[0.796065,0,0.7446715],[-0.1498633,0.7818315,0.7446715],[-0.7396399,-0.2943675,0.7446715],[0.6462017,0.7818315,0.3992718],[1.049102,-0.2943675,-0.03143449],[-0.8895032,0.487464,0.3992718],[-0.8658909,-0.6614378,-0.03143449],[0.8992386,0.487464,-0.3768342],[0.5685687,-0.6614378,-0.6538232],[-1.015754,0.1203937,-0.3768342],[-0.2836832,-0.8247995,-0.6538232],[0.4187054,0.1203937,-0.9992228],[-0.4335465,-0.042968,-0.9992228]],
"face":[[0,1,4,2],[0,2,6,3],[1,5,8,4],[3,6,10,7],[5,9,12,8],[7,10,13,11],[9,11,13,12],[0,3,7,11,9,5,1],[2,4,8,12,13,10,6]]};

var mesh = BABYLON.MeshBuilder.CreatePolyhdron("h", {custom: heptagonalPrism}, scene);

IcoSphere

This a sphere based upon an icosahedron with 20 triangular faces which can be subdivided.

var icosphere = BABYLON.MeshBuilder.CreateIcoSphere("ico", {radius: 5, radiusY: 8, subdivisions: 6}, scene);

Properties, all optional :

property value default value
radius (number) radius 1
radiusX (number) the X radius, overwrites the radius value radius
radiusY (Vector3) the Y radius, overwrites the radius value radius
radiusZ (number) the Z radius, overwrites the radius value radius
subdivisions (number) the number of subdivisions 4
flat (boolean) if true, the mesh faces have their own normals true
updatable (boolean) true if the mesh is updatable false
sideOrientation (number) side orientation DEFAULTSIDE

Decals

Example :

var decal = BABYLON.MeshBuilder.CreateDecal("decal", mesh,  {position: myPos}, scene);

Don't forget the mesh parameter which is the mesh depicting the decal.

Properties, all optional :

property value default value
position (Vector3) position of the decal (World coordinates) (0, 0, 0)
normal (Vector3) the normal of the mesh where the decal is applied onto (World coordinates) Vector3.Up
size (Vector3) the x, y, z sizes of the decal (1, 1, 1)
angle (number) the angle to rotate the decal 0



Parametric Shapes

Lines

You must set at least the points property. On update, you must set the points and instance properties.

Example :

var lines = BABYLON.MeshBuilder.CreateLines("lines", {points: myArray}, scene);
// creates an instance
lines = BABYLON.MeshBuilder.CreateLines("lines", {points: myArray, instance: lines});
// updates the existing instance of lines : no need for the parameter scene here

Properties :

property value default value
points (Vector3[]) array of Vector3, the path of the line REQUIRED
updatable (boolean) true if the mesh is updatable false
instance (LineMesh) an instance of a line mesh to be updated null

Dashed Lines

You must set at least the points property. On update, you must set the points and instance properties.

Example :

var dashedLines = BABYLON.MeshBuilder.CreateDashedLines("dl", {points: myArray}, scene);
// creates an instance
dashedLines = BABYLON.MeshBuilder.CreateDashedLines(null, {points: myArray, instance: dashedLines});
// updates the existing instance of dashedLines : no need for the parameter scene here

Properties :

property value default value
points (Vector3[]) array of Vector3, the path of the line REQUIRED
dashSize (number) size of the dashes 3
gapSize (number) size of the gaps 1
dashBn (number) intended number of dashes 200
updatable (boolean) true if the mesh is updatable false
instance (LineMesh) an instance of a line mesh to be updated null

LineSystem

You must set at least the lines property. On update, you must set the lines and instance properties.

Example :

var lineSystem = BABYLON.MeshBuilder.CreateLineSystem("lineSystem", {lines: myArray}, scene);
// creates an instance
lineSystem = BABYLON.MeshBuilder.CreateLineSystem(null, {lines: myArray, instance: lineSystem});
// updates the existing instance of lineSystem : no need for the parameter scene here

Properties :

property value default value
lines (Vector3[]) array of lines, each line being an array of successive Vector3 REQUIRED
updatable (boolean) true if the mesh is updatable false
instance (LineMesh) an instance of a line system mesh to be updated null

Ribbon

You must set at least the pathArray property. On update, you must set the pathArray and instance properties.

Example :

var ribbon = BABYLON.MeshBuilder.CreateRibbon("ribbon", {pathArray: myPaths}, scene);
// creates an instance
ribbon = BABYLON.MeshBuilder.CreateRibbon(null, {pathArray: myPaths, instance: ribbon});
// updates the existing instance of ribbon : no need for the parameter scene

Properties :

property value default value
pathArray (Vector3[][]) array of array of Vector3, the array of paths REQUIRED
closeArray (boolean) to force the ribbon to join its last and first paths false
closePath (boolean) to force each ribbon path to join its last and first points false
offset (number) used if the pathArray has one path only half the path length
updatable (boolean) true if the mesh is updatable false
sideOrientation (number) side orientation DEFAULTSIDE
instance (LineMesh) an instance of a ribbon to be updated null
invertUV (boolean) to swap the U and V coordinates at geometry construction time (texture rotation of 90°) false

Tube

You must set at least the path property. On update, you must set the path and instance properties and you can set the radius, radiusFunction or arc properties.

Example :

var tube = BABYLON.MeshBuilder.CreateTube("tube", {path: myPath}, scene);
// creates an instance
tube = BABYLON.MeshBuilder.CreateTube(null, {path: myPath, instance: tube});
// updates the existing instance of tube : no need for the parameter scene

Properties :

property value default value
path (Vector3[]) array of Vector3, the path of the tube REQUIRED
radius (number) the radius of the tube 1
tessellation (number) the number of radial segments 64
radiusFunction ( function(i, distance) ) a function returning a radius value from (i, distance) parameters null
cap (number) tube cap : NO_CAP, CAP_START, CAP_END, CAP_ALL NO_CAP
arc (number) ratio of the tube circumference between 0 and 1 1
updatable (boolean) true if the mesh is updatable false
sideOrientation (number) side orientation DEFAULTSIDE
instance (LineMesh) an instance of a tube to be updated null
invertUV (boolean) to swap the U and V coordinates at geometry construction time (texture rotation of 90°) false

Extruded Shapes

You must set at least the shape and path properties. On update, you must set the shape, path and instance properties and you can set the scale and rotation properties.

Example :

var extruded = BABYLON.MeshBuilder.ExtrudeShape("ext", {shape: myShape, path: myPath}, scene);
// creates an instance
extruded = BABYLON.MeshBuilder.ExtrudeShape(null, {shape: myShape, path: myPath, scale: newScale, rotation: newRotation, instance: extruded});
// updates the existing instance of extruded : no need for the parameter scene

Properties :

property value default value
shape (Vector3[]) array of Vector3, the shape you want to extrude REQUIRED
path (Vector3[]) array of Vector3, the extrusion axis REQUIRED
scale (number) the value to scale the shape 1
rotation (number) the value to rotate the shape each step along the path 0
cap (number) extrusion cap : NO_CAP, CAP_START, CAP_END, CAP_ALL NO_CAP
updatable (boolean) true if the mesh is updatable false
sideOrientation (number) side orientation DEFAULTSIDE
instance (LineMesh) an instance of an extruded shape to be updated null
invertUV (boolean) to swap the U and V coordinates at geometry construction time (texture rotation of 90°) false

Custom Extruded Shapes

You must set at least the shape and path properties. On update, you must set the shape, path and instance properties and you can set the rotationFunction or scaleFunction properties.

Example :

var extruded = BABYLON.MeshBuilder.ExtrudeShapeCustom("ext", {shape: myShape, path: myPath}, scene);
// creates an instance
extruded = BABYLON.MeshBuilder.ExtrudeShapeCustom(null, {shape: myShape, path: myPath, scaleFunction: myScaleF, rotationFunction: myRotF, instance: extruded});
// updates the existing instance of extruded : no need for the parameter scene

Properties :

property value default value
shape (Vector3[]) array of Vector3, the shape you want to extrude REQUIRED
path (Vector3[]) array of Vector3, the extrusion axis REQUIRED
scaleFunction ( function(i, distance) ) a function returning a scale value from (i, distance) parameters {return 1;}
rotationFunction ( function(i, distance) ) a function returning a rotation value from (i, distance) parameters {return 0;}
ribbonClosePath (boolean) the underlying ribbon closePath parameter value false
ribbonCloseArray (boolean) the underlying ribbon closeArray parameter value false
cap (number) extrusion cap : NO_CAP, CAP_START, CAP_END, CAP_ALL NO_CAP
updatable (boolean) true if the mesh is updatable false
sideOrientation (number) side orientation DEFAULTSIDE
instance (LineMesh) an instance of an extruded shape to be updated null
invertUV (boolean) to swap the U and V coordinates at geometry construction time (texture rotation of 90°) false

Lathe

You must set at least the shape property.

Example :

var lathe = BABYLON.MeshBuilder.CreateLathe("lathe", {shape: myShape}, scene);

Properties :

property value default value
shape (Vector3[]) array of Vector3, the shape you want to turn REQUIRED
radius (number) the value to radius of the lathe 1
tessellation (number) the number of iteration around the lathe 64
arc (number) ratio of the circumference between 0 and 1 1
cap (number) tube cap : NO_CAP, CAP_START, CAP_END, CAP_ALL NO_CAP
closed (boolean) to open/close the lathe circumference, should be set to false when used with arc true
updatable (boolean) true if the mesh is updatable false
sideOrientation (number) side orientation DEFAULTSIDE
invertUV (boolean) to swap the U and V coordinates at geometry construction time (texture rotation of 90°) false