blender-material-ops

Blender 材质操作指南

强制规则：

1. 用 node.type 查找节点（不用 node.name，中文版名字不同）
2. 创建材质后必须验证节点数和颜色值
3. bpy.data.materials.new() 会自动创建默认 BSDF+Output，不要再 new 一对
4. 需要重建节点时，先 nodes.clear() 再 new

---

规则 0：use_nodes=True 的隐含行为 🔴

mat = bpy.data.materials.new(name="MyMat")
mat.use_nodes = True
# 此时 mat.node_tree.nodes 已包含:
#   - 1 个 Principled BSDF (type='BSDF_PRINCIPLED')
#   - 1 个 Material Output (type='OUTPUT_MATERIAL')
#   - 1 条 BSDF→Output 连接
# 不需要也不能再 nodes.new() 同类型节点！

❌ 典型错误（重复节点，材质变灰）

mat = bpy.data.materials.new(name="Wall")
mat.use_nodes = True
# 已经有默认节点了！下面又创建一对 → 总共 4 个节点
bsdf = mat.node_tree.nodes.new('ShaderNodeBsdfPrincipled')  # 重复!
output = mat.node_tree.nodes.new('ShaderNodeOutputMaterial')  # 重复!
# 新 BSDF 没连到 Output，材质显示为灰色

---

模式 A：创建新材质（最常用）

直接使用 use_nodes=True 创建的默认节点，只修改参数：

mat = bpy.data.materials.new(name="Wall_Material")
mat.use_nodes = True
tree = mat.node_tree

# 通过 type 查找默认节点（兼容中英文 Blender）
bsdf = None
output = None
for node in tree.nodes:
    if node.type == 'BSDF_PRINCIPLED':
        bsdf = node
    elif node.type == 'OUTPUT_MATERIAL':
        output = node

# 设置参数
bsdf.inputs['Base Color'].default_value = (0.9, 0.85, 0.75, 1.0)
bsdf.inputs['Roughness'].default_value = 0.8
bsdf.inputs['Metallic'].default_value = 0.0

# 验证
assert len(tree.nodes) == 2, f"节点数异常: {len(tree.nodes)}"
assert len(tree.links) == 1, f"连接数异常: {len(tree.links)}"

---

模式 B：修改已有材质

只改参数，不碰节点结构：

mat = bpy.data.materials.get("Wall_Material")
if mat and mat.use_nodes:
    for node in mat.node_tree.nodes:
        if node.type == 'BSDF_PRINCIPLED':
            node.inputs['Base Color'].default_value = (0.95, 0.9, 0.8, 1.0)
            node.inputs['Roughness'].default_value = 0.7
            break

---

模式 C：重建损坏的材质

先清除再创建——材质有重复节点或连接断开时使用：

mat = bpy.data.materials.get("Wall_Material")
if not mat:
    mat = bpy.data.materials.new(name="Wall_Material")

mat.use_nodes = True
tree = mat.node_tree

# 清除所有节点（关键步骤）
tree.nodes.clear()

# 重新创建
bsdf = tree.nodes.new(type='ShaderNodeBsdfPrincipled')
bsdf.location = (0, 0)
bsdf.inputs['Base Color'].default_value = (0.9, 0.85, 0.75, 1.0)
bsdf.inputs['Roughness'].default_value = 0.8

output = tree.nodes.new(type='ShaderNodeOutputMaterial')
output.location = (300, 0)

tree.links.new(bsdf.outputs['BSDF'], output.inputs['Surface'])

# 验证
assert len(tree.nodes) == 2
assert len(tree.links) == 1