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

1. Read the Technique Routing Table below to identify which technique(s) match the user's request
2. Read the relevant file(s) from techniques/ — each file contains core principles, implementation steps, and complete code templates
3. If you need deeper understanding (math derivations, advanced patterns), follow the reference link at the bottom of each technique file to reference/
4. 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(