Blender Materials

Blender Materials

Apply physically-based materials to objects. Use only Principled BSDF — it's the only shader that exports cleanly to glTF and matches what other DCC tools expect.

The metallic switch — never an in-between

The single most-important rule: Metallic is a switch, not a slider. Set it to 0.0 (dielectric: plastic, wood, glass, skin) or 1.0 (metal: steel, gold, copper). Values between 0.2 and 0.8 are almost always wrong; they produce energy-non-conservative renders that look "plasticky."

Exception: dark mirror lenses (sunglasses) use ~0.8 to combine strong reflection with slight tint — that's a stylistic choice, not strict PBR.

Decision tree

What is it made of?
├── Raw metal (steel, gold, copper, etc.)
│   → Metallic=1.0, Base Color = F0 reflectance from physicallybased.info
│   → Roughness controls polish (0.05 mirror → 0.4 brushed → 0.7+ weathered)
│
├── Glass / clear / refractive
│   → Metallic=0, Transmission=1.0, IOR=1.5 (glass), Roughness=0.0
│   → Add Volume Absorption for thick tinted glass
│
├── Plastic / wood / stone (dielectric, opaque)
│   → Metallic=0, IOR=1.45 (plastic) or 1.5 (most others)
│   → Roughness per finish (0.15 glossy / 0.6 matte)
│   → Coat Weight 0.5+ for varnished/lacquered surfaces
│
├── Skin / wax / marble (subsurface scattering)
│   → Metallic=0, Subsurface Weight=1.0
│   → Subsurface Radius RGB tuned per material (skin: red scatters deepest)
│
├── Cloth / fabric (sheen)
│   → Metallic=0, Sheen Weight 0.2-0.5
│   → Roughness 0.6+, Sheen Roughness 0.5
│
└── Mirror / chrome (special metal)
    → Metallic=1.0, Roughness=0.02-0.05, near-white base

Reference-look handoff

If the goal is to match an original/reference image rather than make a generally attractive render, chain-load reference-look-calibration. It owns measurement of hue/saturation/value, object extent, glow/aura color, and before/after look metrics. This skill should then apply the requested material/lighting/render changes within that calibrated target.

Recipes (the 12 to know)

Each recipe creates the material and assigns it to a target object. Replace 'GEO-target' with your actual object name.

set_input helper — required for some Blender 5.x BSDF inputs

In Blender 5.x's Principled BSDF v2, two inputs are flagged `enabled=False` in the data API: Weight and Subsurface IOR. These are reachable by iteration or index but not by string-key lookup — bsdf.inputs['Subsurface IOR'] raises KeyError even though the input exists and its value is respected at render time. This is a Blender 5.x quirk surfaced during v0.4.0 → v0.5.0 validation.

Use this helper whenever a recipe sets an input that might be in the disabled-but-functional state. It works on every input (enabled or not) and is forward-compatible if more inputs become disabled in future Blender versions:

def set_input(node, name, value):
    """Set a node input by name. Works on inputs with enabled=False
    that fail string-key lookup (e.g. 'Subsurface IOR' on Blender 5.x).
    """
    for inp in node.inputs:
        if inp.name == name:
            inp.default_value = value
            return True
    return False

For inputs that are reliably enabled (Base Color, Metallic, Roughness, IOR, Transmission Weight, Sheen Weight, etc.), direct string-key assignment still works fine — the helper is only required where an input is conditionally disabled. Recipe 9 (Skin) uses it because Subsurface IOR is one of the affected inputs.

Recipe 1 — Brushed steel

import bpy

mat = bpy.data.materials.new('MAT-steel_brushed')
mat.use_nodes = True
bsdf = mat.node_tree.nodes['Principled BSDF']
bsdf.inputs['Base Color'].default_value = (0.56, 0.57, 0.58, 1.0)
bsdf.inputs['Metallic'].default_value = 1.0
bsdf.inputs['Roughness'].default_value = 0.25

obj = bpy.data.objects['GEO-target']
if obj.data.materials:
    obj.data.materials[0] = mat
else:
    obj.data.materials.append(mat)
print(f"material:MAT-steel_brushed→{obj.name}")

Recipe 2 — Polished gold

import bpy
mat = bpy.data.materials.new('MAT-gold_polished')
mat.use_nodes = True
bsdf = mat.node_tree.nodes['Principled BSDF']
bsdf.inputs['Base Color'].default_value = (1.022, 0.782, 0.344, 1.0)
bsdf.inputs['Metallic'].default_value = 1.0
bsdf.inputs['Roughness'].default_value = 0.05
bpy.data.objects['GEO-target'].data.materials.append(mat)
print('material:gold_polished')

Recipe 3 — Polished copper

import bpy
mat = bpy.data.materials.new('MAT-copper_polished')
mat.use_nodes = True
bsdf = mat.node_tree.nodes['Principled BSDF']
bsdf.inputs['Base Color'].default_value = (0.926, 0.721, 0.504, 1.0)
bsdf.inputs['Metallic'].default_value = 1.0
bsdf.inputs['Roughness'].default_value = 0.05
bpy.data.objects['GEO-target'].data.materials.append(mat)
print('material:copper_polished')

Recipe 4 — Mirror chrome

import bpy
mat = bpy.data.materials.new('MAT-chrome')
mat.use_nodes = True
bsdf = mat.node_tree.nodes['Principled BSDF']
bsdf.inputs['Base Color'].default_value = (0.55, 0.56, 0.55, 1.0)
bsdf.inputs['Metallic'].default_value = 1.0
bsdf.inputs['Roughness'].default_value = 0.02
bpy.data.objects['GEO-target'].data.materials.append(mat)
print('material:chrome')

Recipe 5 — Clear glass

import bpy
mat = bpy.data.materials.new('MAT-glass_clear')
mat.use_nodes = True
bsdf = mat.node_tree.nodes['Principled BSDF']
bsdf.inputs['Base Color'].default_value = (1.0, 1.0, 1.0, 1.0)
bsdf.inputs['Metallic'].default_value = 0.0
bsdf.inputs['Roughness'].default_value = 0.0
bsdf.inputs['Transmission Weight'].default_value = 1.0
bsdf.inputs['IOR'].default_value = 1.5
bpy.data.objects['GEO-target'].data.materials.append(mat)
print('material:glass_clear')

Recipe 6 — Frosted glass

import bpy
mat = bpy.data.materials.new('MAT-glass_frosted')
mat.use_nodes = True
bsdf = mat.node_tree.nodes['Principled BSDF']
bsdf.inputs['Base Color'].default_value = (1.0, 1.0, 1.0, 1.0)
bsdf.inputs['Transmission Weight'].default_value = 1.0
bsdf.inputs['IOR'].default_value = 1.5
bsdf.inputs['Roughness'].default_value = 0.3
bpy.data.objects['GEO-target'].data.materials.append(mat)
print('material:glass_frosted')

Recipe 6b — Coloured glass (wine bottle, tinted vials, decorative glass)

Using only Base Color to tint Principled BSDF makes coloured glass look flat or metallic. Real coloured glass has volume absorption: light passing through gets tinted by the distance it travels, so thick parts look darker and thin parts look lighter. This is the depth-based richness that makes glass read as glass.

Pattern: keep the surface near-white with slight roughness, attach a Volume Absorption shader to the Material Output's Volume input.

import bpy

def set_input(node, name, value):
    for inp in node.inputs:
        if inp.name == name:
            inp.default_value = value
            return True
    return False

mat = bpy.data.materials.new('MAT-glass_wine')
mat.use_nodes = True
nodes = mat.node_tree.nodes
links = mat.node_tree.links
bsdf = nodes['Principled BSDF']
output = nodes['Material Output']

# Surface: near-white with tiny roughness (breaks mirror-finish look)
set_input(bsdf, 'Base Color', (0.85, 0.95, 0.85, 1.0))   # near-white
set_input(bsdf, 'Metallic', 0.0)
set_input(bsdf, 'Roughness', 0.025)                       # critical: not 0.0; that looks metallic
set_input(bsdf, 'Transmission Weight', 1.0)
set_input(bsdf, 'IOR', 1.52)                              # bottle glass

# Volume Absorption — depth-based tint
volume = nodes.new('ShaderNodeVolumeAbsorption')
set_input(volume, 'Color', (0.10, 0.45, 0.18, 1.0))       # saturated wine-bottle green
set_input(volume, 'Density', 30.0)                         # higher = more colour over short distance

links.new(volume.outputs['Volume'], output.inputs['Volume'])

bpy.data.objects['GEO-target'].data.materials.append(mat)