three.js Shaders and Materials

Role

Workflow for custom surface shading and shader effects in three.js without breaking the engine's lighting, shadows, or fog - which is where most custom shaders lose their AAA look. This skill owns the approach choice, effect recipes, integration rules, and QA. Scene setup, IBL, and post-processing live in threejs-pipeline; textures come from pbr-texture-gen.

Choosing the Approach

Work down this ladder; stop at the first level that covers the need.

1. Built-in PBR materials. MeshStandardMaterial + MeshPhysicalMaterial already cover most AAA surfaces: clearcoat (car paint, lacquer), sheen (fabric, velvet), transmission + thickness + ior (glass, liquids), iridescence (soap, oil), anisotropy (brushed metal, hair). A custom shader for something a built-in property or a texture map already does is a maintenance liability, not an upgrade.
2. TSL node materials (three/webgpu + three/tsl) for custom logic on new projects. TSL compiles to WGSL on WebGPU and GLSL on the automatic WebGL 2 fallback, so one implementation covers both. Assign nodes on MeshStandardNodeMaterial/MeshPhysicalNodeMaterial: colorNode, normalNode, roughnessNode, metalnessNode, emissiveNode, positionNode (vertex displacement), opacityNode. Engine lighting keeps working because you feed inputs into the PBR pipeline instead of replacing it.
3. GLSL on WebGLRenderer-only projects: patch built-ins with material.onBeforeCompile (inject uniforms, replace #include chunks) so lights, shadows, and fog stay intact. Reserve raw ShaderMaterial for genuinely unlit work - skybox, FX quads, particles, post passes.

TSL Core Patterns