
## How to Create a Mesh from Scratch

Each and every shape inBabylon.js is built from a mesh of triangles or facets as shown below:

![Custom Mesh](/img/features/scene/custom1.jpg)

Every facet is made up of three vertices each of which is assigned data that not only affects the position of the facet but also 
its colour, texture and how it is lit. The complex process of applying a shader to turn this data into a viewable mesh 
is all carried out byBabylon.js.

## Positions and Indices

Creating a mesh with two facets, one with vertices at `(-5, 2, -3), (-7, -2, -3), (-3, -2, -3)` and the other with vertices at `(5, 2, 3), (7, -2, 3), (3, -2, 3)`, requires each vertex to have a unique index. Indices should start at `0` and increase consecutively.

index | position
--- | ---
0 | (-5, 2, -3)
1 | (-7, -2, -3)
2 | (-3, -2, -3)
3 | (5, 2, 3)
4 | (7, -2, 3)
5 | (3, -2, 3)

Note that order does not matter when assigning indices.

The positions data is stored in an array of numbers. The vertex with index 0 is placed with `x` coordinate in `array[0]`, `y` at `array[1]` and `z` at `array[2]`. 
In general, the vertex with index `i` has `x` coordinate at `array[3i]`, `y` at `array[3i + 1]` and `z` at `array[3i +2]`.

Indices forming a facet are placed together in triples, as in the above example with `(0, 1, 2)` and `(3, 4, 5)`.
The indices data is also stored in an array of numbers with each triple being kept together.

In the above example the positions array is `[-5, 2, -3, -7, -2, -3, -3, -2, -3, 5, 2, 3, 7, -2, 3, 3, -2, 3]` and 
the indices array is `[0, 1, 2, 3, 4, 5]`.

```javascript
var customMesh = new BABYLON.Mesh("custom", scene);

var positions = [-5, 2, -3, -7, -2, -3, -3, -2, -3, 5, 2, 3, 7, -2, 3, 3, -2, 3];
var indices = [0, 1, 2, 3, 4, 5];
	
var vertexData = new BABYLON.VertexData();

vertexData.positions = positions;
vertexData.indices = indices;	

vertexData.applyToMesh(customMesh);
```

<Playground id="#VKBJN#2" title="Custom Mesh With Positions And Indices" description="Simple example of a custom mesh with positions and indices."/>

## Normals 

Usually a normal to a plane is a vector that is at right angles to a plane and for this example this is true. 
BabylonJS will calculate normals for a facet and for free standing facets not sharing any vertices with another facet 
the normals will be mathematical normals. For more on how normals affect lighting see [Normals](/features/featuresDeepDive/mesh/creation/custom/vertexNormals).

### Calculating

Normals are calculated on the vertexData object using the `ComputeNormal` method which takes arrays for positions, indices and normals as parameters.

Additions to code:

```javascript
var customMesh = new BABYLON.Mesh("custom", scene);
	
var positions = [-5, 2, -3, -7, -2, -3, -3, -2, -3, 5, 2, 3, 7, -2, 3, 3, -2, 3];
var indices = [0, 1, 2, 3, 4, 5];	
	
//Empty array to contain calculated values or normals added
var normals = [];

//Calculations of normals added
BABYLON.VertexData.ComputeNormals(positions, indices, normals);
	
var vertexData = new BABYLON.VertexData();

vertexData.positions = positions;
vertexData.indices = indices;
vertexData.normals = normals; //Assignment of normal to vertexData added

vertexData.applyToMesh(customMesh);
```

*Note:* To make your custom mesh updatable you need add a second parameter with value `true` when applying the mesh to the vertex data.

```javascript
vertexData.applyToMesh(customMesh, true);
```

give the array `normals = [ 0, 0, -1, 0, 0, -1, 0, 0, -1, 0, 0, 1, 0, 0, 1, 0, 0, 1]`.

Normals are stored in an array of numbers such that index `i` refers to the vector `(normals[3i], normals[3i + 1], normals[3i + 2])`
and so:

index | normal
---| ---
0 | (0, 0, -1)
1 | (0, 0, -1)
2 | (0, 0, -1)
3 | (0, 0, 1)
4 | (0, 0, 1)
5 | (0, 0, 1)


### Direction

Clearly the normals for each facet are pointing in opposite directions. They all point away from the origin. 

![Normal Direction](/img/how_to/Mesh/normals1.jpg)

Looking from the origin towards facet 3, 4, 5 then the order in the indices array 3, 4, 5 around the facet is clockwise.

Looking from the origin towards facet 0, 1, 2 then the order in the indices array 0, 1, 2 around the facet is also clockwise.

<Playground id="#VKBJN#6" title="Custom Mesh With Normals" description="Simple example of a custom mesh with normals."/>

Reversing the order of one or both sets of facet indices in the playground will show how the normals change direction.

### Lighting

The closest facet to the camera in now coloured white and the farthest from the camera is black. 
This is because the addition of the normals affects the use of light on the facet.

The light in the scene is travelling in the direction of the positive z axis. 

```javascript
var light = new BABYLON.DirectionalLight("direct", new BABYLON.Vector3(0, 0, 1), scene);
```

White light travelling in the opposite direction to that of the normal is reflected back and the facet is seen as white, while white light travelling in the same direction as the normal is absorbed and the facet is seen as black.

### Visibility

Removing the wireframe effect then:

1. Camera looking in positive z direction

![Positive Z Direction](/img/how_to/Mesh/normals3.jpg)

Black facet cannot be seen.

2. Camera looking in negative z direction

![Negative Z Direction](/img/how_to/Mesh/normals4.jpg)

White facet not seen.

Why is this? There are two faces to each facet; the face that the normal is pointing away from is the front face, the other is the backface. 
By defaultBabylon.js does not render the back face.

Due to this, many meshes that draw solids will not have a visible back face for its facet.

To draw the back face of a mesh turn `backFaceCulling` to `false` for the material being applied to the mesh.

```javascript
mat.backFaceCulling = false;
```

![Both Facets](/img/how_to/Mesh/normals5.jpg)

Comment line 41 out in the following to see back face culling happening.

<Playground id="#VKBJN#7" title="Custom Mesh With Both Facets" description="Simple example of a custom mesh with both facets."/>

## Color

The simplest way to assign a color to the custom mesh is by applying a standard material to the mesh and let Babylon.js do all the work. However 
color can be set for a facet within the vertex data. For information on how the arrangement of facets used in constructing a mesh can affect how colors are displayed see [Applying Materials to Facets](/features/featuresDeepDive/materials/using/texturePerBoxFace).

Colors for each vertex are placed in an array as groups of four in the order red, green, blue and alpha for transparency. For the facet 0, 1, 2 to be colored red and the facet 3, 4, 5 to be colored green, each vertex 
on each facet is given the same color.

index | color
--- | ---
0 | (1, 0, 0, 1)
1 | (1, 0, 0, 1)
2 | (1, 0, 0, 1)
3 | (0, 1, 0, 1)
4 | (0, 1, 0, 1)
5 | (0, 1, 0, 1)

and the array is `[1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 0, 0, 0, 1, 1, 0, 0, 1, 0, 1]`.

Adding to the code:

```javascript
var customMesh = new BABYLON.Mesh("custom", scene);
	
var positions = [-5, 2, -3, -7, -2, -3, -3, -2, -3, 5, 2, 3, 7, -2, 3, 3, -2, 3];
var indices = [0, 1, 2, 3, 4, 5];
var colors = [1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 0, 0, 0, 1, 1, 0,  0, 1, 0, 1]; //color array added
	
var normals = [];
	
var vertexData = new BABYLON.VertexData();
BABYLON.VertexData.ComputeNormals(positions, indices, normals);

vertexData.positions = positions;
vertexData.indices = indices;
vertexData.colors = colors; //Assignment of colors to vertexData
vertexData.normals = normals; //Assignment of normal to vertexData added

vertexData.applyToMesh(customMesh);
```
In the playground below see what happens when you make the vertices on the red facet different colors.

<Playground id="#VKBJN#8" title="Custom Mesh With Vertex Colors" description="Simple example of a custom mesh with vertex colors."/>

### Notes on the Playground

Since a material is no longer being used, `backFaceCulling` cannot be set and so the camera will have to be rotated for the far facet to be seen. The far facet will remain black despite whatever color is applied as all light is still being absorbed by this facet.

When the scene starts the camera is very nearly full face on to the facet and pointing in the direction the light is travelling. With the camera in this position most of the white light is reflected back into the camera as a highlight and the facet is seen as almost white.

As the camera is rotated around the facet will change from appearing as white to red as the highlight effect dissipates.

For a more controlled lighting effects use a [material](/features/featuresDeepDive/materials/using/materials_introduction) as well as, or instead of, setting vertex colors.

Adding a light with direction the reverse of the current one will light both sides.

<Playground id="#VKBJN#104" title="Custom Mesh With Both Sides Lit" description="Simple example of a custom mesh with both sides lit."/>

<Playground id="#VKBJN#105" title="Custom Mesh With Both Sides Color Variation" description="Simple example of a custom mesh with both sides color variation."/> 

## Texture

The simplest method is to just use [materials](/features/featuresDeepDive/materials/using/materials_introduction) and let Babylon.js apply the given image as a texture. 
However should you wish to have more control on how a texture is applied to a facet then you need to create and set the uv array.

Think of any image to be applied as a texture as having a pair of axes set at the bottom and left-hand side of the image; the u axis and the v axis respectively. 
(u, v as x and y are used for position axes). The origin being the left-hand bottom corner of the image, the top being at v = 1 and the right hand edge at u = 1 as 
in the diagram below.

![Image with uv axes](/img/how_to/Mesh/uv1.jpg)

For simplication the following only uses the facet 0, 1, 2.

Each vertex of the facet is assigned a uv coordinate pair from the image. 

![Image with uv triangle](/img/how_to/Mesh/uv2.jpg)

index | color
--- | ---
0 | (0, 1)
1 | (0, 0)
2 | (1, 0)

forming the uv array `[0, 1, 0, 0, 1, 0];`.

Using the following code:

```javascript
var customMesh = new BABYLON.Mesh("custom", scene);
	
var positions = [-5, 2, -3, -7, -2, -3, -3, -2, -3];
var indices = [0, 1, 2];
var uvs = [0, 1, 0, 0, 1, 0];
	
var normals = [];
BABYLON.VertexData.ComputeNormals(positions, indices, normals);

var vertexData = new BABYLON.VertexData();

vertexData.positions = positions;
vertexData.indices = indices;
vertexData.normals = normals;
vertexData.uvs = uvs;

vertexData.applyToMesh(customMesh);
```
results in:

![Result on Facet](/img/how_to/Mesh/uv3.jpg)

Note that the image is skewed since the shape of the triangular facet and that on the image do not match.

Adding in these lines at the appropiate points:

```javascript
var colors = [1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1];

var vertexData.colors = colors;
```

gives:

![Result on Facet with red color added](/img/how_to/Mesh/uv4.jpg)

In the playground below clicking on next will cycle you through a variety of values for the uv coordinates.

<Playground id="#VKBJN#14" title="Varying UV Values" description="Simple example of varying UV values." image="/img/playgroundsAndNMEs/pg-VKBJN-4.png"/>

*Notes about Playground above*: The camera has been disabled for the above playground. The uv values are shown and the relative index are shown on the texture image. 
One day this playground might improve. You will get some idea of how to achieve reflections and rotations of textures on a facet. However for a mesh the [arrangement of facets](/features/featuresDeepDive/mesh/facetData) must be considered when trying to achieve a particular texture mapping on the mesh.

### Calculating UVs

Calculating the uvs for a custom mesh obviously depends on the shape of the mesh and which parts of the texture you want projected onto the mesh at which position. Here is an example with a relatively simple mesh which is basically a flat surface with a couple of protudences.

<Playground id="#I092BE" title="Custom Mesh With UV Calculation" description="Simple example of a custom mesh with UV calculation."/>

The above playground takes the bottom left corner as matching the bottom left corner of the texture image and from the x, z position of each vertex calculates the uv value as the fractional distance of `(x, z)` from the bottom left corner.

In general, if the bottom left corner is at `(a, b)` and the bounding width and height of the mesh are w and h respectively then for each `(x, z)`:

`u = (x - a) / w and v = (z - b) / h`


## How To Update Vertices

## Vertex Data

The data contained in each of a mesh's vertices can be obtained from the vertex buffer. This data includes the position of and normal at the vertex 
as well as color and/or uv values. You can also obtain the indices for each vertex. 

```javascript
var positions = mesh.getVerticesData(BABYLON.VertexBuffer.PositionKind);
var normals = mesh.getVerticesData(BABYLON.VertexBuffer.NormalKind);
var colors = mesh.getVerticesData(BABYLON.VertexBuffer.ColorKind);
var uvs = mesh.getVerticesData(BABYLON.VertexBuffer.UVKind);

var indices = mesh.getIndices();
```
Each set of data is an array of numbers as detailed in [Creating Custom Meshes](/features/featuresDeepDive/mesh/creation/custom/custom). 

For example positions will be an array such as [-5, 2, -3, -7, -2, -3, -3, -2, -3, 5, 2, 3, 7, -2, 3, 3, -2, 3] and the  
indices array such as [0, 1, 2, 3, 4, 5] giving the following table.

index|position
-----|----
0| (-5, 2, -3)
1| (-7, -2, -3)
2| (-3, -2, -3)
3| (5, 2, 3)
4| (7, -2, 3)
5| (3, -2, 3)

## Updating the Data

Make sure that the mesh has been set as updatable on creation. Then this is just a matter of altering any of the data in the positions, normals, colors and uvs arrays to suit the project followed updating the vertex data 

```javascript
mesh.updateVerticesData(BABYLON.VertexBuffer.PositionKind, positions);
mesh.updateVerticesData(BABYLON.VertexBuffer.NormalKind, normals);
mesh.updateVerticesData(BABYLON.VertexBuffer.ColorKind, colors);
mesh.updateVerticesData(BABYLON.VertexBuffer.UVKind, uvs);
```

*Note: * When creating your own custom mesh to make it updatable you need to add a second parameter with value true when applying the mesh to  the vertex data.

When a mesh is created, the normal for each face is created smoothly to match the intended shape such as a sphere. To flatten the normals to make the mesh flatly shaded convertToFlatShadedMesh can be used.
```javascript
sphere.convertToFlatShadedMesh()
```
<Playground id="#H05E9H" title="Updating Vertex Data" description="Simple example of updating vertex data."/>

```javascript
vertexData.applyToMesh(customMesh, true);
```
## Adding to the Data

What happens if you want to add to vertexData after creating a mesh? For example many of the set and parametric meshes are created without the ColorKind array so it is not possible to use

```javascript
mesh.updateVerticesData(BABYLON.VertexBuffer.ColorKind, colors);
```

since _mesh.getVerticesData(BABYLON.VertexBuffer.ColorKind)_ will return _null_.

In this case after creating a color for each vertex in a color array use

```javascript
mesh.setVerticesData(BABYLON.VertexBuffer.ColorKind, colors);
```
 as an example 

 ```javascript
var colors = mesh.getVerticesData(BABYLON.VertexBuffer.ColorKind);
if(!colors) {
    colors = [];

    var positions = mesh.getVerticesData(BABYLON.VertexBuffer.PositionKind);

    for(var p = 0; p < positions.length / 3; p++) {
        colors.push(Math.random(), Math.random(), Math.random(), 1);
    }
}

mesh.setVerticesData(BABYLON.VertexBuffer.ColorKind, colors);
 ```

## Examples

Scaling Positions: <Playground id="#VE6GP#4" title="Scaling Positions" description="Simple example of updating vertex data with scaled positions."/>
Playing Around with Positions: <Playground id="#VE6GP#2" title="Playing With Positions" description="Simple example of updating vertex data and playing with positions."/>
Adding Color to Vertices: <Playground id="#ZRZIIZ#2" title="Adding Colors To Vertices" description="Simple example of adding colors to vertices."/>


## Vertex Normals

Each triangular facet of a mesh comprises three vertices. Besides a position each vertex has another important vector3 called a normal. These vertex normals are used by the [shader code](/features/featuresDeepDive/materials/shaders/introToShaders) in calculating how the mesh is lit. Unlike a mathematical normal there is no necessity for them to be set at right angles and for curved shapes such as a sphere they may not be. In the case of a sphere they are set as the mathematical normal of the sphere surface rather than that of the flat facets of the mesh that create the sphere.

At first the vertex normals are calculated as the mathematical normals for the facet. It then depends whether you want to view the facets as flat surfaces or as part of curve. For flat surfaces the vertex normals remain as the mathematical normals. To enhance the curve when viewed under light where triangular facets share vertices with the same positions each shared vertex normal is recalculated to be the average of the mathematical normals of the shared vertex normals.

These effects are explored below.

In the following two playgrounds see how the changing directions within the normals array affect how it is lit:

<Playground id="#VKBJN#18" title="Vertex Normals Varying In Unison" description="Simple example of vertex normals varying in unison."/>

<Playground id="#VKBJN#19" title="Showing Normals Varying" description="Simple example of showing vertex normal variation."/>

##Normals and Minimum Vertices

![Wireframe](/img/how_to/Mesh/box1.jpg)

The box above has 8 vertices. If we want to keep the indices to the minimum they will be 0, 1, 2, 3, 4, 5, 6, 7.

Facets 0, 3, 7 and 3, 7, 6 and 0, 3, 2 all have vertex 3 in common and vertex 3 can only have one
entry in the normals array associated with it.

How doesBabylon.js calculate the `normal` for vertex 3?

The diagram below shows that the average of the three mathematical normals at each vertex is used:

![Normals](/img/how_to/Mesh/box4.jpg)

Besides minimising the number of vertices needed there are other advantages as will be seen when creating a sphere.

Keeping the indices to a minimum the normals at each corner are an average of the mathematical normals of the three faces that meet at that corner. So 8 corners and 8 unique vertex normals.

## Table of Unique Indices, Positions and Normals for Box with Minimum Vertices

| index | position         | normal                                                              |
| ----- | ---------------- | ------------------------------------------------------------------- |
| 0     | ( -1 , 1 , -1 )  | ( -0.5773502691896258 , 0.5773502691896258 , -0.5773502691896258 )  |
| 1     | ( 1 , 1 , -1 )   | ( 0.8164965809277261 , 0.4082482904638631 , -0.4082482904638631 )   |
| 2     | ( 1 , -1 , -1 )  | ( 0.4082482904638631 , -0.4082482904638631 , -0.8164965809277261 )  |
| 3     | ( -1 , -1 , -1 ) | ( -0.4082482904638631 , -0.8164965809277261 , -0.4082482904638631 ) |
| 4     | ( -1 , 1 , 1 )   | ( -0.4082482904638631 , 0.4082482904638631 , 0.8164965809277261 )   |
| 5     | ( 1 , 1 , 1 )    | ( 0.4082482904638631 , 0.8164965809277261 , 0.4082482904638631 )    |
| 6     | ( 1 , -1 , 1 )   | ( 0.5773502691896258 , -0.5773502691896258 , 0.5773502691896258 )   |
| 7     | ( -1 , -1 , 1 )  | ( -0.8164965809277261 , -0.4082482904638631 , 0.4082482904638631 )  |

## Normals and Flat Shaded Meshes.

There are times, such as needing each face of a box to be covered in a [different material](/features/featuresDeepDive/mesh/facetData),
when it is better to have the box constructed from separate faces each of which are constructed by two facets and no two faces
sharing a vertex indices. They will of course share vertex positions.

![Seperate Faces](/img/how_to/Mesh/box3.jpg)

InBabylon.js this can be achieved using the `convertToFlatShadedMesh` function. The results are shown below:

![Flat Shaded Normals](/img/how_to/Mesh/box5.jpg)

For a flat shaded mesh each of the triangular facets making a face of the box has mathematical normals as their vertex normals. For simplicity of illustration we will only consider the the six faces making up the box than the full range of triangular facets used in the mesh construction. Each face has 4 corners, each corner has a unique normal at right angles to the face. There are 6 faces on a box and so 24 unique corner normals.

## Table of Faces, Corners, Positions and Normals for Flat Shaded Box

| Face  | corner | position         | normal           |
| ----- | ------ | ---------------- | ---------------- |
| Front | 0      | ( -1 , 1 , -1 )  | ( 0 , 0 , -1 )   |
| Front | 1      | ( 1 , -1 , -1 )  | ( 0 , 0 , -1 )   |
| Front | 2      | ( 1 , 1 , -1 )   | ( 0 , 0 , -1 )   |
| Front | 3      | ( -1 , 1 , -1 )  | ( 0 , 0 , -1 )   |
| Back  | 4      | ( -1 , 1 , 1 )   | ( 0 , 0 , 1 )    |
| Back  | 5      | ( 1 , -1 , 1 )   | ( 0 , 0 , 1 )    |
| Back  | 6      | ( -1 , -1 , 1 )  | ( 0 , 0 , 1 )    |
| Back  | 7      | ( -1 , 1 , 1 )   | ( 0 , 0 , 1 )    |
| Right | 8      | ( 1 , 1 , -1 )   | ( 1 , -0 , 0 )   |
| Right | 9      | ( 1 , -1 , 1 )   | ( 1 , -0 , 0 )   |
| Right | 10     | ( 1 , 1 , 1 )    | ( 1 , -0 , 0 )   |
| Right | 11     | ( 1 , 1 , -1 )   | ( 1 , 0 , 0 )    |
| Left  | 12     | ( -1 , 1 , -1 )  | ( -1 , 0 , 0 )   |
| Left  | 13     | ( -1 , -1 , 1 )  | ( -1 , 0 , 0 )   |
| Left  | 14     | ( -1 , -1 , -1 ) | ( -1 , 0 , 0 )   |
| Left  | 15     | ( -1 , 1 , -1 )  | ( -1 , -0 , -0 ) |
| Top   | 16     | ( -1 , 1 , -1 )  | ( 0 , 1 , 0 )    |
| Top   | 17     | ( 1 , 1 , 1 )    | ( 0 , 1 , 0 )    |
| Top   | 18     | ( -1 , 1 , 1 )   | ( 0 , 1 , 0 )    |
| Top   | 19     | ( 1 , 1 , -1 )   | ( 0 , 1 , -0 )   |
| Base  | 20     | ( -1 , -1 , -1 ) | ( 0 , -1 , -0 )  |
| Base  | 21     | ( 1 , -1 , 1 )   | ( 0 , -1 , -0 )  |
| Base  | 22     | ( 1 , -1 , -1 )  | ( 0 , -1 , -0 )  |
| Base  | 23     | ( -1 , -1 , 1 )  | ( 0 , -1 , 0 )   |

## Playground Showing Box Normals

<Playground id="#1H7L5C#37" title="Box Normals" description="Simple example of box normals."/>

## Advantage of Shared Normals

Sharing normals means that the shader produces a rounder looking sphere since the vertex normals are the mathematical normals of the sphere surface.

Applying the function `converToFlatShadedMesh` shows the individual faces making up the sphere. For a flat shaded sphere the normals of each facet are the mathematical normals of the facet.

<Playground id="#1H7L5C#38" title="Comparing Shading of Spheres" description="Simple example comparing shading of spheres."/>



## Custom Meshes

Of course there will be times that the created meshes already available in Babylon.js do not serve your needs. In this case you can develop your own meshes from vertex data. Vertex data requires a list of vertices and indices to show how the vertices are formed into triangular facets to build the mesh. For lighting, material and texture you will need to provide vertex normals, colors and uv values. When the existing meshes partially meet your needs you can obtain their vertex data and update it, provided you create the mesh with the update option set to true in the first place.


## Goldberg Polyhedron

Within Babylon.js a Goldberg polyhedron (GBP) is formed as a dual of an icosahedron based geodesic polyhedron and its vertices mapped onto a sphere. The two parameters m and n used in forming the geodesic base also determine the arrangement of faces for the GBP.

![Dual](/img/snippets/geo31.png)  
Fig 1 - The red grid is the dual of the blue grid and vice-versa.

On this page we explain how to create a GBP directly. More information about [GBP Mathematics](/guidedLearning/workshop/Geodesic_Math) and the [first development stage of coding a GBP](/guidedLearning/workshop/Geodesic_Code) are available in the documentation workshop.

A GBP can only be created using `MeshBuilder`

A GBP consists of 12 pentagonal faces and a number of hexagonal faces determined by m and n. The option parameter when creating a GBP has different properties than those for `CreateGeodesic` or for `CreatePolyhedron`. However additional properties and methods, to those of a standard mesh, are available for a Goldberg mesh. These allow individual, or groups of pentagonal and hexagonal faces to be colored, textured or built upon giving a hexagon-grid planet shaped world.

The world consists of 12 poles, the pentagonal faces plus a number of hexagonal faces. Around each of the poles there is a group of hexagonal faces that are closer to one pole than the others. These are the unshared faces of the world. Depending on the value of the second parameter, **n**, there may be zero or more faces that are equidistant from two or even three poles. These are the shared faces.

![Faces](/img/snippets/geo32.png)  
Fig 2 - Poles are black, unshared faces are colored and shared faces are white.

The faces are stored in the following order

- the poles 0 to 11
- the unshared faces for pole 0, then for pole 1, pole 2 etc
- the shared faces come at the end

## MeshBuilder

usage :

```javascript
const goldbergPoly = BABYLON.MeshBuilder.CreateGoldberg("goldberg", options, scene); //scene is optional and defaults to the current scene
```

| option          | value                                                             | default value |
| --------------- | ----------------------------------------------------------------- | ------------- |
| m               | _(number)_ an integer > 0                                         | 1             |
| n               | _(number)_ a positive or zero integer &lt;= m                     | 0             |
| size            | _(number)_ polyhedron size                                        | 1             |
| sizeX           | _(number)_ X axis polyhedron size, overwrites the _size_ property | 1             |
| sizeY           | _(number)_ Y axis polyhedron size, overwrites the _size_ property | 1             |
| sizeZ           | _(number)_ Z axis polyhedron size, overwrites the _size_ property | 1             |
| updatable       | _(boolean)_ true if the mesh is updatable                         | false         |
| sideOrientation | _(number)_ side orientation                                       | DEFAULTSIDE   |

## Additional Properties and Methods

### Properties

Over and above the features of a standard mesh there are a number of read only features stored in the property `goldbergData` object.

Access to each follows the following example patterns

```javascript
const goldbergPoly = BABYLON.MeshBuilder.CreateGoldberg("goldberg", options);
const nbFaces = goldbergPoly.goldbergData.nbFaces;
const centerOfFace32 = goldbergPoly.goldbergData.faceCenters[32];
```

The following are all the properties of `goldbergData`

| Property        | Value                                                                |
| --------------- | -------------------------------------------------------------------- |
| nbFaces         | _(number)_ Total number of faces in the GBP                          |
| nbFacesAtPole   | _(number)_ The pole plus the closest hexagons                        |
| nbUnsharedFaces | _(number)_ Total number of hexagonal faces closest to the poles      |
| nbSharedFaces   | _(number)_ Total number of faces equidistant to two poles            |
| adjacentFaces   | _(number[][])_ Array of the faces adjacent to a particular face      |
| faceCenters     | _(Vector3[])_ Array of centers of each face                          |
| faceYaxis       | _(Vector3[])_ Array of normals of each face                          |
| faceXaxis       | _(Vector3[])_ Array of vectors perpendicular to normal for each face |
| faceZaxis       | _(Vector3[])_ Array of vectors perpendicular to normal for each face |

The vector properties faceCenters[face], and faceXaxis[face], faceYaxis[face] and faceZaxis[face] can be used as a frame of reference to place meshes on the given face.

### Methods

#### Colors

Groups of faces can be colored using

```javascript
goldbergPoly.setGoldbergFaceColors(colorArray); //resets face colors whether the mesh is updatable or not
//or
goldbergPoly.updateGoldbergFaceColors(colorArray); //resets face colors only when the mesh is updatable
```

where `colorArray` is an array of elements of the form [start face, end face, Color4]

For example

```javascript
const colorArray = [
  [18, 18, new BABYLON.Color4(1, 0, 0, 1)], // color face 18 red
  [26, 37, new BABYLON.Color4(0, 1, 0, 1)], //color faces 26 to 37 inclusive green
];
```

PG: <Playground id="#A8VZGP#34" title="Color Faces" description="Coloring individual faces"/>

PG: <Playground id="#A8VZGP#106" title="Pick and Color" description="Pick a face and color red"/>

PG: <Playground id="#A8VZGP#36" title="Adjacent Faces" description="Faces immediately adjacent"/>

PG: <Playground id="#A8VZGP#37" title="Random Adjacent Faces" description="Moving from face to adjacent face"/>

#### Textures

Groups of faces can have their texture changed by using

```javascript
goldbergPoly.setGoldbergFaceUVs(uvArray); //resets face UVs whether the mesh is updatable or not
//or
goldbergPoly.updateGoldbergFaceUVs(uvArray); //resets face UVs only when the mesh is updatable
```

where `uvArray` is an array of elements of the form [start face, end face, center, radius, angle]

center is a Vector2 with 0 &le; x, &le; 1 and 0 &le; y &le; 1 giving the relative center of a pentagon/hexagon, within a image, of given radius and set at the given angle. The image used should be square to prevent distortion of the texture.

For example

```javascript
const uvArray = [
  [18, 18, new BABYLON.Vector2(0.25, 0.75), 0.25, 0], // updates the uvs for face 18 to match the vertices of the green hexagon in Fig 3
  [26, 37, new BABYLON.Vector2(0.625, 0.37), 0.37, Math.PI / 2], //updates the uvs for faces 26 to 37 to match the vertices of the red hexagon in Fig 3
];
```

For the poles pentagons are used to match the uvs.

![Face Texture](/img/snippets/geo33.png)  
Fig 3 - Areas of Image to Use as Face Textures

![Texture map](https://assets.babylonjs.com/environments/hexworld.jpg)  
Fig 4 - Texture Map to Apply to Different Faces

In the following playground different areas of the texture map from Fig 4 are applied to the 12 polar regions and to the shared faces

PG: <Playground id="#A8VZGP#38" title="Different Textures" description="The poles and their close neighbours share textures"/>

![Texture](https://assets.babylonjs.com/environments/redarrow.jpg)
Fig 5 - Same Texture for the Hexagonal Faces
In the following playground the same area is applied to all the hexagonal faces and a blank area to the poles.

PG: <Playground id="#A8VZGP#39" title="Angling Textures" description="Changing the angle of a texture area"/>

#### Placing Meshes

A mesh can be placed on a face using

```javascript
goldbergPoly.placeOnGoldbergFaceAt(mesh, face, position); //position is a Vector3
```

The position is relative to the center of the face and the axes, faceXaxis, faceYaxis and faceZaxis

For example
placing a box mesh on face 32

```javascript
const height = 2;
const width = 0.1;
const depth = 0.08;
const box = BABYLON.MeshBuilder.CreateBox("box", { width: width, depth: depth, height: height });
const position = new BABYLON.Vector3(0.53, height / 2, 0.34);
goldbergPoly.placeOnGoldbergFaceAt(box, 32, position);
```

Meshes should be sized accoring to the size of the face. To keep a mesh within a face values for position.x and position.z should be between around &PlusMinus;radius of face \* &radic;3

PG: <Playground id="#A8VZGP#40" title="Placing Meshes" description="Land masses with buildings"/>

### Faces Related to a Pole

Since the faces are stored in the following order, the poles 0 to 11, the unshared faces closest to pole 0, then to pole 1, pole 2 etc and finally the shared faces, those equidistant from two or more poles, this can be used to find face numbers related to a particular pole.

For pole 0 &le; k &lt 12 you can determine the face number for the unshared faces closest to pole k using

```javascript
const faceNumb = goldbergPoly.relatedGoldBergFace(k, s); // 0 <= s < nbFacesAtPole
```

The unshared faces related to a pole are numbered in an anti-clockwise spiral around the pole.

For the shared faces you use

```javascript
const faceNumb = goldbergPoly.relatedGoldBergFace(n); //0 <= n < nbSharedFaces
```

missing out the second parameter. For n = 0 the face number returned is that of the first shared face, n = 1 that of the second shared face and so on.

## Importing An Exported Goldberg Mesh

Although a Goldberg mesh is a very specialized mesh Babylon.js supports the export and import of a Goldberg mesh using standard export and import methods.

## Example

A Goldberg mesh is exported to file.babylon.

```javascript
BABYLON.SceneLoader.ImportMeshAsync("", "PATH TO FOLDER", "file.babylon").then((result) => {
  const goldbergPoly = result.meshes[0];
});
```

PG: <Playground id="#A8VZGP#43" title="Import as a Goldberg Mesh" description="Additional properties and methods can also be applied"/>


Create Custom Meshes

Custom Meshes

Coming next

Create Custom Meshes From Scratch

Learn how to create custom meshes in Babylon.js.

Updating Vertices

Learn how to update vertices of a mesh in Babylon.js.

Vertex Normals

Learn all about vertex normals in Babylon.js.