blender-asset-qa

资产 QA（审核关卡）

绝不要假设生成或编辑的网格是正确的。先用数据检查，再目视检查。

流程

1. 自动检查，一次性传入一个资产的所有对象： scripts/qa_check.py -- --objects Body Head Hat --profile game 配置：game（默认）、render（宽松）、print（必须封闭）、roblox（每个网格 20k 个三角面、必须封闭、无多边形面、最多 4 个影响）。
2. 修复每一项 errors（见下表），然后重新运行，直到 "pass": true。每条警告都必须修复或明确接受，并向用户说明原因。
3. 始终进行目视检查：
   • 实时：对目标使用 MCP look，设置 mode="angles"，分别以 material/solid 着色和 wireframe 模式检查一次。使用 xray 查看内部。
   • 无头模式：运行 scripts/review_shots.py -- --objects ... --mode random（每个对象一种颜色，便于发现分离的部分），然后运行 --mode wire 检查拓扑。打开生成的 PNG。
4. 报告：每个对象的三角面数、已修复的问题，以及仍然接受的警告。

各项检查结果的含义 → 修复方法

检查结果	原因	修复方法
zfighting A<->B	两个朝向相同的表面在 --eps（1 mm）范围内发生重叠	删除隐藏的重复面，或沿法线偏移 ≥ 2–5 mm，或对它们进行布尔运算/合并
back_to_back	面以相反的法线相互接触（方块面对面粘合）	删除隐藏面（避免浪费三角面和烘焙瑕疵）
floating	岛状部分/对象在 --tol 范围内未与其他部分接触	移动使其接触（吸附）、桥接，或连接并合并。如果预期如此（火花、UI），请单独检查
enclosed	部分完全位于另一部分内部，且不接触（眼睛、内部机械结构）	通常没问题。确认这是预期的
inside_out_islands	封闭部分的法线朝内	对该部分执行 mesh.normals_make_consistent(inside=False)
inconsistent_normals_edges	相邻面绕序方向相反	重新计算法线；如果问题仍存在，检查是否有非流形接缝
nonmanifold_edges / wire_edges	每条边关联超过 2 个面，或存在多余边	溶解/删除多余面；执行 delete_loose
boundary_edges	存在开口（不利于打印、Roblox 和烘焙）	填补（fill_holes/edge_face_add）或封口
degenerate_faces / zero_length_edges	几何体塌陷	执行 dissolve_degenerate(threshold=1e-4)
duplicate_verts	接缝未焊接	执行 remove_doubles(threshold=1e-4)（按距离合并）；之后检查 UV 接缝
ngons	面的边数超过 4	局部三角化/四边化；仅在不会变形的平面硬表面上，才适合使用多边形面
未应用/负缩放	对象变换	执行 transform_apply(rotation=True, scale=True)；负缩放会在导出时翻转法线
uv_maps: 0 / UV 面积为零 / 重叠	缺少 UV 展开或展开不良	使用 blender-retopology-uv
未加权 / 影响数超过 4	蒙皮	使用 blender-character-rigging（weights_check.py）
ground_z ≠ 0	资产悬空或下沉	将原点移到底部并设置 z = 0（道具）

脚本无法完全判断的手动检查项

• 轮廓和比例：检查目标相机距离下的效果。与参考图和实际尺寸（ob.dimensions）比较。
• 着色瑕疵：硬边上的平滑（需要锐边/加权法线），以及曲面极点处的收缩。
• 看起来不合理的相交（例如腿穿过座椅），即使它们“连接”在一起。
• 浪费三角面的内部/隐藏几何体（使用 xray）。
• 变形：将骨架摆到极限姿势（肘部 140°、膝盖 150°、肩部抬起），检查体积是否塌陷。
• 材质分配：每个面都使用预期材质，且没有默认灰色材质槽。

调整参数

• --eps 是 z-fight 距离。大型环境场景可将其调高至 0.005，微型珠宝则可调低至 0.0002。
• --tol 是分离部件的接触容差。对于粗大的拼装模型，可调高此值。
• --no-modifiers 用于检查基础网格。默认检查经过求值的（修改器）结果，也就是实际导出的内容。
• 超过 --max-tris（300k）后，会跳过 z-fight 和悬空检查。请按部件检查高多边形源模型。