Como usar
- Copie o comando e verifique o pacote antes de instalar no seu ambiente de agente.
- Consulte no original as ferramentas, credenciais e ambientes necessários.
- Descreva os dados de entrada e a entrega esperada; confira a saída com as fontes.
npx skills add https://github.com/thanhnguyxnorg/blendops --skill material-quality-checkerAntes de começar
- A instalação não inclui assinatura de modelo, franquia API ou acesso aos seus arquivos.
- Estrelas e instalações indicam atividade, não um teste independente de qualidade ou segurança.
Renderizado do repositório de origem, preservando títulos, exemplos, código, tabelas, links e imagens.
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
<!-- blendops:generated:start exclusions -->
- 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)
<!-- blendops:generated:end exclusions -->
Trigger phrases
<!-- blendops:generated:start triggers -->
- "are the materials okay"
- "check PBR sanity"
- "texture budget for materials"
- "will the materials work in Three.js"
<!-- blendops:generated:end triggers -->
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 (
+Yup) 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 Producedunless concrete output evidence exists. - Truth states are downgrade-only (never upgrade without recorded evidence) and remain strictly separate from per-material
Pass / Warn / Failvalidation 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
- Read the material list from scene plan or measured scene.
- For each material, evaluate PBR sanity rules (see
references/pbr-sanity-rules.md). - Evaluate texture budget per material against pinned budget.
- Evaluate consumer-stack compatibility (see
references/consumer-stack-rules.md). - Assign per-material verdict; collect notes.
- Compute top-line status (any Fail → Fail; any Warn → Warn; otherwise Pass).
- Highlight worst offenders; emit remediation hints.
- Hand off to
scene-readiness(broader review) orrender-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
+Ynormal 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 Produceddefault 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
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
<!-- blendops:generated:start handoffs -->
- [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
<!-- blendops:generated:end handoffs -->
Non-goals
- Edit materials.
- Generate shader code.
- Replace
scene-readiness(this skill is one of its inputs). - Run Blender.
References
references/pbr-sanity-rules.mdreferences/texture-budget-rules.mdreferences/consumer-stack-rules.md../../laws/evidence-before-done.md../../docs/skill-system.md