--- name: material-quality-checker description: Validate PBR material sanity, texture budgets, and web/runtime compatibility per material before render or export. --- # material-quality-checker ## Purpose Run a focused pass/warn/fail check on each material in the scene against PBR sanity, texture budgets, and consumer-stack compatibility — without expanding into lighting or composition concerns. ## Quick start - enumerate every material referenced in the scene plan or measured scene - check PBR sanity (albedo range, normal map sign, roughness/metallic plausibility) - check texture budget (resolution, count, format) - check consumer-stack compatibility (KHR extensions, unsupported features for chosen target) - emit per-material verdicts + a top-line status ## When to use - before render - before GLB export - after a material change request - as a sub-check during full quality review ## When not to use - upstream lookdev and material planning → use `../lighting-material-plan/SKILL.md` (use lighting-material-plan) - lighting validation → use `../lighting-quality-checker/SKILL.md` (use lighting-quality-checker) - composition / camera validation → use `../composition-quality-checker/SKILL.md` (use composition-quality-checker) - broad pass/warn/fail scene readiness → use `../scene-readiness/SKILL.md` (use scene-readiness) - web integration and viewer handoff → use `../glb-web-handoff/SKILL.md` (use glb-web-handoff) - to fix or edit materials (this skill validates and emits remediation hints only; it never edits) → use `../lighting-material-plan/SKILL.md` (this skill validates and emits remediation hints only; it never edits) ## Trigger phrases - "are the materials okay" - "check PBR sanity" - "texture budget for materials" - "will the materials work in Three.js" ## Prerequisites / readiness - material list known (from scene plan or measured scene) - consumer stack target known (Cycles render / Eevee preview / GLB → web) - texture budget pinned (typically from `mobile-glb-budget`) ## Input schema ### Required inputs | Input | Why it is required | |---|---| | Material list | Determines scope of the check | | Consumer target | Cycles vs Eevee vs glTF imposes different rules | | Texture budget | Drives texture-resolution and count checks | ### Optional inputs | Input | Use | |---|---| | Existing render reference | Allows visual cross-check | | Variant list | Configurator materials need separate variant rows | ### Assumptions to confirm - Albedo / base-color textures are sRGB; data textures (normal, roughness, metallic, AO) are linear. - Normal maps follow OpenGL convention (`+Y` up) for glTF-bound exports. - Shader graph is glTF-export-compatible if export is in scope. - Principled BSDF sockets are resolved by name (not position); version-dependent socket assumptions are marked in Notes. ## Output schema ### Primary output A per-material verdict table: name, type (PBR / non-PBR / variant), albedo state, normal state, roughness/metallic state, texture count + resolution sum, consumer-stack compatibility, verdict (Pass / Warn / Fail), notes. ### Secondary output - top-line status (Pass / Warn / Fail) computed from rows (separate from runtime/artifact truth states) - worst-offender highlighting (one or two materials to fix first) - remediation hint per Fail row (advisory only, without performing the fix) ### Evidence / caveat output - Artifact status defaults to `Not Produced` unless concrete output evidence exists. - Truth states are downgrade-only (never upgrade without recorded evidence) and remain strictly separate from per-material `Pass / Warn / Fail` validation verdicts. ```txt Runtime status: Not Run | Attempted | Produced | Verified | Failed Artifact status: Not Produced | Produced | Verified | Failed Evidence used: Limitations: ``` ## Required laws - `../../laws/evidence-before-done.md` - `../../laws/non-blender-user-language.md` - `../../laws/no-arbitrary-python-interface.md` - `../../laws/official-runtime-only.md` ## Official runtime boundary This skill validates plans or measured scene snapshots. It never modifies materials, runs Blender, or exports a GLB. If actual material values are needed, rely on a measured scene description (plan output, runtime tool snapshot) — never invent values. For runtime path attribution, see `../../docs/runtime-stack-strategy.md`. ## Operating procedure 1. Read the material list from scene plan or measured scene. 2. For each material, evaluate PBR sanity rules (see `references/pbr-sanity-rules.md`). 3. Evaluate texture budget per material against pinned budget. 4. Evaluate consumer-stack compatibility (see `references/consumer-stack-rules.md`). 5. Assign per-material verdict; collect notes. 6. Compute top-line status (any Fail → Fail; any Warn → Warn; otherwise Pass). 7. Highlight worst offenders; emit remediation hints. 8. Hand off to `scene-readiness` (broader review) or `render-export-evidence` (next runtime step). ## Decision tree ```txt Albedo pure white (1,1,1)? → Warn (real-world materials rarely are) Albedo pure black (0,0,0)? → Warn (likely error; even charcoal is ~0.04) Roughness = 0? → Warn (perfect mirror very rare) Metallic between 0 and 1 (not 0 or 1)? → Warn (PBR metallic is binary in physical sense) Normal map sign or convention unknown? → Warn until verified Texture above per-tier cap? → Fail Material count above pinned cap? → Fail (whole-scene) Unsupported shader node for chosen export? → Fail (e.g. OSL nodes for glTF) Unsupported shader feature for glTF export (OSL custom shaders, unbaked procedural noise/wave/voronoi, or drivers on material values)? → Fail Uses KHR glTF extensions (unlit, transmission, volume, ior, specular, clearcoat, emissive_strength, anisotropy, iridescence, variants) without consumer-stack confirmation? → Warn (escalate to Fail if target consumer explicitly lacks support) ``` ## Playbooks ### Playbook A: Single hero product, glTF export Hard rules: 4-channel ORM (Occlusion / Roughness / Metallic) packed; sRGB albedo; OpenGL normal; ≤ 4 materials; KHR extensions only if consumer stack confirmed. ### Playbook B: Configurator with variants Each variant row separately checked; share material slots where possible; verify `KHR_materials_variants` consumer support. ### Playbook C: Cycles-only render (no GLB) Looser texture format rules (EXR / Float allowed); still check albedo / normal / roughness sanity; ignore glTF-only constraints. ## Mode handling ### Text-only mode Verdicts based on plan / spec only; mark `Artifact status: Not Produced`. ### Runtime-ready mode Verdicts based on measured scene snapshot; cite tool used. Never upgrade to `Verified` without recorded measurement. ### Blocked runtime mode Skip rows that depend on measurement; mark explicitly. ## Validation checklist - [ ] Every material listed - [ ] PBR sanity columns filled (sRGB albedo, linear data textures, OpenGL `+Y` normal for glTF) - [ ] Principled BSDF sockets verified by name (version-dependent sockets marked) - [ ] Texture budget compared to pinned cap - [ ] Consumer-stack compatibility and KHR extensions checked - [ ] Per-material verdict assigned (`Pass / Warn / Fail`, kept separate from truth states) - [ ] Top-line status derived from rows - [ ] Worst offenders highlighted - [ ] Remediation hints advisory only (no material edits performed) - [ ] Honest downgrade-only evidence label (`Artifact status: Not Produced` default without concrete output evidence) ## Pass / Warn / Fail rubric | Verdict | Criteria | |---|---| | Pass | All materials pass sanity + budget + consumer compatibility; no Warns escalating to Fail. | | Warn | One or more materials have plausibility flags (white albedo, edge metallic) but no hard violations. | | Fail | Any material exceeds texture budget, uses unsupported features for chosen export, or violates per-tier caps. | ## Failure handling - Missing texture file → Fail with path note. - Invented values without measurement → refuse; produce empty rows + ask for plan or measurement. - User pushes for "Pass" without checks → restate requirement, do not relabel. ## Troubleshooting | Problem | Response | |---|---| | Material visible in viewport but missing from list | Confirm linked vs appended status; re-check measured scene snapshot. | | Roughness, metallic, normal, or AO texture looks wrong | Verify color space is linear (not sRGB); add Warn/Fail with remediation hint. | | Normal map looks inverted in glTF viewer | Verify OpenGL (`+Y` up) convention; add Warn until convention confirmed. | | GLB export fails or drops material features | Check for OSL custom shaders, unbaked procedural nodes (`noise`, `wave`, `voronoi`), or drivers on material values; add Fail with node/driver names. | | KHR extension appearance missing in target viewer | Confirm consumer support for `unlit`, `transmission`, `volume`, `ior`, `specular`, `clearcoat`, `emissive_strength`, `anisotropy`, `iridescence`, or `variants`. | | Value lands on the wrong shader input | Socket was resolved by index across Blender versions; re-resolve Principled BSDF inputs by name. | ## Best practices - Pair every Fail with the rule that triggered it. - Mark Warn rows that escalate to Fail when consumer is mobile (e.g. 4K texture warns on desktop, fails on mobile). - Cite consumer stack in every verdict. - Resolve Principled BSDF inputs by name across Blender versions; never by position. - Keep this skill narrow — do not creep into lighting or composition. ## Good examples - "Albedo (0.04, 0.04, 0.04), Roughness 0.4 (linear), Metallic 0, ORM packed 1024², GLB-compatible. Verdict: Pass." ## Bad examples - "Materials look fine." — no per-material rows, no verdicts. - "Verified PBR" — without a sanity rule cited. ## User-facing response template ```txt Consumer target: Texture budget cap: | Material | Type | Albedo | Normal | Rough/Met | Tex count + res | Consumer | Verdict | Notes | |---|---|---|---|---|---|---|---|---| | | PBR | | | | | | Pass/Warn/Fail | | Top-line: Worst offenders: Remediation hints: Runtime status: Artifact status: Evidence used: Limitations: Next: ``` ## Anti-patterns - Performing material edits inside this skill. - Inventing values to make rows pass. - Resolving shader sockets by index instead of by name. - Assuming a Principled socket exists on every Blender version. - Marking Verified without measurement. - Mixing lighting / composition checks here. ## Cross-skill handoff - [retry] Upstream lookdev & material planning → `../lighting-material-plan/SKILL.md` - [upstream_reference] Mobile/web texture budget definition → `../mobile-glb-budget/SKILL.md` - [progression] Broad readiness review → `../scene-readiness/SKILL.md` - [progression] Lighting validation → `../lighting-quality-checker/SKILL.md` - [progression] Composition validation → `../composition-quality-checker/SKILL.md` - [progression] Polycount budget → `../polycount-budget-checker/SKILL.md` - [progression] Render / GLB export evidence → `../render-export-evidence/SKILL.md` - [progression] Web handoff → `../glb-web-handoff/SKILL.md` ## Non-goals - Edit materials. - Generate shader code. - Replace `scene-readiness` (this skill is one of its inputs). - Run Blender. ## References - `references/pbr-sanity-rules.md` - `references/texture-budget-rules.md` - `references/consumer-stack-rules.md` - `../../laws/evidence-before-done.md` - `../../docs/skill-system.md`