Imported from akillness/jeo-skills (.agent-skills/threejs-shaders/SKILL.md). Install upstream with npx skills add akillness/jeo-skills --skill threejs-shaders. Copyright stays with the author (MIT).

Three.js Shaders

Use this skill for custom GPU programs and safe built-in material extension. Route PBR surface selection to threejs-materials, textures/UV data to threejs-textures, and full-screen composer effects to threejs-postprocessing.

When to use this skill

• Write a ShaderMaterial or RawShaderMaterial vertex/fragment program
• Pass time, colors, textures, transforms, or per-instance data through uniforms/varyings
• Implement displacement, fresnel, dissolve, gradients, noise, rim lighting, or custom effects
• Extend a built-in material with onBeforeCompile without replacing its PBR behavior
• Diagnose GLSL compilation, coordinate-space, precision, or GPU-cost failures

Instructions

Step 1: Choose the least invasive shader path

Start from a built-in material when it already owns the lighting/PBR behavior you need. Use a custom material only when the visual model truly differs.

Step 2: Make data flow explicit

const material = new THREE.ShaderMaterial({
  uniforms: {
    uTime: { value: 0 },
    uColor: { value: new THREE.Color("#4f8cff") },
  },
  vertexShader: `
    varying vec2 vUv;
    void main() {
      vUv = uv;
      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
    }
  `,
  fragmentShader: `
    uniform vec3 uColor;
    varying vec2 vUv;
    void main() {
      gl_FragColor = vec4(uColor * vec3(vUv.y), 1.0);
    }
  `,
});

A uniform is constant for a draw call; a varying is written by the vertex shader and interpolated into the fragment shader. Name coordinate spaces (local, world, view, clip, uv) in variables and comments. Most shader bugs are an implicit space mismatch.

Step 3: Update only the intended uniform values

material.uniforms.uTime.value = elapsedSeconds;

Mutate .value; do not replace the uniforms object every frame. Reuse Color, Vector, and texture objects where possible. For instanced variation, use supported attributes rather than creating one material per instance.

Step 4: Extend built-in materials cautiously

onBeforeCompile depends on internal shader chunks and can change across Three.js revisions. Keep replacements narrow, set material.customProgramCacheKey() when program variants depend on application state, and test against the locked project version. Do not use source-string replacement as a permanent abstraction without a versioned test surface.

Step 5: Verify compile, visual, and performance behavior

• Check browser shader compile logs and reduce to a minimal shader before debugging details.
• Validate at least one known coordinate/normal/UV case with a diagnostic color output.
• Test precision and derivatives on target mobile hardware if supported by the product.
• Measure fragment overdraw, texture samples, loops, and material variants before shipping.
• Dispose feature-owned custom materials and render targets at teardown.

Examples

Fresnel rim signal

Compute/view a normalized normal and view direction in the same space, then derive the rim term from their dot product. Test front-facing and grazing angles; a negative/incorrect space conversion often makes a fresnel effect appear inverted or fixed to the camera.

Vertex displacement

Displace in object/local space and pass the deformed position/normal logic through a consistent lighting model. High-frequency displacement needs enough geometry density; a shader cannot create silhouette detail that the mesh does not contain.

Best practices

1. Start with the smallest shader that renders a constant color, then add data flow.
2. State coordinate spaces and normalize only where mathematically required.
3. Keep uniform updates allocation-free in the render loop.
4. Prefer a built-in material extension over reimplementing PBR lighting.
5. Profile on target GPUs; a visually small fragment effect can dominate frame time.

References

• Three.js Shaders source coverage
• ShaderMaterial documentation
• Three.js manual: custom shaders