Home › Blender (Python add-ons) › Blender Python add-on AGENTS.md

Blender Python add-on AGENTS.md

AGENTS.md for Blender add-ons and extensions in Python (bpy): manifest, operators and panels, register/unregister, properties, and headless tests.

AGENTS.mdBlender (Python add-ons)

Copy AGENTS.md

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

# AGENTS.md: Blender add-on (bpy)

## Commands
- Build an extension zip: `blender --command extension build` (reads `blender_manifest.toml`)
- Validate: `blender --command extension validate`
- Headless tests: `blender --background --factory-startup --python-exit-code 1 --python tests/run_tests.py`
- Check `blender_version_min` in the manifest and only use bpy APIs available in that version.

## Code map
`blender_manifest.toml` (id, version, `blender_version_min`, permissions) · `__init__.py` (register/unregister only) · `operators/`, `panels/`, `props.py`, `utils/`.

## Rules
- Every class (Operator, Panel, PropertyGroup, Menu) is listed in one `classes` tuple, registered in order in `register()` and unregistered in reverse in `unregister()`. Re-enabling the add-on must not error.
- Operators: `bl_idname = "myaddon.verb_noun"`, `bl_label`, `bl_options = {'REGISTER', 'UNDO'}` for anything that changes data, a `poll()` classmethod, and return `{'FINISHED'}` or `{'CANCELLED'}`. Report problems with `self.report({'ERROR'}, msg)`.
- Panels: `bl_space_type`, `bl_region_type`, `bl_category`; draw only, never modify data in `draw()`.
- Store settings in a `PropertyGroup` attached via `bpy.types.Scene.myaddon = PointerProperty(...)` (remove it in `unregister`). Preferences go in `AddonPreferences` keyed by `__package__`.
- Prefer data API (`bpy.data`, mesh/`bmesh`) over `bpy.ops` inside loops; `bpy.ops` depends on context and is slow. If you need an operator, pass a context with `context.temp_override(...)`.
- Don't store references to `bpy` data blocks across undo or file loads; look them up by name or use handlers with `@persistent`.
- Network access, file writes outside the user's chosen path, and subprocesses must be declared in manifest `permissions` and done only when the user triggers them.
- Third-party Python wheels are bundled via the manifest's `wheels` list, not installed with pip at runtime.

## Done
Validate and build succeed, headless tests pass, and the add-on enables, runs, and disables cleanly in a fresh profile.