Build: The Metal-Flake Paint

The whole file after this topic. If yours differs, you can copy this one and carry on.

import * as THREE from "three";

// The Lumen paint: a metallic base with tiny tilted flakes, under a clear glossy coat.
// It is a MeshPhysicalMaterial, so the scene's lights, shadows, environment and tone mapping all keep working.
// onBeforeCompile edits three.js's own shader text before it is compiled (Topic 12.6 says why that is fragile).

/** Puts `extra` after `token` in a three.js shader. Throws if the token is gone, because three.js changed its chunks. */
function insertAfter(source, token, extra) {
  if (!source.includes(token)) throw new Error("paint.glsl.js: " + token + " is not in this version of three.js's shader");
  return source.replace(token, token + "\n" + extra);
}

const VERTEX_DECLARATIONS = `
varying vec3 vFlakePos;                         // where on the object this pixel is (object space)
varying vec3 vToViewX; varying vec3 vToViewY; varying vec3 vToViewZ;   // the object's axes in view space`;

const VERTEX_SET = `
vFlakePos = position;
vToViewX = normalMatrix * vec3(1.0, 0.0, 0.0);
vToViewY = normalMatrix * vec3(0.0, 1.0, 0.0);
vToViewZ = normalMatrix * vec3(0.0, 0.0, 1.0);`;

const FRAGMENT_DECLARATIONS = `
uniform float uFlakeScale;      // flakes per metre
uniform float uFlakeDensity;    // 0 to 1: the share of cells that hold a flake
uniform float uFlakeStrength;   // how far a flake tilts the surface
varying vec3 vFlakePos;
varying vec3 vToViewX; varying vec3 vToViewY; varying vec3 vToViewZ;

vec3 flakeHash(vec3 p) {        // a repeatable random vec3 from 0 to 1 for a cell
  p = fract(p * vec3(0.1031, 0.1030, 0.0973));
  p += dot(p, p.yxz + 33.33);
  return fract((p.xxy + p.yxx) * p.zyx);
}`;

// Runs right after three.js has worked out the surface normal. The clear coat has its own normal, so it stays smooth.
const FRAGMENT_FLAKES = `
vec3 flakeCell = floor(vFlakePos * uFlakeScale);
float flakePresent = step(flakeHash(flakeCell + 7.0).x, uFlakeDensity);
vec3 tilt = flakeHash(flakeCell) * 2.0 - 1.0;                       // a random direction in object space
vec3 tiltView = tilt.x * vToViewX + tilt.y * vToViewY + tilt.z * vToViewZ;
normal = normalize(normal + uFlakeStrength * flakePresent * tiltView);
roughnessFactor *= mix(1.0, 0.5, flakePresent);                     // a flake is smoother than the paint round it`;

export function createPaint({ color = "#ff6b2c", flakeScale = 140, flakeDensity = 0.45, flakeStrength = 0.7 } = {}) {
  const paint = new THREE.MeshPhysicalMaterial({ color, metalness: 0.75, roughness: 0.4, clearcoat: 1, clearcoatRoughness: 0.05 });
  paint.name = "lumen-paint";
  const uniforms = {
    uFlakeScale: { value: flakeScale },
    uFlakeDensity: { value: flakeDensity },
    uFlakeStrength: { value: flakeStrength },
  };
  paint.userData.flake = uniforms; // so a UI can change them later: paint.userData.flake.uFlakeScale.value = 200
  paint.onBeforeCompile = (shader) => {
    Object.assign(shader.uniforms, uniforms); // share the same objects, so later changes reach the GPU
    shader.vertexShader = insertAfter(shader.vertexShader, "#include <common>", VERTEX_DECLARATIONS);
    shader.vertexShader = insertAfter(shader.vertexShader, "#include <begin_vertex>", VERTEX_SET);
    shader.fragmentShader = insertAfter(shader.fragmentShader, "#include <common>", FRAGMENT_DECLARATIONS);
    shader.fragmentShader = insertAfter(shader.fragmentShader, "#include <normal_fragment_maps>", FRAGMENT_FLAKES);
  };
  paint.customProgramCacheKey = () => "lumen-paint-1"; // one program for every paint made here, whatever its colour
  // material.clone() (Phase 8's glow uses it) does not copy onBeforeCompile, so a clone would lose its flakes: copy it by hand
  paint.clone = function () {
    const copy = THREE.MeshPhysicalMaterial.prototype.clone.call(this);
    copy.onBeforeCompile = this.onBeforeCompile;
    copy.customProgramCacheKey = this.customProgramCacheKey;
    return copy;
  };
  return paint;
}