---

name: scenario-blender-texturing-shading description: "Use when texturing, shading or look-developing in Blender: building a PBR material from a texture set, displacement, procedural materials, edge wear, dirt, grime, color variation, decals, box or triplanar mapping on meshes without UVs, stylized character skin (subsurface, pores), eyes and cornea, hand-painted stylized textures, texture painting or painting masks headless. Also when a material looks plastic, CG, waxy or blown out, color spaces are wrong, or EEVEE and Cycles disagree." license: MIT

Texturing and shading (Blender 5.2)

Expert shading is layered masks feeding physically plausible values: a clean base (scanned set or flat colors), then contrasty black/white masks that place color, roughness, height and subsurface, all editable in nodes. Values are judged under honest light in both engines, and baking comes last, for portability. If a sibling skill named here is missing from your available skills, ask the user to install it (npx skills add scenario-labs/skills --skill <name>); unattended, proceed from tool schemas and flag the gap.

REQUIRED BACKGROUND: scenario-blender-expert (execution channel, review loop, 5.2 API changes). Baking maps: scenario-blender-uv-baking. Lighting and final renders: scenario-blender-lighting-rendering.

Toolkit: scripts/bx_materials.py (builders, headless painting, checks; exercised by tests/code/blender-texturing-shading/). sys.path.append("<this skill>/scripts"); import bx_materials as M.

Stance (the expert delta)

• Data maps are Non-Color, "not what looks better, what's correct" (Price). Only base color and emission are sRGB.
• Normal map OR displacement, never both (Price, confirmed by Cycles lead Brecht): they encode the same relief. Displacement when heights will be combined or truly displaced; normal map for export and 8-bit safety.
• Masks, not painted color. Kaspar and Price build every effect as a grayscale mask into a Mix or HSV Factor; color lives in the A/B inputs. Masks need contrast (Color Ramp stops pulled in) or they barely show. The same masks drive roughness, height and SSS.
• Realism: scanned set plus masks; stylized: procedural (Price vs Kaspar and Ryan King). Kaspar strips photos to their pattern (blur plus grain extract) and adds grunge himself, and bakes at the end for portability (export, EEVEE load time), not for Cycles speed.
• Micro detail in roughness, not bump, for skin and hair (Kaspar); edit roughness through HSV Value, never by unplugging the map (Price). Specular stays 0.5. Bump Distance is the real height of the map's 0..1: lower Distance, not Strength (Kaspar).
• Judge honestly: Standard view, neutral mid-gray background, Base Color black to read roughness, a hard backlight and a light from below (Kaspar); grazing light for relief (Price); unlit for hand-painted albedo (Abbitt). EEVEE for iteration, Cycles as the truth, and they must match (Kaspar).
• SSS follows anatomy (Kaspar): high on ears, nose, lids, lips, fingertips; low over bone. Black/white mask, Map Range sets values.
• Bevel, AO, Pointiness and Random Per Island are Cycles-only, and Bevel/AO are stochastic [added, measured]: EEVEE shows no Bevel edges; thresholded live masks give 17 to 18% fractional metallic at any sample count. Bake before thresholding, or use vertex curvature.

Establish first

Input	Changes	Default when silent
Target: Cycles still, EEVEE, game engine	live Cycles-only nodes vs baked; AO in albedo (render) vs ORM (game)	Cycles finals, EEVEE side by side
Style: realistic or stylized	scanned set + grime vs procedural or hand-painted light	stylized restraint (Kaspar)
UVs and deformation	UV images vs box projection vs Object procedurals	rigid, no UVs: box; deforming: UV only
Scale	tile size, bump/displacement meters	real meters, scale applied (all experts)
Texel budget, export	2K to 4K hero paint, 4K to 8K large tiling surfaces	2K hero prop, glTF ORM, OpenGL normals

Workflow

1. Base per part. Prefixed materials, placeholders removed, diffuse_color set; values picked on the Diffuse Color pass (matcap made Kaspar's skin too pale). Apply scale. GATE: M.value_report(objs) clean.
2. Base material. Set: M.pbr_from_textures(mat, M.find_texture_set(dir), uv_map=...): color spaces by role, AO multiplied at factor 1 (Price: restores the cavity shadow flash capture removes; ao_mode="gltf" for games), bump only without a normal map, height_as="displacement" drops the normal map and sets Cubic interpolation, Displacement and Bump, Scale 0.2 for Poliigon (fixed 20 cm range); add Simple subdivision and shade smooth. UV tile = the set's physical size. Rigid, no UVs: projection="BOX". Procedural: Object coordinates (UV on deforming meshes), Noise Detail at most 5 (cost doubles per level, Price). GATE: M.audit_material(mat, obj) has no errors.
3. Masks. Kaspar's rule is mask frequency against vertex density: vertex colors for broad soft masks (and Price's environments: tiling UVs repeat image strokes, layouts change), images for fine or exported detail, UV bands for hems. Headless: M.mask_from_points, M.write_vertex_values, M.smooth_attribute, M.curvature_attribute, M.TexelMap + M.project. Price's Color Burn: soft mask (A) burned by a contrast-ramped height map (B) breaks the mask along bricks or into grout (procedures P18). GATE: render each mask as emission.
4. Layers. M.add_wear(mat, edge_color=..., edge_roughness=..., edge_metallic=1) adds variation, cavity/grunge dirt and chipped edges. Blend modes: Multiply darkens (grime, mold), Screen lightens (efflorescence, highlights; Add exceeds 1), Subtract on the height chain for spalling (Price). Chain order sets age (a decal before grime reads old). Decals: Alpha into Factor, Extension Clip (M.add_decal). GATE: M.preview(objs, out, rigs=("studio", "roughness")): effects follow form and water paths, nothing uniform, repeats broken.
5. Character specifics. M.stylized_skin(mat, obj=body) (masks col_brighter/col_darker/col_lips/col_sss/col_rough); M.stylized_eye per eye object (origin at the eyeball center) plus M.cornea_material and cornea.visible_shadow = False; hair shine: Anisotropic with a Tangent on a strand-aligned UV map (Cycles only). GATE: rigs=("backlit",): red glow on ears, nostrils, lips, fingers; front not waxy; sclera off-white.
6. Stylized hand-painted light (Abbitt): lighter top, darker bottom, Multiply in crevices, Screen on extremities. Headless: M.painted_light(mat, obj) from a curvature attribute, bake Emit, judge with rigs=("unlit",).
7. Painting, where masks cannot place it. GUI: brushes are assets (Paint Hard/Soft, Airbrush, Blur, Smear, Fill, Mask); a factory 5.2 session paints BLACK until the brush and unified color are set; strokes project from the screen, so face the surface (Abbitt); Erase needs an alpha channel; bleed 8 to 12 px (Kaspar, Abbitt). Use M.gui_texture_stroke(): it forces a redraw (projection painting occludes with the depth buffer of the previous draw: a stroke issued in the setup call painted 162 texels in one run instead of about 14,000, full coverage in another) and resamples dabs. Headless: M.TexelMap + M.paint_stroke paints by world distance, seams included; M.dilate, then M.save_image (images are never saved with the .blend by a script). GATE: renders from views crossing seams.
8. Lookdev check and bake. M.preview (EEVEE and Cycles, studio, backlit, roughness), M.value_report, labeled frames and node groups (Kaspar, Price). Bake procedural channels via Emission, 30+ samples, validate by rebuilding from the maps (scenario-blender-uv-baking).

Numbers

Value	Number	Source
Dielectric albedo / metal reflectance	sRGB about 30 to 240 / 180 to 255; metallic 0 or 1	ranges [added]; binary metallic: Ryan King, Price
Skin roughness	0.68 to 0.72, rough zones 0.72 to 1, lips and mouth about 0.4	Kaspar
Pores	Voronoi Smooth F1 scales 100 and 200, noise mix 0.2 to 0.25	Kaspar, on his UVs
Skin SSS scale (5.2)	0.005 to 0.04 m	measured on a 0.33 m head; Kaspar's v1 0.02 to 0.15 is waxy in 5.2
Bump	Distance about 0.001, Strength 0.1 to 0.2 for fabric	Kaspar
Displacement	Scale 0.2 (Poliigon), Midlevel 0.5, Cubic, 16-bit source	Price
Brick wall roughness	about 0.7	Price
Color tweak	Hue within 0.5 plus or minus 0.04	Price
Noise Detail	5 or less	Price
Edge-wear Bevel radius	0.04 on a 1 m crate	measured
Paint bleed / island margin	8 to 12 px / 0.01 to 0.05	Kaspar, Abbitt
Painted height	2K, 32-bit float, base 0.5, Non-Color	Kaspar; 0.5 gray base also Ryan King
Bake samples	30 minimum	Kaspar

Quality gates

Measurable:

• M.audit_material(mat, obj): color spaces by role, no image straight into Normal, explicit UV maps, Bump Distance at most 0.05, no Add Shader or raw summed normals, Emission Strength set, no gray constant metallic, normal map plus displacement flagged, non-Cubic displacement image, Noise Detail above 6, unsaved images.
• M.value_report(objs): dielectric albedo within 30 to 243 sRGB (under 2% outside), metal above 180, fractional metallic under 5% (live Bevel/AO wear exceeds it until baked), roughness std above 0.01.
• Scale applied; color attributes named col_* and matching every Attribute node exactly (Kaspar, Price).

Visual: M.preview EEVEE vs Cycles nearly identical; roughness row shows breakup; backlit glow only where flesh is thin; grazing light shows relief without terracing; repeats broken at distance; per-layer mute renders each add something (Price); scale against a human reference.

Common mistakes

Mistake	Looks like	Fix
Data map left sRGB	bent bump, wrong gloss	Non-Color
Normal map and displacement together (Node Wrangler default)	doubled or broken relief	keep one
Displacement with no geometry or Catmull-Clark	nothing, or rounded corners	Simple subdivision, shade smooth
Pre-4.5 Bump Distance 1.0	stepped, plastic	real height, about 0.001 to 0.01
Emission Color set, Strength 0	no glow	Strength above 0
Kaspar's v1 SSS values in 5.2	waxy white ears	0.005 to 0.04, check backlit
Bevel wear or Pointiness in EEVEE or games	wear missing	bake, or curvature_attribute
Threshold on live Bevel/AO for metallic	grainy gray borders	bake, then threshold
Cornea shell in EEVEE, default thickness	iris magnified	Thickness 0 (cornea_material)
Mask straight from Noise	effect barely visible	ramp or Map Range for contrast
Stroke right after setup	partial or no paint, varies per run	redraw first (gui_texture_stroke)
Paint color never set / new color attribute	black strokes / white mask	set colors; write zeros first
Box projection or Generated coords on a rig	texture swims	UV coordinates

Blender 5.2 notes

• Principled v2: Subsurface Weight/Scale (no Subsurface Color), Specular IOR Level, Transmission Weight, Coat, Emission Strength default 0. Sockets by name; Mix node by index (RGBA: A=6, B=7, Result=2).
• Color spaces sRGB, Non-Color, Linear Rec.709. Displacement node Scale default 0.01; material.displacement_method (not material.cycles); EEVEE displaces since 4.2 (Displacement and Bump).
• use_nodes deprecated; surface_render_method replaces blend_method; refraction needs use_raytrace_refraction plus scene ray tracing.
• EEVEE ignores anisotropy, Bevel, Pointiness, Random Per Island (verified). Random Walk SSS rescaled in 5.2. Musgrave is inside Noise.
• Brushes are assets; custom brushes need "Save Changes to Asset" (Abbitt); image_brush_type; Blur is SOFTEN; sample color Shift+X.
• paint.vertex_color_dirt works headless in Object mode; byte images store encoded values, float Linear Rec.709 images convert to sRGB when saved as PNG.

References

• references/procedures.md: tested code for every stage (texture sets, displacement rule, box projection, wear, curvature, decals, skin, eyes, anisotropy, GUI and headless painting, high-pass, checks, camera-ray world, clay switch, painted light, Color Burn masks, physical UV scale).
• references/expert-notes.md: reasoning per expert with timestamps and the disagreements with their deciding conditions.
• references/critique.md: rubric for judging your own renders and node trees.
• references/sources.md: every source video, credential, best timestamps.