A Range of Meshes


In the 3D virtual world shapes are built from meshes, lots of trangular facets joined together, each facet made from three vertices.

A mesh

Babylon.js provides for the creation of predefined meshes and of custom meshes. For all meshes the underlying data structure is exposed and can be updated.

Specialist meshes such as sprites, 2D particles and 3D solid particles are also available.


There are two types of predefined meshes, set shapes and parametric shapes. Set shapes usually already have names in everyday use and their forms are well known and recognized. 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 known but also included in set shapes are a torus, a torus knot and the polyhedra. Parametric shapes have no everyday names but are formed through data sets and parameters and most often their shape is unpredictable. These include lines, a system of lines, ribbons, tubes, extrusions, lathed shapes and irregular polygons.

Mention has already been made of the horizonal plane called the ground which is your common flat everyday surface like a floor. You will be pleased to know that it comes in other varieties to provide an outside terrain with rolling hills and valleys. For a view from a distance terrain you use GroundFromAHeightMap. If you literally want rolling hills add the extension dynamic terrain which gives you an infinite landscape to fly over.

Ways of Creating a Predefined Mesh

Since Babylon.js version 2.3 there are two techniques to use to create a predefined mesh. Using the newest technique a mesh is created using the MeshBuilder method where meshes are created with the following format and <Mesh> is replaced with the required type of mesh.

var mesh = BABYLON.MeshBuilder.Create<Mesh>(name, {param1 : val1, param2: val2}, scene);

The older or legacy method which has the form

var mesh = BABYLON.Mesh.Create<Mesh>(name, param1, param2, ..., scene, optional_parameter1, ........);

and is still available and will often be seen in Playground examples.

The MeshBuilder method has the advantages of making all (or some) of the parameters optional depending on the mesh and provides more features than the legacy method. Using default values for the shapes the only parameters need for mesh creation is a name, which can be blank and an empty object.

For example to create a box which is an unit cube all that is needed is

var box = BABYLON.MeshBuilder.CreateBox("", {});

However, You will find most people will still write

var box = BABYLON.MeshBuilder.CreateBox("", {}, scene);

since the ability to drop the scene parameter is fairly recent, not well know, old habits die hard and if you transfer your code to a project with more than one scene then missing it out can cause confusion. But if you are working with just one scene, and most people are, and you are happy to do so you can leave it out.

With the legacy method the scene parameter must be present, you can only create a box that is a cube and if you wanted a cuboid you needed to apply scaling, which is some circumastance could prove tricky. However it can be fairly quick to type.

For example if you want an updatable cuboid with different dimensions in all directions that is doublesided so you can view it from the inside and outside then using MeshBuilder requires

var box = BABYLON.MeshBuilder.CreateBox("", {height: 6, width: 4, depth: 2, updatable: true, sideOrientation: BABYLON.Mesh.DOUBLESIDE});

whereas the legacy method needs

var box = BABYLON.Mesh.CreateBox("box", 1, scene, true, BABYLON.Mesh.DOUBLESIDE);
box.scaling = new BABYLON.Vector3(4, 6, 2);

and the scene prameter is necessary to position the updatable and sideOrientation parameters correctly.

Also using MeshBuilder you can apply different colors and images to individual faces of meshes that have distinct faces (for example a box does but a sphere does not). This is not possible with the legacy method.

For a second example consider the creation of a truncated cone with a diameter of 3 top and and 6 at the bottom, with height 5 constructed using 16 radial sections and 10 vertical subdivisions.


var options = {
    diameterBottom: 6, 
    height: 5, 
    tessellation: 16, 
    subdivisions: 10
var cylinder = BABYLON.MeshBuilder.CreateCylinder("myCylinder", options);


var cylinder = BABYLON.Mesh.CreateCylinder("myCylinder", 5, 3, 6, 16, 10, scene);

Creating a Custom Mesh

To create your own custom mesh requires you to know the internal data structure of a mesh and how to transfer details of your shape to this structure by setting the positions and normals of the vertices making up each triangular facet. With a little mathematics knowledge this is quite straight forward should you wish to do it.

Want to know more about the facets that make up a mesh then enabling FacetData is just for you. You can obtain a facets position and its mathematical normal for example.

Further Reading will show you how to do all of these.

Other Mesh Features

Copying a Mesh

The following features reduce the number of draw calls. When you want a number of meshes that share the same geometry and material, you can create one mesh and then obtain many instances of that mesh and re-position each and rotate each seperately. When you want many meshes with the same geometry but having different materials then Babylon.js provides you with the facility to clone a mesh.

Another way available to you, especially if you want a very large number of identical meshes is to use particles. You have the option of using 2D meshes or sprites or f or very many identical 3D meshes that can be positioned and rotated individually and are fast then the solid particle system (SPS) is for you.

Collide with a Camera, another Mesh, a Ray or Pointer

When you are moving around a scene in a first person shooter manner then you want to be able to react if an object is blocking the way. You can as Camera Collision is a provided facility. As is the Intersection of Meshes, Raycasting and Pointer Clicked on Mesh

Accessing Mesh Data, Morphing or Updating

The facility to read data on the facets making up a mesh and also the vertices making up each facet of the mesh is available for all meshes. This data can be over written to update an existing mesh, provided the mesh was created as updatable (the mesh's updatable parameter is set to true) in the first place and no change is made in the number of vertices. For more information see Updating Vertices.

Some parametric shapes have an instance parameter in its MeshBuilder options and can be updated by setting the instance option the initially created parametric shape. Currently all the parametric shapes, except for the Lathe and Polygon (both Create and Extend), can have their mesh updated in this way.

From Babylon.js version 3.0 morphing, or distoring a mesh through a number of transitions, is possible by creating a copy of the mesh, the target, updating the target and then adjusting the influence of the target mesh from 0 to 1.

Further Reading

Basic - L1

Meshes 101
Parametric Shapes 101
Sprites 101
Particles 101
Mesh Collisions 101
Mesh Picking 101
Ray Casting 101
Using Decals
How to Use the Solid Particle System
Set the Position, Rotation and Scale of a Mesh

Mid Level - L2

Using PolygonMeshBuilder
Ribbon Tutorial
Highlight Layer

More Advanced - L3

How to use Instances
How to Merge Meshes
Mathematics and Ribbons
How to use Curve3
How to use Path3D
How to use Facet Data
How to use LOD
How to Dynamically Morph a Mesh
How to use Morph Targets
How to use Bones and Skeletons
How to use EdgesRenderer
Creating Custom Meshes
Facet Normals
Updating Vertices