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

Optional inputs

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.

Runtime status: Not Run | Attempted | Produced | Verified | Failed
Artifact status: Not Produced | Produced | Verified | Failed
Evidence used: <links, paths, logs, or "none">
Limitations: <known gaps>

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

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

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

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

Consumer target: <Cycles / Eevee / glTF mobile / glTF desktop>
Texture budget cap: <N MP total>

| Material | Type | Albedo | Normal | Rough/Met | Tex count + res | Consumer | Verdict | Notes |
|---|---|---|---|---|---|---|---|---|
| <name> | PBR | <state> | <state> | <state> | <N x Wpx> | <ok/warn/fail> | Pass/Warn/Fail | <note> |

Top-line: <Pass / Warn / Fail>
Worst offenders: <list 1-2>
Remediation hints: <advisory hints per Fail/Warn row, no edits performed>
Runtime status: <Not Run | Attempted | Produced | Verified | Failed>
Artifact status: <Not Produced | Produced | Verified | Failed>
Evidence used: <links, paths, logs, or "none">
Limitations: <gaps>
Next: <scene-readiness | render-export-evidence | glb-web-handoff | lighting-material-plan>

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