blender-syntax-materials
Use when creating or modifying Blender materials and shader nodes via Python. Prevents the breaking change of using old Principled BSDF input names (e.g., "Subsurface" renamed to "Subsurface Weight" in 4.0). Covers material creation, node tree setup, Principled BSDF input mapping, UV assignment, texture loading, and material slot management. Keywords: material, shader, Principled BSDF, node tree, texture, UV map, material_slot, ShaderNodeBsdfPrincipled, node links, Blender materials, assign material to object, create material from code, change color.
- License 许可
- MIT
- 最近更新
- 2026-11-09
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- blender-syntax-materials
- license
- MIT
- metadata
- { "author": "OpenAEC-Foundation", "version": "1.0" }
- description
- Use when creating or modifying Blender materials and shader nodes via Python. Prevents the breaking change of using old Principled BSDF input names (e.g., "Subsurface" renamed to "Subsurface Weight" in 4.0). Covers material creation, node tree setup, Principled BSDF input mapping, UV assignment, texture loading, and material slot management. Keywords: material, shader, Principled BSDF, node tree, texture, UV map, material_slot, ShaderNodeBsdfPrincipled, node links, Blender materials, assign material to object, create material from code, change color.
- compatibility
- Designed for Claude Code. Requires Blender 3.x/4.x/5.x with Python.
02 资源文件 3
- 参考文档references/anti-patterns.md13.9 KB
- 参考文档references/examples.md13.2 KB
- 参考文档references/methods.md13.1 KB
03 SKILL.md 正文
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.
Version Decision Tree
Creating material code?
├── Target Blender 4.0+ ONLY?
│ ├── YES → Use 4.0+ Principled BSDF socket names directly
│ └── NO → Use version-safe helper (see Pattern 3)
│
Setting transparency/alpha blending?
├── Blender 4.2+?
│ ├── YES → mat.surface_render_method = 'BLENDED'
│ └── NO (3.x / 4.0-4.1) → mat.blend_method = 'BLEND'
│
Connecting texture to Principled BSDF?
├── Color texture (diffuse, base color)?
│ └── Connect to "Base Color" input (all versions)
├── Normal map?
│ └── Connect via ShaderNodeNormalMap → "Normal" input
└── Data texture (roughness, metallic, AO)?
└── Set image colorspace to 'Non-Color'
Essential Patterns
Pattern 1: Create and Assign a Material
# Blender 3.x/4.x/5.x: create material and assign to object
import bpy
mat = bpy.data.materials.new(name="MyMaterial")
mat.use_nodes = True # REQUIRED before accessing node_tree
obj = bpy.context.active_object
if obj.data.materials:
obj.data.materials[0] = mat # Replace first slot
else:
obj.data.materials.append(mat) # Add new slot
Pattern 2: Build a Complete Node Tree
# Blender 3.x/4.x/5.x: node tree from scratch
mat = bpy.data.materials.new("NodeMaterial")
mat.use_nodes = True
tree = mat.node_tree
# Clear defaults
tree.nodes.clear()
# Create nodes
principled = tree.nodes.new('ShaderNodeBsdfPrincipled')
principled.location = (0, 0)
output = tree.nodes.new('ShaderNodeOutputMaterial')
output.location = (400, 0)
# Link BSDF to output
tree.links.new(principled.outputs["BSDF"], output.inputs["Surface"])
Pattern 3: Version-Safe Principled BSDF Input Access
# Blender 3.x/4.0+: handle renamed sockets
import bpy
def set_principled_value(node, socket_3x, socket_4x, value):
"""Set Principled BSDF input with version-safe socket name."""
if bpy.app.version >= (4, 0, 0):
socket_name = socket_4x
else:
socket_name = socket_3x
if socket_name in node.inputs:
node.inputs[socket_name].default_value = value
# Usage
set_principled_value(principled, "Subsurface", "Subsurface Weight", 0.1)
set_principled_value(principled, "Specular", "Specular IOR Level", 0.5)
set_principled_value(principled, "Transmission", "Transmission Weight", 1.0)
set_principled_value(principled, "Coat", "Coat Weight", 0.3)
set_principled_value(principled, "Sheen", "Sheen Weight", 0.1)
set_principled_value(principled, "Emission", "Emission Color", (1, 1, 1, 1))
Pattern 4: Texture Node with UV Mapping
# Blender 3.x/4.x/5.x: image texture with UV coordinates
tree = mat.node_tree
tex_coord = tree.nodes.new('ShaderNodeTexCoord')
tex_coord.location = (-800, 0)
mapping = tree.nodes.new('ShaderNodeMapping')
mapping.location = (-600, 0)
tex_node = tree.nodes.new('ShaderNodeTexImage')
tex_node.location = (-400, 0)
img = bpy.data.images.load("/path/to/texture.png", check_existing=True)
tex_node.image = img
# Link: TexCoord → Mapping → Image Texture → Principled BSDF
tree.links.new(tex_coord.outputs["UV"], mapping.inputs["Vector"])
tree.links.new(mapping.outputs["Vector"], tex_node.inputs["Vector"])
tree.links.new(tex_node.outputs["Color"], principled.inputs["Base Color"])
Pattern 5: Alpha/Transparency Setup (Version-Dependent)
# Blender 4.2+: EEVEE transparency
mat.surface_render_method = 'BLENDED' # 4.2+ ONLY
# Blender 3.x / 4.0-4.1: EEVEE transparency
# mat.blend_method = 'BLEND' # REMOVED in 4.2
# Version-safe pattern
if bpy.app.version >= (4, 2, 0):
mat.surface_render_method = 'BLENDED'
else:
mat.blend_method = 'BLEND'
Principled BSDF Socket Rename Table (3.x -> 4.0+)
| Blender 3.x Name | Blender 4.0+ Name | Notes |
|---|---|---|
Base Color |
Base Color |
Unchanged |
Subsurface |
Subsurface Weight |
Renamed |
Subsurface Color |
REMOVED | Use Base Color instead |
Specular |
Specular IOR Level |
Renamed |
Specular Tint |
Specular Tint |
Type changed: Float -> Color |
Transmission |
Transmission Weight |
Renamed |
Coat |
Coat Weight |
Renamed |
Sheen |
Sheen Weight |
Renamed |
Emission |
Emission Color |
Renamed |
Metallic |
Metallic |
Unchanged |
Roughness |
Roughness |
Unchanged |
IOR |
IOR |
Unchanged |
Alpha |
Alpha |
Unchanged |
Normal |
Normal |
Unchanged |
Common Operations
Assign Material to Specific Faces
# Blender 3.x/4.x/5.x: multi-material assignment
import bpy
obj = bpy.context.active_object
# Add two materials to object
mat_a = bpy.data.materials.new("Material_A")
mat_b = bpy.data.materials.new("Material_B")
obj.data.materials.append(mat_a)
obj.data.materials.append(mat_b)
# Assign material index per polygon
for polygon in obj.data.polygons:
if polygon.center.z > 0:
polygon.material_index = 1 # Material_B
else:
polygon.material_index = 0 # Material_A
Add Material Slot via Operator
# Blender 3.x/4.x/5.x: operator-based slot management
import bpy
obj = bpy.context.active_object
bpy.context.view_layer.objects.active = obj
# Add empty slot
bpy.ops.object.material_slot_add()
# Assign material to active slot
obj.material_slots[obj.active_material_index].material = mat
# Remove active slot
bpy.ops.object.material_slot_remove()
Access Default Principled BSDF
When use_nodes = True is set on a new material, Blender creates a default Principled BSDF and Material Output automatically.
# Blender 3.x/4.x/5.x: access default nodes without clearing
mat = bpy.data.materials.new("QuickMaterial")
mat.use_nodes = True
principled = mat.node_tree.nodes.get("Principled BSDF")
# principled is the auto-created ShaderNodeBsdfPrincipled
UV Layer Management
# Blender 3.x/4.x/5.x: UV layer access
mesh = obj.data
# List UV layers
for uv_layer in mesh.uv_layers:
print(uv_layer.name)
# Get active UV layer
active_uv = mesh.uv_layers.active
# Create new UV layer
new_uv = mesh.uv_layers.new(name="ProjectionUV")
# Read UV coordinates (per-loop, NOT per-vertex)
for loop_idx in range(len(mesh.loops)):
uv = active_uv.data[loop_idx].uv
# uv.x, uv.y are the coordinates
# Modify UV coordinates
for loop_idx in range(len(mesh.loops)):
active_uv.data[loop_idx].uv.x *= 2.0
active_uv.data[loop_idx].uv.y *= 2.0
Load and Configure Image Textures
# Blender 3.x/4.x/5.x: image loading
import bpy
# Load from file (reuse existing if already loaded)
img = bpy.data.images.load("/path/to/texture.png", check_existing=True)
# Create new blank image (for baking)
img = bpy.data.images.new("BakeTarget", width=2048, height=2048)
# Configure texture node
tex_node = tree.nodes.new('ShaderNodeTexImage')
tex_node.image = img
tex_node.interpolation = 'Linear' # 'Linear', 'Closest', 'Cubic', 'Smart'
tex_node.projection = 'FLAT' # 'FLAT', 'BOX', 'SPHERE', 'TUBE'
tex_node.extension = 'REPEAT' # 'REPEAT', 'EXTEND', 'CLIP'
# Set color space
img.colorspace_settings.name = 'sRGB' # For diffuse/color textures
# img.colorspace_settings.name = 'Non-Color' # For normal, roughness, metallic
Normal Map Setup
# Blender 3.x/4.x/5.x: normal map node chain
tree = mat.node_tree
normal_tex = tree.nodes.new('ShaderNodeTexImage')
normal_tex.image = bpy.data.images.load("/path/to/normal.png", check_existing=True)
normal_tex.image.colorspace_settings.name = 'Non-Color' # REQUIRED for normal maps
normal_map = tree.nodes.new('ShaderNodeNormalMap')
tree.links.new(normal_tex.outputs["Color"], normal_map.inputs["Color"])
tree.links.new(normal_map.outputs["Normal"], principled.inputs["Normal"])
Remove All Materials from Object
# Blender 3.x/4.x/5.x: clear all material slots
obj.data.materials.clear()
Common Shader Node Types
| Node Type String | Class | Purpose |
|---|---|---|
'ShaderNodeBsdfPrincipled' |
Principled BSDF | Main PBR shader |
'ShaderNodeOutputMaterial' |
Material Output | Final output |
'ShaderNodeTexImage' |
Image Texture | Load image files |
'ShaderNodeTexCoord' |
Texture Coordinate | UV, Object, Generated coords |
'ShaderNodeMapping' |
Mapping | Transform texture coordinates |
'ShaderNodeNormalMap' |
Normal Map | Convert image to normal vector |
'ShaderNodeMixShader' |
Mix Shader | Blend two shaders |
'ShaderNodeBsdfTransparent' |
Transparent BSDF | Transparency shader |
'ShaderNodeBsdfGlass' |
Glass BSDF | Glass shader |
'ShaderNodeMath' |
Math | Scalar math operations |
'ShaderNodeMixRGB' |
Mix (Color) | Blend colors (3.x name) |
'ShaderNodeMix' |
Mix | Blend colors/vectors (4.0+) |
'ShaderNodeValToRGB' |
Color Ramp | Map value to color gradient |
'ShaderNodeBump' |
Bump | Generate bump from height |
'ShaderNodeSeparateXYZ' |
Separate XYZ | Split vector components |
'ShaderNodeCombineXYZ' |
Combine XYZ | Merge components to vector |
'ShaderNodeTexNoise' |
Noise Texture | Procedural noise |
'ShaderNodeTexVoronoi' |
Voronoi Texture | Procedural voronoi |
'ShaderNodeGroup' |
Node Group | Reusable node group instance |
EEVEE vs Cycles Material Differences
| Property | EEVEE | Cycles | Notes |
|---|---|---|---|
| Transparency | Requires surface_render_method (4.2+) or blend_method (3.x-4.1) |
Automatic from Alpha | EEVEE needs explicit config |
| Screen Space Refraction | mat.use_screen_refraction = True |
Not needed | EEVEE-specific |
| Backface Culling | mat.use_backface_culling |
mat.use_backface_culling |
Same API |
| Displacement | mat.cycles.displacement_method |
mat.cycles.displacement_method |
Cycles-only |
| Shadow Mode | mat.shadow_method (3.x-4.1) |
Automatic | EEVEE-specific |
Version-Specific Migration Rules
| Feature | Blender 3.x | Blender 4.0+ | Blender 4.2+ |
|---|---|---|---|
| Principled BSDF sockets | Old names | New names (see table) | Same as 4.0 |
| Alpha blending (EEVEE) | mat.blend_method = 'BLEND' |
mat.blend_method = 'BLEND' |
mat.surface_render_method = 'BLENDED' |
| Shadow method (EEVEE) | mat.shadow_method |
mat.shadow_method |
Property restructured |
| Mix node | 'ShaderNodeMixRGB' |
'ShaderNodeMix' (preferred) |
'ShaderNodeMix' |
| Specular Tint type | Float (0.0-1.0) | Color (RGBA) | Color (RGBA) |
Reference Links
- references/methods.md — Complete API signatures for Material, NodeTree, ShaderNode, UV layers, Image
- references/examples.md — Working code examples for common material workflows
- references/anti-patterns.md — What NOT to do with materials, with WHY explanations
Official Sources
- https://docs.blender.org/api/current/bpy.types.Material.html
- https://docs.blender.org/api/current/bpy.types.ShaderNodeBsdfPrincipled.html
- https://docs.blender.org/api/current/bpy.types.ShaderNodeTree.html
- https://docs.blender.org/api/current/bpy.types.UVLoopLayers.html
- https://docs.blender.org/api/current/bpy.types.Image.html
- https://developer.blender.org/docs/release_notes/4.0/python_api/
04 同仓库更多 Skills
manimce-best-practices
Trigger when: (1) User mentions "manim" or "Manim Community" or "ManimCE", (2) Code contains `from manim import *`, (3) User runs `manim` CLI commands, (4) Working with Scene, MathTex, Create(), or ManimCE-specific classes. Best practices for Manim Community Edition - the community-maintained Python animation engine. Covers Scene structure, animations, LaTeX/MathTex, 3D with ThreeDScene, camera control, styling, and CLI usage. NOT for ManimGL/3b1b version (which uses `manimlib` imports and `manimgl` CLI).
drawio
Create, edit, replicate, import, and export draw.io diagrams with an offline YAML-first workflow: architecture, network topologies, flowcharts, UML/ER, org charts, Mermaid/CSV conversion, existing .drawio bundles, style presets, themes, and non-publication formula diagrams. For publication figures (paper, thesis, IEEE, camera-ready) use drawio-academic-skills instead.
drawio-academic-skills
Publication-figure overlay for draw.io. Use instead of drawio whenever the diagram is for a paper, thesis, dissertation, journal, conference, IEEE/ACM submission, manuscript, camera-ready, Word/LaTeX figure, or other publication. Applies venue, figure-type, color, caption/legend, formula, and paper-readability gates for architecture, workflow, roadmap, network-topology, and replicated paper figures.
uncertainty-and-units
Tracks physical units and propagates measurement uncertainty in scientific calculations using pint and uncertainties. Use for unit conversion and dimensional checking, GUM uncertainty budgets, Type A and Type B evaluation, coverage factors and expanded uncertainty, Monte Carlo propagation, significant-figure and plus-minus reporting, error propagation through curve fits, CODATA constants, auditing Python code for stripped units or broken uncertainty propagation, and order-of-magnitude plausibility checks using dimensionless groups (Reynolds, Peclet, Damkohler, Knudsen, Biot, Womersley), characteristic scales such as diffusion time or Debye length, and observed magnitude ranges. Trigger on "is this number physically reasonable", "sanity check these units", "what regime is this flow in", or a result that looks off by orders of magnitude.
statistical-analysis
Guided statistical analysis for research data - test selection, assumption checking, effect sizes, power analysis, Bayesian alternatives, and APA-formatted reporting. Use whenever a user wants to compare groups, test a hypothesis, analyze experimental or survey data, check statistical assumptions, compute required sample sizes, or write up results - even if they never name a specific test. Covers t-tests, ANOVA, chi-square, correlation, regression, non-parametric and Bayesian methods. For low-level model APIs, see the statsmodels and pymc skills.
simpy
Builds, inspects, tests, and analyzes bounded process-based discrete-event simulations with SimPy. Use for event scheduling, resource queues, interrupts, monitoring, independent replications, warm-up, and reproducible output analysis.