Material Quality Checker

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

• lighting validation (use lighting-quality-checker)
• composition / camera validation (use composition-quality-checker)
• broad pass/warn/fail readiness (use blender-scene-quality-checker)
• to fix materials (this skill validates, it does not edit)

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 glb-mobile-performance-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.

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
• worst-offender highlighting (one or two materials to fix first)
• remediation hint per Fail row (without performing the fix)

Evidence / caveat output

Runtime status: Not Run | Attempted | Produced | Verified | Failed | Blocked / Not Run
Artifact status: Not Run | 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 blender-scene-quality-checker (broader review) or render-export-evidence (next runtime step).

Decision tree

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)

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 Run.

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
• [ ] Texture budget compared to pinned cap
• [ ] Consumer-stack compatibility checked
• [ ] Per-material verdict assigned
• [ ] Top-line status derived from rows
• [ ] Worst offenders highlighted
• [ ] No remediation performed inside this skill
• [ ] Honest evidence label

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 texture looks "too dark" | Verify color space (linear, not sRGB); add Warn. | | Normal map looks inverted | Verify Y-axis convention; add Warn until convention confirmed. | | GLB export fails on a material | Check unsupported nodes (OSL, drivers); add Fail with node names. |

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.
• 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

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: 
Limitations: 
Next: blender-scene-quality-checker / render-export-evidence

Anti-patterns

• Performing material edits inside this skill.
• Inventing values to make rows pass.
• Marking Verified without measurement.
• Mixing lighting / composition checks here.

Cross-skill handoff

• Broad readiness review → ../blender-scene-quality-checker/SKILL.md
• Lighting validation → ../lighting-quality-checker/SKILL.md
• Composition validation → ../composition-quality-checker/SKILL.md
• Polycount budget → ../polycount-budget-checker/SKILL.md
• GLB export evidence → ../render-export-evidence/SKILL.md
• Web handoff → ../glb-web-handoff/SKILL.md

Non-goals

• Edit materials.
• Generate shader code.
• Replace blender-scene-quality-checker (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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ThanhNguyxnOrg
• Source: ThanhNguyxnOrg/blendops
• License: MIT
• Homepage: https://github.com/ThanhNguyxnOrg/blendops

Install and usage instructions live in the source repository linked above.