
## Custom Blocks

Starting with v5.0, you can create custom blocks by wrapping plain [GLSL](https://www.khronos.org/opengl/wiki/OpenGL_Shading_Language) code. This can be handy when you have complicated code that would be difficult to recreate with the existing node material blocks.

### Register Custom Blocks with the NME

Currently, a custom block is described by a `.json` file that you must provide when registering a new custom block in the Node Material Editor:

![Register Custom Block](/img/how_to/Materials/customBlock_register.webp)

When you click the "+" icon to add (register) a new custom block, you will be prompted for the `.json` file that describes the block.

Here's how a **Multiply** custom block could be implemented:
```json
{
    "name": "CustomMultiply",
    "comments": "Multiplies the left and right inputs of the same type together",
    "target": "Neutral",
    "inParameters": [
        {
            "name": "left",
            "type": "AutoDetect"
        },
        {
            "name": "right",
            "type": "AutoDetect"
        }
    ],
    "outParameters": [
        {
            "name": "output",
            "type": "BasedOnInput",
            "typeFromInput": "left"
        }
    ],
    "inLinkedConnectionTypes" : [
        {
            "input1": "left",
            "input2": "right",
            "looseCoupling": false
        }
    ],
    "functionName": "multiply_{TYPE_left}",
    "code": [
        "{TYPE_output} myHelper_{TYPE_left}({TYPE_left} l, {TYPE_right} r) { return l * r; }",
        "void multiply_{TYPE_left}({TYPE_left} l, {TYPE_right} r, out {TYPE_output} result) {",
        "   result = myHelper_{TYPE_left}(l, r);",
        "}"
    ]    
}
```
Most of the properties should be self-explanatory. Here are the possible values for some of the properties:
* target: **Neutral**, **Vertex**, **Fragment**, **VertexAndFragment**
* in/out parameters: **Float**, **Int**, **Vector2**, **Vector3**, **Vector4**, **Color3**, **Color4**, **Matrix**, **Object**, **AutoDetect**, **BasedOnInput**
* in parameters only: **sampler2D**, **samplerCube**

As this block allows any type of input (**Float**, **Vector3**, etc., as the **AutoDetect** value shows for the **left** and **right** parameter types), the type of **output** is set to `BasedOnInput` to inherit the value of the input plugged into **left** (the value of `typeFromInput`) at runtime. Also, we want the types of the **left** and **right** inputs to be the same (once an input is plugged in, the other one should inherit the same type), which is why we have an `inLinkedConnectionTypes` section in the file.

As the types are not known at the time we create the .json file, we must reference them in the [GLSL](https://www.khronos.org/opengl/wiki/OpenGL_Shading_Language) code by using the special syntax `{TYPE_XXX}` where **XXX** is the name of an input/output: at runtime, these constructs will be replaced by the right type (**float**, **vec2**, etc).

Note that we used a `myHelper_{TYPE_left}` helper function only to demonstrate that you can use other functions in the code, you don't have to write all your code in the main function.

Lastly, the main function (the one exported in the **functionName** property) must return `void`, and the output parameter(s) it returns must be declared as **out** parameters of the function (see example).

### Using Custom Blocks

Custom blocks are no different from the other blocks, so you simply need to drag and drop a block from the list on the left into the main area:

![Register Custom Block](/img/how_to/Materials/customBlock_use.webp)

Here, the `myPerlin2D` block is a `Perlin2D` custom block (see the list of custom blocks in the left menu).

This block has been imported into the NME with this .json file:
```json
{
    "name": "Perlin2D",
    "comments": "Generates a Perlin noise single value given a vec2 and time",
    "target": "Neutral",
    "inParameters": [
        {
            "name": "p",
            "type": "Vector2"
        },
        {
            "name": "dim",
            "type": "Float"
        },
        {
            "name": "time",
            "type": "Float"
        }
    ],
    "outParameters": [
        {
            "name": "output",
            "type": "Float"
        }
    ],
    "functionName": "perlin",
    "code": [
        "float rand(vec2 co){return fract(sin(dot(co.xy ,vec2(12.9898,78.233))) * 43758.5453);}", 
        "float rand(vec2 co, float l) {return rand(vec2(rand(co), l));}", 
        "float rand(vec2 co, float l, float t) {return rand(vec2(rand(co, l), t));}", 
        "", 
        "void perlin(vec2 p, float dim, float time, out float result) {", 
        "   vec2 pos = floor(p * dim);", 
        "   vec2 posx = pos + vec2(1.0, 0.0);", 
        "   vec2 posy = pos + vec2(0.0, 1.0);", 
        "   vec2 posxy = pos + vec2(1.0);", 
        "   ", 
        "   float c = rand(pos, dim, time);", 
        "   float cx = rand(posx, dim, time);", 
        "   float cy = rand(posy, dim, time);", 
        "   float cxy = rand(posxy, dim, time);", 
        "   ", 
        "   vec2 d = fract(p * dim);", 
        "   d = -0.5 * cos(d * 3.14159265358979323846) + 0.5;", 
        "   ", 
        "   float ccx = mix(c, cx, d.x);", 
        "   float cycxy = mix(cy, cxy, d.x);", 
        "   float center = mix(ccx, cycxy, d.y);", 
        "   ", 
        "   result = center * 2.0 - 1.0;", 
        "}"
    ]    
}
```

Here's the link to the NME: <NME id="#3WEKUZ#1" title="Custom Perlin2D block" description="A node material that uses a custom Perlin2D block" image="/img/playgroundsAndNMEs/NMEPerlin2DCustomBlock.webp"/>

### Using Custom Blocks for Ray Marching
Ray marching is commonly used for rendering fractals, volumetric effects, and scenes with complex, procedural objects. It’s flexible and can handle a wide range of situations, but it can be computationally intensive, especially for complex scenes or objects with intricate geometry. Ray marching has been possible in Babylon.js since its inception through custom shaders. In Node Material, the way to enable it is by authoring custom blocks.

![An example of ray marching which fuses a rounded rectangular mesh with a sphere mesh](/img/tools/nme/rayMarchingExample.webp)

There is no universal ray marching block in Node Material, as each experience that uses ray marching may have different requirements. To learn how to get started with a custom block, we have an [in-depth article about using ray marching in node material](https://medium.com/@babylonjs/ray-marching-in-the-babylon-js-node-material-editor-967b5b8c269c) that includes simple and complex examples. The article also discusses the additional blocks that have been added to the Node Material Editor, like the `FragDepth` block, to support ray marching in a custom block.

Here are a couple of examples of ray marching. One is a simple example using a custom block in the Node Material Editor, and the other is a very complex example showing the power of ray marching with a custom shader in a Babylon.js Playground.

<NME id="#GD8DSL#27" title="Ray Marching Custom Block" description="A node material that uses a custom Ray Marching block" image="/img/playgroundsAndNMEs/rayMarchingNME.webp"/>

<Playground id="#M3QR7E#78" title="Snail Ray Marching Scene" description="A complex example of ray marching with a custom block." image="/img/playgroundsAndNMEs/rayMarchingSnail.webp"/>



## Custom Frames

<Youtube id="_bxAQM0pnzs"/>

<Youtube id="9wL777qGpiI"/>

![NME](/img/how_to/Materials/custom_frames_1.webp)

When using the Node Material Editor, we can create frames by holding Shift and dragging the mouse across nodes within the graph.

A frame is an easy way to group several nodes together and collapse them into a smaller group to declutter the graph and allow you to reuse certain node branches. We can rename the frame, change its color, and even make a note/comment about it.

When we collapse the frame, input and output ports that are linked to other nodes outside the frame will be exposed on the frame edges. (You can manually set a port to be exposed as well.) Here, we can edit the exposed ports by renaming them or even changing their order.

![NME](/img/how_to/Materials/custom_frames_2.webp)

We can export a frame by using the “Export” button.

Once exported, we can load it back into our project for future use by clicking the “+” symbol on the “Custom Frames” tab of the node menu in the left panel.

![NME](/img/how_to/Materials/custom_frames_3.webp)

By loading a custom frame, we can reuse it quickly just like any other node block. Custom frames will stay in this menu any time you open the Node Material Editor.

![NME](/img/how_to/Materials/custom_frames_4.webp)

We also have a library of custom frames available for you to leverage here: https://github.com/BabylonJS/Assets/tree/master/nme/customFrames

### Tile and Offset

This custom frame is primarily used to tile and/or offset `UV`s, but you can use it to modify any `Vector2`.

Example setup (you must set your texture to generate visible output):

![Tile and Offset](/img/resources/nme-custom-frames/tile-offset-setup.webp)

Some example values and the results are provided in the following table:

 tileX | tileY | offsetX | offsetY | result                                                                       
 ----- | ----- | ------- | ------- | ---------------------------------------------------------------------------- 
 1     | 1     | 0       | 0       | ![Tile and Offset](/img/resources/nme-custom-frames/tile-offset-1-1-0-0.webp)  
 2     | 4     | 0       | 0       | ![Tile and Offset](/img/resources/nme-custom-frames/tile-offset-2-4-0-0.webp)  
 3     | 1     | 0       | 0       | ![Tile and Offset](/img/resources/nme-custom-frames/tile-offset-3-1-0-0.webp)  
 1     | 1     | 0       | 0.5     | ![Tile and Offset](/img/resources/nme-custom-frames/tile-offset-1-1-0-05.webp) 

### UV Twirl

You can use this custom frame to twirl the UVs and create twirled textures.

Connect the custom frame:

![UV Twirl](/img/resources/nme-custom-frames/uv-twirl-setup.webp)

The output is the original texture:

![UV Twirl](/img/resources/nme-custom-frames/uv-twirl-start.webp)

By changing the `strength` value, the image gets twirled around the `center`:

![UV Twirl](/img/resources/nme-custom-frames/uv-twirl-twirled.webp)

### Screen Position

A normalized screen position from 0,0 (bottom left) to 1,1 (top right)

![Screen Position](/img/resources/nme-custom-frames/screen-position-setup.webp)

produces this output:

![Screen Position](/img/resources/nme-custom-frames/screen-position-output.webp)



## Overview

The [Smart Filters Editor](/toolsAndResources/sfe) (SFE) is used to compose multiple shaders into complex effects, while the [Node Material Editor](/toolsAndResources/nme) (NME) is used to create shaders. These tools can complement each other: NME can export static shader files that you can import into SFE and chain like any other block. To enable this, NME offers a special "Smart Filters" mode.

The workflow is file-based and follows three steps:

1. Build a shader in NME
2. Export the shader as an [annotated GLSL file](/features/featuresDeepDive/smartFilters/creatingNewBlocks#using-annotated-glsl-code)
3. Import the GLSL file into SFE

<br/>
If you're new to either, start by reading more about [Node Materials](/features/featuresDeepDive/materials/node_material/nodeMaterial) and [Smart Filters](/features/featuresDeepDive/smartFilters/introductionToSmartFilters).

## Example

![NME](/img/how_to/Materials/nmeToSfe.webp)
NME Source: <NME id="#QYN8UY#5" title="Halftone Shader" description="An example demonstrating how to create a Smart Filter-ready shader." />

## New NME Blocks

<Alert severity="info" title="Only Fragment Shader Support">Smart Filters are designed to support a set of screen-space optimizations—ones that don’t easily allow vertex shader customization. As a result, "Smart Filters" mode does not support the usual vertex shader capabilities of NME.</Alert>

Alongside the standard 2D-compatible NME blocks, the Smart Filters mode introduces a few specialized blocks:

### SmartFilterFragmentOutput

_Required._ Receives the final color output of the SFE block. Similar to a regular fragment output block, but distinct: since a SmartFilter composes multiple shaders together, this block doesn’t directly write to the final frame color.

### ScreenUV

_Optional._ Provides the screen quad’s UV coordinates in the range of 0-1. This is a preconfigured input block for use with Smart Filter’s UV system.

### SmartFilterTexture

_Optional._ Represents the sampling of a texture in a Smart Filter. If no `source` connection is provided, then this block also represents the texture itself.

Textures used in the Node Material graph are placeholders; they are not serialized on export. They will need to be reassigned after loading the block in SFE.

## Input Connection Points

By default, each InputBlock (and blocks with texture sources) is exposed as an input connection point in the exported SFE block. The value you assign to an InputBlock in NME becomes the default for that connection point.

<Alert severity="info" title="Constants">To keep an InputBlock from appearing as an input connection, set the `Type` field to `Constant` under its "Properties" tab.</Alert>

## Naming

To name the exported shader block, modify the `Name` of the Node Material. This field is located under the graph's "General" property tab.

To name the input connection points for the shader block, repeat the same steps as above for each of:

- Textures: rename the corresponding SmartFilterTextureBlock or, if its `source` point is connected, the ImageSourceBlock.
- All other inputs: rename their corresponding InputBlocks.

## Exporting

Once finished, use the `Export shaders for SFE` button under the graph's "File" property tab. This will download an annotated GLSL block definition file with the suffix `.block.glsl`. To import it into your SFE project, read about [using custom blocks in SFE](/toolsAndResources/sfe#custom-blocks).



## Creating Shaders The Easy Way

Creating shaders can be a dense and complicated process, often requiring knowledge of GLSL and a strong understanding of how shaders work. Starting with Babylon.js 4.1, the Node Material Editor was introduced. This visual editor lets you connect blocks together to make shaders. It's really that simple.

<img src="/img/how_to/Materials/nme1.webp" title="Babylon.js Node Material Editor"/>

You can jump in and play around with it here: <NME id="" title="Node Material Editor" description="The starting basic template for creating Node Materials."/>

For an introductory look at the Node Material Editor, check out where it all started with this video:

<Youtube id="34uIGJH0ySU"/>

When you're ready to learn more, head on over to the [Node Material Documentation](/features/featuresDeepDive/materials/node_material/nodeMaterial) for more info.

You can also dive into the API that powers it all here: [API documentation.](/typedoc/classes/babylon.nodematerial)

One handy tip in the Node Material Editor preview window is that you can CTRL+hover to see the RGB values.

<img src="/img/how_to/Materials/nmeRGBTrick.webp" title="Babylon.js Node Material Editor"/>


## Why Utility Blocks Matter

Utility blocks do not belong to a single runtime domain. Instead, they make graphs easier to inspect, shape, prototype, and connect to surrounding systems.

In practice, these are often the blocks that make authoring comfortable rather than merely possible.

## Logging And Inspection

### `ConsoleLog`

Use `ConsoleLog` when you want immediate visibility into what the graph is doing.

This is one of the best first-pass debugging tools because it requires almost no setup and pairs well with event blocks, constants, variables, or scene-derived values.

### `DebugBlock`

Use `DebugBlock` when you want to inspect a data stream in-place without changing its value.

This is especially useful in the middle of a longer chain where you want to see what value is actually flowing through the graph.

## Easing And Value Shaping

### `Easing`

Use `Easing` when a graph needs a standard easing transform instead of a strictly linear value progression.

### `BezierCurveEasing`

Use `BezierCurveEasing` when you want more custom control over the easing curve.

These blocks are especially helpful when graphs drive motion, animation blending, or timed transitions.

## Context And Integration

### `Context`

Use `Context` when the graph needs access to contextual data exposed by the flow-graph runtime.

This block helps bridge authored graph logic to the environment in which the graph executes.

### `FunctionReference`

Use `FunctionReference` when graph logic needs to hold or expose a function reference as data.

### `CodeExecution`

Use `CodeExecution` when the graph needs to bridge into a code-driven execution path.

This is an advanced integration tool and is most useful when a purely visual graph needs to cooperate with surrounding application logic.

## Choosing The Right Utility Block

- Use `ConsoleLog` for immediate, low-friction diagnostics.
- Use `DebugBlock` for in-graph value inspection.
- Use `Easing` or `BezierCurveEasing` when values should change more naturally over time.
- Use `Context`, `FunctionReference`, and `CodeExecution` when integrating graph logic with runtime context or external logic.


The Node Material Editor

Creating Shaders The Easy Way

Related videos

Further reading

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.

Coming next

Node Material Editor Custom Blocks

Learn all about how to create custom blocks in the super handy Node Material Editor.

Node Material Editor Custom Frames

Learn all about how to create custom frames in the super handy Node Material Editor.

Usage with the Smart Filter Editor

Learn how to create shader blocks for the Smart Filter Editor using Node Material Editor