blender
Automate Blender scenes with the bpy Python API, build Geometry Nodes workflows, configure Cycles or EEVEE renders, and troubleshoot headless batch jobs.
SKILL.mdskills/blender/SKILL.md
GitHubBlender 4.x 3D Creation Suite AI Skill Guide (Claude)
Overview & Engine Architecture
Blender 4.2 LTS / 4.3+ / 5.x is an open-source DCC suite. Agent automation runs through bpy (Python), CLI background mode, and optional Geometry Nodes procedural graphs. Render engines: Cycles (path-traced, farm-friendly) and EEVEE (real-time; identifier changed across 4.2→5.0 — resolve at runtime, do not hardcode BLENDER_EEVEE_NEXT).
Claude acts as a Principal Technical Artist / Pipeline TD: headless blender --background, deterministic stills, idempotent scene scripts, addon packaging (bl_info), and export validation (glTF/FBX/USD).
┌─────────────────────────────────────────────────────────────┐
│ Blender automation stack │
│ bpy.data / RNA → depsgraph → Cycles|EEVEE → files │
│ CLI: -b blend -P script.py | -E CYCLES -f N -a (last!) │
│ Determinism: cycles.seed, fixed samples, no animated seed │
└─────────────────────────────────────────────────────────────┘
Version pins (document in every pipeline README): pin Blender minor (e.g. 4.2.11 LTS). GPU backends: CUDA / OPTIX / HIP / ONEAPI / METAL after -- (see CLI render docs).
When to use / when not to
Use when
- Batch stills/animations, asset conversion, procedural scene generation, CI smoke renders.
- Geometry Nodes or modifier stacks must be evaluated headlessly.
- You need reproducible Cycles output (golden frames, A/B materials).
Do not use when
- Real-time game runtime (use Unity/Godot/Unreal skills).
- Legal/commercial work requires Autodesk-only formats without conversion — validate export importers downstream.
- Host has no GPU and Cycles GPU is mandatory without CPU fallback plan.
Operational Capabilities & Agent Directives
- Data API first: Mutate
bpy.data,scene, object properties; usebpy.opsonly with explicit context overrides in--background. - CLI argument order: Put
-o,-F,-E, frame range before-f/-a; render flags must be last or Blender ignores them. - Deterministic Cycles: Set
scene.cycles.seed, disable animated seed, fix sample count (turn off adaptive sampling for golden tests); document OIDN availability — headless Linux builds often lack OpenImageDenoise and abort if denoise stays enabled. - Color management: Set
scene.view_settings.view_transform,look, and export color space explicitly; linear EXR for comp, sRGB/Rec.709 for web stills — never assume default OCIO matches farm workers. - Engine resolution:
scene.render.engine = bpy.context.preferences.addons['cycles'].preferences...or iteratebpy.types.RenderEngine— EEVEE enum names differ by version. - Exit codes: Wrap
main(); on failuresys.exit(1)so CI fails; logblender --versionat job start.
Headless batch: deterministic Cycles still
render_still.py — run: blender -b scene.blend --python render_still.py -- --cycles-device OPTIX
import bpy
import sys
def main():
scene = bpy.context.scene
scene.render.engine = "CYCLES"
scene.cycles.device = "GPU" # or CPU-only farm
scene.cycles.samples = 128
scene.cycles.use_adaptive_sampling = False
scene.cycles.seed = 42
scene.cycles.use_animated_seed = False
# Disable denoise if OIDN missing on worker
scene.cycles.use_denoising = False
scene.render.image_settings.file_format = "OPEN_EXR"
scene.render.image_settings.color_mode = "RGBA"
scene.render.filepath = "//out/frame_####"
bpy.ops.render.render(write_still=True)
if __name__ == "__main__":
try:
main()
except Exception as e:
print("BLENDER_PIPELINE_FAIL", e, file=sys.stderr)
sys.exit(1)
Animation farm split: render frame ranges per worker (-s / -e), merge with bpy.ops.cycles.merge_images or FFmpeg concat of EXR/PNG sequences.
Export pipelines
| Target | Operator / notes | Pitfalls |
|---|---|---|
| glTF 2.0 | bpy.ops.export_scene.gltf |
Apply scale; Draco optional; check NLA vs active action |
| FBX | export_scene.fbx |
Unit scale 0.01 vs 1.0; bone roll |
| USD | Blender USD exporter | Instance paths, material binding |
| Alembic | Cache transforms/deforms | Frame range, subframe sampling |
Always apply scale (or document non-uniform scale) before export; validate in target engine (Unity/Unreal importers).
Failure taxonomy
| Symptom | Likely cause | Fix |
|---|---|---|
| Black render | No camera/lights/world | Assert scene.camera; add key light |
context is incorrect |
bpy.ops in wrong mode |
Data API or temp_override |
Failed to denoise |
OIDN absent on server | use_denoising = False or install OIDN build |
| EEVEE enum not found | Version drift | Query available engines at runtime |
| Non-deterministic noise | Animated seed / adaptive sampling | Fixed seed + fixed samples |
| Washed stills vs viewport | Wrong view transform / display device | Match view_settings + file format color space |
Practitioner pattern (r/blenderhelp): background jobs fail silently when -a precedes -o — reorder CLI.
Essential CLI
blender --version
blender -b file.blend -E CYCLES -o //renders/frame_#### -F PNG -f 1 -- --cycles-device CPU
blender --factory-startup -b --python tests/smoke_bpy.py
blender -b file.blend -P pipeline/export_gltf.py
Paths (Windows): %APPDATA%\Blender Foundation\Blender\<ver>\scripts\addons
Agent Operational Directive
MANDATORY: Pin Blender version in CI. Set Cycles seed + fixed samples for deterministic output. Put
-f/-alast on CLI. Prefer EXR + documented OCIO for color-critical pipelines. Exit non-zero on pipeline failure.