blender-syntax-materials

Quick Reference

Critical Warnings

NEVER use Blender 3.x Principled BSDF socket names in 4.0+ code. Sockets were renamed in 4.0 (e.g., "Subsurface" -> "Subsurface Weight"). Using old names raises KeyError.

NEVER use mat.blend_method in Blender 4.2+. This property was removed. Use mat.surface_render_method instead.

NEVER access UV data per-vertex. UV coordinates are stored per-loop (per face corner). Access via uv_layers.data[loop_index].

NEVER call bpy.data.images.load() without check_existing=True. Omitting it creates duplicate image data blocks on repeated loads.

NEVER set colorspace_settings.name incorrectly. Use 'sRGB' for color/diffuse textures and 'Non-Color' for normal maps, roughness, metallic, and other data textures.

ALWAYS set mat.use_nodes = True before accessing mat.node_tree. Without this, node_tree is None.

ALWAYS store the reference returned by bpy.data.materials.new(). Blender may append .001 if the name already exists.