Writing Shaders in Babylon.js

Create a ShaderMaterial with GLSL

The BABYLON.ShaderMaterial class takes a name, a reference to the scene, a shader path or store key, and an options object that specifies which attributes and uniforms the shader expects. Unlike Three.js, Babylon.js does not automatically inject attribute declarations, so you must tell the engine which vertex attributes your shader reads (typically "position", "normal", and "uv") through the attributes array in the options.

The uniforms array in the options lists the names of uniform variables that Babylon.js should manage. The engine provides automatic uniforms for the world, view, projection, and world-view-projection matrices when you include them by name. You access these in GLSL as uniform mat4 world;, uniform mat4 viewProjection;, or uniform mat4 worldViewProjection;. The naming convention differs from Three.js, so developers porting shaders between engines need to adjust their matrix uniform names.

Setting uniform values from JavaScript uses typed setter methods on the material: material.setFloat("time", value), material.setVector3("lightDir", new BABYLON.Vector3(1, 1, 0)), material.setColor3("tint", new BABYLON.Color3(1, 0, 0)), and material.setTexture("diffuseMap", texture). These methods are called before rendering and push values to the GPU. The typed setters ensure that JavaScript values are correctly translated to GLSL types.

Material properties like backFaceCulling, alphaMode, wireframe, and depthFunction configure the GPU pipeline state around your shader, the same as with built-in materials. Setting material.needAlphaBlending = function() { return true; } enables transparency for the material, which controls when the mesh is rendered relative to opaque objects in the scene.

Use the Shader Store and External Files

Babylon.js provides multiple ways to store and reference shader source code. The BABYLON.Effect.ShadersStore is a global object where you can register shader source strings with named keys. A vertex shader stored as ShadersStore["myCustomVertexShader"] and a fragment shader as ShadersStore["myCustomFragmentShader"] can be referenced by the key "myCustom" when creating the ShaderMaterial. The engine appends "VertexShader" and "FragmentShader" suffixes automatically.

For HTML-based projects, you can place shader source in <script> tags with custom type attributes (like type="x-shader/x-vertex") and an ID that follows the same naming convention. The engine reads the script tag's text content as shader source. This approach keeps shaders visible in the HTML file, which some developers prefer for small projects or prototyping.

For larger projects, external shader files (.vertex.fx and .fragment.fx) are the cleanest approach. Place the files in a known directory, and pass the file path (without extensions) as the shader path when creating the ShaderMaterial. Babylon.js loads both files asynchronously using XMLHttpRequest. This separation of shader code from JavaScript logic makes version control cleaner and lets specialized shader developers work on .fx files independently.

The BABYLON.Effect.IncludesShadersStore handles reusable shader code fragments. You can register common functions (noise generators, lighting helpers, math utilities) as includes and reference them in your shaders with #include<includeName>. This prevents code duplication across multiple shader programs and mirrors the include system that Babylon.js uses internally for its built-in materials.

Build Materials with the Node Material Editor

The Node Material Editor (NME) is a browser-based visual tool for building Babylon.js materials without writing GLSL. You open it at nme.babylonjs.com, drag processing blocks onto a canvas, and connect them with wires that represent data flow. Each block performs a specific operation: texture sampling, math (add, multiply, lerp), transformations, lighting calculations, or output to the final material channels (diffuse color, alpha, vertex position).

The NME produces a NodeMaterial object that can be exported as JSON, saved to a file, and loaded in your game at runtime with BABYLON.NodeMaterial.ParseFromSnippetAsync() or from a JSON file. The loaded material behaves like any other Babylon.js material: you can assign it to meshes, update its input values programmatically, and it integrates with the engine's lighting and shadow systems.

Common NME patterns include PBR materials with custom detail overlays, animated UV-scrolling effects, vertex displacement for terrain or waves, and multi-texture blending controlled by height maps or noise. The visual feedback is immediate, as the NME shows a live preview of the material on a test mesh while you build it, making iteration fast and intuitive.

NodeMaterial is especially valuable for artists and technical artists who need to iterate on visual effects without modifying game code. A shader developer can build a NodeMaterial template with exposed input blocks (texture slots, color parameters, animation speed), and then artists can adjust those inputs in the editor or through the Babylon.js Inspector at runtime. This workflow separates the technical shader structure from the artistic tuning, which scales well in team environments.

With Babylon.js v8.0, the NME introduced the Loop node for iterative computations, enabling effects like multi-sample blur, ray marching, and iterative noise generation directly in the visual graph. This extends NodeMaterial's capabilities into territory that previously required custom GLSL.

Extend Standard Materials with Plugins

Babylon.js's Material Plugin system lets you inject custom shader code into the engine's standard and PBR materials. This is analogous to Three.js's onBeforeCompile approach, but structured as a formal API with defined injection points rather than string manipulation of generated shader source.

A material plugin registers custom uniform declarations, vertex shader modifications, and fragment shader modifications at specific points in the standard material's shader pipeline. You define which code runs before lighting, after lighting, or at other well-defined stages. The engine merges your custom code with the standard material's shader, preserving the full PBR lighting model, image-based lighting, shadow mapping, and fog while adding your custom effect.

Practical use cases include vertex displacement for wind or water animation on PBR-lit surfaces, custom fresnel effects on top of standard reflections, triplanar texture mapping for terrain that uses the PBR shading model, and custom detail textures that blend with the base material's normal and roughness maps. The plugin approach lets you add one specific custom behavior without reimplementing the entire PBR pipeline from scratch.

Plugins also support per-mesh configuration through custom defines. You can conditionally enable or disable plugin features per material instance, and the engine compiles separate shader variants for each configuration. This is more efficient than using if-statements in the shader, because the GPU does not pay for disabled features at all.

Manage Textures and Animated Uniforms

Textures in Babylon.js ShaderMaterial are set with material.setTexture("uniformName", texture). The engine handles texture unit assignment, binding, and sampler configuration automatically. You can use any Babylon.js texture type: Texture for 2D images, CubeTexture for environment maps, RawTexture for procedurally generated data, DynamicTexture for canvas-based content, and VideoTexture for video playback as a texture source.

For animated effects, update uniforms every frame using the scene's onBeforeRenderObservable. Register a callback that sets the time uniform (or any other per-frame value) before each render: scene.onBeforeRenderObservable.add(() => { material.setFloat("time", performance.now() / 1000.0); }). This observer pattern ensures that uniform updates happen at the right point in the frame lifecycle, after scene graph updates but before GPU submission.

Babylon.js also supports render target textures, which are framebuffer objects that you render into and then use as inputs for other materials. This is the mechanism behind reflection probes, refraction textures, and custom multi-pass rendering effects. A ShaderMaterial can read from a render target texture the same way it reads from any other texture, enabling effects like mirrors, security camera views, portals, and custom shadow maps.

For performance monitoring, the Babylon.js Inspector provides real-time statistics including draw calls, active texture count, shader compilation time, and per-material rendering cost. The Inspector can be toggled at runtime in development builds, making it the primary tool for diagnosing shader-related performance issues in Babylon.js projects.