Shader Craft

A unified skill covering 36 GLSL shader techniques (ShaderToy-compatible) for real-time visual effects.

Invocation

/shader-dev <request>

$ARGUMENTS contains the user's request (e.g. "create a raymarched SDF scene with soft shadows").

Skill Structure

shader-dev/

├── SKILL.md                      # Core skill (this file)

├── techniques/                   # Implementation guides (read per routing table)

│   ├── ray-marching.md           # Sphere tracing with SDF

│   ├── sdf-3d.md                 # 3D signed distance functions

│   ├── lighting-model.md         # PBR, Phong, toon shading

│   ├── procedural-noise.md       # Perlin, Simplex, FBM

│   └── ...                       # 34 more technique files

└── reference/                    # Detailed guides (read as needed)

    ├── ray-marching.md           # Math derivations & advanced patterns

    ├── sdf-3d.md                 # Extended SDF theory

    ├── lighting-model.md         # Lighting math deep-dive

    ├── procedural-noise.md       # Noise function theory

    └── ...                       # 34 more reference files

How to Use

• Read the Technique Routing Table below to identify which technique(s) match the user's request

• Read the relevant file(s) from techniques/ — each file contains core principles, implementation steps, and complete code templates

• If you need deeper understanding (math derivations, advanced patterns), follow the reference link at the bottom of each technique file to reference/

• Apply the WebGL2 Adaptation Rules below when generating standalone HTML pages

Technique Routing Table

User wants to create...

Primary technique

Combine with

3D objects / scenes from math

ray-marching + sdf-3d

lighting-model, shadow-techniques

Complex 3D shapes (booleans, blends)

csg-boolean-operations

sdf-3d, ray-marching

Infinite repeating patterns in 3D

domain-repetition

sdf-3d, ray-marching

Organic / warped shapes

domain-warping

procedural-noise

Fluid / smoke / ink effects

fluid-simulation

multipass-buffer

Particle effects (fire, sparks, snow)

particle-system

procedural-noise, color-palette

Physically-based simulations

simulation-physics

multipass-buffer

Game of Life / reaction-diffusion

cellular-automata

multipass-buffer, color-palette

Ocean / water surface

water-ocean

atmospheric-scattering, lighting-model

Terrain / landscape

terrain-rendering

atmospheric-scattering, procedural-noise

Clouds / fog / volumetric fire

volumetric-rendering

procedural-noise, atmospheric-scattering

Sky / sunset / atmosphere

atmospheric-scattering

volumetric-rendering

Realistic lighting (PBR, Phong)

lighting-model

shadow-techniques, ambient-occlusion

Shadows (soft / hard)

shadow-techniques

lighting-model

Ambient occlusion

ambient-occlusion

lighting-model, normal-estimation

Path tracing / global illumination

path-tracing-gi

analytic-ray-tracing, multipass-buffer

Precise ray-geometry intersections

analytic-ray-tracing

lighting-model

Voxel worlds (Minecraft-style)

voxel-rendering

lighting-model, shadow-techniques

Noise / FBM textures

procedural-noise

domain-warping

Tiled 2D patterns

procedural-2d-pattern

polar-uv-manipulation

Voronoi / cell patterns

voronoi-cellular-noise

color-palette

Fractals (Mandelbrot, Julia, 3D)

fractal-rendering

color-palette, polar-uv-manipulation

Color grading / palettes

color-palette

—

Bloom / tone mapping / glitch

post-processing

multipass-buffer

Multi-pass ping-pong buffers

multipass-buffer

—

Texture / sampling techniques

texture-sampling

—

Camera / matrix transforms

matrix-transform

—

Surface normals

normal-estimation

—

Polar coords / kaleidoscope

polar-uv-manipulation

procedural-2d-pattern

2D shapes / UI from SDF

sdf-2d

color-palette

Procedural audio / music

sound-synthesis

—

SDF tricks / optimization

sdf-tricks

sdf-3d, ray-marching

Anti-aliased rendering

anti-aliasing

sdf-2d, post-processing

Depth of field / motion blur / lens effects

camera-effects

post-processing, multipass-buffer

Advanced texture mapping / no-tile textures

texture-mapping-advanced

terrain-rendering, texture-sampling

WebGL2 shader errors / debugging

webgl-pitfalls

—

Technique Index

Geometry & SDF

• sdf-2d — 2D signed distance functions for shapes, UI, anti-aliased rendering

• sdf-3d — 3D signed distance functions for real-time implicit surface modeling

• csg-boolean-operations — Constructive solid geometry: union, subtraction, intersection with smooth blending

• domain-repetition — Infinite space repetition, folding, and limited tiling

• domain-warping — Distort domains with noise for organic, flowing shapes

• sdf-tricks — SDF optimization, bounding volumes, binary search refinement, hollowing, layered edges, debug visualization

Ray Casting & Lighting

• ray-marching — Sphere tracing with SDF for 3D scene rendering

• analytic-ray-tracing — Closed-form ray-primitive intersections (sphere, plane, box, torus)

• path-tracing-gi — Monte Carlo path tracing for photorealistic global illumination

• lighting-model — Phong, Blinn-Phong, PBR (Cook-Torrance), and toon shading

• shadow-techniques — Hard shadows, soft shadows (penumbra estimation), cascade shadows

• ambient-occlusion — SDF-based AO, screen-space AO approximation

• normal-estimation — Finite-difference normals, tetrahedron technique

Simulation & Physics

• fluid-simulation — Navier-Stokes fluid solver with advection, diffusion, pressure projection

• simulation-physics — GPU-based physics: springs, cloth, N-body gravity, collision

• particle-system — Stateless and stateful particle systems (fire, rain, sparks, galaxies)

• cellular-automata — Game of Life, reaction-diffusion (Turing patterns), sand simulation

Natural Phenomena

• water-ocean — Gerstner waves, FFT ocean, caustics, underwater fog

• terrain-rendering — Heightfield ray marching, FBM terrain, erosion

• atmospheric-scattering — Rayleigh/Mie scattering, god rays, SSS approximation

• volumetric-rendering — Volume ray marching for clouds, fog, fire, explosions

Procedural Generation

• procedural-noise — Value noise, Perlin, Simplex, Worley, FBM, ridged noise

• procedural-2d-pattern — Brick, hexagon, truchet, Islamic geometric patterns

• voronoi-cellular-noise — Voronoi diagrams, Worley noise, cracked earth, crystal

• fractal-rendering — Mandelbrot, Julia sets, 3D fractals (Mandelbox, Mandelbulb)

• color-palette — Cosine palettes, HSL/HSV/Oklab, dynamic color mapping

Post-Processing & Infrastructure

• post-processing — Bloom, tone mapping (ACES, Reinhard), vignette, chromatic aberration, glitch

• multipass-buffer — Ping-pong FBO setup, state persistence across frames

• texture-sampling — Bilinear, bicubic, mipmap, procedural texture lookup

• matrix-transform — Camera look-at, projection, rotation, orbit controls

• polar-uv-manipulation — Polar/log-polar coordinates, kaleidoscope, spiral mapping

• anti-aliasing — SSAA, SDF analytical AA, temporal anti-aliasing (TAA), FXAA post-process

• camera-effects — Depth of field (thin lens), motion blur, lens distortion, film grain, vignette

• texture-mapping-advanced — Biplanar mapping, texture repetition avoidance, ray differential filtering

Audio

• sound-synthesis — Procedural audio in GLSL: oscillators, envelopes, filters, FM synthesis

Debugging & Validation

• webgl-pitfalls — Common WebGL2/GLSL errors: fragCoord, main() wrapper, function order, macro limitations, uniform null

WebGL2 Adaptation Rules

All technique files use ShaderToy GLSL style. When generating standalone HTML pages, apply these adaptations:

Shader Version & Output

• Use canvas.getContext("webgl2")

• Shader first line: #version 300 es, fragment shader adds precision highp float;

• Fragment shader must declare: out vec4 fragColor;

• Vertex shader: attribute → in, varying → out

• Fragment shader: varying → in, gl_FragColor → fragColor, texture2D() → texture()

Fragment Coordinate

• **Use gl_FragCoord.xy** instead of fragCoord (WebGL2 does not have fragCoord built-in)

// WRONG

vec2 uv = (2.0 * fragCoord - iResolution.xy) / iResolution.y;

// CORRECT

vec2 uv = (2.0 * gl_FragCoord.xy - iResolution.xy) / iResolution.y;

main() Wrapper for ShaderToy Templates

• ShaderToy uses void mainImage(out vec4 fragColor, in vec2 fragCoord)

• WebGL2 requires standard void main() entry point — always wrap mainImage:

void mainImage(out vec4 fragColor, in vec2 fragCoord) {

    // shader code...

    fragColor = vec4(col, 1.0);

}

void main() {

    mainImage(fragColor, gl_FragCoord.xy);

}

Function Declaration Order

• GLSL requires functions to be declared before use — either declare before use or reorder:

// WRONG — getAtmosphere() calls getSunDirection() before it's defined

vec3 getAtmosphere(vec3 dir) { return getSunDirection(); } // Error!

vec3 getSunDirection() { return normalize(vec3(1.0)); }

// CORRECT — define callee first

vec3 getSunDirection() { return normalize(vec3(1.0)); }

vec3 getAtmosphere(vec3 dir) { return getSunDirection(); } // Works

Macro Limitations

• #define cannot use function calls — use const instead:

// WRONG

#define SUN_DIR normalize(vec3(0.8, 0.4, -0.6))

// CORRECT

const vec3 SUN_DIR = vec3(0.756, 0.378, -0.567); // Pre-computed normalized value

Script Tag Extraction

• When extracting shader source from <script> tags, ensure #version is the first character — use .trim():

const fs = document.getElementById('fs').text.trim();

Common Pitfalls

• Unused uniforms: Compiler may optimize away unused uniforms, causing gl.getUniformLocation() to return null — always use uniforms in a way the compiler cannot optimize out

• Loop indices: Use runtime constants in loops, not #define macros in some ES versions

• Terrain functions: Functions like terrainM(vec2) need XZ components — use terrainM(pos.xz + offset) not terrainM(pos + offset)

HTML Page Setup

When generating a standalone HTML page:

• Canvas fills the entire viewport, auto-resizes on window resize

• Page background black, no scrollbars: body { margin: 0; overflow: hidden; background: #000; }

• Implement ShaderToy-compatible uniforms: iTime, iResolution, iMouse, iFrame

• For multi-pass effects (Buffer A/B), use WebGL2 framebuffer + ping-pong (see multipass-buffer technique)

Common Pitfalls

JS Variable Declaration Order (TDZ — causes white screen crash)

let/const variables must be declared at the top of the <script> block, before any function that references them:

// 1. State variables FIRST

let frameCount = 0;

let startTime = Date.now();

// 2. Canvas/GL init, shader compile, FBO creation

const canvas = document.getElementById('canvas');

const gl = canvas.getContext('webgl2');

// ...

// 3. Functions and event bindings LAST

function resize() { /* can now safely reference frameCount */ }

function render() { /* ... */ }

window.addEventListener('resize', resize);

Reason: let/const have a Temporal Dead Zone — referencing them before declaration throws ReferenceError, causing a white screen.

GLSL Compilation Errors (self-check after writing shaders)

• Function signature mismatch: Call must exactly match definition in parameter count and types. If defined as float fbm(vec3 p), cannot call fbm(uv) with a vec2

• Reserved words as variable names: Do not use: patch, cast, sample, filter, input, output, common, partition, active

• Strict type matching: vec3 x = 1.0 is illegal — use vec3 x = vec3(1.0); cannot use .z to access a vec2

• No ternary on structs: ESSL does not allow ternary operator on struct types — use if/else instead

Performance Budget

Deployment environments may use headless software rendering with limited GPU power. Stay within these limits:

• Ray marching main loop: ≤ 128 steps

• Volume sampling / lighting inner loops: ≤ 32 steps

• FBM octaves: ≤ 6 layers

• Total nested loop iterations per pixel: ≤ 1000 (exceeding this freezes the browser)

Quick Recipes

Common effect combinations — complete rendering pipelines assembled from technique modules.

Photorealistic SDF Scene

• Geometry: sdf-3d (extended primitives) + csg-boolean-operations (cubic/quartic smin)

• Rendering: ray-marching + normal-estimation (tetrahedron method)

• Lighting: lighting-model (outdoor three-light model) + shadow-techniques (improved soft shadow) + ambient-occlusion

• Atmosphere: atmospheric-scattering (height-based fog with sun tint)

• Post: post-processing (ACES tone mapping) + anti-aliasing (2x SSAA) + camera-effects (vignette)

Organic / Biological Forms

• Geometry: sdf-3d (extended primitives + deformation operators: twist, bend) + csg-boolean (gradient-aware smin for material blending)

• Detail: procedural-noise (FBM with derivatives) + domain-warping

• Surface: lighting-model (subsurface scattering approximation via half-Lambert)

Procedural Landscape

• Terrain: terrain-rendering + procedural-noise (erosion FBM with derivatives)

• Texturing: texture-mapping-advanced (biplanar mapping + no-tile)

• Sky: atmospheric-scattering (Rayleigh/Mie + height fog)

• Water: water-ocean (Gerstner waves) + lighting-model (Fresnel reflections)

Stylized 2D Art

• Shapes: sdf-2d (extended library) + sdf-tricks (layered edges, hollowing)

• Color: color-palette (cosine palettes) + polar-uv-manipulation (kaleidoscope)

• Polish: anti-aliasing (SDF analytical AA) + post-processing (bloom, chromatic aberration)

Shader Debugging Techniques

Visual debugging methods — temporarily replace your output to diagnose issues.

What to check

Code

What to look for

Surface normals

col = nor * 0.5 + 0.5;

Smooth gradients = correct normals; banding = epsilon too large

Ray march step count

col = vec3(float(steps) / float(MAX_STEPS));

Red hotspots = performance bottleneck; uniform = wasted iterations

Depth / distance

col = vec3(t / MAX_DIST);

Verify correct hit distances

UV coordinates

col = vec3(uv, 0.0);

Check coordinate mapping

SDF distance field

col = (d > 0.0 ? vec3(0.9,0.6,0.3) : vec3(0.4,0.7,0.85)) * (0.8 + 0.2*cos(150.0*d));

Visualize SDF bands and zero-crossing

Checker pattern (UV)

col = vec3(mod(floor(uv.x*10.)+floor(uv.y*10.), 2.0));

Verify UV distortion, seams

Lighting only

col = vec3(shadow); or col = vec3(ao);

Isolate shadow/AO contributions

Material ID

col = palette(matId / maxMatId);

Verify material assignment