blender-python-addon — Cursor rule: what it does, how to install
Cursor rule for writing Blender Python add-ons. Enforces clean operator lifecycles, structured panels, and safe Blender API calls.
.cursor/rules/blender-python-addon.mdcWhat blender-python-addon does
This rule targets **/*.py, blender_manifest.toml, and __init__.py files inside add-on projects. It instructs the agent to split codebases into separate modules for operators, UI panels, property groups, and preferences. The __init__.py file serves strictly as the entry point with paired register() and unregister() routines.
API guidelines mandate explicit bl_idname, bl_label, and bl_options on all classes. Operators must validate runtime context inside poll() before executing. For long-running operations, modal state machines or timers take priority over blocking the main thread. Mesh modifications must rely on bmesh with batched edits.
Mutating scene data inside panel draw() functions causes redraw feedback loops and UI crashes. Forgetting to clean up keymaps, handlers, and custom properties during unregister() leaves dirty state in the active Blender session.
What it helps with
- organize Blender add-on files into isolated modules
- prevent UI lag in modal operators using timers
- batch mesh geometry edits with
bmesh - validate context inside operator
poll()methods - clean up custom properties and handlers during
unregister()
Example prompts for the agent
- Scaffold a modal operator using a timer so the Blender UI remains responsive.
- Create a custom
PropertyGroupand wire it up to an add-on preferences panel. - Write a smoke test that registers the add-on, triggers primary operators, and unregisters cleanly.
How to install blender-python-addon
Manually: put the files in place
.cursor/rules/blender-python-addon.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.claude/rules/blender-python-addon.mdThe paths frontmatter field limits the files: move globs from the source into paths
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.github/instructions/blender-python-addon.instructions.mdThe applyTo field sets which files it applies to: move globs from the source into applyTo
Manually: put the files in place
.devin/rules/blender-python-addon.mdManually: put the files in place
.clinerules/blender-python-addon.mdStep by step, with commands for each platform: Cursor rules: .mdc files, four modes and what replaced .cursorrules
Questions about blender-python-addon
How do I install blender-python-addon in Cursor?
Place the rule content into .cursor/rules/blender-python-addon.mdc inside your project root. Cursor will reference these instructions whenever you edit Python scripts or manifest files.
What does blender-python-addon do?
It directs Cursor to follow proper Blender Python patterns. It enforces context checks in poll(), separate invoke() and execute() steps, and safe property registration.
How does the rule handle mesh edits and UI performance?
It requires batching mesh modifications via bmesh rather than individual updates. It also prohibits scanning scene objects or altering Blender data inside panel draw() routines.
Source text
blender-python-addon.mdc · CC0-1.0
---
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.
## 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.
© PatrickJS · CC0-1.0 · PatrickJS/awesome-cursorrules
