wikis / Blender (for Agents) / wiki / concepts / bpy-data-first-automation.md view as markdown report a mistake

bpy.data First Automation

Definition

bpy.data first automation is the practice of editing Blender data-blocks directly instead of relying primarily on UI-style operators.

How It Works

The script creates meshes, materials, collections, cameras, lights, actions, and node trees through bpy data APIs. It sets RNA properties directly and links objects into collections. Operators from bpy ops are reserved for tasks where Blender already packages complex behavior as an operator.

Key Parameters

• Object and collection naming conventions.
• Whether data-blocks are created fresh, reused, or updated.
• Direct property settings for transforms, materials, render settings, and visibility.
• Cleanup policy for old generated data.

When To Use

Use this for generated scenes, deterministic setup blocks, testable asset creation, material assignment, camera and light construction, and any agent script expected to run in background mode.

Risks & Pitfalls

• Some operations are more tedious through direct data APIs than through operators.
• Low-level mesh construction requires correct vertices, faces, normals, and transforms.
• Agents may hallucinate property names; validate with actual Blender runs.

Related Concepts

• operator context management
• idempotent scene scripts
• debugging blender agent runs

Sources

• raw/blender-python-api-notes.md
• raw/blender-agent-field-guide.md