Skip to content

BumpyClock/agent-templates / skills/shader-art-coding

shader-art-coding

Verified

Writes, 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.

FileKindSize
CREDITS.mdmarkdown6.3 KB
LICENSEother1.0 KB
SKILL.mdskill md7.1 KB
agents/openai.yamlconfig298 B
glsl/architecture.glslother1.8 KB
glsl/atmosphere.glslother4.6 KB
glsl/camera.glslother2.1 KB
glsl/color.glslother4.7 KB
glsl/common.glslother2.7 KB
glsl/debug.glslother1.4 KB
glsl/domain.glslother4.8 KB
glsl/hash.glslother4.1 KB
glsl/intersect.glslother1.7 KB
glsl/noise.glslother21.3 KB
glsl/operators.glslother5.3 KB
glsl/pattern.glslother3.1 KB
glsl/post.glslother2.6 KB
glsl/raymarch.glslother4.0 KB
glsl/sdf2d.glslother11.7 KB
glsl/sdf3d.glslother10.0 KB
glsl/shading.glslother4.6 KB
glsl/tonemap.glslother4.8 KB
glsl/volume.glslother3.4 KB
glsl/water.glslother3.1 KB
references/composition-and-debugging.mdmarkdown5.2 KB
references/formula-code-couples-materials.mdmarkdown15.5 KB
references/formula-code-couples-sdf.mdmarkdown20.5 KB
references/formula-code-couples-terrain.mdmarkdown17.1 KB
references/formula-cookbook.mdmarkdown19.0 KB
references/library-index.mdmarkdown56.2 KB
references/noise-use-cases.mdmarkdown17.1 KB
references/procedural-buildings.mdmarkdown7.5 KB
references/rendering-pipeline.mdmarkdown8.4 KB
references/sdf-library-guide.mdmarkdown10.4 KB
references/shader-workflow.mdmarkdown3.5 KB
references/subject-routing.mdmarkdown9.7 KB
references/terrain-production.mdmarkdown7.3 KB
references/water-quality.mdmarkdown10.6 KB
scripts/glsl_tools.pyscript29.4 KB
templates/alpine-valley.glslother3.9 KB
templates/coastal-water.glslother7.6 KB
templates/noise-progression.glslother2.3 KB
templates/noise-terrain-map.glslother2.2 KB
templates/ocean.glslother13.1 KB
templates/pattern-swatches.glslother3.6 KB
templates/procedural-city.glslother4.5 KB
templates/raymarch-sdf.glslother5.3 KB
templates/sdf-2d-poster.glslother3.7 KB
templates/terrain.glslother4.7 KB
templates/volumetric-clouds.glslother3.9 KB

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.
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 implementationStars: 318kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 318kUpdated Claude CodeCodexVerifiedInstall
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 fallbackStars: 318kUpdated Claude CodeCodexVerifiedInstall
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 alwaysStars: 318kUpdated Claude CodeCodexVerifiedInstall