b-open-io/shaders

Three.js Shader Development

Custom shaders for Three.js — from simple material overrides to full WebGPU node graphs. Covers the complete workflow: choosing an approach, writing code, debugging, and shipping.

When to Use This Skill

• Custom materials that go beyond built-in Three.js materials
• Visual effects: noise, dissolve, Fresnel, hologram, water, cel shading, chromatic aberration
• Post-processing pipelines with pmndrs/postprocessing
• Procedural textures and geometry displacement
• Raymarching and SDF-based scenes
• Porting GLSL shaders into TSL for WebGPU compatibility

TSL vs GLSL — Choose Before Writing Anything

| | TSL (Three Shader Language) | GLSL (ShaderMaterial) | |---|---|---| | WebGPU | Yes (compiles to WGSL automatically) | No | | WebGL fallback | Yes (automatic) | Yes | | Syntax | JavaScript / node graph | Raw GLSL strings | | Built-in uniforms | Auto-inferred | Manual declarations | | Best for | New projects, r163+, R3F | Legacy code, full manual control |

Default choice: TSL. Production-ready since r163. Use GLSL only when targeting legacy environments or when RawShaderMaterial manual control is specifically required.

Read references/tsl-guide.md for the full TSL API including all node types, built-ins, control flow, and material setup.

TSL Quick Start (R3F)

import { extend, useFrame } from '@react-three/fiber';
import * as THREE from 'three/webgpu';
import { color, float, time, mix, mx_noise_float, positionWorld, uniform } from 'three/tsl';

function NoiseSphere() {
  const noiseUniform = uniform(0);

  useFrame(({ clock }) => {
    noiseUniform.value = clock.elapsedTime;
  });

  const noise = mx_noise_float(positionWorld.mul(1.5).add(time.mul(0.3)));
  const dynamicColor = mix(color(0x1a0533), color(0x00eaff), noise);

  return (
    <mesh>
      <sphereGeometry args={[1, 64, 64]} />
      <meshStandardNodeMaterial
        colorNode={dynamicColor}
        roughnessNode={float(0.4)}
      />
    </mesh>
  );
}

Renderer requirement: WebGPURenderer from three/webgpu — it automatically falls back to WebGL2 when WebGPU is unavailable. Import materials from three/webgpu, nodes from three/tsl.

GLSL Quick Start (R3F)

import { useRef, useMemo } from 'react';
import { useFrame } from '@react-three/fiber';
import * as THREE from 'three';

const vertexShader = `
  varying vec2 vUv;
  void main() {
    vUv = uv;
    gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
  }
`;

const fragmentShader = `
  uniform float uTime;
  uniform vec3 uColor;
  varying vec2 vUv;
  void main() {
    float n = sin(vUv.x * 10.0 + uTime) * 0.5 + 0.5;
    gl_FragColor = vec4(uColor * n, 1.0);
  }
`;

function ShaderMesh() {
  const matRef = useRef();
  const uniforms = useMemo(() => ({
    uTime:  { value: 0 },
    uColor: { value: new THREE.Color(0x00aaff) }
  }), []);

  useFrame(({ clock }) => {
    if (matRef.current) matRef.current.uniforms.uTime.value = clock.elapsedTime;
  });

  return (
    <mesh>
      <planeGeometry args={[2, 2]} />
      <shaderMaterial ref={matRef} vertexShader={vertexShader} fragmentShader={fragmentShader} uniforms={uniforms} />
    </mesh>
  );
}

Memoize uniforms with useMemo — without it, a new object is created every render and the material recompiles. Update .uniforms.uTime.value inside useFrame, never the object reference.

Read references/glsl-patterns.md for complete recipes: noise, Fresnel, dissolve, hologram, water, matcap, toon shading, particles, and more.

Debugging Shaders

Shader errors are silent: the mesh renders black, pink, or nothing. Debug systematically:

Visual debugging (most effective)

Output intermediate values as colors to inspect them directly:

// Is my UV correct?
gl_FragColor = vec4(vUv, 0.0, 1.0);

// Is my normal correct?
gl_FragColor = vec4(normalize(vNormal) * 0.5 + 0.5, 1.0);

// Is my noise in range?
gl_FragColor = vec4(vec3(noiseValue), 1.0);

In TSL, assign any node directly to colorNode:

material.colorNode = normalWorld.mul(0.5).add(0.5);  // visualize normals
material.colorNode = positionLocal;                    // visualize position

Common failure patterns

| Symptom | Likely cause | |---|---| | Solid black | Missing lights, normals inverted, or NaN from division by zero | | Pink / magenta | Texture not loaded, sampler2D binding missing | | Flickering | Uniform not updated every frame, or uniformsNeedUpdate needed | | No visible change | Wrong material reference, or effect not connected to colorNode | | NaN propagation | Division by zero, sqrt of negative, atan of zero vector — check all math |

Tools

• Spector.js (browser extension): captures WebGL draw calls and shader state
• Chrome GPU profiler (chrome://tracing): GPU timeline and overdraw analysis
• Three.js renderer.info: draw calls, triangles, textures in flight

Performance Rules

Apply these unconditionally on every shader:

1. Avoid dynamic branching in fragment shaders — if/else on GPU creates divergent execution across warps. Prefer step(), mix(), or select() (TSL).
2. Precompute in vertex shader — values constant across a triangle (world position, normal transforms) belong in the vertex stage, not the fragment.
3. Minimize texture lookups — each texture2D / texture() call is a memory fetch. Cache results in a variable; never sample the same texture twice.
4. Use mediump where possible — in fragment shaders, declare precision mediump float; unless high precision is required. Saves bandwidth on mobile GPUs.
5. Limit overdraw — transparent materials with complex fragment shaders on overlapping geometry are multiplicatively expensive. Use depthWrite: true where possible.
6. Noise is expensive — FBM with 6+ octaves can cost 5–10ms per frame. Profile before adding octaves.

Post-Processing

Install pmndrs/postprocessing:

bun add postprocessing              # vanilla
bun add @react-three/postprocessing # R3F wrapper

Effect ordering (wrong order produces incorrect results):

1. SSAO           → needs depth buffer, must come first
2. DepthOfField   → needs depth, before color grading
3. Bloom          → operates on HDR scene before tone mapping
4. ToneMapping    → converts HDR → LDR; must follow Bloom
5. ChromaticAberration → full-screen warp, near end
6. Vignette       → full-screen overlay
7. Noise          → full-screen overlay, last

Performance cost at a glance:

| Effect | Cost | |---|---| | ChromaticAberration, Vignette, Noise, ToneMapping | Very Low | | Bloom (no mipmapBlur), SMAA, GodRays | Low–Medium | | SSAO, DepthOfField, Bloom (mipmapBlur) | Medium–High |

Mobile: Skip SSAO and DepthOfField entirely. Use Bloom without mipmapBlur. Keep Vignette + Noise for polish at near-zero cost.

One EffectPass merges multiple effects into one draw call — always prefer <EffectPass camera={...} effects={[bloom, smaa, toneMap]} /> over separate passes.

Read references/postprocessing.md for full R3F setup, all effect parameters, custom effect authoring, and the selective bloom pattern.

Reference Files

• references/tsl-guide.md — Complete TSL API: node types, uniforms, built-ins, control flow, varyings, NodeMaterial setup, GLSL→TSL migration
• references/glsl-patterns.md — Common GLSL shader recipes with complete vertex + fragment code
• references/postprocessing.md — Full pmndrs/postprocessing guide: R3F setup, all effects, custom effect authoring