material-quality-checker

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

• 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: <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 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: <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 × Wpx> | <ok/warn/fail> | Pass/Warn/Fail | <note> |

Top-line: <Pass / Warn / Fail>
Worst offenders: <list 1-2>
Limitations: <gaps>
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