Blender Python Addon

Cursor-Regel für Blender-Add-on-Entwicklung in Python: korrekte bpy-Struktur, Operatoren, Panels und Registrierung.

Original-Beschreibung der Autoren: Blender Python add-on rules for operators, panels, properties, registration, testing, and API-safe scripting

Die Regel

---
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.

So nutzt du sie

Die Regel kopieren (Button oben) oder als Datei herunterladen und im Projekt unter .cursor/rules/ ablegen — Cursor lädt sie beim nächsten Start automatisch. Ältere Cursor-Versionen lesen alternativ eine einzelne .cursorrules-Datei im Projektstamm; dort einfach den Regel-Text ohne den Kopfblock zwischen den ----Zeilen einfügen.

Der Regel-Text ist englisch — Cursor versteht ihn unabhängig von der Sprache, in der Sie mit dem Editor chatten.

Im Detail

Regel für die Entwicklung von Blender-Add-ons in Python: Sie bringt Cursor die Blender-API-Konventionen bei — bpy-Modulstruktur, Operator- und Panel-Klassen, register()/unregister()-Boilerplate sowie typische Fallstricke wie das Blockieren des Main-Threads. Der Vorteil gegenüber generischem Python-Code ist, dass Cursor Blender-spezifische Muster wie Property Groups oder UI-Layout in draw() korrekt anwendet statt generischen Skriptcode vorzuschlagen. Lohnt sich für 3D-Artists und Entwickler, die eigene Blender-Tools bauen und wiederkehrenden Setup-Code nicht jedes Mal manuell schreiben wollen. Für reine Blender-Nutzung ohne Skripting ist die Regel irrelevant.

Praxis-Tipp

Prompt z. B. „Erstelle ein Blender-Add-on mit einem Operator, der alle ausgewählten Objekte skaliert, plus Panel im Sidebar“ — Cursor generiert register()/unregister() und bl_info automatisch korrekt.

Lizenz & Quelle

• Lizenz: CC0 1.0
• Quelle: PatrickJS/awesome-cursorrules (GitHub)

Lade …