Skip to content

alivirgo/Major-AI-Skills / plugins/mas-3d-games/skills/blender

blender

Verified

Automate Blender scenes with the bpy Python API, build Geometry Nodes workflows, configure Cycles or EEVEE renders, and troubleshoot headless batch jobs.

Blender 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

  1. Data API first: Mutate bpy.data, scene, object properties; use bpy.ops only with explicit context overrides in --background.
  2. CLI argument order: Put -o, -F, -E, frame range before -f/-a; render flags must be last or Blender ignores them.
  3. 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.
  4. 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.
  5. Engine resolution: scene.render.engine = bpy.context.preferences.addons['cycles'].preferences... or iterate bpy.types.RenderEngine — EEVEE enum names differ by version.
  6. Exit codes: Wrap main(); on failure sys.exit(1) so CI fails; log blender --version at 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

TargetOperator / notesPitfalls
glTF 2.0bpy.ops.export_scene.gltfApply scale; Draco optional; check NLA vs active action
FBXexport_scene.fbxUnit scale 0.01 vs 1.0; bone roll
USDBlender USD exporterInstance paths, material binding
AlembicCache transforms/deformsFrame range, subframe sampling

Always apply scale (or document non-uniform scale) before export; validate in target engine (Unity/Unreal importers).


Failure taxonomy

SymptomLikely causeFix
Black renderNo camera/lights/worldAssert scene.camera; add key light
context is incorrectbpy.ops in wrong modeData API or temp_override
Failed to denoiseOIDN absent on serveruse_denoising = False or install OIDN build
EEVEE enum not foundVersion driftQuery available engines at runtime
Non-deterministic noiseAnimated seed / adaptive samplingFixed seed + fixed samples
Washed stills vs viewportWrong view transform / display deviceMatch 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/-a last on CLI. Prefer EXR + documented OCIO for color-critical pipelines. Exit non-zero on pipeline failure.

receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall