blender-asset-qa
Skill779 starsChanged 15 days agoMITView on GitHub
Mandatory review gate for any mesh or asset created or edited in Blender. Detects z-fighting, floating/detached parts, inverted or inconsistent normals, non-manifold/open geometry, degenerate faces, duplicate verts, n-gons, unapplied scale, UV problems, bad skin weights, material/texture errors, and renders multi-angle review sheets. Use before calling any modeling, export or delivery task done.
In this repository29 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- blender-addon-developmentSkill
- blender-animationSkill
- blender-character-riggingSkill
- blender-clothingSkill
- blender-coreSkill
- blender-environment-kitsSkill
- blender-export-pipelinesSkill
- blender-facial-shapekeysSkill
- blender-game-optimizationSkill
- blender-geometry-nodesSkill
- blender-hair-groomingSkill
- blender-hardsurface-modelingSkill
- blender-lighting-lookdevSkill
- blender-pbr-materialsSkill
- blender-pipeline-automationSkill
- blender-renderingSkill
- blender-retopology-uvSkill
- blender-scene-setupSkill
- blender-sculptingSkill
- blender-simulationSkill
- blender-stylized-nprSkill
- blender-texture-bakingSkill
- blender-texturingSkill
- blender-time-of-daySkill
- blender-video-editingSkill
- blender-weather-fxSkill
- blender-workflow-recipesSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Never assume a generated or edited mesh is correct.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Asset QA (review gate)
Never assume a generated or edited mesh is correct. Check it with numbers, then look at it.
Procedure
- Automated check, passing one asset's objects together:
scripts/qa_check.py -- --objects Body Head Hat --profile gameProfiles:game(default),render(lenient),print(watertight required),roblox(20k tris/mesh, watertight, no n-gons, ≤4 influences). - Fix every
errorsentry (table below), then re-run until"pass": true. Each warning must be either fixed or explicitly accepted, with the reason reported to the user. - Visual check, always:
- Live: MCP
lookwithmode="angles"on the targets, once inmaterial/solidshading and once inwireframe. Usexrayfor internals. - Headless:
scripts/review_shots.py -- --objects ... --mode random(one color per object, which makes detached pieces obvious), then--mode wirefor topology. Open the returned PNG.
- Live: MCP
- Report: tris per object, issues fixed, and remaining accepted warnings.
What each finding means → fix
| Finding | Cause | Fix |
zfighting A<->B | two surfaces facing the same way within --eps (1 mm) that overlap | delete the hidden duplicate, or offset ≥ 2–5 mm along the normal, or boolean/merge them |
back_to_back | faces touching with opposite normals (boxes glued face-to-face) | delete the hidden faces (wasted tris, bake artifacts) |
floating | island/object not touching any other part within --tol | move it to make contact (snap), bridge it, or join and merge. If floating is intended (sparks, UI), check it separately |
enclosed | part fully inside another, not touching (eyes, internal mechanics) | usually fine. Confirm it's intended |
inside_out_islands | closed part with normals pointing in | mesh.normals_make_consistent(inside=False) on that part |
inconsistent_normals_edges | neighbouring faces wound in opposite directions | recalc normals; if it persists, look for non-manifold seams |
nonmanifold_edges / wire_edges | >2 faces per edge, or stray edges | dissolve/delete the extra faces; delete_loose |
boundary_edges | open holes (bad for print/Roblox/bakes) | fill (fill_holes/edge_face_add) or cap |
degenerate_faces / zero_length_edges | collapsed geometry | dissolve_degenerate(threshold=1e-4) |
duplicate_verts | unwelded seams | remove_doubles(threshold=1e-4) (Merge by Distance); check UV seams after |
ngons | faces with >4 sides | triangulate/quadrangulate locally; n-gons are fine only on flat hard-surface faces that never deform |
| unapplied/negative scale | object transform | transform_apply(rotation=True, scale=True); negative scale flips normals on export |
uv_maps: 0 / zero-area UV / overlap | missing or bad unwrap | blender-retopology-uv |
| unweighted / >4 influences | skinning | blender-character-rigging (rig_check.py) |
ground_z ≠ 0 | asset floats or sinks | move the origin to the bottom and set z = 0 (props) |
| faces on empty/missing slot | material removed or index out of range | assign a material; engines show grey/magenta |
feeds [...] but is sRGB | normal/roughness/metal/AO map tagged as color | image.colorspace_settings.is_data = True (Non-Color) |
| missing texture file | broken path, unpacked | relink (blender-scene-setup path cleanup) or pack |
| unused slot / Non-Color base color | leftovers, wrong tag | remove the slot; base color and emission are sRGB |
Manual checks the script can't fully judge
- Silhouette and proportions at the target camera distance. Compare with references and real-world size (
ob.dimensions). - Shading artifacts: smoothing on hard edges (needs sharp edges/weighted normals), and pinching at poles on curved surfaces.
- Intersections that look wrong (a leg clipping a seat), even though they're "attached".
- Interior/hidden geometry that wastes tris (use
xray). - Deformation: pose the rig at extremes (elbow 140°, knee 150°, shoulder raised) and look for collapsing volume.
- Material assignment: slots and color spaces are checked automatically. Still look at whether each part got the intended material.
Tuning
--epsis the z-fight distance. Raise it to 0.005 for large environment scenes, and lower it to 0.0002 for tiny jewelry.--tolis the contact tolerance for detached parts. Raise it for chunky kitbash.--no-modifierschecks the base mesh. By default the evaluated (modifier) result is checked, which is what gets exported.- Above
--max-tris(300k), the z-fight and floating checks are skipped. Check high-poly sources per part instead.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.