Principled BSDF input names changed in 4.5.0 - use names not indices

bsdf.inputs['Transmission Weight'].default_value = 1.0 # was 'Transmission' bsdf.inputs['Subsurface Weight'].default_value = 0.2 # was 'Subsurface' bsdf.inputs['Emission Color'].default_value = (1,1,1,1) # was 'Emission' bsdf.inputs['Base Color'].default_value = (0.8, 0.2, 0.2, 1.0)


---

## Procedural texturing on parametric geometry (loop-gauntlet lessons, 2026-09-10)

- **Use Texture Coordinate > Object, not the default Generated
  coordinates, for procedural textures on parametric architecture.** A
  Noise texture on Generated coordinates stretched into streaks on
  120-segment arc rings and long boxes; Object coordinates are metric and
  isotropic because all objects share the world origin.
- **Caveat: Object coordinates are relative to the object, so changing the
  object's transform changes the material.** Applying transforms, joining,
  realising instances, baking to world space or re-centring the origin
  silently changes the scale, orientation or phase of every pattern fed by
  Texture Coordinate > Object - no error, and the geometry numbers (face
  count, bounding box, part count) still pass. Two relatives: a procedural
  node with an unlinked Vector input uses Generated coordinates (the mesh
  bounding box), and Geometry > Position is world space. Before applying or
  baking, list the materials that read any of these (check inside node
  groups too). Either keep the transform, or store the evaluated
  object-space coordinates as a FLOAT_VECTOR point attribute BEFORE the
  bake and replace every linked Object output with the Vector output of an
  Attribute node (type Geometry, that attribute name). Read-back: render
  the same camera rig from the source and from the result and compare the
  images, or sample one pixel - a mean absolute difference of 1.1e-3 against
  1.5e-4 once fixed was invisible by eye at 512 px and was the only signal.
- **Brick texture reads the X/Y of its input vector - it is planar in that
  plane, not aligned to the surface it is applied to.** On a wall lying in
  the YZ plane a Brick texture produces blotches instead of coursing. Build
  a Z-based course mask instead (SeparateXYZ > multiply > fract >
  less-than > bump) - it works on every wall orientation and lines up
  scene-wide.
- **A texture that shares a shader with an already-accepted plate must
  share its histogram.** Before assigning a new image plate to a shader
  slot that an accepted plate already uses, match the new plate's
  luminance mean and standard deviation to the accepted one (a two-line
  PIL script: read both images, scale/offset the new one to match mean and
  std). Two extra relief plates with greyscale means of 126 and 172 against
  an accepted plate's 181 rendered as dark grey stone instead of matching
  stone, costing a full iteration before the mismatch was found.
- **A photo's surface grain becomes an unwanted bump map at close range.**
  A photo-derived plate used as colour-plus-bump reads as rough bark
  texture when the nearest matched camera is close (about 2 m); reserve
  photo-derived plates for bands whose nearest camera is several metres
  away, and use the smoothest (e.g. generated) plate on close-up bands.

---

## QUICK START

### Create PBR Material

```python
import bpy

mat = bpy.data.materials.new("PBR_Material")
mat.use_nodes = True
nodes = mat.node_tree.nodes
links = mat.node_tree.links
nodes.clear()

bsdf = nodes.new('ShaderNodeBsdfPrincipled')
bsdf.inputs['Base Color'].default_value = (0.8, 0.2, 0.2, 1.0)
bsdf.inputs['Roughness'].default_value = 0.5
bsdf.inputs['Metallic'].default_value = 0.0

output = nodes.new('ShaderNodeOutputMaterial')
links.new(bsdf.outputs['BSDF'], output.inputs['Surface'])

# Assign to active object
obj = bpy.context.active_object
if obj and obj.type == 'MESH':
    obj.data.materials.append(mat)
    print(f"Material '{mat.name}' assigned to '{obj.name}'")

STANDARD WORKFLOWS

Workflow 1: Procedural Texture (No Image Files)

Use When: Natural materials (stone, wood, rust) without image textures

import bpy

mat = bpy.data.materials.new("Procedural_Stone")
mat.use_nodes = True
nodes = mat.node_tree.nodes
links = mat.node_tree.links
nodes.clear()

texcoord = nodes.new('ShaderNodeTexCoord')
noise = nodes.new('ShaderNodeTexNoise')
noise.inputs['Scale'].default_value = 5.0
noise.inputs['Detail'].default_value = 8.0
noise.inputs['Roughness'].default_value = 0.6

ramp = nodes.new('ShaderNodeValToRGB')
ramp.color_ramp.elements[0].color = (0.2, 0.2, 0.2, 1.0)  # dark stone
ramp.color_ramp.elements[1].color = (0.7, 0.7, 0.7, 1.0)  # light stone

bsdf = nodes.new('ShaderNodeBsdfPrincipled')
bsdf.inputs['Roughness'].default_value = 0.85

output = nodes.new('ShaderNodeOutputMaterial')

links.new(texcoord.outputs['Object'], noise.inputs['Vector'])
links.new(noise.outputs['Fac'], ramp.inputs['Fac'])
links.new(ramp.outputs['Color'], bsdf.inputs['Base Color'])
links.new(bsdf.outputs['BSDF'], output.inputs['Surface'])

print("Procedural stone material created")

Workflow 2: Glass / Transparent Material

import bpy

mat = bpy.data.materials.new("Glass")
mat.use_nodes = True
mat.blend_method = 'BLEND'
nodes = mat.node_tree.nodes
links = mat.node_tree.links
nodes.clear()

bsdf = nodes.new('ShaderNodeBsdfPrincipled')
bsdf.inputs['Transmission Weight'].default_value = 1.0   # 4.5+ name
bsdf.inputs['IOR'].default_value = 1.45
bsdf.inputs['Roughness'].default_value = 0.0

output = nodes.new('ShaderNodeOutputMaterial')
links.new(bsdf.outputs['BSDF'], output.inputs['Surface'])

# EEVEE_NEXT: enable ray tracing for refractions
bpy.context.scene.eevee.use_raytracing = True

print("Glass material created")

Workflow 3: Material Layering with Mix Shader

Use When: Combining materials (metal + rust, clean + dirty, worn + fresh)

import bpy

mat = bpy.data.materials.new("Layered_Metal")
mat.use_nodes = True
nodes = mat.node_tree.nodes
links = mat.node_tree.links
nodes.clear()

# Clean metal
bsdf_metal = nodes.new('ShaderNodeBsdfPrincipled')
bsdf_metal.inputs['Metallic'].default_value = 1.0
bsdf_metal.inputs['Roughness'].default_value = 0.2
bsdf_metal.inputs['Base Color'].default_value = (0.7, 0.7, 0.7, 1.0)

# Rust / weathering layer
bsdf_rust = nodes.new('ShaderNodeBsdfPrincipled')
bsdf_rust.inputs['Base Color'].default_value = (0.5, 0.2, 0.1, 1.0)
bsdf_rust.inputs['Roughness'].default_value = 0.9

# Noise-based mask
noise = nodes.new('ShaderNodeTexNoise')
noise.inputs['Scale'].default_value = 10.0

mix = nodes.new('ShaderNodeMixShader')

output = nodes.new('ShaderNodeOutputMaterial')

links.new(noise.outputs['Fac'], mix.inputs['Fac'])
links.new(bsdf_metal.outputs['BSDF'], mix.inputs[1])
links.new(bsdf_rust.outputs['BSDF'], mix.inputs[2])
links.new(mix.outputs['Shader'], output.inputs['Surface'])

print("Layered metal/rust material created")

Workflow 4: Reusable Node Group

import bpy

# Create a reusable weathering node group
group = bpy.data.node_groups.new("Weathering", 'ShaderNodeTree')
group_in = group.nodes.new('NodeGroupInput')
group_out = group.nodes.new('NodeGroupOutput')

# Interface (5.1+ uses interface API)
iface = group.interface
iface.new_socket("Scale", in_out='INPUT', socket_type='NodeSocketFloat')
iface.new_socket("Mask", in_out='OUTPUT', socket_type='NodeSocketColor')

noise = group.nodes.new('ShaderNodeTexNoise')
group.links.new(group_in.outputs['Scale'], noise.inputs['Scale'])
group.links.new(noise.outputs['Color'], group_out.inputs['Mask'])

# Use the group in a material
mat = bpy.data.materials.new("Weathered")
mat.use_nodes = True
nodes = mat.node_tree.nodes
node_group = nodes.new('ShaderNodeGroup')
node_group.node_tree = group
node_group.inputs['Scale'].default_value = 5.0

print(f"Node group '{group.name}' created and referenced")

ADVANCED TECHNIQUES

Cross-Engine Optimization

import bpy

engine = bpy.context.scene.render.engine

if engine == 'BLENDER_EEVEE':
    # EEVEE: performance-conscious, keep it simple
    mat.refraction_depth = 0.1
    # Real-time: avoid expensive SSS and volumetrics unless needed
else:  # CYCLES
    # Full ray tracing - enable SSS, caustics, etc.
    bsdf.inputs['Subsurface Weight'].default_value = 0.1
    bsdf.inputs['Subsurface Radius'].default_value = (0.1, 0.05, 0.03)

TROUBLESHOOTING

Material Not Appearing in Viewport

import bpy

# Set viewport to Material Preview or Rendered shading
for area in bpy.context.screen.areas:
    if area.type == 'VIEW_3D':
        for space in area.spaces:
            if space.type == 'VIEW_3D':
                space.shading.type = 'MATERIAL'  # NOT 'MATERIAL_PREVIEW' (4.5+)

Shader Socket AttributeError

# 'NodeSocketShader' has no default_value - it only accepts links
# [FAIL] bsdf.outputs['BSDF'].default_value = ...
# [OK] Just connect it:
links.new(bsdf.outputs['BSDF'], output.inputs['Surface'])

Faces all on slot 0 after assigning materials from Python (obs 244)

mesh.materials.clear() resets every face's material_index to 0. A mesh built from bmesh parts (faces given index 0 and 1) and then cleared and re-appended rendered with one material; the build's print listed both slot names, so it looked right. Append the slots ONCE (before or after bm.to_mesh), never call clear() on a mesh whose faces carry indices, and verify by COUNTING FACES PER SLOT in the saved file - a list of slot names proves the slots exist, not that faces use them. When a cause goes into a code comment, probe it first: the plausible one here ("to_mesh clamps indices on a mesh with no slots") was wrong.

Material Renders Black

import bpy

nodes = mat.node_tree.nodes
links = mat.node_tree.links

# Verify output node exists
output = next((n for n in nodes if n.type == 'OUTPUT_MATERIAL'), None)
if not output:
    output = nodes.new('ShaderNodeOutputMaterial')

# Ensure BSDF is connected to surface
if not output.inputs['Surface'].is_linked:
    bsdf = next((n for n in nodes if n.type == 'BSDF_PRINCIPLED'), None)
    if bsdf:
        links.new(bsdf.outputs['BSDF'], output.inputs['Surface'])
        print("Fixed: reconnected BSDF to output")

VALIDATION CHECKLIST

Engine set (BLENDER_EEVEE or CYCLES)
BSDF inputs use 4.5+ naming convention
Material Output node connected
Viewport shading = MATERIAL (not MATERIAL_PREVIEW)
Test render validates appearance
Procedural meshes: faces-per-slot count read back from the saved file (no materials.clear() after indices are set)
Before applying/joining/baking transforms: materials reading Object / Generated / Position coordinates listed, and a before/after render (or sampled pixel) matches

VERSION HISTORY

v2.1.3 (2026-10-30) - Obs 244: materials.clear() resets material_index; troubleshooting entry and checklist line.

v2.1.1 (2026-10-09) - Observation 98: applying, joining, realising or baking transforms silently changes materials that read Object-space coordinates (also Generated and Geometry Position); caveat added to the procedural-texturing section with the attribute rewire and a same-rig render diff as the read-back, plus one validation checklist line.

v2.1.0 (2026-09-10) - Loop-gauntlet lessons: procedural textures need Object coordinates (not Generated) on parametric geometry, Brick texture is planar-XY (use a Z-based course mask for walls), and image plates sharing a shader with an accepted plate must be histogram-matched, with photo-derived plates reserved for bands far from the nearest camera.

v2.0.0 (2026-06-10) - MCP migration

Removed HTTP Bridge requirements and curl steps
Removed import requests / requests.post() wrappers
Added import bpy to all code blocks
Updated target: Blender 5.1+
Added node group workflow with 5.1+ interface API

v1.0.0 (2025-10-24) - Initial release

Status: Production Ready Maintainer: VFX Pipeline Team Dependencies: Blender 5.1+, Python 3.11+

blender-materials-shaders

Blender Materials & Shaders Skill

Breaking Changes (4.5+ / 5.1+)