BumpyClock/agent-templates / skills/shader-art-coding
shader-art-coding
VerifiedWrites, debugs, and art-directs procedural GLSL fragment shaders (Shadertoy mainImage, WebGL2 / GLSL ES 3.00): SDF raymarching, procedural buildings/cities, 2D distance-field graphics, noise / fBm / domain warping, terrain, ocean/coastal water optics, clouds and other volumes, PBR lighting, color and tonemapping. Ships a verified GLSL building-block library with a bundler and checker. Use when the user asks for a shader, Shadertoy, GLSL/.frag/.glsl code, a raymarcher, an SDF scene, a procedural texture or generative visual, or wants a shader fixed, optimized, ported or explained. Not for HLSL/Unity ShaderLab or non-graphics GPU compute.
references/composition-and-debugging.md
View on GitHub# Composition and Debugging
## Contents
- [Composition Rules for Procedural Shaders](#composition-rules-for-procedural-shaders)
- [Debugging Ritual](#debugging-ritual)
- [Formula Verification From Visual Sources](#formula-verification-from-visual-sources)
- [Common Failure Modes](#common-failure-modes)
- [Quality Passes](#quality-passes)
- [Response Pattern](#response-pattern)
## Composition Rules for Procedural Shaders
Make the image readable before making it detailed:
- Use one dominant silhouette or value mass.
- Reserve high contrast for the focal area.
- Separate foreground, midground, and background by value and saturation.
- Use atmosphere, scale, and texture frequency to show depth.
- Let repeated elements vary in size, color, angle, or phase.
- Keep large forms stable; animate small details unless the scene is about motion.
For bilateral organic carrier scenes (characters, creatures, faces, figurines):
- Establish dominant/secondary lobe proportions first.
- Use symmetry only as a starting point; break it with pose, anisotropic strands, shell layers, or expression parameters.
- Detail focal bilateral features more than distant or peripheral shapes.
- Use material contrast to separate subsurface, woven, filament, metallic, accumulation, or prop materials.
For heightfield scenes (landscapes, dunes, oceans):
- Build the heightfield silhouette first.
- Place the sun and horizon early.
- Use distance fog before adding tiny density-field details.
- Use instance/material IDs for variation but keep clump structure coherent.
For constructed objects (buildings, machines, tiled and modular props):
- Define the base primitive and repetition system.
- Keep local coordinates and cell IDs available for color variation.
- Add seams, interstitial fields, bevels, or edge wear after the major tiling reads correctly.
## Debugging Ritual
When a shader fails visually, inspect fields instead of guessing. Every shader in this pack declares
`#define DEBUG_MODE 0` (Shadertoy has no custom uniforms) and uses one numbering:
| Mode | Shows | Library helper | Look for |
|---|---|---|---|
| 0 | final render | | |
| 1 | distance field / contours (2D slice through a 3D scene) | `debugDistance(d)` | wrong signs, kinked blends, bad scale |
| 2 | normals | `debugNormal(n)` | seams, noise, flipped faces |
| 3 | material / cell ids | `debugIdColor(id)` | lost ids, repetition errors |
| 4 | step count or depth | `debugHeat(steps / maxSteps)` | overshooting fields, wasted steps |
| 5 | masks / density | grayscale or RGB-packed masks | hard edges, noisy masks |
| 6 | lighting terms | key, fill, specular in R, G, B | missing shadows, AO on the sun |
Order of inspection: coordinates, raw field, ids, normals, steps, lighting terms, then re-enable composition in
layers. Do not debug a full shaded image when the broken term can be displayed directly.
## Formula Verification From Visual Sources
When learning from a video, screenshot, or visual derivation, sample more than the final frame:
- Early frames reveal the primitive and coordinate system.
- Middle frames reveal IDs, local coordinates, repetition, and masking.
- Late frames reveal material, lighting, and detail breakup.
- Final frames often reveal temporal polish: subtle camera drift, procedural background blur, atmospheric motion, or tiny pose changes.
- Top-ranked code/formula frames often overrepresent final code, so also inspect chronological sheets.
Record the verified formula families, not copied source. For each family, capture:
- visual stage,
- coordinate space,
- scalar/vector field,
- IDs retained,
- visible debug output,
- final material/rendering use.
This prevents the common mistake of remembering the final image but missing the controllable formulas that built it.
## Common Failure Modes
- Aspect distortion: coordinates divide by `iResolution.x` and `iResolution.y` inconsistently.
- Dead noise: high-frequency noise is added before the large form works.
- Mushy SDFs: smooth unions use a radius larger than the feature scale.
- Lost material IDs: geometry distance and material assignment are separated incorrectly.
- Shadow acne: epsilon is too small or not scaled by hit distance.
- Flat composition: all objects have similar value and saturation.
- Expensive loops: nested fbm inside raymarching inside shadow calls.
- Temporal shimmer: noise or thresholds change abruptly with time or distance.
## Quality Passes
Run these passes in order:
- Shape pass: show only silhouettes and major masks.
- Value pass: convert mentally to grayscale; focal contrast should survive.
- Material pass: each material should be identifiable under simple light.
- Light pass: key direction, fill, shadow softness, and rim are deliberate.
- Atmosphere pass: distance, scale, and depth are clear.
- Motion pass: animation has stable phase and loops if requested.
- Performance pass: reduce octaves, step counts, shadow calls, and repeated map evaluations.
## Response Pattern
When presenting a shader, include:
- What the shader renders.
- The complete code or the precise patch.
- Debug controls or intermediate fields.
- Tuning knobs.
- Performance notes if raymarching, fbm, shadows, or volumetrics are involved.
- Whether it was compile-checked (`scripts/glsl_tools.py check`), and how.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |