Threejs Syntax Shaders

threejs-syntax-shaders

Quick Reference

ShaderMaterial vs RawShaderMaterial

Uniform Type Map

Critical Warnings

NEVER pass a bare value as a uniform -- ALWAYS wrap it in { value: ... }. Writing uniforms: { uTime: 0.0 } silently fails; ALWAYS write uniforms: { uTime: { value: 0.0 } }.

NEVER declare built-in uniforms or attributes in a ShaderMaterial shader -- Three.js injects them automatically. Redeclaring causes a GLSL compilation error.

ALWAYS declare ALL uniforms, attributes, and precision in RawShaderMaterial shaders -- nothing is injected for you.

NEVER use gl_FragColor or texture2D() when glslVersion is THREE.GLSL3 -- use a declared out vec4 variable and texture() instead.

ALWAYS call material.needsUpdate = true after changing defines -- defines are compiled into the shader, so changes require recompilation.

---

ShaderMaterial

Constructor

import * as THREE from 'three';

const material = new THREE.ShaderMaterial({
  uniforms: {
    uTime: { value: 0.0 },
    uColor: { value: new THREE.Color(0x00ff00) },
    uTexture: { value: someTexture },
  },
  vertexShader: `
    varying vec2 vUv;
    void main() {
      vUv = uv;
      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
    }
  `,
  fragmentShader: `
    uniform float uTime;
    uniform vec3 uColor;
    varying vec2 vUv;
    void main() {
      gl_FragColor = vec4(uColor * vUv.x, 1.0);
    }
  `,
  transparent: false,
  wireframe: false,
  side: THREE.FrontSide,
});

Properties

---

Built-in Uniforms (ShaderMaterial Only)

These are injected automatically. NEVER declare them yourself.

// Transform matrices
uniform mat4 modelMatrix;           // Object -> World
uniform mat4 modelViewMatrix;       // Object -> Camera
uniform mat4 projectionMatrix;      // Camera -> Clip
uniform mat4 viewMatrix;            // World -> Camera
uniform mat3 normalMatrix;          // Transpose inverse of modelViewMatrix

// Camera
uniform vec3 cameraPosition;        // Camera world position

// When lights: true
uniform vec3 ambientLightColor;
// Plus structured arrays for directional, point, spot, hemisphere lights

Built-in Attributes (ShaderMaterial Only)

These are injected automatically. NEVER declare them yourself.

attribute vec3 position;    // Vertex position
attribute vec3 normal;      // Vertex normal
attribute vec2 uv;          // Primary UV coordinates
attribute vec2 uv2;         // Secondary UV (for aoMap, lightMap)
attribute vec4 tangent;     // Tangent vector (if computeTangents was called)
attribute vec3 color;       // Vertex color (if geometry has color attribute)

---

RawShaderMaterial

Use when you need full control over the shader source. NOTHING is injected.

const material = new THREE.RawShaderMaterial({
  uniforms: {
    uModelViewMatrix: { value: new THREE.Matrix4() },
    uProjectionMatrix: { value: new THREE.Matrix4() },
  },
  vertexShader: `
    precision highp float;
    attribute vec3 position;
    uniform mat4 uModelViewMatrix;
    uniform mat4 uProjectionMatrix;
    void main() {
      gl_Position = uProjectionMatrix * uModelViewMatrix * vec4(position, 1.0);
    }
  `,
  fragmentShader: `
    precision highp float;
    void main() {
      gl_FragColor = vec4(1.0, 0.0, 0.0, 1.0);
    }
  `,
});

ALWAYS add precision highp float; (or mediump) at the top of both shaders in RawShaderMaterial. Omitting precision causes a GLSL compilation error on mobile and some desktop drivers.

---

ShaderChunk -- Reusing Three.js Shader Code

THREE.ShaderChunk contains all internal shader fragments. Use #include <chunk_name> in ShaderMaterial (NOT RawShaderMaterial).

Common Chunks

Accessing Chunks Programmatically

// Read the source of any chunk
console.log(THREE.ShaderChunk.common);
console.log(THREE.ShaderChunk.fog_pars_vertex);

---

onBeforeCompile -- Patching Built-in Materials

Modify an existing material's shader at compile time. This preserves PBR lighting, shadows, and all built-in features.

const material = new THREE.MeshStandardMaterial({ color: 0xff0000 });

material.onBeforeCompile = (shader) => {
  shader.uniforms.uTime = { value: 0.0 };

  shader.vertexShader = shader.vertexShader.replace(
    '#include <begin_vertex>',
    `
    #include <begin_vertex>
    transformed.y += sin(transformed.x * 5.0 + uTime) * 0.5;
    `
  );

  // Store reference for uniform updates
  material.userData.shader = shader;
};

// ALWAYS override customProgramCacheKey when using onBeforeCompile
material.customProgramCacheKey = () => 'my-wavy-material';

// In animation loop
if (material.userData.shader) {
  material.userData.shader.uniforms.uTime.value = clock.getElapsedTime();
}

ALWAYS override customProgramCacheKey() when using onBeforeCompile -- without it, Three.js may reuse a cached unpatched shader program, causing your modifications to silently disappear.

ALWAYS check material.userData.shader exists before accessing uniforms -- the shader object is created lazily on first render and can be recreated when material.needsUpdate = true.

---

Defines -- Preprocessor Directives

const material = new THREE.ShaderMaterial({
  defines: {
    USE_FOG: '',           // #define USE_FOG
    MAX_LIGHTS: 4,         // #define MAX_LIGHTS 4
    EPSILON: '0.001',      // #define EPSILON 0.001
  },
  // ...shaders
});

Changing defines at runtime:

material.defines.MAX_LIGHTS = 8;
material.needsUpdate = true;  // REQUIRED -- triggers recompilation

---

GLSL3 Mode

const material = new THREE.ShaderMaterial({
  glslVersion: THREE.GLSL3,
  vertexShader: `
    in vec3 position;           // 'attribute' becomes 'in'
    uniform mat4 modelViewMatrix;
    uniform mat4 projectionMatrix;
    out vec3 vPosition;         // 'varying' becomes 'out'

    void main() {
      vPosition = position;
      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
    }
  `,
  fragmentShader: `
    precision highp float;
    in vec3 vPosition;          // 'varying' becomes 'in'
    out vec4 fragColor;         // replaces gl_FragColor

    void main() {
      fragColor = vec4(vPosition * 0.5 + 0.5, 1.0);
    }
  `,
});

GLSL1 vs GLSL3 Syntax

---

Uniform Update Pattern

// At creation
const material = new THREE.ShaderMaterial({
  uniforms: {
    uTime: { value: 0.0 },
    uResolution: { value: new THREE.Vector2(window.innerWidth, window.innerHeight) },
    uMouse: { value: new THREE.Vector2() },
  },
  vertexShader: '...',
  fragmentShader: '...',
});

// In animation loop -- update the .value property directly
function animate() {
  material.uniforms.uTime.value = performance.now() / 1000;
  material.uniforms.uMouse.value.set(mouseX, mouseY);
  renderer.render(scene, camera);
  requestAnimationFrame(animate);
}

NEVER replace the uniform object itself (e.g., material.uniforms.uTime = { value: 5 }). ALWAYS mutate the existing .value property. Replacing the object breaks the internal reference.

---

Reference Links

• references/methods.md -- Complete API signatures
• references/examples.md -- Working code examples
• references/anti-patterns.md -- What NOT to do

Official Sources

• https://threejs.org/docs/#api/en/materials/ShaderMaterial
• https://threejs.org/docs/#api/en/materials/RawShaderMaterial
• https://threejs.org/docs/#api/en/renderers/shaders/ShaderChunk
• https://threejs.org/docs/#api/en/renderers/shaders/UniformsLib

threejs-syntax-shaders -- Anti-Patterns

Anti-Pattern 1: Bare Uniform Values

WRONG:

const material = new THREE.ShaderMaterial({
  uniforms: {
    uTime: 0.0,                    // WRONG -- bare value
    uColor: new THREE.Color(),     // WRONG -- bare value
  },
});

CORRECT:

const material = new THREE.ShaderMaterial({
  uniforms: {
    uTime: { value: 0.0 },                    // ALWAYS wrap in { value: }
    uColor: { value: new THREE.Color() },      // ALWAYS wrap in { value: }
  },
});

Why: Three.js expects every uniform to be an object with a value property. Bare values are silently ignored -- the uniform is never sent to the GPU, and the shader uses uninitialized data.

---

Anti-Pattern 2: Replacing Uniform Objects Instead of Mutating .value

WRONG:

// In animation loop
material.uniforms.uTime = { value: performance.now() };  // WRONG -- replaces object

CORRECT:

// In animation loop
material.uniforms.uTime.value = performance.now();  // ALWAYS mutate .value

Why: Three.js caches internal references to uniform objects. Replacing the object breaks the reference, so the GPU never receives the updated value.

---

Anti-Pattern 3: Declaring Built-in Uniforms in ShaderMaterial

WRONG:

// In a ShaderMaterial vertex shader
uniform mat4 modelViewMatrix;   // WRONG -- already injected
uniform mat4 projectionMatrix;  // WRONG -- already injected
attribute vec3 position;        // WRONG -- already injected

CORRECT:

// In a ShaderMaterial vertex shader -- just use them directly
void main() {
  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
}

Why: ShaderMaterial automatically prepends built-in uniform and attribute declarations. Redeclaring them causes a GLSL compilation error ("identifier already declared"). This ONLY applies to ShaderMaterial -- RawShaderMaterial requires explicit declarations.

---

Anti-Pattern 4: Forgetting customProgramCacheKey with onBeforeCompile

WRONG:

material.onBeforeCompile = (shader) => {
  shader.vertexShader = shader.vertexShader.replace(
    '#include <begin_vertex>',
    '#include <begin_vertex>\ntransformed.y += 1.0;'
  );
};
// No customProgramCacheKey -- Three.js may reuse a cached unpatched program

CORRECT:

material.onBeforeCompile = (shader) => {
  shader.vertexShader = shader.vertexShader.replace(
    '#include <begin_vertex>',
    '#include <begin_vertex>\ntransformed.y += 1.0;'
  );
};
material.customProgramCacheKey = () => 'my-displaced-material';

Why: Three.js caches compiled shader programs by material type and parameters. Without a unique cache key, Two materials of the same type may share a cached program, causing your onBeforeCompile modifications to silently disappear on the second instance.

---

Anti-Pattern 5: Using GLSL1 Syntax with glslVersion: GLSL3

WRONG:

const material = new THREE.ShaderMaterial({
  glslVersion: THREE.GLSL3,
  fragmentShader: `
    varying vec2 vUv;              // WRONG -- 'varying' is not valid in GLSL3
    void main() {
      gl_FragColor = vec4(1.0);    // WRONG -- gl_FragColor does not exist in GLSL3
    }
  `,
});

CORRECT:

const material = new THREE.ShaderMaterial({
  glslVersion: THREE.GLSL3,
  fragmentShader: `
    precision highp float;
    in vec2 vUv;                   // 'varying' becomes 'in' in fragment shader
    out vec4 fragColor;            // Declare output explicitly

    void main() {
      fragColor = vec4(1.0);      // Write to declared output
    }
  `,
});

Why: GLSL 3.0 ES removes attribute, varying, gl_FragColor, and texture2D(). Using them causes compilation errors. ALWAYS use in/out, a declared output variable, and texture().

---

Anti-Pattern 6: Forgetting precision in RawShaderMaterial

WRONG:

const material = new THREE.RawShaderMaterial({
  vertexShader: `
    attribute vec3 position;      // WRONG -- no precision declaration
    void main() {
      gl_Position = vec4(position, 1.0);
    }
  `,
  fragmentShader: `
    void main() {                 // WRONG -- no precision declaration
      gl_FragColor = vec4(1.0);
    }
  `,
});

CORRECT:

const material = new THREE.RawShaderMaterial({
  vertexShader: `
    precision highp float;
    attribute vec3 position;
    void main() {
      gl_Position = vec4(position, 1.0);
    }
  `,
  fragmentShader: `
    precision highp float;
    void main() {
      gl_FragColor = vec4(1.0, 0.0, 0.0, 1.0);
    }
  `,
});

Why: RawShaderMaterial injects NOTHING -- no precision qualifier, no uniforms, no attributes. The fragment shader requires an explicit precision declaration on mobile GPUs and many desktop drivers. Omitting it causes a GLSL compilation error.

---

Anti-Pattern 7: Using #include Chunks in RawShaderMaterial

WRONG:

const material = new THREE.RawShaderMaterial({
  vertexShader: `
    precision highp float;
    #include <common>              // WRONG -- not processed in RawShaderMaterial
    attribute vec3 position;
    void main() {
      gl_Position = vec4(position, 1.0);
    }
  `,
});

CORRECT (use ShaderMaterial instead):

const material = new THREE.ShaderMaterial({
  vertexShader: `
    #include <common>              // Works in ShaderMaterial
    void main() {
      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
    }
  `,
});

Or manually inline the chunk:

const material = new THREE.RawShaderMaterial({
  vertexShader: `
    precision highp float;
    ${THREE.ShaderChunk.common}
    attribute vec3 position;
    uniform mat4 modelViewMatrix;
    uniform mat4 projectionMatrix;
    void main() {
      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
    }
  `,
});

Why: RawShaderMaterial does NOT process #include directives. The string #include <common> is passed literally to the GLSL compiler, which does not understand it, causing a compilation error.

---

Anti-Pattern 8: Setting needsUpdate on Uniform Changes

WRONG:

material.uniforms.uTime.value = 1.0;
material.needsUpdate = true;          // WRONG -- unnecessary and expensive

CORRECT:

material.uniforms.uTime.value = 1.0;  // Just update the value -- no needsUpdate needed

Why: Uniform values are sent to the GPU every frame automatically. Setting material.needsUpdate = true triggers a full shader recompilation, which is extremely expensive (causes a frame stutter). ONLY set needsUpdate = true when changing defines, vertexShader, fragmentShader, lights, fog, or clipping.

---

Anti-Pattern 9: Storing onBeforeCompile Shader Reference Without Null Check

WRONG:

material.onBeforeCompile = (shader) => {
  shader.uniforms.uTime = { value: 0 };
  material.userData.shader = shader;
};

// In animation loop -- crashes if shader has not compiled yet
material.userData.shader.uniforms.uTime.value = clock.getElapsedTime();

CORRECT:

material.onBeforeCompile = (shader) => {
  shader.uniforms.uTime = { value: 0 };
  material.userData.shader = shader;
};

// In animation loop -- ALWAYS check existence
if (material.userData.shader) {
  material.userData.shader.uniforms.uTime.value = clock.getElapsedTime();
}

Why: The onBeforeCompile callback runs lazily on first render. Before the first renderer.render() call, material.userData.shader is undefined. Additionally, setting material.needsUpdate = true can recreate the shader object, invalidating old references. ALWAYS guard access with a null check.

---

Official Sources

• https://threejs.org/docs/#api/en/materials/ShaderMaterial
• https://threejs.org/docs/#api/en/materials/RawShaderMaterial
• https://threejs.org/docs/#api/en/renderers/shaders/ShaderChunk

threejs-syntax-shaders -- Examples

Example 1: Basic Custom ShaderMaterial

A minimal ShaderMaterial with a time-based color animation.

import * as THREE from 'three';

const material = new THREE.ShaderMaterial({
  uniforms: {
    uTime: { value: 0.0 },
    uColor: { value: new THREE.Color(0x3399ff) },
  },
  vertexShader: `
    varying vec2 vUv;

    void main() {
      vUv = uv;
      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
    }
  `,
  fragmentShader: `
    uniform float uTime;
    uniform vec3 uColor;
    varying vec2 vUv;

    void main() {
      float pulse = sin(uTime * 3.0) * 0.5 + 0.5;
      vec3 color = mix(uColor, vec3(1.0), pulse * vUv.y);
      gl_FragColor = vec4(color, 1.0);
    }
  `,
});

const mesh = new THREE.Mesh(new THREE.PlaneGeometry(2, 2), material);

// Animation loop
const clock = new THREE.Clock();
function animate() {
  material.uniforms.uTime.value = clock.getElapsedTime();
  renderer.render(scene, camera);
  requestAnimationFrame(animate);
}
animate();

---

Example 2: Vertex Displacement with Texture

Displaces vertices along their normals using a height map texture.

import * as THREE from 'three';

const loader = new THREE.TextureLoader();
const heightMap = loader.load('/textures/heightmap.png');

const material = new THREE.ShaderMaterial({
  uniforms: {
    uHeightMap: { value: heightMap },
    uDisplacement: { value: 0.5 },
  },
  vertexShader: `
    uniform sampler2D uHeightMap;
    uniform float uDisplacement;
    varying vec2 vUv;
    varying float vHeight;

    void main() {
      vUv = uv;
      float height = texture2D(uHeightMap, uv).r;
      vHeight = height;
      vec3 displaced = position + normal * height * uDisplacement;
      gl_Position = projectionMatrix * modelViewMatrix * vec4(displaced, 1.0);
    }
  `,
  fragmentShader: `
    varying vec2 vUv;
    varying float vHeight;

    void main() {
      vec3 low = vec3(0.0, 0.2, 0.8);
      vec3 high = vec3(1.0, 0.9, 0.3);
      vec3 color = mix(low, high, vHeight);
      gl_FragColor = vec4(color, 1.0);
    }
  `,
});

const geometry = new THREE.PlaneGeometry(10, 10, 256, 256);
const mesh = new THREE.Mesh(geometry, material);

---

Example 3: onBeforeCompile -- Patching MeshStandardMaterial

Adds a wave vertex displacement to a standard PBR material while preserving all lighting and shadow behavior.

import * as THREE from 'three';

const material = new THREE.MeshStandardMaterial({
  color: 0x2194ce,
  roughness: 0.4,
  metalness: 0.1,
});

material.onBeforeCompile = (shader) => {
  // Add custom uniforms
  shader.uniforms.uTime = { value: 0.0 };
  shader.uniforms.uAmplitude = { value: 0.3 };

  // Inject uniform declaration at top of vertex shader
  shader.vertexShader = `
    uniform float uTime;
    uniform float uAmplitude;
  ` + shader.vertexShader;

  // Replace begin_vertex chunk to add displacement
  shader.vertexShader = shader.vertexShader.replace(
    '#include <begin_vertex>',
    `
    #include <begin_vertex>
    float wave = sin(transformed.x * 4.0 + uTime * 2.0) *
                 cos(transformed.z * 4.0 + uTime * 1.5);
    transformed.y += wave * uAmplitude;
    `
  );

  // Store shader reference for uniform updates
  material.userData.shader = shader;
};

// ALWAYS override customProgramCacheKey with onBeforeCompile
material.customProgramCacheKey = () => 'wavy-standard';

// Animation loop
const clock = new THREE.Clock();
function animate() {
  if (material.userData.shader) {
    material.userData.shader.uniforms.uTime.value = clock.getElapsedTime();
  }
  renderer.render(scene, camera);
  requestAnimationFrame(animate);
}
animate();

---

Example 4: RawShaderMaterial with GLSL3

A RawShaderMaterial using GLSL 3.0 ES syntax for full control.

import * as THREE from 'three';

const material = new THREE.RawShaderMaterial({
  glslVersion: THREE.GLSL3,
  uniforms: {
    uProjectionMatrix: { value: new THREE.Matrix4() },
    uModelViewMatrix: { value: new THREE.Matrix4() },
    uTime: { value: 0.0 },
  },
  vertexShader: `
    precision highp float;

    in vec3 position;
    in vec2 uv;

    uniform mat4 uProjectionMatrix;
    uniform mat4 uModelViewMatrix;
    uniform float uTime;

    out vec2 vUv;
    out float vWave;

    void main() {
      vUv = uv;
      vec3 pos = position;
      pos.z = sin(pos.x * 5.0 + uTime) * 0.2;
      vWave = pos.z;
      gl_Position = uProjectionMatrix * uModelViewMatrix * vec4(pos, 1.0);
    }
  `,
  fragmentShader: `
    precision highp float;

    in vec2 vUv;
    in float vWave;

    out vec4 fragColor;

    void main() {
      vec3 color = vec3(vUv, 0.5 + vWave);
      fragColor = vec4(color, 1.0);
    }
  `,
});

// With RawShaderMaterial, you MUST manually update the matrix uniforms
const mesh = new THREE.Mesh(new THREE.PlaneGeometry(4, 4, 64, 64), material);

function animate() {
  mesh.updateMatrixWorld();
  material.uniforms.uModelViewMatrix.value.multiplyMatrices(
    camera.matrixWorldInverse,
    mesh.matrixWorld
  );
  material.uniforms.uProjectionMatrix.value.copy(camera.projectionMatrix);
  material.uniforms.uTime.value = performance.now() / 1000;
  renderer.render(scene, camera);
  requestAnimationFrame(animate);
}

---

Example 5: ShaderMaterial with Fog and Lights Support

Using ShaderChunk includes to integrate with Three.js fog and lighting systems.

import * as THREE from 'three';

const material = new THREE.ShaderMaterial({
  uniforms: {
    ...THREE.UniformsLib.fog,
    uColor: { value: new THREE.Color(0xff6600) },
  },
  vertexShader: `
    #include <common>
    #include <fog_pars_vertex>

    varying vec3 vNormal;

    void main() {
      vNormal = normalize(normalMatrix * normal);
      vec4 mvPosition = modelViewMatrix * vec4(position, 1.0);
      gl_Position = projectionMatrix * mvPosition;
      #include <fog_vertex>
    }
  `,
  fragmentShader: `
    #include <common>
    #include <fog_pars_fragment>

    uniform vec3 uColor;
    varying vec3 vNormal;

    void main() {
      float light = dot(vNormal, normalize(vec3(1.0, 1.0, 1.0)));
      light = clamp(light, 0.2, 1.0);
      gl_FragColor = vec4(uColor * light, 1.0);
      #include <fog_fragment>
    }
  `,
  fog: true,  // REQUIRED to enable fog uniform injection
});

---

Official Sources

• https://threejs.org/docs/#api/en/materials/ShaderMaterial
• https://threejs.org/docs/#api/en/materials/RawShaderMaterial
• https://threejs.org/examples/#webgl_shader
• https://threejs.org/examples/#webgl_shader_lava

threejs-syntax-shaders -- Methods Reference

ShaderMaterial Constructor

new THREE.ShaderMaterial(parameters?: {
  uniforms?: { [name: string]: { value: any } },
  uniformsGroups?: THREE.UniformsGroup[],
  vertexShader?: string,
  fragmentShader?: string,
  defines?: { [name: string]: string | number },
  extensions?: {
    clipCullDistance?: boolean,
    multiDraw?: boolean,
  },
  wireframe?: boolean,
  wireframeLinewidth?: number,
  lights?: boolean,
  fog?: boolean,
  clipping?: boolean,
  glslVersion?: null | typeof THREE.GLSL3,
  defaultAttributeValues?: { [name: string]: number[] },
  // Inherited from Material:
  side?: THREE.Side,
  transparent?: boolean,
  opacity?: number,
  depthTest?: boolean,
  depthWrite?: boolean,
  blending?: THREE.Blending,
})

---

RawShaderMaterial Constructor

new THREE.RawShaderMaterial(parameters?: {
  // Same parameters as ShaderMaterial
  // Difference: NO built-in uniforms, attributes, or precision injected
  uniforms?: { [name: string]: { value: any } },
  vertexShader?: string,
  fragmentShader?: string,
  defines?: { [name: string]: string | number },
  glslVersion?: null | typeof THREE.GLSL3,
  // ...all Material base properties
})

---

ShaderMaterial Properties

---

ShaderMaterial Methods (Inherited from Material)

---

Built-in Uniforms (Injected by ShaderMaterial)

Transform Matrices

Camera

Lighting (when lights: true)

---

Built-in Attributes (Injected by ShaderMaterial)

---

ShaderChunk API

// Access any internal shader chunk by name
THREE.ShaderChunk['common']          // Returns string with source code
THREE.ShaderChunk['fog_pars_vertex'] // Returns fog vertex pars source

Usage in GLSL (ShaderMaterial only)

#include <common>
#include <fog_pars_vertex>

---

onBeforeCompile Callback Signature

material.onBeforeCompile = (shader: {
  uniforms: { [name: string]: { value: any } },
  vertexShader: string,
  fragmentShader: string,
  defines: { [name: string]: string | number },
}, renderer: THREE.WebGLRenderer) => void;

customProgramCacheKey Signature

material.customProgramCacheKey = (): string => {
  return 'unique-key-for-this-variant';
};

---

UniformsLib

Three.js groups commonly-used uniforms into libraries:

THREE.UniformsLib.common    // diffuse map, opacity, alphaMap, UV transform
THREE.UniformsLib.envmap    // environment map uniforms
THREE.UniformsLib.normalmap // normal map uniforms
THREE.UniformsLib.fog       // fogColor, fogNear, fogFar, fogDensity
THREE.UniformsLib.lights    // all light type uniforms

UniformsUtils

// Merge multiple uniform objects (deep clone)
const merged = THREE.UniformsUtils.merge([
  THREE.UniformsLib.common,
  THREE.UniformsLib.lights,
  { uCustom: { value: 1.0 } },
]);

// Clone uniforms (deep copy of values)
const cloned = THREE.UniformsUtils.clone(someUniforms);

---

Official Sources

• https://threejs.org/docs/#api/en/materials/ShaderMaterial
• https://threejs.org/docs/#api/en/materials/RawShaderMaterial
• https://threejs.org/docs/#api/en/renderers/shaders/ShaderChunk
• https://threejs.org/docs/#api/en/renderers/shaders/UniformsLib
• https://threejs.org/docs/#api/en/renderers/shaders/UniformsUtils