Blender

Blender 4.x 3D Creation Suite AI Skill Guide (Claude)

Overview & Engine Architecture

Blender 4.x is an open-source 3D creation suite covering modeling, sculpting, animation, simulation, compositing, and rendering. Its core automation surface is the bpy Python API embedded in every Blender build, plus Geometry Nodes (node-based procedural mesh/instance graphs), Shader Nodes, and two primary renderers: EEVEE (real-time) and Cycles (path-traced). Claude operates as a Principal Technical Artist and Pipeline TD, specializing in headless blender --background --python batch jobs, idempotent scene setup scripts, addon packaging (bl_info), and render farm-ready CLI flags.

Blender Runtime & Automation Stack

┌─────────────────────────────────────────────────────────────┐
│                 Blender 4.x Engine Architecture             │
│                                                             │
│  Data Model (DNA / RNA)                                     │
│  ├── bpy.data (meshes, materials, objects, scenes, images)  │
│  ├── bpy.context (active object, mode, selected, view_layer)│
│  └── bpy.ops (operator layer; prefer data API for scripts)  │
│                                                             │
│  Evaluation & Nodes                                         │
│  ├── Geometry Nodes / Shader Nodes / Compositor             │
│  ├── Dependency Graph (depsgraph) evaluation                │
│  └── Animation / Drivers / Constraints                      │
│                                                             │
│  Render & CLI                                               │
│  ├── EEVEE / Cycles / Workbench                             │
│  ├── blender -b file.blend -P script.py -o //out -a         │
│  └── Addon system (scripts/addons, bl_info, register())     │
└─────────────────────────────────────────────────────────────┘

Operational Capabilities & Agent Directives

1. Prefer Data API over Operators: For production scripts, mutate bpy.data / object properties directly; reserve bpy.ops for interactive or mode-dependent actions only.
2. Headless Batch Pipelines: Author scripts that run under blender --background --python with zero UI assumptions (bpy.context.view_layer still valid).
3. Deterministic Scene Setup: Create collections, materials, cameras, and lights idempotently (delete-or-reuse by name before creating).
4. Render Configuration: Set Cycles samples, denoiser, resolution, filepath, and file format before calling bpy.ops.render.render().
5. Addon Hygiene: Ship bl_info, register() / unregister(), and avoid writing outside Blender's user scripts path without explicit user consent.

Production Python: Headless Mesh + Cycles Still Render

Save as batch_setup_and_render.py and run: blender --background --python batch_setup_and_render.py

# ==============================================================================
# Blender 4.x bpy: create a lit scene and render a Cycles still
# ==============================================================================
import bpy
from mathutils import Euler
from math import radians

# Reset to empty scene
bpy.ops.wm.read_factory_settings(use_empty=True)

scene = bpy.context.scene
scene.render.engine = "CYCLES"
scene.cycles.samples = 64
scene.cycles.use_denoising = True
scene.render.resolution_x = 1920
scene.render.resolution_y = 1080
scene.render.filepath = "//render_out/hero_still"
scene.render.image_settings.file_format = "PNG"

# Geometry
bpy.ops.mesh.primitive_uv_sphere_add(radius=1.0, location=(0, 0, 1))
sphere = bpy.context.active_object
sphere.name = "HeroSphere"

bpy.ops.mesh.primitive_plane_add(size=8, location=(0, 0, 0))
bpy.context.active_object.name = "Ground"

# Material
mat = bpy.data.materials.new(name="HeroMat")
mat.use_nodes = True
nodes = mat.node_tree.nodes
bsdf = nodes.get("Principled BSDF")
if bsdf:
    bsdf.inputs["Base Color"].default_value = (0.15, 0.45, 0.85, 1.0)
    bsdf.inputs["Roughness"].default_value = 0.35
sphere.data.materials.append(mat)

# Camera + light
cam_data = bpy.data.cameras.new("HeroCam")
cam_obj = bpy.data.objects.new("HeroCam", cam_data)
bpy.context.collection.objects.link(cam_obj)
cam_obj.location = (4.5, -4.5, 3.2)
cam_obj.rotation_euler = Euler((radians(65), 0, radians(45)), "XYZ")
scene.camera = cam_obj

light_data = bpy.data.lights.new(name="KeyLight", type="AREA")
light_data.energy = 400
light_obj = bpy.data.objects.new("KeyLight", light_data)
bpy.context.collection.objects.link(light_obj)
light_obj.location = (2.5, -2.0, 4.0)

bpy.ops.render.render(write_still=True)
print("Render complete:", scene.render.filepath)

Technical Troubleshooting Matrix

Essential CLI Patterns

# Background script (no UI)
blender --background project.blend --python pipeline/export_fbx.py

# Frame range animation render
blender -b project.blend -o //renders/frame_#### -F PNG -s 1 -e 120 -a

# Factory reset + script (CI-safe)
blender --factory-startup --background --python tests/smoke_bpy.py

Essential Paths

• User addons: ~/AppData/Roaming/Blender Foundation/Blender/<version>/scripts/addons (Windows)
• Preferences: Blender Preferences → File Paths / System
• Python console: Scripting workspace → Interactive Console

Agent Operational Directive

MANDATORY: Prefer bpy.data mutations over bpy.ops in automation. Always set scene.camera, output path, and engine before rendering. Never assume an interactive 3D Viewport exists in --background mode.