---
title: "bpy.data First Automation"
type: concept
tags: [bpy, data-api, deterministic, foundational]
created: 2026-06-04
updated: 2026-06-04
sources: ["raw/blender-python-api-notes.md", "raw/blender-agent-field-guide.md"]
confidence: high
---

# 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 [[entities/bpy]] data APIs. It sets RNA properties directly and links objects into collections. Operators from [[entities/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

- [[concepts/operator-context-management]]
- [[concepts/idempotent-scene-scripts]]
- [[concepts/debugging-blender-agent-runs]]

## Sources

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