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.

Testing and Debugging

• Test scripts in a clean Blender profile and a representative production scene.
• Add smoke tests that import the add-on, register it, run core operators, and unregister cleanly.
• Log actionable messages with self.report() for user-facing operator feedback.
• Keep version-specific API differences isolated behind helper functions.

Common Mistakes

• Do not forget to unregister classes, handlers, timers, and keymaps.
• Do not mutate Blender data from panel draw() methods.
• Do not assume an active object, selected object, or mode without checking context.
• Do not hardcode absolute asset paths.