blender-python-addon

---

description: Blender Python add-on rules for operators, panels, properties, registration, testing, and API-safe scripting globs: ["**/*.py", "blender_manifest.toml", "init.py"] alwaysApply: false

Blender Python Add-on Rules

Add-on Structure

• Keep add-on entry points in __init__.py with clear register() and unregister() functions.
• Group operators, panels, properties, preferences, and utilities into separate modules for non-trivial add-ons.
• Use bl_info or blender_manifest.toml according to the Blender version and packaging target.
• Keep UI labels concise and user-facing text translatable where appropriate.

API Usage

• Use bpy.types.Operator for actions, bpy.types.Panel for UI, and bpy.types.PropertyGroup for grouped settings.
• Define bl_idname, bl_label, and bl_options explicitly.
• Validate context in poll() before enabling operators.
• Use invoke() for interactive setup and execute() for the actual operation.
• Return {'FINISHED'} or {'CANCELLED'} consistently.
• Use dependency graph updates and evaluated objects when reading final scene state.

Data and Properties

• Register custom properties through PropertyGroup classes instead of loose global state.
• Store add-on preferences in AddonPreferences.
• Use PointerProperty, CollectionProperty, and typed properties with names and descriptions.
• Clean up custom properties and handlers during unregister().

Safety and Performance

• Do not run destructive scene operations without explicit user action.
• Avoid blocking UI work in modal operators; use timers or modal state machines for long operations.
• Batch mesh changes and use bmesh when editing mesh data programmatically.
• Avoid repeatedly scanning large scenes in draw methods.
• Keep file paths configurable and use Blender path utilities.