
## Creating PBR materials

It is incredibly easy to utilize Physically Based Rendering with Node Materials thanks to the PBRMettalic_Roughness block.

You can use these playgrounds and materials as starting points for your own experiments to create PBR materials in the NME (note that the node material may take some time to load in the PG - the mesh will stay black until the material is loaded):

-   Full use of all PBR blocks:
-   PG: <Playground id="#D8AK3Z#44" title="PBR Blocks Playground" description="Playground of the full use of PBR blocks in NME." image="/img/playgroundsAndNMEs/PGPBRNME.jpg" isMain={true} category="Node Material"/>
-   Material: <NME id="#EPY8BV#6" title="PBR Blocks NME" description="Node Material Editor of the full use of PBR blocks." image="/img/playgroundsAndNMEs/NMEPBRNME.jpg"/>
-   PBR material with sheen only:
    -   PG: <Playground id="#MUX769#4" title="PBR Blocks Sheen Only Playground" description="Playground of PBR blocks in NME using sheen only." image="/img/playgroundsAndNMEs/PGPBRSheenNME.jpg"/>
    -   Material: <NME id="#V3R0KJ" title="PBR Blocks Sheen Only NME" description="Node Material Editor of PBR blocks using sheen only." image="/img/playgroundsAndNMEs/NMEPBRSheenNME.jpg"/>
-   PBR material with clear coat only:
    -   PG: <Playground id="#0XSPF6#6" title="PBR Blocks Clear Coat Only NME" description="Playground of PBR blocks in NME using clear coat only." image="/img/playgroundsAndNMEs/PGPBRclearCoatNME.jpg"/>
    -   Material: <NME id="#C3NEY1#4" title="PBR Blocks Sheen Only NME" description="Node Material Editor of PBR blocks using clear coat only." image="/img/playgroundsAndNMEs/NMEPBRclearCoatNME.jpg"/>
-   PBR material with sub surface only:
    -   PG: <Playground id="#7QAN2T#8" title="PBR Blocks sub surface Only Playground" description="Playground of PBR blocks in NME using sub surface only." image="/img/playgroundsAndNMEs/PGPBRsubSurfaceNME.jpg"/>
    -   Material: <NME id="#100NDL#1" title="PBR Blocks sub surface Only NME" description="Node Material Editor of PBR blocks using sub surface only." image="/img/playgroundsAndNMEs/NMEPBRsubSurfaceNME.jpg"/>

The inputs of the different PBR blocks are using the same names as in the `PBRMetallicRoughnessMaterial` class, so you can refer to [this doc](/typedoc/classes/babylon.pbrmetallicroughnessmaterial) for explanations about them.

Some of the parameters are available as properties when clicking on the block in the NME.

For eg, for `Reflection`:

![Reflection properties](/img/how_to/Materials/nme_reflection_prop.png)

Or for `PBRMetallicRoughness`:

![PBR properties](/img/how_to/Materials/nme_pbr_prop.png)

As for the standard `PBRMaterial`, if no texture is provided for the **Reflection** / **Refraction** texture, the one declared at the scene level (`scene.environmentTexture`) is used instead.

By default, if something is connected to the `a` input of the `FragmentOutput` block, alpha blending is enabled. If you don't need alpha blending, don't connect this input.

Regarding the `PBRMetallicRoughness` block, you have access to each output component separately (`ambient`, `diffuse`, `specular`, ...) if you want or you can directly use `lighting` to get the composite output. In the names of the separate outputs, `dir` means `direct` (component from direct lights) and `Ind` means `Indirect` (component from indirect lighting, meaning the environment).

A note about image processing and manual compositing: Note that the composited `lighting` output of the `PBRMetallicRoughness` block also adds image processing from the scene. If you desire to to add additional components to the standard lighting setup, you will want to do the compositing yourself, using the separated components. The outputs of the separated components are in Linear color space. This is important because if you desire to calculate scene image processing in your manual composite, you'll need the `ImageProcessing` block. This block assumes input values in gamma color space by default and runs an internal conversation to a linear color space output. You will need to turn this conversion off in the `ImageProcessing` block properties to pass linear through without a conversion. 

<Youtube id="CRg8P1Af1M0"/>


## Creating Particle shaders

Starting with Babylon.js v4.2, you can now create particle shaders (to be used with a particle system) with the node material editor.

You need simply to change the mode to _Particle_:

![Particle choice](/img/how_to/Materials/particleMenu.png)

Some blocks are made unavailable in this mode (they are hidden from the block list), as they have no meaning: the mesh, post process and animation blocks.

Also, in this mode, you can't create a vertex shader, only a fragment shader: the vertex shader is fixed and not updatable.

Note that everything is driven by the parameters of the particle system instance. For eg, if the current particle system displayed in the preview area does not use "ramp gradients", the `ParticleRampGradient` block does nothing (it does not add ramp gradients to the shader), it's just a pass-through. Same thing for the `ParticleBlendMultiply` block. The exception is the `ParticleTexture` block, and only in the preview area of the node editor: if you provide a texture for this block it will be used as the particle texture in the preview area, else the texture defined in the current particle system will be used. In any case, when using the material in a live program, the texture will always be the one defined by the `ParticleSystem.particleTexture` property.

The materials you create in the **Particle** mode can also be used for GPU particle systems, save for these restrictions:

-   GPU particle systems don't support ramp gradients, so the `RampGradientBlock` won't do anything (you can still use it in your material, it will simply do nothing)
-   GPU particle systems don't support the `textureMask` property, so you should not use the `ParticleTextureMask` block in your materials targeted for GPU particle systems, else display artifacts will appear

When you have created your particle shader in the NME, you can link the material to a particle system instance by calling the `NodeMaterial.createEffectForParticles` method:

```javascript
nodeMaterial.createEffectForParticles(particleSystem);
```

PG: <Playground id="#J9J6CG#1" title="NME Particle Shaders Example" description="Playground example of using the Node Material Editor to create Particle Shaders." image="/img/playgroundsAndNMEs/PGNMEParticleShader.jpg" isMain={true} category="Node Material"/>

The full fragment shader used by default by the particle system can be recreated in the NME: <NME id="#X3PJMQ#1" title="NME Full Default Fragment Shader" description="Node Material Editor setup of the default fragment shader for particle systems." image="/img/playgroundsAndNMEs/NMEdefaultParticleFragmentShader.jpg"/>

As explained above, if you want to use this material for GPU particle systems, you should remove the use of the `ParticleTextureMask` block: <NME id="#X3PJMQ#2" title="NME Full Default Fragment Shader GPU Version" description="Node Material Editor setup of the default fragment shader for particle systems on the GPU." image="/img/playgroundsAndNMEs/NMEdefaultParticleFragmentShaderGPU.jpg"/>


## Creating Post Processes with Node Materials

Starting with Babylon.js v4.2, you can now create post processes with the node material editor.

You need simply to change the mode to _Post Process_:

![PostProcess choice](/img/how_to/Materials/postprocessMenu.png)

In this mode, the special block **CurrentScreen** corresponds to the frame buffer that will be passed to your post process when you use this material as a post process in a real scenario. You can load any texture you want, it's simply an helper for you to see how your post process will render in the end.

Some blocks are made unavailable in this mode (they are hidden from the block list), as they have no meaning: the mesh, particle and animation blocks.

When you have created your post process material in the NME, you can create a regular `BABYLON.PostProcess` instance by calling the `NodeMaterial.createPostProcess` method:

```javascript
const postProcess = nodeMaterial.createPostProcess(camera);
```

You can also update an existing post process:

```javascript
const myPostProcess = new BABYLON.PostProcess(...);
...
nodeMaterial.createEffectForPostProcess(myPostProcess);
```

PG: <Playground id="#WB27SW#1" title="NME Post Process Playground Example" description="Playground example of using the Node Material Editor to create a Post Process effect." image="/img/playgroundsAndNMEs/PGNMEPostProcess.jpg" isMain={true} category="Node Material"/>

As for regular node materials, you can access the blocks programmatically and change their values:

Base material: <Playground id="#WB27SW#4" title="NME Post Process Base Node Material" description="Playground example of a NME Post Process Base Material." image="/img/playgroundsAndNMEs/PGNMEPostProcessBaseMaterial.jpg"/>

Programmatically updated material: <Playground id="#WB27SW#3" title="NME Post Process Base Material Modification" description="Playground example of modifying a base Post Process material programmatically." image="/img/playgroundsAndNMEs/PGNMEPostProcessBaseMaterialModification.jpg"/>


## Creating Procedural textures

Starting with Babylon.js v4.2, you can now create procedural textures with the node material editor.

You need simply to change the mode to _Procedural texture_ this time:

Some blocks are made unavailable in this mode (they are hidden from the block list), as they have no meaning: the mesh, particle and animation blocks.

When you have created your procedural texture in the NME, you can create a regular `BABYLON.ProceduralTexture` instance by calling the `NodeMaterial.createProceduralTexture` method:

```javascript
const proceduralTexture = nodeMaterial.createProceduralTexture(256);
```

As always, you can also load the NodeMaterial from our snippet server:

```
var ground = BABYLON.MeshBuilder.CreateGround("ground", {width: 6, height: 6}, scene);

BABYLON.NodeMaterial.ParseFromSnippetAsync("#A7A3UB#1", scene).then((nodeMaterial) => {
    const proceduralTexture = nodeMaterial.createProceduralTexture(256);

    let mat = new BABYLON.StandardMaterial();

    mat.emissiveTexture = proceduralTexture;

    ground.material = mat;
});
```

Playground: <Playground id="#8S19ZC#1" title="NME Procedural Texture Example" description="Playground example of using the Node Material Editor to create a Procedural Texture." image="/img/playgroundsAndNMEs/PGNMEProceduralTexture.jpg" isMain={true} category="Node Material"/>

You can check out this video for more information:
<Youtube id="qqMuuSM7GvI"/>



## Node Material

The Node Material is a simple, highly customizable material that you can build yourself piece by piece. Combined with the powerful node-based editor, you can easily create stunning custom GPU shaders and FX for your Babylon.js scenes.

The Node Material allows you to avoid writing complicated shader language code, instead replacing it with simple processes of either using UI (the Node Material Editor) or by creating and connecting node blocks in your scene code (the Node Material blocks).

To get started, it's important to understand how the Node Material works under the hood, starting by learning how to create a Node Material using code.

### Creating a Node Material using code

#### Initial steps

If you are interested in learning how to create node materials through code, you might consider starting with the video below as it goes over 3 important tips to help you get started:

<Youtube id="GrmVObi6caQ"/>

To start using the Node Material, you just need to instantiating one:

```
var nodeMaterial = new BABYLON.NodeMaterial("node material", scene, { emitComments: true });
```

Please note that the third parameter will contain optional values that will let you configure how the material will build its shader:

- `emitComments`: Set this value to true if you want the blocks to emit comments in the shader code

#### Adding blocks

Blocks can be added by just instantiating them:

```
var morphTargets = new BABYLON.MorphTargetsBlock("morphTargets");
```

For input blocks, you can then define either their value or the source of the value:

```
var timeInput = new BABYLON.InputBlock("time");
timeInput.value = 0;
```

or

```
var viewProjectionInput = new BABYLON.InputBlock("viewProjection");
viewProjectionInput.setAsSystemValue(BABYLON.NodeMaterialSystemValues.ViewProjection);
```

System values can be:

- BABYLON.NodeMaterialSystemValues.World
- BABYLON.NodeMaterialSystemValues.View
- BABYLON.NodeMaterialSystemValues.WorldView
- BABYLON.NodeMaterialSystemValues.Projection
- BABYLON.NodeMaterialSystemValues.ViewProjection
- BABYLON.NodeMaterialSystemValues.WorldViewProjection
- BABYLON.NodeMaterialSystemValues.CameraPosition
- BABYLON.NodeMaterialSystemValues.FogColor
- BABYLON.NodeMaterialSystemValues.DeltaTime

Input blocks can also take their value from a mesh attribute:

```javascript
let positionInput = new BABYLON.InputBlock("position");
positionInput.setAsAttribute("position");
```

Attributes can be:

- position
- normal
- tangent
- uv
- uv2
- matricesIndices
- matricesWeights
- matricesIndicesExtra
- matricesWeightsExtra

When you manually set the value of an InputNode, you can flag it as `node.isConstant` to indicate that the value will not be dynamically updated and thus the node material will be able to optimize the block by not generating an uniform for this value.

The following functions will let you get information about your InputNode:

- `isSystemValue`
- `isAttribute`
- `isUniform`
- `isConstant`

When an InputNode is an uniform (eg. a manual value that will be sent to the shader) and not a constant, you can set `inputNode.visibleInInspector` to true so users will be able to visually control the value of the node using Babylon.js Inspector.

You can even csutomize the look and feel of the Inspector UI by defining `inputNode.min` and `inputNode.max` to get a slider instead of an input text box.

#### Connecting blocks

By default calling `block.connectTo(otherBlock)` will try to establish a connection by picking an output from the first block and connect it to an available input in the second one:

```javascript
var positionInput = new BABYLON.InputBlock("position");
positionInput.setAsAttribute("position");

var worldInput = new BABYLON.InputBlock("world");
worldInput.setAsSystemValue(BABYLON.NodeMaterialSystemValues.World);

var worldPos = new BABYLON.TransformBlock("worldPos");
positionInput.connectTo(worldPos);
worldInput.connectTo(worldPos);
```

If you do not want to use the automatic connection you can then pick the output and the input you want to connect directly:

```javascript
worldInput.output.connectTo(boneBlock.world);
```

You can check if two connection points can connect with

```javascript
if (worldInput.output.canConnectTo(boneBlock.world)) {
    ...
}
```

The system will throw an exception if you try to connect two incompatible connection points.

When connected, two connection points can be disconnected with:

```javascript
worldInput.output.disconnectFrom(boneBlock.world);
```

#### Gettings blocks

Once a graph is built inside a NodeMaterial, you can use the following API to get a specific node by name:

```javascript
let block = nodeMaterial.getBlockByName("MyBlock");
```

You can also get a block using a predicate:

```javascript
let block = nodeMaterial.getBlockByPredicate((b) => b.getClassName() === "AddBlock" && b.name === "foo");
```

Or you can also use this API to get an InputNode and use it to setup its value if the node is set manual value:

```javascript
let block = nodeMaterial.getInputBlockByPredicate((b) => b.name === "foo");
block.value = 10;
```

Note that while this API generically works for all input blocks, not all input blocks have a "value" attribute. For example texture blocks would have block.texture instead of block.value. Be sure to check the [API documentation](/typedoc/classes/babylon.nodematerial) for detail.

You can access the list of InputBlocks with:

```javascript
nodeMaterial.getInputBlocks();
```

Or you can get all blocks registered with a node material with:

```javascript
nodeMaterial.attachedBlocks;
```

Be sure to also check out the full [API documentation.](/typedoc/classes/babylon.nodematerial)

#### Building the Node Material

Once setup, you can ask the Node Material to build its internal shaders (vertex and fragment) by calling `nodeMaterial.build(true)`. You can set the boolean parameter to true to get a log of the final shaders on the console.

The build function will throw an exception if the shaders cannot be compiled:

```javascript
try {
  nodeMaterial.build(true);
} catch (err) {
  console.log("Unable to compile because " + err);
}
```

Once successfully built, you can use the Node Material like any other materials:

```javascript
myMesh.material = nodeMaterial;
```

#### Example

Here is one of the simplest code using the Node Material:

```javascript
var nodeMaterial = new BABYLON.NodeMaterial("node material", scene, { emitComments: true });
var positionInput = new BABYLON.InputBlock("position");
positionInput.setAsAttribute("position");

var worldInput = new BABYLON.InputBlock("world");
worldInput.setAsSystemValue(BABYLON.NodeMaterialSystemValues.World);

var worldPos = new BABYLON.TransformBlock("worldPos");
positionInput.connectTo(worldPos);
worldInput.connectTo(worldPos);

var viewProjectionInput = new BABYLON.InputBlock("viewProjection");
viewProjectionInput.setAsSystemValue(BABYLON.NodeMaterialSystemValues.ViewProjection);

var worldPosdMultipliedByViewProjection = new BABYLON.TransformBlock("worldPos * viewProjectionTransform");
worldPos.connectTo(worldPosdMultipliedByViewProjection);
viewProjectionInput.connectTo(worldPosdMultipliedByViewProjection);

var vertexOutput = new BABYLON.VertexOutputBlock("vertexOutput");
worldPosdMultipliedByViewProjection.connectTo(vertexOutput);

// Pixel
var pixelColor = new BABYLON.InputBlock("color");
pixelColor.value = new BABYLON.Color4(0.8, 0.8, 0.8, 1);

var fragmentOutput = new BABYLON.FragmentOutputBlock("fragmentOutput");
pixelColor.connectTo(fragmentOutput);

// Add to nodes
nodeMaterial.addOutputNode(vertexOutput);
nodeMaterial.addOutputNode(fragmentOutput);
```

Please note that this code is equivalent to:

```javascript
var nodeMaterial = new BABYLON.NodeMaterial("node material", scene, { emitComments: true });
nodeMaterial.setToDefault();
```

Here's an advanced and fantastic example of creating an impressive Node Material manually.
<Playground id="#GETMGI#2" title="Advanced Dissolve Node Material" description="Advanced Node Material shader created manually."/>

### Using the Node Material Editor

Now that you've learned how the system works and understand how you can use it to create complex shaders more quickly than learning a new shader language, you should probably know that it can actually get even easier!

The [Node Material Editor](/toolsAndResources/tools/nme) is an incredibly powerful tool that allows you to create and connect blocks in a simple visual editor.

![NME](/img/how_to/Materials/nme.jpg)

To invoke the editor you can call `nodematerial.edit()` but this code must be called inside a user interaction (like a click event). You can also call it through the Inspector:

```javascript
scene.debugLayer.show();
scene.debugLayer.select(nodeMaterial);
```

When selected in the Inspector, you can find an edit button in the Node Material property pane.

You can also use a standalone version of the editor here: <NME id="" title="Node Material Editor" description="The starting basic template for creating Node Materials." image="/img/playgroundsAndNMEs/nodeMaterial.jpg"/>

Learn more about the [Node Material Editor here](/toolsAndResources/tools/nme).

### Recreating the StandardMaterial

As a training exercise and to show what is possible to do with the Node Material Editor, the `StandardMaterial` has been recreated in the NME:

- <NME id="#AT7YY5#6" title="Full Standard Material NME" description="A Node Material Editor setup of the full standard material." image="/img/playgroundsAndNMEs/NMEfullStandardMaterial.jpg"/>
- <NME id="#AT7YY5#7" title="Standard Material Without Alpha NME" description="A Node Material Editor setup of the standard material without alpha support." image="/img/playgroundsAndNMEs/NMEstandardMaterialNoAlpha.jpg"/>
- <Playground id="#M5VQE9#19" title="Playground of Standard Material and NME Standard Material" description="Playground to compare the existing `StandardMaterial` and the corresponding Node Material." image="/img/playgroundsAndNMEs/PGstandardMaterialNMEstandardMaterial.jpg" isMain={true} category="Node Material"/>

Note that the only difference between the full material and the material without alpha support is that nothing is wire to the `fragmentOutput.a` input. If you don't need alpha support, you should use the "non alpha" node material as alpha-based materials have some constraints:

- they don't write to the zbuffer and are only sorted among themselves, so some sorting rendering artifacts can arise
- they need the `transparencyShadow` property to be `true` for shadow rendering

Let's see how the material has been created and how to use it.

#### Main building frames

The material is divided into several frames, mirroring the main features of the standard material:

- Instances
- Morphs and bones
- Ambient
- Diffuse
- Specular
- Reflection
- Emissive
- Bump (normal map)
- Opacity
- Lightmap
- Vertex color
- Fog

In each of these frames, you generally find a boolean float node that enable/disable the feature, and possibly some other properties to fine-tune the feature. Most of these properties are **Constant** properties, meaning they won't consume a _uniform_ in the shaders and won't be visible in the Inspector / be updatable in javascript: you must change their value directly in the material (they correspond to the `#define` you can find in the standard material shader code).

Note that you won't find this enable/disable property in the **Instances**, **Morphs and bones** and **Fog** frames: they are always enabled. That's because they depend on the mesh geometry / settings (or on a scene setting for **Fog**): those frames will be a simple "pass-through" if the corresponding feature doesn't exist on the mesh / scene, so no need to explicitly disable it in that case.

#### Additional building frames

There are a number of additional frames that help organizing the graph more cleanly:

- Final normal. This frame takes the output from the **Bump** frame and builds the final world normal used in subsequent computations (**Reflection** and **Lights**). You can change the `TWOSIDEDLIGHTING` boolean if you want the lighting to be applied whatever the triangle side facing are.
- Final diffuse computation. It is the frame responsible for computing the final diffuse component, taking into account the ambient, emissive and vertex color components. Here you can modify the `LINKEMISSIVEWITHDIFFUSE` and `EMISSIVEASILLUMINATION` booleans to change the way the diffuse value is computed.
- Final color computation. Everything is brought together to compute the final rgb color: ambient (texture), specular, reflection and emissive.
- Final alpha computation. After the opacity (alpha) is generated from the **Opacity** frame, a number of additional computation is performed to produce the final alpha value. You can step in this computation by mean of two booleans, `REFLECTIONOVERALPHA` and `SPECULAROVERALPHA`.
- Premultiply alpha to color. This one does what its title says and is enabled by the `PREMULTIPLYALPHA` boolean.

#### Construction notes

The material itself is not so complicated as each feature is generally restricted to its own frame and has few connections with other frames. That helps to keep each building block manageable and easily understandable.

Below are a few things of note.

#### Working without a `if` statement

As you may know, there's no `if` statement / block in the node material editor, so one must be creative to overcome this. Luckily, the standard material does not use this statement heavily (as it's better to avoid it for performance sake), so it is easy enough to deal with it. Most of the time, it is something like `if boolean is true, use this value in subsequent computation, else use that other value instead`. A **Lerp** block is the tool to use:

```c
Lerp(a, b, gradient)
```

`gradient` is the boolean: if it is 0, `a` is the output, if it is 1, `b` is the output. Then use the output in subsequent computation.

Example:

![Emissive](/img/how_to/Materials/nme_lerp.png)

If `EMISSIVE` is set to 0, the output is `vEmissiveColor`, else it is the color from the emissive map. In effect, the `EMISSIVE` boolean lets you choose to use either the constant `vEmissiveColor` color or the color from the texture map as the emissive color.

#### Discarding the fragment based on alpha cutoff value

This construct is meant to discard the fragment if alpha testing is enabled and if the alpha value is below some threshold value (cutoff value). It looks like this:

![Discard](/img/how_to/Materials/nme_discard.png)

As you can see, the `alphaCutOff` node is not directly connected to the `cutoff` input of **Discard** (the **Discard** block will discard the fragment if the `value` input is lower than the `cutoff` input). That's because we need to let the user enable or disable this feature.

What it does instead is comparing the alpha value from the diffuse texture to `ALPHATEST - 1 + alphaCutOff`, `ALPHATEST` being the boolean value that lets the user enable (1) or disable (0) the feature.

If `ALPHATEST = 1`, the computed value is `alphaCutOff`, which is the expected input for `Discard.cutoff` in that case (alpha testing is enabled).

If `ALPHATEST = 0`, the computed value is `-1 + alphaCutOff`. As `alphaCutOff` is a value between 0 and 1, `-1 + alphaCutOff` will always be lower or equal to 0. So, `Discard.cutoff` &lt;= 0 in that case, meaning the fragment will never be discarded (which is the expected result when alpha testing is disabled).

You could also have used `Lerp(0, alphaCutOff, ALPHATEST)` as the input for `Discard.cutoff`, but it's likely that the addition + subtraction used above is faster than a `Lerp` on GPUs (would need some benchmarking to be sure), even if it's by a small (negligible) margin.

### Loading from a file saved from the Node Material Editor

You can directly setup a Node Material from a file saved from the Node Material Editor.

Here is the code to use:

```javascript
let nodeMaterial = await BABYLON.NodeMaterial.ParseFromFileAsync("Name For Your Shader", "URL To Your Saved Shader", scene);
```

Here's an example of how to load a saved shader file and apply it to a mesh.

<Playground id="#APVSUF" title="Load a Saved Shader File" description="Load a saved shader file and apply it to the material of a mesh."/>

### Sharing unique URLs

When using the <NME id="" title="Node Material Editor" description="The starting basic template for creating Node Materials." image="/img/playgroundsAndNMEs/nodeMaterial.jpg"/>, you can have an additional option to save your work using a unique URL (like the Playground for instance). You can then share these urls (which are immutable).

Example: <NME id="#2F999G" title="Node Material Editor Unique URL Example" description="Example Node Material Editor saved with a unique URL." image="/img/playgroundsAndNMEs/NMEsnippetServerSaveExample.jpg"/>

### Loading from a snippet (unique URL)

You can use the following code to load a saved node material from a unique URL:

```javascript
BABYLON.NodeMaterial.ParseFromSnippetAsync("2F999G", scene).then((nodeMaterial) => {
  sphere.material = nodeMaterial;
});
```

When using NME within the Playground, you have the opportunity to edit your material with the Inspector and let the Playground update your snipped id automatically (each time NME will save a new snippet id it will inform the playground to also change the id in your code.

And to begin with you can simply call this code to start a new Node Material from scratch:

```javascript
BABYLON.NodeMaterial.ParseFromSnippetAsync("_BLANK", scene).then((nodeMaterial) => {
  sphere.material = nodeMaterial;
});
```

Note:

- There is a use case where you may want to load a node material, but ignore any embedded or linked textures stored in the json. This could be where you are going to supply new textures in code and you don't want to incur the cost of loading the old textures or if you are reusing a node material from an old project where only the textures need to be updated. To do this, place this static property in your code before creating or loading your node materials:

```javascript
BABYLON.NodeMaterial.IgnoreTexturesAtLoadTime = true;
```

And then from there you could have used the Inspector to edit it (The inspector can replace the \_\_BLANK with the right id later on).

### Node material examples

Here are some node material examples that you can use "as is" or extend with the NME:

- <Playground id="#9B0DNU#36" title="Incredible NME Ocean Shader" description="Incredible NME Ocean Shader." isMain={true} category="Node Material"/>
- <NME id="#I4DJ9Z" title="GridMaterial Recreated in the Node Material Editor" description="Example Node Material Recreation of the GridMaterial." image="/img/playgroundsAndNMEs/NMEgridMaterial.jpg" isMain={true} category="Materials"/>
- <NME id="#YDGZCJ" title="'Mist' Post Process in the Node Material Editor" description="Example Node Material 'Mist' Post Process Effect." image="/img/playgroundsAndNMEs/NMEmistPostProcess.jpg"/>
- <NME id="#D0USYC" title="'Dissolve' Post Process in the Node Material Editor" description="Example Node Material 'Dissolve' Post Process Effect." image="/img/playgroundsAndNMEs/NMEdissolvePostProcess.jpg"/>



## How To use the Node Material with Particles

The Node Material Editor (aka NME) is a powerful tool that can be used to design shaders, [particles](/features/divingDeeper/materials/node_material/nodeMaterial#creating-particle-shaders), and [post processes](/features/divingDeeper/materials/node_material/nodeMaterial#creating-post-processes).

This article will help you set up a simple scene that will contain only a few lines of code, because all of the work will be done using our editors.

You can see the final result here: 

<Playground id="#RA18GJ" title="Node Material With Particles" description="Simple example of using the node material to create a particle fragment shader." image="/img/playgroundsAndNMEs/features/divingDeeperNodeMaterialParticle1.jpg"/>

## Setting up the scene

Setting up this scene is actually quite simple. We only need a scene, a camera, and a sphere to act as the particle emitter:

```
var scene = new BABYLON.Scene(engine);

var camera = new BABYLON.ArcRotateCamera("Camera", 0, 0.8, 10, BABYLON.Vector3.Zero(), scene);
camera.attachControl(canvas, true);

// Create a random emitter
var sphere = BABYLON.MeshBuilder.CreateSphere("sphere", {diameter: 0.01, segments: 4}, scene);
```

## Invoking the inspector to create our particle system

If you are executing this code in the [Playground](https://playground.babylonjs.com), you can simply click on the Inspector button inside the header bar.

If you are running the code on your own, you can call `scene.debugLayer.show()`.

Once there, you can right click on the "Particle Systems" node to create a new particle system:

![Create new system](/img/how_to/Particles/create_new_system.jpg)

The inspector will then let you play with all the parameters to define the system the way you want.

When you're done setting up your system, you can go to the Snippet zone and click "Save to Snippet Server":

![Save a snippet](/img/how_to/Particles/save_snippet.jpg)

This will give you a snippet ID that we will use later to load the particle system from our code.

You can see my setup in this playground:

<Playground id="#KST50Y" title="Particles Created In the Inspector" description="Simple example showing particles saved and loaded from the snippet server."/>

## Working with the snippet server

The beauty of the snippet server is that it gives you a central place to store and update your particle system without having to modify your code.

We can use the [async/await pattern](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) in our example to load a snippet asychronously. We can flag our function as `async` and then `await` a link to our particle system using the snippet ID:

```
var createScene = async function () {

    var scene = new BABYLON.Scene(engine);

    var camera = new BABYLON.ArcRotateCamera("Camera", 0, 0.8, 10, BABYLON.Vector3.Zero(), scene);
    camera.attachControl(canvas, true);

    // Create a random emitter
    var sphere = BABYLON.MeshBuilder.CreateSphere("sphere", {diameter: 0.01, segments: 4}, scene);

    // Load the previously setup particle system (it was setup with the inspector)
    let system = await BABYLON.ParticleHelper.CreateFromSnippetAsync("T54JV7#13", scene, false);
    system.emitter = sphere;

    return scene;
};
```

As you can see, you can simply call `BABYLON.ParticleHelper.CreateFromSnippetAsync` to download your particle system from the snippet server.

If you do not want to (or cannot) use async / await, you can get the same outcome using Promises:

```
BABYLON.ParticleHelper.CreateFromSnippetAsync("T54JV7#13", scene, false).then(system => {
    system.emitter = sphere;
});
```

## Creating the node material for our particle system

We are going to use the same approach for the node material.

To setup our material, let's open the NME at [https://nme.babylonjs.com/](https://nme.babylonjs.com/)

The NME can be used for materials, particles and postprocesses. We'll switch to particles mode:

![Particle mode in NME](/img/how_to/Particles/nme_particle.jpg)

For this demo, I created a material where the particles are displayed with one texture when above ground (y = 0) and with another one below ground, with a smooth transition between the two. Here is the the shader I ended up with: <NME id="#345ATT#4" title="Node Material Particle Shader Example" description="Simple example of using the node material to create a particle fragment shader." image="/img/playgroundsAndNMEs/divingDeeperNodeMaterialParticle2.jpg"/>

![Demo shader](/img/how_to/Particles/demo_shader.jpg)

In a nutshell, I'm checking the particle position in world space and using a [smoothstep](https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/smoothstep.xhtml) to output a value between 0 and 1, which is then used with a gradient between black and white. This color is then used to mix (lerp) between two textures.

Just like the particle system, you can save your creation to the snippet server and gets a snippet Id.

## Applying the material
The final step is to get that shader from the snippet server and use it with our particle system.

To do so, we will use the exact same approach as before:
```
// Load our node material
let nodeMaterial = await BABYLON.NodeMaterial.ParseFromSnippetAsync("#345ATT#4", scene);

// Apply it to the particle system
nodeMaterial.createEffectForParticles(system);
```

As you can see the NodeMaterial class has a handy function to apply it to a particle system.

And voila! 
The final code is extremely simple (thanks to async/await in particular):

```
var createScene = async function () {

    var scene = new BABYLON.Scene(engine);

    var camera = new BABYLON.ArcRotateCamera("Camera", 0, 0.8, 10, BABYLON.Vector3.Zero(), scene);
    camera.attachControl(canvas, true);

    // Create a random emitter
    var sphere = BABYLON.MeshBuilder.CreateSphere("sphere", {diameter: 0.01, segments: 4}, scene);

    // Load the previously setup particle system (it was setup with the inspector)
    let system = await BABYLON.ParticleHelper.CreateFromSnippetAsync("T54JV7#13", scene, false);
    system.emitter = sphere;

    // Load our node material
    let nodeMaterial = await BABYLON.NodeMaterial.ParseFromSnippetAsync("#345ATT#4", scene);
    
    // Apply it to the particle system
    nodeMaterial.createEffectForParticles(system);

    return scene;
};
```

## Automatic updates

The best part is that our Playground can evolve automagically. If you open the main Playground (referenced at the beginning of this article), you can keep editing the particle system or the material, and your code will automatically update. This happens every time open the Inspector and use one of the editors. When you click "Save to Snippet Server", the system will be smart enough to work with the Playground and update the link for you:

![Automatic update](/img/how_to/Particles/auto-pg.gif)

You can see in the GIF that the Snippet ID for the particle system is updated to version #14 when I hit the save button.

Now that we know about that automatic update,there was another option to create the initial particle. You could have called the CreateFromSnippetAsync with a "__BLANK" id:

```
BABYLON.ParticleHelper.CreateFromSnippetAsync("_BLANK", scene, false).then(system => {
    system.emitter = sphere;
});
```

And then from there you could have used the Inspector to edit it (The inspector can replace the __BLANK with the right id later on)


## Node Material

The Node Material is a new kind of material available from Babylon.js v4.1. It will let you create a new material by assembling building blocks, or nodes, quickly and easily. These nodes define how vertex and pixel shaders will behave by assembling the nodes in the order needed.

This way you will be in control of everything related to the rendering of our meshes without having to learn GLSL. Furthermore, thanks to our library of predefined nodes, you will be able to reuse entire portions of the Babylon.js engine by just adding a new node for lighting, fog, bones, etc..


Here's what [Wikipedia](https://en.wikipedia.org/wiki/Compute_kernel) has to say about compute shaders:
> In computing, a compute kernel is a routine compiled for high throughput accelerators (such as graphics processing units (GPUs), digital signal processors (DSPs) or field-programmable gate arrays (FPGAs)), separate from but used by a main program (typically running on a central processing unit). They are sometimes called compute shaders, sharing execution units with vertex shaders and pixel shaders on GPUs, but are not limited to execution on one class of device, or graphics APIs.

Note that in Babylon.js this is a [WebGPU](/features/advanced_topics/webGPU) feature only (starting at v5.0), WebGL does not support compute shaders.

You can query the engine for compute shader support by doing:
```javascript
engine.getCaps().supportComputeShaders
```

## Creating a compute shader
Use the `ComputeShader` class to create a computer shader, much like you would use `ShaderMaterial` to create a material for some custom shader code:
```javascript
const cs1 = new BABYLON.ComputeShader("myCompute", engine, { computeSource: copyTextureComputeShader }, { bindingsMapping:
    {
        "dest": { group: 0, binding: 0 },
        "src": { group: 0, binding: 2 }
    }
});
```
`copyTextureComputeShader` is the shader code and `bindingsMapping` an object that maps an input variable name (from the shader source code) to its binding location: see below for more explanations.

Once you have created the compute shader instance, you can set the input values by using the appropriate methods (see [ComputeShader class](/typedoc/classes/babylon.computeshader)):
```javascript
cs1.setTexture("src", src);
cs1.setStorageTexture("dest", dest);
```

A compute shader can be executed by calling one of the `dispatch()` or `dispatchWhenReady()` methods.

## Types of variables passed to compute shaders
Variables you pass to a compute shader can be of the following types:
* **texture**. Use `ComputeShader.setTexture()` to pass a regular texture to the shader.
* **storage texture**. A storage texture is a texture you can write to from your compute shader. Note that you can't read from a storage texture, only write to it. If you wrote something in a storage texture and need to read from it in a shader, simply pass it as a regular texture. In Babylon.js, storage textures are created as regular textures but pass a special flag for the `creationFlag` parameter: `BABYLON.Constants.TEXTURE_CREATIONFLAG_STORAGE`. There are also two helper methods that you can use to create storage textures: `BABYLON.RawTexture.CreateRGBAStorageTexture()` and `BABYLON.RawTexture.CreateRStorageTexture()`. Use `ComputeShader.setStorageTexture()` to pass a storage texture to the shader.
* **uniform buffer**. It's a buffer you can create by instantiating the `UniformBuffer` class and that can be used to pass some constant values to the shader side (values that still can be updated in the course of your program - they are constants inside the shader). Note that you need to first create the layout of this buffer by calling the `addUniform` method **in the order the properties appear in the buffer in the shader code**! The last point is important as the layout you create must match the layout of the buffer as used in the shader code. Once you have created the layout, you can set some values through calls to the `updateXXX()` methods. Once you are ready to update the buffer on the GPU side, call `update()`. Use `ComputeShader.setUniformBuffer()` to pass a uniform buffer to the shader.
* **storage buffer**. This is an arbitrary buffer that you can use to read or write values. Use the `StorageBuffer` class to create such buffers. Use `ComputeShader.setStorageBuffer()` to pass a storage buffer to the shader.
* **sampler**. This is a custom texture sampler object that you can use to sample a texture. Use the `TextureSampler` class to create one and `ComputeShader.setTexturesSampler()` to pass a texture sampler to the shader. See the next section for more explanations about texture samplers.

## Shader language and input bindings
The compute shader must be written in [WGSL](https://gpuweb.github.io/gpuweb/wgsl/), which is the shader language used by [WebGPU](/features/advanced_topics/webGPU).

As GLSL shaders can be stored in `ShaderStore.ShadersStore`, WGSL shaders can be stored in `ShaderStore.ShadersStoreWGSL` and you can pass the name of the key used to store the shader in this object to the `ComputeShader` constructor. You can also directly pass the shader code to the constructor (as done in the example above).

Browsers do not currently support reflection for WGSL shaders, meaning we are not able to automatically retrieve the binding and group values of the input variables, as seen here:
```wgsl
@group(0) @binding(0) var dest : texture_storage_2d<rgba8unorm, write>;
@group(0) @binding(1) var srcSampler : sampler;
@group(0) @binding(2) var src : texture_2d<f32>;
```
That's why you need to provide those bindings yourself when creating a new `ComputeShader` instance:
```javascript
const cs1 = new BABYLON.ComputeShader("myCompute", engine, { computeSource: copyTextureComputeShader }, { bindingsMapping:
    {
        "dest": { group: 0, binding: 0 },
        "src": { group: 0, binding: 2 }
    }
});
```
Note that for a (sampled) texture variable as `src` in the example above, you can instruct the system to automatically bind the sampler corresponding to the texture. To do that, you must declare the sampler with a binding value equal to the binding value of the texture minus 1 and you should pass `true` as the 3rd parameter of the `setTexture()` call (or don't pass anything, as `true` is the default value). In this case, you must **not** add this sampler in the `bindingsMapping` object.

If you don't need/want to auto-bind the sampler corresponding to a texture, you can instruct the system not to bind the sampler by passing `false` as the 3rd parameter to `ComputeShader.setTexture()`.

You can also bind your own sampler by creating one (see the [TextureSampler class](/typedoc/classes/babylon.texturesampler)) and use the `ComputeShader.setTextureSampler()` method:
```javascript
const cs1 = new BABYLON.ComputeShader("myCompute", engine, { computeSource: copyTextureComputeShader }, { bindingsMapping:
    {
        "dest": { group: 0, binding: 0 },
        "srcSampler": { group: 0, binding: 1 },
        "src": { group: 0, binding: 2 }
    }
});
const sampler = new BABYLON.TextureSampler().setParameters();
cs1.setTextureSampler("samplerSrc", sampler);
```
In that case, you must add this sampler in the `bindingsMapping` object.

## Examples

### Simple compute shaders

<Playground id="#3URR7V#171" engine="webgpu" title="Simple compute shaders" description="A simple example of creating various compute shaders" image="/img/extensions/webgpu/simpleComputeShader.png"/>

This PG creates 3 compute shaders:
* the first one is loading a texture and copying it into another texture by means of a compute shader. This texture is then applied on the ground. **Warning**: it is for demonstration purpose only, don't use this compute shader in real code, a simple copy buffer would be enough to achieve the same thing!
* the second one is clearing a texture with a constant value and applying it to the sphere. Once again, **don't use it in real code**! Note that we don't use `addUniform` to create the layout of the uniform buffer: when there's a single property in a uniform buffer, calling `updateXXX()` to set the value of the property will also create the layout.
* the third one is computing the multiplication of two matrices. It uses 3 storage buffers, 2 for the two input matrices and one for the result. The result buffer is then read and dumped to the console log. It is a direct port of [Get started with GPU Compute on the Web](https://developers.google.com/web/updates/2019/08/get-started-with-gpu-compute-on-the-web).

### Image Blur

<Playground id="#3URR7V#173" engine="webgpu" title="Blur compute shader" description="This example shows how to blur an image using a WebGPU compute shader" image="/img/extensions/webgpu/blur.png"/>

This is a direct port of the WebGPU sample [imageBlur](http://austin-eng.com/webgpu-samples/samples/imageBlur).

Note that in the sample we are calling `dispatchWhenReady()` for the first compute shader to be sure the compute effect is ready before going on, but for the next shaders we simply call `dispatch()` because as they are using the same shader code we are sure the effect will be ready (as it is the same one).

### Compute Boids

<Playground id="#3URR7V#176" engine="webgpu" title="Boids compute shader" description="A GPU compute particle simulation that mimics the flocking behavior of birds" image="/img/extensions/webgpu/boids.png"/>

This is a direct port of the WebGPU sample [computeBoids](http://austin-eng.com/webgpu-samples/samples/computeBoids).

It is a compute shader that updates two ping-pong buffers which store particle data. The data is used to draw instanced particles.

Note that it is using the (new in 5.0) `Mesh.forcedInstanceCount` property to set an instance count for a mesh that has no instances (`InstancedMesh`) but that we would like to render multiple times because we provide the appropriate vertex buffers manually.

As the storage buffers we use to compute the particle positions and velocities will be used as (instanced) vertex buffers, we must flag them as `BUFFER_CREATIONFLAG_VERTEX` at creation time (see the `new BABYLON.StorageBuffer(...)` calls in the code).

### Hydraulic erosion

<Playground id="#C90R62#13" engine="webgpu" title="Hydraulic erosion" description="Simulate erosion to make terrains look more natural"/>

This is a port of the great project [Hydraulic-Erosion](https://github.com/SebLague/Hydraulic-Erosion): all credits to sebastlague@gmail.com!

The generation of the terrain and the simulation of the erosion is done by using two different compute shaders.

Note that this sample also works in WebGL2 where compute shaders are not available but you should be careful when setting the parameters: don't raise too much **Iterations**, **Radius**, **Max lifetime**, **Resolution** else you may stuck your browser as now the terrain generation and erosion processes are handled on the CPU side!

### Slime simulation

<Playground id="#GXJ3FZ#48" engine="webgpu" title="Slime simulation" description="Simulate organic-like agents"/>

This is a port of the great project [Slime-Simulation](https://github.com/SebLague/Slime-Simulation): all credits to sebastlague@gmail.com!

The implentation in WGSL is a little less pretty than the HLSL one because at the time of this writing WebGPU does not support read/write textures, so we had to use a storage buffer for the `TrailMap` texture. That means we need some copy buffer to texture and texture to buffer functions and we have to do 4 reads from `TrailMap` instead of a single one when we need to get a `vec4` (see the code), which is likely less performant than its HLSL counterpart.

### Ocean demo

<Playground id="#YX6IB8#55" engine="webgpu" title="Ocean demo" description="Ocean simulation" image="/img/extensions/webgpu/ocean.png"/>

This is a port of the great project [FFT-Ocean](https://github.com/gasgiant/FFT-Ocean): all credits to Ivan Pensionerov (https://github.com/gasgiant)!

This sample uses a lot of compute shader runs: there are around 200-250 compute shaders running each frame! Use F8 to show/hide the GUI (after you click anywhere in the rendering area to give focus to the canvas) and WASD to move.


Node Material

Node Material

In This Category

Node Material

The Node Material is a simple, highly customizable material that you can build yourself piece by piece. Combined with the powerful node-based editor, you can easily create stunning custom GPU shaders and FX for your Babylon.js scenes.

Node Material and PBR

Using Physically Based Rendering with the Node Material.

Node Material Post Processes

Learn how to create custom Post Process effects using the Node Material.

Node Material Procedural Textures

Learn how to create Proecedural Textures using the Node Material.

Node Material Particle Shaders

Learn how to create Particle Shaders using the Node Material.

Available Node Material Blocks

The Node Material is a simple, highly customizable material that you can build yourself piece by piece. Combined with the powerful node-based editor, you can easily create stunning custom GPU shaders and FX for your Babylon.js scenes.

Node Material and Particles

Learn how to use the node material editor to create particle shaders.