shader-dev

# 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](techniques/ray-marching.md) + [sdf-3d](techniques/sdf-3d.md) | lighting-model, shadow-techniques |
| Complex 3D shapes (booleans, blends) | [csg-boolean-operations](techniques/csg-boolean-operations.md) | sdf-3d, ray-marching |
| Infinite repeating patterns in 3D | [domain-repetition](techniques/domain-repetition.md) | sdf-3d, ray-marching |
| Organic / warped shapes | [domain-warping](techniques/domain-warping.md) | procedural-noise |
| Fluid / smoke / ink effects | [fluid-simulation](techniques/fluid-simulation.md) | multipass-buffer |
| Particle effects (fire, sparks, snow) | [particle-system](techniques/particle-system.md) | procedural-noise, color-palette |
| Physically-based simulations | [simulation-physics](techniques/simulation-physics.md) | multipass-buffer |
| Game of Life / reaction-diffusion | [cellular-automata](techniques/cellular-automata.md) | multipass-buffer, color-palette |
| Ocean / water surface | [water-ocean](techniques/water-ocean.md) | atmospheric-scattering, lighting-model |
| Terrain / landscape | [terrain-rendering](techniques/terrain-rendering.md) | atmospheric-scattering, procedural-noise |
| Clouds / fog / volumetric fire | [volumetric-rendering](techniques/volumetric-rendering.md) | procedural-noise, atmospheric-scattering |
| Sky / sunset / atmosphere | [atmospheric-scattering](techniques/atmospheric-scattering.md) | volumetric-rendering |
| Realistic lighting (PBR, Phong) | [lighting-model](techniques/lighting-model.md) | shadow-techniques, ambient-occlusion |
| Shadows (soft / hard) | [shadow-techniques](techniques/shadow-techniques.md) | lighting-model |
| Ambient occlusion | [ambient-occlusion](techniques/ambient-occlusion.md) | lighting-model, normal-estimation |
| Path tracing / global illumination | [path-tracing-gi](techniques/path-tracing-gi.md) | analytic-ray-tracing, multipass-buffer |
| Precise ray-geometry intersections | [analytic-ray-tracing](techniques/analytic-ray-tracing.md) | lighting-model |
| Voxel worlds (Minecraft-style) | [voxel-rendering](techniques/voxel-rendering.md) | lighting-model, shadow-techniques |
| Noise / FBM textures | [procedural-noise](techniques/procedural-noise.md) | domain-warping |
| Tiled 2D patterns | [procedural-2d-pattern](techniques/procedural-2d-pattern.md) | polar-uv-manipulation |
| Voronoi / cell patterns | [voronoi-cellular-noise](techniques/voronoi-cellular-noise.md) | color-palette |
| Fractals (Mandelbrot, Julia, 3D) | [fractal-rendering](techniques/fractal-rendering.md) | color-palette, polar-uv-manipulation |
| Color grading / palettes | [color-palette](techniques/color-palette.md) | — |
| Bloom / tone mapping / glitch | [post-processing](techniques/post-processing.md) | multipass-buffer |
| Multi-pass ping-pong buffers | [multipass-buffer](techniques/multipass-buffer.md) | — |
| Texture / sampling techniques | [texture-sampling](techniques/texture-sampling.md) | — |
| Camera / matrix transforms | [matrix-transform](techniques/matrix-transform.md) | — |
| Surface normals | [normal-estimation](techniques/normal-estimation.md) | — |
| Polar coords / kaleidoscope | [polar-uv-manipulation](techniques/polar-uv-manipulation.md) | procedural-2d-pattern |
| 2D shapes / UI from SDF | [sdf-2d](techniques/sdf-2d.md) | color-palette |
| Procedural audio / music | [sound-synthesis](techniques/sound-synthesis.md) | — |
| SDF tricks / optimization | [sdf-tricks](techniques/sdf-tricks.md) | sdf-3d, ray-marching |
| Anti-aliased rendering | [anti-aliasing](techniques/anti-aliasing.md) | sdf-2d, post-processing |
| Depth of field / motion blur / lens effects | [camera-effects](techniques/camera-effects.md) | post-processing, multipass-buffer |
| Advanced texture mapping / no-tile textures | [texture-mapping-advanced](techniques/texture-mapping-advanced.md) | terrain-rendering, texture-sampling |
| WebGL2 shader errors / debugging | [webgl-pitfalls](techniques/webgl-pitfalls.md) | — |

## 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)
```glsl
// 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:
```glsl
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:
```glsl
// 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:
```glsl
// 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()`:
```javascript
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:

```javascript
// 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
1. **Geometry**: sdf-3d (extended primitives) + csg-boolean-operations (cubic/quartic smin)
2. **Rendering**: ray-marching + normal-estimation (tetrahedron method)
3. **Lighting**: lighting-model (outdoor three-light model) + shadow-techniques (improved soft shadow) + ambient-occlusion
4. **Atmosphere**: atmospheric-scattering (height-based fog with sun tint)
5. **Post**: post-processing (ACES tone mapping) + anti-aliasing (2x SSAA) + camera-effects (vignette)

### Organic / Biological Forms
1. **Geometry**: sdf-3d (extended primitives + deformation operators: twist, bend) + csg-boolean (gradient-aware smin for material blending)
2. **Detail**: procedural-noise (FBM with derivatives) + domain-warping
3. **Surface**: lighting-model (subsurface scattering approximation via half-Lambert)

### Procedural Landscape
1. **Terrain**: terrain-rendering + procedural-noise (erosion FBM with derivatives)
2. **Texturing**: texture-mapping-advanced (biplanar mapping + no-tile)
3. **Sky**: atmospheric-scattering (Rayleigh/Mie + height fog)
4. **Water**: water-ocean (Gerstner waves) + lighting-model (Fresnel reflections)

### Stylized 2D Art
1. **Shapes**: sdf-2d (extended library) + sdf-tricks (layered edges, hollowing)
2. **Color**: color-palette (cosine palettes) + polar-uv-manipulation (kaleidoscope)
3. **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 |