File: NodeMaterial.md | Updated: 11/15/2025
Base class for all node materials.
Constructs a new node material.
The alpha test of node materials is by default inferred from the alphaTest property. This node property allows to overwrite the default and define the alpha test with a node instead.
If you don't want to overwrite the alpha test but modify the existing value instead, use materialAlphaTest.
Default is null.
The lighting of node materials might be influenced by ambient occlusion. The default AO is inferred from an ambient occlusion map assigned to aoMap and the respective aoMapIntensity. This node property allows to overwrite the default and define the ambient occlusion with a custom node instead.
If you don't want to overwrite the diffuse color but modify the existing values instead, use materialAO.
Default is null.
This node allows to modulate the influence of backdropNode to the outgoing light.
Default is null.
This node can be used to implement a variety of filter-like effects. The idea is to store the current rendering into a texture e.g. via viewportSharedTexture(), use it to create an arbitrary effect and then assign the node composition to this property. Everything behind the object using this material will now be affected by a filter.
const material = new NodeMaterial()
material.transparent = true;
// everything behind the object will be monochromatic
material.backdropNode = saturation( viewportSharedTexture().rgb, 0 );
Backdrop computations are part of the lighting so only lit materials can use this property.
Default is null.
This node can be used to influence how an object using this node material casts shadows. To apply a color to shadows, you can simply do:
material.castShadowNode = vec4( 1, 0, 0, 1 );
Which can be nice to fake colored shadows of semi-transparent objects. It is also common to use the property with Fn function so checks are performed per fragment.
materialCustomShadow.castShadowNode = Fn( () => {
hash( vertexIndex ).greaterThan( 0.5 ).discard();
return materialColor;
} )();
Default is null.
Allows to overwrite the geometry position used for shadow map projection which is by default positionLocal, the vertex position in local space.
Default is null.
The diffuse color of node materials is by default inferred from the color and map properties. This node property allows to overwrite the default and define the diffuse color with a node instead.
material.colorNode = color( 0xff0000 ); // define red color
If you don't want to overwrite the diffuse color but modify the existing values instead, use materialColor.
material.colorNode = materialColor.mul( color( 0xff0000 ) ); // give diffuse colors a red tint
Default is null.
Allows to overwrite depth values in the fragment shader.
Default is null.
The environment of node materials can be defined by an environment map assigned to the envMap property or by Scene.environment if the node material is a PBR material. This node property allows to overwrite the default behavior and define the environment with a custom node.
material.envNode = pmremTexture( renderTarget.texture );
Default is null.
Whether this material is affected by fog or not.
Default is true.
This node property can be used if you need complete freedom in implementing the fragment shader. Assigning a node will replace the built-in material logic used in the fragment stage.
Default is null.
This node property is intended for logic which modifies geometry data once or per animation step. Apps usually place such logic randomly in initialization routines or in the animation loop. geometryNode is intended as a dedicated API so there is an intended spot where geometry modifications can be implemented.
The idea is to assign a Fn definition that holds the geometry modification logic. A typical example would be a GPU based particle system that provides a node material for usage on app level. The particle simulation would be implemented as compute shaders and managed inside a Fn function. This function is eventually assigned to geometryNode.
Default is null.
Whether this material uses hardware clipping or not. This property is managed by the engine and should not be modified by apps.
Default is false.
This flag can be used for type testing.
Default is true.
Whether this material is affected by lights or not.
Default is false.
Node materials which set their lights property to true are affected by all lights of the scene. Sometimes selective lighting is wanted which means only some lights in the scene affect a material. This can be achieved by creating an instance of LightsNode with a list of selective lights and assign the node to this property.
const customLightsNode = lights( [ light1, light2 ] );
material.lightsNode = customLightsNode;
Default is null.
Discards the fragment if the mask value is false.
Default is null.
MRT configuration is done on renderer or pass level. This node allows to overwrite what values are written into MRT targets on material level. This can be useful for implementing selective FX features that should only affect specific objects.
Default is null.
The normals of node materials are by default inferred from the normalMap/normalScale or bumpMap/bumpScale properties. This node property allows to overwrite the default and define the normals with a node instead.
If you don't want to overwrite the normals but modify the existing values instead, use materialNormal.
Default is null.
The opacity of node materials is by default inferred from the opacity and alphaMap properties. This node property allows to overwrite the default and define the opacity with a node instead.
If you don't want to overwrite the opacity but modify the existing value instead, use materialOpacity.
Default is null.
This node can be used to define the final output of the material.
TODO: Explain the differences to fragmentNode.
Default is null.
The local vertex positions are computed based on multiple factors like the attribute data, morphing or skinning. This node property allows to overwrite the default and define local vertex positions with nodes instead.
If you don't want to overwrite the vertex positions but modify the existing values instead, use positionLocal.
material.positionNode = positionLocal.add( displace );
Default is null.
This node can be used to influence how an object using this node material receive shadows.
const totalShadows = float( 1 ).toVar();
material.receivedShadowNode = Fn( ( [ shadow ] ) => {
totalShadows.mulAssign( shadow );
//return float( 1 ); // bypass received shadows
return shadow.mix( color( 0xff0000 ), 1 ); // modify shadow color
} );
Default is null.
Allows to overwrite the position used for shadow map rendering which is by default positionWorld, the vertex position in world space.
Default is null.
Represents the type of the node material.
Overrides: Material#type
This node property can be used if you need complete freedom in implementing the vertex shader. Assigning a node will replace the built-in material logic used in the vertex stage.
Default is null.
Builds this material with the given node builder.
builder | The current node builder.
---|---
Copies the properties of the given node material to this instance.
source | The material to copy.
---|---
Overrides: Material#copy
Returns: A reference to this node material.
Allows to define a custom cache key that influence the material key computation for render objects.
Overrides: Material#customProgramCacheKey
Returns: The custom cache key.
Most classic material types have a node pendant e.g. for MeshBasicMaterial there is MeshBasicNodeMaterial. This utility method is intended for defining all material properties of the classic type in the node type.
material | The material to copy properties with their values to this node material.
---|---
Setups the vertex and fragment stage of this node material.
builder | The current node builder.
---|---
Setups the clipping node.
builder | The current node builder.
---|---
Returns: The clipping node.
Setups the depth of this material.
builder | The current node builder.
---|---
Setups the computation of the material's diffuse color.
builder | The current node builder.
---|---
geometry | The geometry.
Setups the environment node from the material.
builder | The current node builder.
---|---
Returns: The environment node.
Setup the fog.
builder | The current node builder.
---|---
outputNode | The existing output node.
Returns: The output node.
Setups the hardware clipping if available on the current device.
builder | The current node builder.
---|---
Setups the light map node from the material.
builder | The current node builder.
---|---
Returns: The light map node.
Setups the outgoing light node.
builder | The current node builder.
---|---
Returns: The outgoing light node.
This method should be implemented by most derived materials since it defines the material's lighting model.
builder | The current node builder.
---|---
Returns: The lighting model.
Setups the lights node based on the scene, environment and material.
builder | The current node builder.
---|---
Returns: The lights node.
Setups the position in clip space.
builder | The current node builder.
---|---
Returns: The position in view space.
Setups the normal node from the material.
Returns: The normal node.
Setups a node material observer with the given builder.
builder | The current node builder.
---|---
Returns: The node material observer.
Setups the outgoing light node variable
Returns: The outgoing light node.
Setups the output node.
builder | The current node builder.
---|---
outputNode | The existing output node.
Returns: The output node.
Setups the computation of the position in local space.
builder | The current node builder.
---|---
Returns: The position in local space.
Setups the position node in view space. This method exists so derived node materials can modify the implementation e.g. sprite materials.
builder | The current node builder.
---|---
Returns: The position in view space.
Setups premultiplied alpha.
builder | The current node builder.
---|---
outputNode | The existing output node.
Returns: The output node.
Abstract interface method that can be implemented by derived materials to setup material-specific node variables.
builder | The current node builder.
---|---
Setups the logic for the vertex stage.
builder | The current node builder.
---|---
Returns: The position in clip space.
Serializes this material to JSON.
meta | The meta information for serialization.
---|---
Overrides: Material#toJSON
Returns: The serialized node.