如何通过Blender Python API将物体材质表面设为Background

报错原因 #

你遇到的RuntimeError: Error: Node type Background undefined是因为Background节点不属于材质节点树的可用类型，它本质是用于场景世界环境的节点。你在UI界面中给物体材质设置Background，实际是Blender自动切换了材质的表面类型，并在材质节点树中生成了适配的节点，而非直接创建世界节点里的Background。

正确实现代码 #

要在物体材质中设置Background效果，需要手动在材质节点树中创建对应节点并正确连接：

import bpy
import ut  # 你的自定义导入模块

obj = ut.import_objects("models/bbox.fbx")[0]
color = (0, 1, 0, 1)  # 目标背景色

# 创建新材质
mat = bpy.data.materials.new(name="Background_Mat")
mat.use_nodes = True
node_tree = mat.node_tree
nodes = node_tree.nodes
links = node_tree.links

# 清除默认的Principled BSDF和输出节点
nodes.clear()

# 创建材质专用的Background节点（类型为ShaderNodeBackground）
node_background = nodes.new(type='ShaderNodeBackground')
node_background.inputs["Color"].default_value = color

# 创建材质输出节点
node_output = nodes.new(type='ShaderNodeOutputMaterial')

# 连接Background节点到材质输出的Surface输入
links.new(node_background.outputs["Background"], node_output.inputs["Surface"])

# 将材质绑定到物体
if obj.data.materials:
    obj.data.materials[0] = mat
else:
    obj.data.materials.append(mat)

关键说明 #

• 材质节点树中对应的Background节点类型是ShaderNodeBackground，而非直接写Background（后者是世界节点的类型名）
• 清除默认节点后必须手动创建ShaderNodeOutputMaterial，否则材质无法正常输出效果
• 连接节点时要对应正确的插槽名：Background节点的Background输出 → 材质输出节点的Surface输入

原有代码的问题点 #

1. 错误使用了世界节点的类型名Background，材质节点树不识别该类型
2. 清除默认节点后未重新创建材质输出节点，导致即使创建了Background节点也无法生效

内容的提问来源于stack exchange，提问作者Erik Hulmák