Procedural Materials

Build a material from surface identity and causes. Color, roughness, metalness, normal, transmission, and emission should describe the same surface—not unrelated noise textures.

This skill contains exemplary examples and assets beyond descriptive guidance, they're worth studying, referencing, or even copying. Use them sufficiently when relevant and do NOT blindly skip them.

Material graph order

stable coordinates
  → structural fields
  → material identity weights
  → causal modifiers
  → filtered microstructure
  → PBR channels
  → lighting/shadow extensions

Read [references/procedural-pbr-system.md](references/procedural-pbr-system.md) for atlas filtering, specular AA, planetary coordinates, world-height wetness, per-instance dissolve, and authored PBR response bundles.

Read the [sculpted gallery frame geometry](../threejs-procedural-geometry/examples/sculpted-gallery-frame/frame-geometry.js) for walnut, antique-gold, and ebony texture/roughness/metalness/clearcoat bundles under a grazing-light setup.

Read the [procedural planet surface](../threejs-procedural-planets/examples/procedural-planet-surface/planet-system.js) for shared geological, climate, water, biome, roughness, and derivative-normal causes on a procedural planetary surface.

Read the [analytic wave optics](../threejs-water-optics/examples/analytic-wave-optics/water-system.js) for coupled reflection, refraction, absorption, filtered microstructure, resolved crest response, and their diagnostic channels.

Read the [lava flow surface material](examples/lava-flow-surface/lava-surface.js) for raymarched procedural height fields whose normals, rock/lava identity, emission, glow, embers, fog, and grain are coupled to one material cause stack.

Read the [raytraced diamond material](examples/raytraced-diamond/diamond-material.js) for a gem whose mesh is its own optical volume: camera-ray entry refraction, a GPU BVH first-hit loop with bounded total-internal-reflection bounces, per-channel IOR dispersion, mip-correct environment exit sampling, and live camera-matrix uniforms.

Read the [spectral dispersive glass material](examples/spectral-dispersive-glass/spectral-glass-material.js) for a transmissive body solved in image space: a double-sided back-face data pass with inverted depth, an iterative interior exit search, bounded total internal reflection, Beer-Lambert absorption over the true path length, and a per-wavelength Cauchy index recombined through CIE 1931. Its reusable optical primitives — exact unpolarised Fresnel, Cauchy coefficients, spectral weights, the rotatable environment probe, and the buffer projection — live in [glass optics](examples/spectral-dispersive-glass/glass-optics.js), and [references/dielectric-glass-optics.md](references/dielectric-glass-optics.md) carries the two-pass contract, buffer format, search bounds, and transmission diagnostics.

Pick between the two transmissive paths by geometry, not by quality. A closed faceted gem whose exit facet must be exact even when it faces away from the camera takes the BVH path. A scanned, assembled, open-sheet, or multi-shell body takes the image-space path, which tolerates inconsistent winding and authored normals pointing either way but cannot see a surface outside the frame.

Read [references/physical-diffraction-grating.md](references/physical-diffraction-grating.md) for the exact embossed-field, CIE/blackbody spectral, phase-grating, Bessel order-efficiency, coherence-broadening, strip-emitter, additive-layer, stable object-frame, limitation, and diagnostic contracts.

Read the [physical diffraction-grating implementation](examples/physical-diffraction-grating/physical-diffraction-grating.js) for a printed substrate plus additive HDR foil response whose star and stripe masks select local groove angle, pitch, and relief while wavelength alone owns spectral colour. Its complete optical model is expressed as a pure TSL graph with Fn, If, and Loop, without embedded native shader source.

Read [references/thin-film-soap-bubble-system.md](references/thin-film-soap-bubble-system.md) for the air-film-air Airy equation, representative RGB spectral bands, two-membrane blending, bounded secondary reflection, capillary mechanics, camera-aware inflow, puncture retraction, limits, and diagnostics.

Read the [thin-film soap bubble system](examples/thin-film-soap-bubbles/soap-bubble-system.js) when soap-film interference must drive the image: it provides wavelength- dependent aqueous index, front and rear membrane passes, analytic nearby- bubble reflection, volume-preserving capillary modes, buoyancy and drag, Taylor-Culick rupture, visible-drop aftermath, and deterministic physics gates.

Required controls

• real or perceptual texture scale;
• material identity weights;
• roughness range and micro-normal strength;
• the causal fields required by the selected material pattern;
• for a transmissive body, the physical constants that define it — index and

Abbe pair, interior path budget, extinction depth — named rather than buried inside expressions;

• for a soap film, the exterior and film indices, nanometre thickness range,

wavelength bands, surface tension, and membrane ordering;

• distance/derivative filtering;
• specular antialiasing;
• channel and mask debug modes.
• emissive-material debug modes when the material owns glow or volumetric

accumulation.

Read [references/hybrid-soil-moss-surface.md](references/hybrid-soil-moss-surface.md) and the [hybrid soil and moss implementation](examples/hybrid-soil-moss-surface/hybrid-soil-moss-surface.js) for texture-backed soil and moss albedo, AO, roughness, and normal microdetail combined with procedural mound displacement, moisture, moss coverage/height, and warped cellular cracks. Do not describe its surface identity as fully procedurally synthesized. When moss must also settle onto a model, read the [model moss implementation](examples/hybrid-soil-moss-surface/model-moss-accumulation.js) for model-locked coverage, upward-face accumulation, displaced thickness, and shared moss PBR identity.

Failure conditions

• every PBR channel samples independent noise;
• roughness is a scalar afterthought;
• high-frequency normals survive below one pixel;
• triplanar projection has visible orientation or scale seams;
• atlas padding is ignored under mipmapping;
• custom lighting removes energy conservation without an explicit stylized goal;
• post-processing is used to hide unstable highlights.
• diffraction hue is painted from UV instead of derived from wavelength;
• a groove frame follows the camera or world axes instead of the object;
• a narrowed diffraction lobe loses energy because its density lacks sigma normalization.
• a soap bubble is treated as a solid glass sphere or painted with a rainbow instead of using air-film-air interference;
• a deformed soap membrane retains the undeformed sphere normal;

Routing boundary

Use $threejs-procedural-fields when the main problem is designing shared scalar/vector causes. Use $threejs-procedural-planets for a complete orbit-to-close-approach body, not merely its material. Use $threejs-parallax-occlusion-mapping when a height field must own ray-marched intersection, silhouette coverage, or relief-aware shadows. Use $threejs-temporal-surfaces for view-aligned wet-glass optics and screen-space history; this skill owns the optical path through a transmissive body itself.