
![Toon material](/img/extensions/materials/toon.webp)

# Using the cell material

Cell material can be found here: [https://cdn.babylonjs.com/materialsLibrary/babylon.cellMaterial.js](https://cdn.babylonjs.com/materialsLibrary/babylon.cellMaterial.js)

<Alert severity="warning" title="Warning" description="The CDN should not be used in production environments. The purpose of our CDN is to serve Babylon packages to users learning how to use the platform or running small experiments. Once you've built an application and are ready to share it with the world at large, you should serve all packages from your own CDN."/>

A demo can be found here: PG: <Playground id="#36VUUE" title="Cell Material" description="Example of cell material"/>

# Creating and customizing the cell material

You can customize some of the material's special properties:

```javascript
// Create a new cell material
var cell = new BABYLON.CellMaterial("cell", scene);

// Set up the diffuse texture
cell.diffuseTexture = new BABYLON.Texture("textures/amiga.jpg", scene);

// Set up diffuse color
cell.diffuseColor = new BABYLON.Color3(1, 0.5, 0);

// Set the material to be high level (default value is true)
// The high level can compute until 5 different lighting levels
// If false, only two levels are available
cell.computeHighLevel = true;
```



## Custom materials

Custom materials let you keep Babylon.js material features while injecting small pieces of GLSL into specific parts of the generated shader.

- `CustomMaterial` extends `StandardMaterial`.
- `PBRCustomMaterial` extends `PBRMaterial`.

Use them when you want to add a focused shader effect without rewriting a full `ShaderMaterial`. For larger reusable material extensions, a material plugin is usually easier to maintain, but custom materials are useful for quick shader customization and prototyping.

## Playground examples

This example uses `CustomMaterial` to add uniforms, displace vertices, change the diffuse color, and adjust the final fragment color:

PG: <Playground id="#QF2QWZ#0" title="CustomMaterial shader injection" description="CustomMaterial example with uniforms, vertex displacement, diffuse color injection, and final color adjustment."/>

This example uses `PBRCustomMaterial` to keep PBR lighting, metallic and roughness behavior while changing the albedo and final fragment color:

PG: <Playground id="#W0OF0A#0" title="PBRCustomMaterial albedo injection" description="PBRCustomMaterial example that keeps PBR lighting while customizing albedo and final fragment color."/>

## Using custom materials

Custom materials are part of the materials library, so they are not included in the main _babylon.js_ file.

For a script reference, include the materials library after Babylon.js:

```html
<script src="https://cdn.babylonjs.com/babylon.js"></script>
<script src="https://cdn.babylonjs.com/materialsLibrary/babylonjs.materials.min.js"></script>
```

<Alert severity="warning" title="Warning" description="The CDN should not be used in production environments. The purpose of our CDN is to serve Babylon packages to users learning how to use the platform or running small experiments. Once you've built an application and are ready to share it with the world at large, you should serve all packages from your own CDN."/>

For ES modules, import the classes from `@babylonjs/materials`:

```javascript
import { CustomMaterial } from "@babylonjs/materials/custom/customMaterial";
import { PBRCustomMaterial } from "@babylonjs/materials/custom/pbrCustomMaterial";
```

## CustomMaterial

`CustomMaterial` starts from `StandardMaterial`. The material keeps standard material properties such as diffuse color, specular color, textures, alpha, lights, fog, and shadows, then applies your injected shader code at the hook points you choose.

```javascript
var material = new BABYLON.CustomMaterial("custom", scene);
material.diffuseColor = BABYLON.Color3.White();
material.AddUniform("stripeScale", "float", 8.0);
material.AddUniform("warmColor", "vec3", new BABYLON.Color3(1.0, 0.5, 0.08));
material.AddUniform("coolColor", "vec3", new BABYLON.Color3(0.03, 0.2, 0.75));

material.Fragment_Definitions(`
    float bandedGradient(float value, float scale) {
        return smoothstep(0.25, 0.75, 0.5 + 0.5 * sin(value * scale));
    }
`);

material.Fragment_Custom_Diffuse(`
    float bands = bandedGradient(vPositionW.y, stripeScale);
    result = mix(coolColor, warmColor, bands);
`);
```

`Fragment_Custom_Diffuse` runs after the standard material has computed its diffuse color. In that hook, `result` is a helper alias for the material's internal `diffuseColor` variable.

## PBRCustomMaterial

`PBRCustomMaterial` starts from `PBRMaterial`. It keeps PBR features such as metallic, roughness, image-based lighting, reflection, and environment response, then lets you inject shader code into the PBR shader.

```javascript
var material = new BABYLON.PBRCustomMaterial("custom-pbr", scene);
material.albedoColor = new BABYLON.Color3(0.9, 0.78, 0.55);
material.metallic = 0.85;
material.roughness = 0.28;
material.AddUniform("stripeScale", "float", 6.0);
material.AddUniform("accentColor", "vec3", new BABYLON.Color3(0.03, 0.55, 1.0));

material.Fragment_Custom_Albedo(`
    float stripe = smoothstep(0.35, 0.75, 0.5 + 0.5 * sin(vPositionW.y * stripeScale));
    result = mix(surfaceAlbedo, accentColor, stripe * 0.65);
`);

material.Fragment_Before_FragColor(`
    finalColor.rgb = mix(finalColor.rgb, vec3(0.05, 0.12, 0.22), 0.12);
`);
```

`Fragment_Custom_Albedo` runs after the PBR material has computed its surface albedo. In that hook, `result` is a helper alias for `surfaceAlbedo`.

## Adding uniforms

Use `AddUniform(name, kind, value)` when your shader code needs a custom uniform:

```javascript
material.AddUniform("tint", "vec3", new BABYLON.Color3(0.2, 0.8, 1.0));
material.AddUniform("scale", "float", 4.0);
material.AddUniform("maskTexture", "sampler2D", new BABYLON.Texture("textures/mask.png", scene));
```

The `kind` string is the GLSL type that will be declared in the shader, such as `float`, `vec2`, `vec3`, `vec4`, `mat4`, or `sampler2D`.

## Shader hook points

These hooks are available on both `CustomMaterial` and `PBRCustomMaterial`:

| Method | Where the code is injected |
| --- | --- |
| `Fragment_Begin(shaderPart)` | At the beginning of the fragment shader main function. |
| `Fragment_Definitions(shaderPart)` | Before the fragment shader main function. Use this for helper functions and varying declarations. |
| `Fragment_MainBegin(shaderPart)` | Near the start of the fragment shader main function. |
| `Fragment_Custom_Alpha(shaderPart)` | Where the shader updates alpha. In this hook, `result` maps to `alpha`. |
| `Fragment_Before_FragColor(shaderPart)` | Just before the final fragment color is written. |
| `Vertex_Begin(shaderPart)` | At the beginning of the vertex shader main function. |
| `Vertex_Definitions(shaderPart)` | Before the vertex shader main function. Use this for helper functions and varying declarations. |
| `Vertex_MainBegin(shaderPart)` | Near the start of the vertex shader main function. |
| `Vertex_Before_PositionUpdated(shaderPart)` | After `positionUpdated` is available and before the final position update. In this hook, `result` maps to `positionUpdated`. |
| `Vertex_Before_NormalUpdated(shaderPart)` | After `normalUpdated` is available and before the final normal update. In this hook, `result` maps to `normalUpdated`. |

`CustomMaterial` also supports:

| Method | Where the code is injected |
| --- | --- |
| `Fragment_Custom_Diffuse(shaderPart)` | After the standard material diffuse color is computed. In this hook, `result` maps to `diffuseColor`. |

`PBRCustomMaterial` also supports:

| Method | Where the code is injected |
| --- | --- |
| `Fragment_Custom_Albedo(shaderPart)` | After the PBR surface albedo is computed. In this hook, `result` maps to `surfaceAlbedo`. |
| `Fragment_Custom_MetallicRoughness(shaderPart)` | During metallic and roughness computation. |
| `Fragment_Custom_MicroSurface(shaderPart)` | During microsurface computation. |
| `Fragment_Before_FinalColorComposition(shaderPart)` | Before final color composition. |

## Notes

The injected shader code is GLSL, including when the scene runs in WebGPU mode.

If you define a varying to pass data from vertex shader code to fragment shader code, declare it in both `Vertex_Definitions` and `Fragment_Definitions`.

Use `AddUniform` for uniforms instead of declaring `uniform` values manually in `Fragment_Definitions` or `Vertex_Definitions`, because custom material uniforms must also be registered with the material.



![Fire material](/img/extensions/materials/fire.webp)

## Using the fire material

Fire material can be found here: [https://cdn.babylonjs.com/materialsLibrary/babylon.fireMaterial.js](https://cdn.babylonjs.com/materialsLibrary/babylon.fireMaterial.js)

<Alert severity="warning" title="Warning" description="The CDN should not be used in production environments. The purpose of our CDN is to serve Babylon packages to users learning how to use the platform or running small experiments. Once you've built an application and are ready to share it with the world at large, you should serve all packages from your own CDN."/>

A demo can be found here: PG: <Playground id="#NES8QN" title="Fire Material" description="Example of fire material"/>

The fire material works with 3 textures:

- The diffuse texture (fire texture)
- The distortion texture (to create perturbations in the diffuse texture)
- The opacity texture (black and white)

**Note:** _The fire material doesn't work with lighting. So, shadow maps are also disabled._

```javascript
var fireMaterial = new BABYLON.FireMaterial("fireMaterial", scene);
fireMaterial.diffuseTexture = new BABYLON.Texture("diffuse.png", scene);
fireMaterial.distortionTexture = new BABYLON.Texture("distortion.png", scene);
fireMaterial.opacityTexture = new BABYLON.Texture("opacity.png", scene);

var plane = BABYLON.MeshBuilder.CreatePlane("fireplane", { size: 1.0 }, scene);
plane.material = fireMaterial;
```

The speed of the flames can be customized like this:

```javascript
fireMaterial.speed = 5.0; // Default is 1.0
```



![Fur material high](/img/extensions/materials/furHigh.webp)

Fur material can be found here: [https://cdn.babylonjs.com/materialsLibrary/babylon.furMaterial.js](https://cdn.babylonjs.com/materialsLibrary/babylon.furMaterial.js)

<Alert severity="warning" title="Warning" description="The CDN should not be used in production environments. The purpose of our CDN is to serve Babylon packages to users learning how to use the platform or running small experiments. Once you've built an application and are ready to share it with the world at large, you should serve all packages from your own CDN."/>

## Using the High Level mode

A demo can be found at: PG: <Playground id="#2322Y7#0" title="Fur Material" description="Example using high level mode"/>

Fur materials have long been the subject of many theories and conference talks, with multiple implementations made possible by different technologies.
Here, with WebGL, we chose one of these implementations because it is easy to use and performs well with simple models.

First, activate High Level mode, which is enabled by default:

```javascript
furMaterial.highLevelFur = true;
```

That's all. The most difficult part is configuring the shells and the fur texture to create the fur effect.
Indeed, you'll have to draw several times the same mesh with an offset (computed in the effect) to create the illusion of fur.
Hopefully, there is a function that creates and returns the shells:

```javascript
// Generate a fur texture (internally used), working like a noise texture, that will be shared between all the shells
var furTexture = BABYLON.FurMaterial.GenerateTexture("furTexture", scene);

furMaterial.furTexture = furTexture;
myMesh.material = furMaterial;

var quality = 30; // Average quality

// Create shells
var shells = BABYLON.FurMaterial.FurifyMesh(myMesh, quality);
```

It now works!
The function "BABYLON.FurMaterial.FurifyMesh" returns an array of "BABYLON.Mesh" that you can dispose later.
The first element is the mesh you used as the source mesh (myMesh here):

```javascript
for (let i = 0; i < shells.length; i++) {
  shells[i].material.dispose();
  shells[i].dispose();
}
```

You can customize the high level fur rendering thanks to some properties:

```javascript
allFurMaterials.furSpacing = 2; // Computes the space between shells. In others words, works as the fur height
```

```javascript
allFurMaterials.furDensity = 20; // Computes the fur density. More the density is high, more you'll have to zoom on the model
```

```javascript
allFurMaterials.furSpeed = 100; // Divides the animation of fur in time according to the gravity
```

```javascript
// Compute the gravity followed by the fur
allFurMaterials.furGravity = new BABYLON.Vector3(0, -1, 0);
```

## Using the fur material without High Level Mode

First, deactivate High Level mode (it is enabled by default, so the following line must be included):

```javascript
furMaterial.highLevelFur = false;
```

![Fur material](/img/extensions/materials/fur.webp)

Demos can be found at:
PG: <Playground id="#EUCNP#6" title="Fur Material" description="Example using low level mode"/>  
 PG: <Playground id="#EUCNP#7" title="Fur Material" description="Example using low level mode and heightmap"/>

The fur material needs a high number of triangular facets in the mesh to work well.
The number of facets needed also depends on the size of the mesh.
Examples that seem to work for the ground and sphere are:

```javascript
var ground = BABYLON.MeshBuilder.CreateGround("ground", { width: 8, height: 8, subdivisions: 200 }, scene);
var sphere = BABYLON.MeshBuilder.CreateSphere("sphere", { segments: 500, diameter: 8 }, scene);
```

The fur material is created using

```javascript
var furMaterial = new BABYLON.FurMaterial("fur_material", scene);

ground.material = furMaterial;
```

## Customize the fur material

You can customise three properties of the fur material:

```javascript
furMaterial.furLength = 3; // Represents the maximum length of the fur, which is then adjusted randomly. Default value is 1.
furMaterial.furAngle = Math.PI / 6; // Represents the angle the fur lies on the mesh from 0 to Math.PI/2. The default angle of 0 gives fur sticking straight up and PI/2 lies along the mesh.
furMaterial.furColor = new BABYLON.Color3(0.44, 0.21, 0.02); // is the default color if furColor is not set.
```

## Using textures

## heightTexture

A greyscale image can be used to set the fur length.
A speckled greyscale image can produce fur like results.
Any greyscale image will affect the fur length, producing a heightmap-type effect.

```javascript
furMaterial.heightTexture = new BABYLON.Texture("speckles.jpg", scene); // Set the fur length with a texture.
```

## diffuseTexture

A texture can also be used to paint the mesh.
The leopard fur texture used in the test is by Martin Wegmann from [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Leopard_fur.JPG)
under the [license](https://creativecommons.org/licenses/by-sa/3.0/deed.en)

```javascript
furMaterial.diffuseTexture = new BABYLON.Texture("leopard_fur.jpg", scene); // Set the fur length with a texture.
```

## Meshes where the number of facets is not user-controlled at creation.

Demos can be found at:
PG: <Playground id="#EUCNP#16" title="Fur Material" description="Leopard fur converted to smooth before increasing facets"/>  
 PG: <Playground id="#EUCNP#17" title="Fur Material" description="Leopard fur converted to smooth after increasing facets"/>

Unlike the ground mesh, where you can supply the number of subdivisions, or the sphere mesh, where you can supply the number of segments, the majority of meshes are created using a minimum number of facets.
To apply the fur material to these meshes, the number of facets per face needs to be increased.

The function increasedFacets will do this:
When n is the number of points per side added to each side of a facet, the number of facets is increased by the square of (n + 1).

```javascript
function increasedFacets(mesh, pps) {
  //pps points per side
  var gaps = pps + 1;
  var n = gaps + 1;
  var fvs = [];
  for (let i = 0; i < n; i++) {
    fvs[i] = [];
  }
  var A, B;
  var d = { x: 0, y: 0, z: 0 };
  var u = { x: 0, y: 0 };
  var indices = [];
  var vertexIndex = [];
  var side = [];
  var uvs = mesh.getVerticesData(BABYLON.VertexBuffer.UVKind);
  var meshIndices = mesh.getIndices();
  var positions = mesh.getVerticesData(BABYLON.VertexBuffer.PositionKind);
  var normals = [];

  for (let i = 0; i < meshIndices.length; i += 3) {
    vertexIndex[0] = meshIndices[i];
    vertexIndex[1] = meshIndices[i + 1];
    vertexIndex[2] = meshIndices[i + 2];
    for (let j = 0; j < 3; j++) {
      A = vertexIndex[j];
      B = vertexIndex[(j + 1) % 3];
      if (side[A] === undefined && side[B] === undefined) {
        side[A] = [];
        side[B] = [];
      } else {
        if (side[A] === undefined) {
          side[A] = [];
        }
        if (side[B] === undefined) {
          side[B] = [];
        }
      }
      if (side[A][B] === undefined && side[B][A] === undefined) {
        side[A][B] = [];
        d.x = (positions[3 * B] - positions[3 * A]) / gaps;
        d.y = (positions[3 * B + 1] - positions[3 * A + 1]) / gaps;
        d.z = (positions[3 * B + 2] - positions[3 * A + 2]) / gaps;
        u.x = (uvs[2 * B] - uvs[2 * A]) / gaps;
        u.y = (uvs[2 * B + 1] - uvs[2 * A + 1]) / gaps;
        side[A][B].push(A);
        for (let k = 1; k < gaps; k++) {
          side[A][B].push(positions.length / 3);
          positions.push(positions[3 * A] + k * d.x, positions[3 * A + 1] + k * d.y, positions[3 * A + 2] + k * d.z);
          uvs.push(uvs[2 * A] + k * u.x, uvs[2 * A + 1] + k * u.y);
        }
        side[A][B].push(B);
        side[B][A] = [];
        l = side[A][B].length;
        for (let a = 0; a < l; a++) {
          side[B][A][a] = side[A][B][l - 1 - a];
        }
      } else {
        if (side[A][B] === undefined) {
          side[A][B] = [];
          l = side[B][A].length;
          for (let a = 0; a < l; a++) {
            side[A][B][a] = side[B][A][l - 1 - a];
          }
        }
        if (side[B][A] === undefined) {
          side[B][A] = [];
          l = side[A][B].length;
          for (let a = 0; a < l; a++) {
            side[B][A][a] = side[A][B][l - 1 - a];
          }
        }
      }
    }
    fvs[0][0] = meshIndices[i];
    fvs[1][0] = side[meshIndices[i]][meshIndices[i + 1]][1];
    fvs[1][1] = side[meshIndices[i]][meshIndices[i + 2]][1];
    for (let k = 2; k < gaps; k++) {
      fvs[k][0] = side[meshIndices[i]][meshIndices[i + 1]][k];
      fvs[k][k] = side[meshIndices[i]][meshIndices[i + 2]][k];
      d.x = (positions[3 * fvs[k][k]] - positions[3 * fvs[k][0]]) / k;
      d.y = (positions[3 * fvs[k][k] + 1] - positions[3 * fvs[k][0] + 1]) / k;
      d.z = (positions[3 * fvs[k][k] + 2] - positions[3 * fvs[k][0] + 2]) / k;
      u.x = (uvs[2 * fvs[k][k]] - uvs[2 * fvs[k][0]]) / k;
      u.y = (uvs[2 * fvs[k][k] + 1] - uvs[2 * fvs[k][0] + 1]) / k;
      for (let j = 1; j < k; j++) {
        fvs[k][j] = positions.length / 3;
        positions.push(positions[3 * fvs[k][0]] + j * d.x, positions[3 * fvs[k][0] + 1] + j * d.y, positions[3 * fvs[k][0] + 2] + j * d.z);
        uvs.push(uvs[2 * fvs[k][0]] + j * u.x, uvs[2 * fvs[k][0] + 1] + j * u.y);
      }
    }
    fvs[gaps] = side[meshIndices[i + 1]][meshIndices[i + 2]];

    indices.push(fvs[0][0], fvs[1][0], fvs[1][1]);
    for (let k = 1; k < gaps; k++) {
      for (let j = 0; j < k; j++) {
        indices.push(fvs[k][j], fvs[k + 1][j], fvs[k + 1][j + 1]);
        indices.push(fvs[k][j], fvs[k + 1][j + 1], fvs[k][j + 1]);
      }
      indices.push(fvs[k][j], fvs[k + 1][j], fvs[k + 1][j + 1]);
    }
  }

  var vertexData = new BABYLON.VertexData();
  vertexData.positions = positions;
  vertexData.indices = indices;
  vertexData.uvs = uvs;

  BABYLON.VertexData.ComputeNormals(positions, indices, normals);
  vertexData.normals = normals;
  mesh.dispose();
  var newmesh = new BABYLON.Mesh("newmesh", scene);
  vertexData.applyToMesh(newmesh);

  return newmesh;
}
```

For sharp-edged meshes such as a box, the shader can separate the faces since the faces meeting at the corners have their own vertices and normals at those vertices.
These meshes are flat shaded. If this separation of the edges is a problem then the function convertToSmoothShadedMesh() can be used.
However, this can produce some artifacts at the edges.

```javascript
function convertToSmoothShadedMesh(mesh) {
  var meshIndices = mesh.getIndices();
  var meshPositions = mesh.getVerticesData(BABYLON.VertexBuffer.PositionKind);
  var mesh_uvs = mesh.getVerticesData(BABYLON.VertexBuffer.UVKind);
  var setPositions = [];
  var indices = [];
  var positions = [];
  var uvs = [];
  var normals = [];
  var p;
  var indexMap = [];
  for (let i = 0; i < meshPositions.length; i += 3) {
    var temp = [];
    temp.push(i / 3, meshPositions[i], meshPositions[i + 1], meshPositions[i + 2], mesh_uvs[(2 * i) / 3], mesh_uvs[(2 * i) / 3 + 1]);
    setPositions.push(temp);
  }
  var i = 0;
  while (setPositions.length > 0) {
    p = setPositions.shift();
    positions.push(p[1], p[2], p[3]);
    uvs.push(p[4], p[5]);
    indexMap[p[0]] = i;
    var j = 0;
    while (j < setPositions.length) {
      if (Math.abs(p[1] - setPositions[j][1]) < Math.pow(0.1, 10) && Math.abs(p[2] - setPositions[j][2]) < Math.pow(0.1, 10) && Math.abs(p[3] - setPositions[j][3]) < Math.pow(0.1, 10)) {
        indexMap[setPositions[j][0]] = i;
        setPositions.splice(j, 1);
      } else {
        j++;
      }
    }
    i++;
  }
  for (let i = 0; i < meshIndices.length; i++) {
    indices.push(indexMap[meshIndices[i]]);
  }

  var vertexData = new BABYLON.VertexData();
  vertexData.positions = positions;
  vertexData.indices = indices;
  vertexData.uvs = uvs;

  BABYLON.VertexData.ComputeNormals(positions, indices, normals);
  vertexData.normals = normals;
  vertexData.applyToMesh(mesh);

  return mesh;
}
```



![Screenshot](/img/extensions/materials/gradient.webp)

You can get the gradient material by:

* Using npm with npm install --save babylonjs babylonjs-materials
* With a direct reference to: https://cdn.babylonjs.com/materialsLibrary/babylonjs.materials.min.js

<Alert severity="warning" title="Warning" description="The CDN should not be used in production environments. The purpose of our CDN is to serve Babylon packages to users learning how to use the platform or running small experiments. Once you've built an application and are ready to share it with the world at large, you should serve all packages from your own CDN."/>

## Using the gradient material

The material creates a smooth gradient with two colors:

```
var sphere = BABYLON.MeshBuilder.CreateSphere("sphere", { segments: 32, diameter: 2 }, scene);

var gradientMaterial = new BABYLON.GradientMaterial("grad", scene);
gradientMaterial.topColor = BABYLON.Color3.Red(); // Set the gradient top color
gradientMaterial.bottomColor = BABYLON.Color3.Blue(); // Set the gradient bottom color
gradientMaterial.offset = 0.25;

sphere.material = gradientMaterial;
```

The gradient material can be configured with:
* `topColor` and `bottomColor` are the two colors used in this gradient material
* `offset` is a number used to offset the color on the Y axis
* `scale` is a number used to scale the color on the Y axis
* `smoothness` is a number (between 0 and 10) that can be used to define the speed of the color change along the Y axis (1 by default)

## Playground example

You can find a live example here: PG: <Playground id="#2IFRKC#63" title="Gradient Material" description="Example of gradient material"/>



## Grid material

![Grid Material](/img/extensions/materials/grid.webp)

## Playground example

A full playground example can be found here: PG: <Playground id="#1UFGZH#12" title="Grid Material" description="Example of grid material"/>

## Using the Grid material

Because the grid material is a Babylon.js extension, it is not included in the main _babylon.js_ file. To use the material, download and reference the extension from the CDN using [babylon.gridMaterial.js](https://cdn.babylonjs.com/materialsLibrary/babylon.gridMaterial.js) or its minified version [babylon.gridMaterial.min.js](https://cdn.babylonjs.com/materialsLibrary/babylon.gridMaterial.min.js).

<Alert severity="warning" title="Warning" description="The CDN should not be used in production environments. The purpose of our CDN is to serve Babylon packages to users learning how to use the platform or running small experiments. Once you've built an application and are ready to share it with the world at large, you should serve all packages from your own CDN."/>

The default grid behavior does not require any setup and displays a black-and-white grid on your meshes:

![gridDefault](/img/extensions/materials/gridDefault.webp)

You can access the live example in this PG: <Playground id="#2KKVBH" title="Grid Material" description="Example of grid material"/>

The grid uses the local position to outline each axis, with one unit shown in black. Only one in ten lines will be fully black; the other lines will be lighter gray. You can think of it as a ruler with bigger marks for centimeters and smaller ones for millimeters.

```javascript
var ground = BABYLON.MeshBuilder.CreateGroundFromHeightMap("ground", "textures/heightMap.png", { width: 100, height: 100, subdivisions: 100, minHeight: 0, maxHeight: 10 }, scene);
ground.material = new BABYLON.GridMaterial("groundMaterial", scene);
```

## Customize the grid material

To help you make the grid fit your scenes, a few controls are available:

- `mainColor`: the main color controls the color of the empty area
- `lineColor`: the line color controls the line color
- `opacity`: the opacity helps changing the lines opacity. In transparent mode (opacity < 1.0), the empty area will always be at an opacity level of `0.08`
- `gridRatio`: subdivide the object size in order to fit with it
- `majorUnitFrequency`: frequency of strong lines
- `minorUnitVisibility`: level of minor lines compared to the major ones
- `gridOffset`: the offset vector3 will shift the cells of the grid by a set amount

### A few clarifications

#### gridRatio

The grid will be projected on objects according to their size. If an object has a size of 1, you'll only see one line on it.
For instance, a cube with a size of 1 will, by default, only have one line:

![Grid Ratio 1](/img/extensions/materials/gridRatio1.webp)

PG: <Playground id="#5S6MD" title="Grid Material" description="Grid ratio of 1"/>

Using a gridRatio of 0.1 will make ten lines appear on it:

![Grid Ratio 2](/img/extensions/materials/gridRatio2.webp)

PG: <Playground id="#5S6MD#1" title="Grid Material" description="Grid ratio of 2"/>

#### majorUnitFrequency

You may have noticed in the gridRatio examples above that only one in ten lines is stronger. This is controlled by the parameter named `majorUnitFrequency`, which has a default value of 10.

Setting it to 2 will make one strong line appear every 2 lines. This is only a scary parameter name for something simple:

![Grid MUF](/img/extensions/materials/gridMUF.webp)

PG: <Playground id="#5S6MD#2" title="Grid Material" description="Example of using multi unit frequency"/>

#### minorUnitVisibility

After setting the frequency of the stronger lines, you might wonder how to control the strength of the minor ones. The parameter `minorUnitVisibility` helps you control this. This value should be smaller than 1, which is the value applied to the main lines. The default value is 0.33, which corresponds to 33% of the `lineColor`.

Setting it to 0.1 will then reinforce the effect of the main lines (by dropping the value of the minor ones):

![Grid MUV](/img/extensions/materials/gridMUV.webp)

PG: <Playground id="#5S6MD#3" title="Grid Material" description="Example of using minor unit visiblity"/>

#### gridOffset

Note that the shift for each axis loops: using a `gridOffset` of `(0, 0, 0)` will give you the same visual result as `(1, 0, 0)`.

PG: <Playground id="#URSDPL#1" title="Grid Material" description="Example of using grid offset"/>

#### useMaxLine

Sometimes the points where grid lines intersect may appear brighter than the rest of the grid. Set useMaxLine to true to remove this effect.

PG: <Playground id="#1UFGZH#222" title="Grid Material" description="Example of using useMaxLine"/>



![Screenshot](/img/extensions/materials/lava.webp)

PG: <Playground id="#1BLVWO#25" title="Lava Material" description="An example of lava material"/>

The Lava material can be found here: [https://cdn.babylonjs.com/materialsLibrary/babylon.lavaMaterial.js](https://cdn.babylonjs.com/materialsLibrary/babylon.lavaMaterial.js)

<Alert severity="warning" title="Warning" description="The CDN should not be used in production environments. The purpose of our CDN is to serve Babylon packages to users learning how to use the platform or running small experiments. Once you've built an application and are ready to share it with the world at large, you should serve all packages from your own CDN."/>

## Using the lava material

The lava material needs at least a noise texture and a diffuse texture to render properly.
Just create a new instance of the material and assign the two textures:

```
var ground = BABYLON.MeshBuilder.CreateGround("ground", { width: 512, height: 512, subdivisions: 32 }, scene);

var lavaMaterial = new BABYLON.LavaMaterial("lava", scene);
lavaMaterial.noiseTexture = new BABYLON.Texture("cloud.png", scene); // Set the bump texture
lavaMaterial.diffuseTexture = new BABYLON.Texture("lavatile.jpg", scene); // Set the diffuse texture

ground.material = lavaMaterial;
```

The diffuse texture provides the color of your lava, while the noise texture represents the lava deformation.
Notice that this material updates the position of each vertex on your object. If there are not enough vertices,
some artifacts may appear.

## Lights
By default, the material is affected by lights. If you wish, you can disable this by using the unlit property.
```
material.unlit = true;
```

PG: <Playground id="#1BLVWO#22" title="Lava Material" description="Lava with unlit material"/>

## Customize the lava material

You can customize two properties of the material:

```
lavaMaterial.speed = 2.0; // Default 1. Represents speed of perturbations of the lava
lavaMaterial.fogColor = new BABYLON.Color3(1, 0, 0); // Default to (0,0,0) black. Represents the color of the fog displayed on the lava ground.
```



![Mix Material](/img/extensions/materials/mixResult.webp)

## Playground example

PG: <Playground id="#1DFTDT" title="Mix Material" description="Example of mix material"/>

## Using the mix material

The mix material is based on the terrain material but works with up to 8 diffuse textures. It is composed of:

- 8 Diffuse textures. (at least 4 required)
- 2 Mixmap textures: represent the intensity of each diffuse texture according to the channels R (red), G (green), B (blue), and A (alpha). (at least one required)

**Note 1: the alpha channel is inverted to help create the mix map textures. In other words, the less alpha you have, the more visible the diffuse texture attached to the alpha channel will be.**

**Note 2: the mix material doesn't support bump mapping, for instance.**

```
// Create a terrain
var terrain = BABYLON.MeshBuilder.CreateGroundFromHeightMap("terrain", "heightMap.png", { width: 100, height: 100, subdivisions: 100, minHeight: 0, maxHeight: 10 }, scene);

// Create the mix material
var mix = new BABYLON.MixMaterial("mix", scene);

// Mix texture 1 (RGBA) is required
mix.mixTexture1 = new BABYLON.Texture("/playground/textures/mixMap.png", scene);

// Mix texture 2 (RGBA) is optional
mix.mixTexture2 = new BABYLON.Texture("/playground/textures/mixMap_2.png", scene);

// Diffuse textures (RGBA) attached to the "mixTexture1"
mix.diffuseTexture1 = new BABYLON.Texture("/playground/textures/floor.png", scene);
mix.diffuseTexture2 = new BABYLON.Texture("/playground/textures/rock.png", scene);
mix.diffuseTexture3 = new BABYLON.Texture("/playground/textures/grass.png", scene);
mix.diffuseTexture4 = new BABYLON.Texture("/playground/textures/floor.png", scene);

// Diffuse textures (RGBA) attached to the "mixTexture2"
mix.diffuseTexture5 = new BABYLON.Texture("/playground/textures/leopard_fur.jpg", scene);
mix.diffuseTexture6 = new BABYLON.Texture("/playground/textures/fur.jpg", scene);
mix.diffuseTexture7 = new BABYLON.Texture("/playground/textures/sand.jpg", scene);
mix.diffuseTexture8 = new BABYLON.Texture("/playground/textures/crate.png", scene);

// Apply the material
terrain.material = mix;
```

That's all!

## Result with only the mix texture 1

With `mix.mixTexture2` undefined or null, the material will only apply mix texture 1:

![Mix Texture 1](/img/extensions/materials/mixMap.webp)
![Mix Material 1](/img/extensions/materials/terrainMixtexture1.webp)

## Result with both mix textures 1 & 2

With `mix.mixTexture2 = new BABYLON.Texture("/playground/textures/mixMap_2.png", scene)`, the material continues by mixing mix texture 1 with mix texture 2. You can then mix up to 8 diffuse textures:

![Mix Texture 2](/img/extensions/materials/mixMap_2.webp)
![Mix Material 2](/img/extensions/materials/mixResult.webp)



![Screenshot](/img/extensions/materials/normal.webp)

## Playground Example 
    
PG: <Playground id="#22VQKB" title="Normal Material" description="Example of normal material"/>

## Using the normal material

It's very simple:
```
var ground = BABYLON.MeshBuilder.CreateGround("ground", { width: 512, height: 512, subdivisions: 32 }, scene);
var normalMaterial = new BABYLON.NormalMaterial("normal", scene);
ground.material = normalMaterial;
```

## Customize the normal material

You can also add a diffuse texture to the normal material.
The normal colors will be mixed with the texture color.

```
normalMaterial.diffuseTexture = new BABYLON.Texture("textures/amiga.jpg", scene);
```



## General

![Screenshot](/img/extensions/materials/shadowOnly.webp)

The goal of the ShadowOnlyMaterial is to display only shadows cast by a light on a receiving object. It is mostly useful when you want to display shadows on a transparent canvas (on top of your existing DOM).

The ShadowOnly material can be found here: [https://cdn.babylonjs.com/materialsLibrary/babylon.shadowOnlyMaterial.js](https://cdn.babylonjs.com/materialsLibrary/babylon.shadowOnlyMaterial.js)

<Alert severity="warning" title="Warning" description="The CDN should not be used in production environments. The purpose of our CDN is to serve Babylon packages to users learning how to use the platform or running small experiments. Once you've built an application and are ready to share it with the world at large, you should serve all packages from your own CDN."/>

A demo can be found here: PG: <Playground id="#1KF7V1" title="Shadow Only Material" description="Example of shadow only material"/>

## Using the ShadowOnly material

ShadowOnly material is very simple to use. Just apply it as a material to any mesh where you want to display only shadows:

```
var ground = BABYLON.MeshBuilder.CreatePlane('ground', { size: 1000 }, scene)
ground.rotation.x = Math.PI / 2
ground.material = new BABYLON.ShadowOnlyMaterial('shadowOnly', scene)
ground.receiveShadows = true
```

By default, the shadow color is black, but you can force an artificial color with `material.shadowColor = BABYLON.Color3.Red()`.

Demo here:  PG: <Playground id="#1KF7V1#19" title="Shadow Only Material" description="Example of shadow only material color"/>

**Limitation:** Please note that only the first light that can reach the mesh will be used. 
So if you have multiple lights in your scene, you may need to use `light.includedOnlyMeshes` or `light.excludedMeshes` or `light.includeOnlyWithLayerMask` or `light.excludeWithLayerMask`.
You can also force the material to pick a specific light with `material.activeLight = light`.




![Sky Material](/img/extensions/materials/sky.webp)

## Introduction

The sky material allows you to create dynamic and texture-free effects for skyboxes.

This work is based on ["A Practical Analytic Model for Daylight"](https://www2.cs.duke.edu/courses/cps124/spring08/assign/07_papers/p91-preetham.pdf).
It was first implemented by [Simon Wallner](http://simonwallner.at/project/atmospheric-scattering/),
improved by [Martin Upitis](http://blenderartists.org/forum/showthread.php?245954-preethams-sky-impementation-HDR),
and finally implemented in Three.js by [zz85](http://twitter.com/blurspline).

The challenge for skyboxes is to reproduce and configure the sky while accounting for the state of the atmosphere.
In other words, it means determining, for example, how light from the sun is scattered by particles.

## Playground example

PG: <Playground id="#E6OZX#221" title="Sky Material" description="Sky material animation"/>

Just press the following keys:

- 1: Set Day
- 2: Set Evening
- 3: Increase Luminance
- 4: Decrease Luminance
- 5: Increase Turbidity
- 6: Decrease Turbidity
- 7: Move horizon to -50
- 8: Restore horizon to 0

## How to use?

Simply create a skybox and assign a new instance of the Sky Material:

```javascript
const skyMaterial = new BABYLON.SkyMaterial("skyMaterial", scene);
skyMaterial.backFaceCulling = false;

const skybox = BABYLON.MeshBuilder.CreateBox("skyBox", { size: 1000.0 }, scene);
skybox.material = skyMaterial;
```

That's all!

## Configuring the Sky Material

You can customize the appearance of the sky, including the time of day. The properties are:

```javascript
skyMaterial.turbidity = 1; // Represents the amount (scattering) of haze as opposed to molecules in atmosphere
```

![skyTurbidity](/img/extensions/materials/skyTurbidity.webp)

```javascript
skyMaterial.luminance = 1; // Controls the overall luminance of sky in interval [0, 1190]
```

![skyLuminance](/img/extensions/materials/skyLuminance.webp)

```javascript
// Control the planet's orientation over the sun
skyMaterial.inclination = 0.5; // The solar inclination, related to the solar azimuth in interval [0, 1]
skyMaterial.azimuth = 0.25; // The solar azimuth in interval [0, 1]
```

Otherwise, if you want to configure the sun position with a BABYLON.Vector3, you can set:

```javascript
// Manually set the sun position
skyMaterial.useSunPosition = true; // Do not set sun position from azimuth and inclination
skyMaterial.sunPosition = new BABYLON.Vector3(0, 100, 0);
```

![skyAzimuthInclination](/img/extensions/materials/skyAzimuthInclination.webp)

```javascript
skyMaterial.rayleigh = 2; // Represents the sky appearance (globally)
```

![skyRayleigh](/img/extensions/materials/skyRayleigh.webp)

```javascript
// Mie scattering (from [Gustav Mie](https://en.wikipedia.org/wiki/Gustav_Mie))
// Related to the haze particles in atmosphere

// The amount of haze particles following the Mie scattering theory
skyMaterial.mieDirectionalG = 0.8;

skyMaterial.mieCoefficient = 0.005; // The mieCoefficient in interval [0, 0.1], affects the property skyMaterial.mieDirectionalG
```

![skyMie](/img/extensions/materials/skyMie.webp)

## Keeping the horizon relative to the camera elevation

In some cases, you would like to keep the horizon's "position" relative to the camera's position (typically a game where you can fly very high).
To do that, the material exposes a vector (`.cameraOffset`) that you can customize.

Typically:

```javascript
// Set the horizon elevation relative to the camera position
skyMaterial.cameraOffset.y = scene.activeCamera.globalPosition.y;
```

**Note**: this will not modify the sun position, as it is considered far enough away, even when the camera is very high.

## Using the sky material to create a reflection texture

A common technique is to use the result of the sky material to reflect the environment, for example when using a PBR material.

The technique consists of creating a reflection probe (which is a cube texture) and rendering the sky mesh with the sky material assigned to it. For example: PG: <Playground id="#4R1H1U" title="Sky Material" description="Example of sky material reflecting the environment"/>



![Terrain Material](/img/extensions/materials/terrain.webp)

## Playground example

PG: <Playground id="#E6OZX#7" title="Terrain Material" description="Example of terrain material"/>

## Using the terrain material

The terrain material works with at least 4 textures:
- 3 Diffuse textures. (required)
- 3 Bump textures. (not required)
- 1 Mixmap texture: represents the intensity of each diffuse texture according to the channels R (red), G (green), and B (blue). (required)

In other words, the Mixmap texture mixes the 3 diffuse textures using the RGB color channels.
A Mixmap texture looks like this (the result is shown in the screenshot above):
![](/img/extensions/materials/terrainMixMap.webp)

The method applied by the terrain material is also called "texture splatting".

```
var terrain = BABYLON.MeshBuilder.CreateGroundFromHeightMap("terrain", "heightMap.png", { width: 100, height: 100, subdivisions: 100, minHeight: 0, maxHeight: 10 }, scene);

var terrainMaterial = new BABYLON.TerrainMaterial("terrainMaterial", scene);
terrainMaterial.mixTexture = new BABYLON.Texture("mixMap.png", scene);
terrainMaterial.diffuseTexture1 = new BABYLON.Texture("grass.png", scene);
terrainMaterial.diffuseTexture2 = new BABYLON.Texture("rock.png", scene);
terrainMaterial.diffuseTexture3 = new BABYLON.Texture("floor.png", scene);

terrainMaterial.bumpTexture1 = new BABYLON.Texture("grassn.png", scene);
terrainMaterial.bumpTexture2 = new BABYLON.Texture("rockn.png", scene);
terrainMaterial.bumpTexture3 = new BABYLON.Texture("floor_bump.png", scene);

terrain.material = terrainMaterial;
```

That's all.



![Tri-Planar Mapping Material](/img/extensions/materials/triPlanar.webp)

# Playground Example

PG: <Playground id="#E6OZX#9" title="Tri-Panar Material" description="Example of tri-planar material"/>

Press "1" to activate the Tri-Planar material (by default).
Press "2" to activate the default material.

# What is tri-planar mapping?
In the case of very large scenes, you are likely to use terrain generated with procedural methods.
In this case, you'll have to compute the vertex positions, normals, UVs, and so on.
One of the trickiest tasks is generating the UV coordinates properly while accounting for possible abrupt changes in the terrain.

For example, an abrupt change can cause this kind of glitch:

![Tri-Planar Mapping Material Problem](/img/extensions/materials/triPlanarProblem.webp)

It should look like this:

![Tri-Planar Mapping Material Resolved](/img/extensions/materials/triPlanarResolved.webp)

The tri-planar mapping material helps resolve this kind of problem and, above all, completely eliminates UV calculations: no UVs needed.

# Using the tri-planar mapping material

The tri-planar material works with at least 3 textures: each texture represents how it is applied along each axis (X, Y, and Z).

Of course, each axis can share the same texture. For example:

```javascript
var triPlanarMaterial = new BABYLON.TriPlanarMaterial("triplanar", scene);

// The 3 diffuse textures must be set, even if they share the same texture reference
triPlanarMaterial.diffuseTextureX = new BABYLON.Texture("rock.png", scene);
triPlanarMaterial.diffuseTextureY = new BABYLON.Texture("grass.png", scene);
triPlanarMaterial.diffuseTextureZ = triPlanarMaterial.diffuseTextureX;
```

You can also customize the tile size by setting the `.tileSize` property:

```javascript
triPlanarMaterial.tileSize = 1.5;
```

For better quality, the tri-planar material also supports normal mapping. Just set the normal textures:

```javascript
var triPlanarMaterial = new BABYLON.TriPlanarMaterial("triplanar", scene);
// ...

// In the case of normal maps, it is not necessary to set the 3 textures
triPlanarMaterial.normalTextureX = new BABYLON.Texture("textures/rockn.png", scene);
triPlanarMaterial.normalTextureY = new BABYLON.Texture("textures/grassn.png", scene);
triPlanarMaterial.normalTextureZ = triPlanarMaterial.normalTextureX;
```


To dive deeper into the theory, you can read this [great article](http://gamedevelopment.tutsplus.com/articles/use-tri-planar-texture-mapping-for-better-terrain--gamedev-13821) about tri-planar mapping.



![Water material](/img/extensions/materials/water.webp)

# Using the water material

The water material can be found here: [https://cdn.babylonjs.com/materialsLibrary/babylon.waterMaterial.js](https://cdn.babylonjs.com/materialsLibrary/babylon.waterMaterial.js)

<Alert severity="warning" title="Warning" description="The CDN should not be used in production environments. The purpose of our CDN is to serve Babylon packages to users learning how to use the platform or running small experiments. Once you've built an application and are ready to share it with the world at large, you should serve all packages from your own CDN."/>

A demo can be found here: PG: <Playground id="#1SLLOJ#20" title="Water Material" description="Example of water material"/>

# Water material demos

- PG: <Playground id="#1SLLOJ#15" title="Water Material" description="Calm lake"/>
- PG: <Playground id="#1SLLOJ#17" title="Water Material" description="Ocean, play with waves"/>
- PG: <Playground id="#1SLLOJ#18" title="Water Material" description="Deep water, play with water color"/>
- PG: <Playground id="#1SLLOJ#19" title="Water Material" description="Beach"/>

The water material needs only a bump texture to render properly.
Just create a new instance of the material and assign its bump texture:

```javascript
var ground = BABYLON.MeshBuilder.CreateGround("ground", { width: 512, height: 512, subdivisions: 32 }, scene);

var waterMaterial = new BABYLON.WaterMaterial("water_material", scene);
waterMaterial.bumpTexture = new BABYLON.Texture("bump.png", scene); // Set the bump texture

ground.material = waterMaterial;
```

To reflect and refract the world, you just have to add the desired meshes to the render list:

```javascript
waterMaterial.addToRenderList(skybox);
waterMaterial.addToRenderList(mesh1);
waterMaterial.addToRenderList(mesh2);
// ... etc.
```

That's all.

# Customize the water material

You can customize the material with these properties:

```javascript
waterMaterial.windForce = 45; // Represents the wind force applied on the water surface
waterMaterial.waveHeight = 1.3; // Represents the height of the waves
waterMaterial.bumpHeight = 0.3; // According to the bump map, represents the pertubation of reflection and refraction
waterMaterial.windDirection = new BABYLON.Vector2(1.0, 1.0); // The wind direction on the water surface (on width and height)
waterMaterial.waterColor = new BABYLON.Color3(0.1, 0.1, 0.6); // Represents the water color mixed with the reflected and refracted world
waterMaterial.colorBlendFactor = 2.0; // Factor to determine how the water color is blended with the reflected and refracted world
waterMaterial.waveLength = 0.1; // The lenght of waves. With smaller values, more waves are generated
```



The Babylon.js materials library is a collection of advanced materials to be used in a Babylon.js scene.

- [Fire material](/toolsAndResources/assetLibraries/materialsLibrary/fireMat)
- [Water material](/toolsAndResources/assetLibraries/materialsLibrary/waterMat)
- [Lava material](/toolsAndResources/assetLibraries/materialsLibrary/lavaMat)
- [Fur material](/toolsAndResources/assetLibraries/materialsLibrary/furMat)
- [Normal material](/toolsAndResources/assetLibraries/materialsLibrary/normalMat)
- [Terrain material](/toolsAndResources/assetLibraries/materialsLibrary/terrainMat)
- [Tri-Planar material](/toolsAndResources/assetLibraries/materialsLibrary/triPlanarMat)
- [Gradient material](/toolsAndResources/assetLibraries/materialsLibrary/gradientMat)
- [Sky material](/toolsAndResources/assetLibraries/materialsLibrary/skyMat)
- [Grid material](/toolsAndResources/assetLibraries/materialsLibrary/gridMat)
- [Shadow Only material](/toolsAndResources/assetLibraries/materialsLibrary/shadowOnlyMat)
- [Cell Shading material](/toolsAndResources/assetLibraries/materialsLibrary/cellShadingMat)
- [Mix material](/toolsAndResources/assetLibraries/materialsLibrary/mixMat)
- [Custom materials](/toolsAndResources/assetLibraries/materialsLibrary/customMat)




# Asset Libraries

This section includes a range of libraries for textures, models, and more that you can load into the Playground. These resources can help you illustrate issues without having to find a CORS-acceptable server to load your own assets into the Playground. It also includes a range of programmable textures and materials built using a variety of shaders.

Materials Library

Coming next

Fire Material

The Babylon.js materials library fire effects.

Water Material

The Babylon.js materials library water effect.

Lava Material

The Babylon.js materials library lava effect.

Fur Material

The Babylon.js materials library fur effect.

Normal Material

The Babylon.js materials library illustrates the range of normals across the mesh.

Terrain Material

The Babylon.js materials library terrain material displays up to 4 terrain textures.

Tri-Planar Mapping Material

The Babylon.js materials library tri-planar mapping material provides an elegant technique to give realistic textures from any angle or on any complex shape.

Gradient material

The Babylon.js materials library gradient material creates a smooth gradient with two colors.

Sky Material

The Babylon.js materials library sky material allows the creation of dynamic and texture-free effects for skyboxes.

Grid Material

The Babylon.js materials library displays a grid across the mesh.

ShadowOnly Material

The Babylon.js materials library ShadowOnlyMaterial displays only shadows cast by a light on a receiving object.

Cell material

The Babylon.js materials library cell material.

Mix Material

The Babylon.js materials library mix map textures.

Custom Materials

The Babylon.js materials library includes CustomMaterial and PBRCustomMaterial for injecting GLSL code into standard and PBR material shaders.