跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
其他技能

blender-python-addon

Best practices for writing Blender Python add-ons using the bpy API, covering operators, panels, properties, registration, and API-safe scripting. Use when creating a Blender add-on, defining bpy.types.Operator or Panel classes, registering PropertyGroup settings, writing register()/unregister() functions, working with bmesh, or debugging add-ons in Blender's Python console.

Mindrally · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add Mindrally/skills --skill blender-python-addon

技能说明


name: blender-python-addon description: "Best practices for writing Blender Python add-ons using the bpy API, covering operators, panels, properties, registration, and API-safe scripting. Use when creating a Blender add-on, defining bpy.types.Operator or Panel classes, registering PropertyGroup settings, writing register()/unregister() functions, working with bmesh, or debugging add-ons in Blender's Python console." metadata: maintainer: Mindrally source: https://github.com/Mindrally/skills

Blender Python Add-on Development

This skill covers building Blender add-ons with the bpy API, including add-on structure, operators, panels, properties, safe scene manipulation, and testing across Blender versions.

Workflow for Building a Blender Add-on

  1. Scaffold the add-on — Create a package with __init__.py as the entry point, and a blender_manifest.toml (Blender 4.2+ extensions) or bl_info dict (legacy add-ons) describing name, version, and supported Blender version.
  2. Define data — Create PropertyGroup classes for grouped settings and register them on the appropriate ID type (e.g., bpy.types.Scene.my_addon = PointerProperty(type=MyAddonSettings)).
  3. Implement operators — Subclass bpy.types.Operator for each user action; implement poll() for availability, invoke() for interactive setup, and execute() for the actual work.
  4. Build UI panels — Subclass bpy.types.Panel to expose operators and properties in the appropriate editor (3D viewport sidebar, properties editor, etc.).
  5. Register everything — List all classes in a classes tuple and register/unregister them in matching register()/unregister() functions; register property pointers alongside their classes.
  6. Test in a clean profile — Launch Blender with --factory-startup, install the add-on, enable it, exercise each operator, then disable it and confirm nothing is left behind.
  7. Package and ship — Zip the add-on folder (or build a .zip extension package) and verify it installs cleanly via Blender's Preferences > Add-ons (or Extensions) panel.

Add-on Structure

  • Keep the add-on's entry point in __init__.py with clear register() and unregister() functions that mirror each other exactly (everything registered must be unregistered, in reverse order).
  • Group operators, panels, properties, preferences, and utility code into separate modules once the add-on grows past a trivial size; import and register them from __init__.py.
  • Use bl_info (pre-4.2 legacy add-ons) or blender_manifest.toml (4.2+ extensions) matching the target Blender version and packaging model — don't mix conventions.
  • Keep UI labels concise and use bpy.app.translations or the "Category"/label conventions so user-facing text can be localized where the project supports it.

API Usage

  • Use bpy.types.Operator for actions, bpy.types.Panel for UI layout, and bpy.types.PropertyGroup for grouped, related settings.
  • Define bl_idname (lowercase, category.action format, e.g. object.apply_custom_modifier), bl_label, and bl_options (e.g., {'REGISTER', 'UNDO'}) explicitly on every operator.
  • Validate context in poll() before allowing an operator to run — check for an active object, correct mode, or valid selection so the operator button greys out instead of erroring.
  • Use invoke() for interactive setup (showing a dialog, reading mouse position) and execute() for the actual operation; invoke() should call self.execute(context) when it doesn't need extra interaction.
  • Return {'FINISHED'} on success or {'CANCELLED'} on failure/user-abort consistently — never return a bare None or an unrecognized string.
  • Use bpy.context.evaluated_depsgraph_get() and object.evaluated_get(depsgraph) when reading final scene state that includes modifiers, shape keys, or other dependency-graph-driven results.

Example: Operator, Panel, and Registration

bl_info = {
    "name": "Random Vertex Color",
    "author": "Example",
    "version": (1, 0, 0),
    "blender": (4, 0, 0),
    "category": "Mesh",
}

import bpy
import random


class MESH_OT_random_vertex_color(bpy.types.Operator):
    """Assign a random color to the active vertex color layer"""

    bl_idname = "mesh.random_vertex_color"
    bl_label = "Randomize Vertex Colors"
    bl_options = {"REGISTER", "UNDO"}

    @classmethod
    def poll(cls, context):
        obj = context.active_object
        return (
            obj is not None
            and obj.type == "MESH"
            and obj.mode == "OBJECT"
            and obj.data.color_attributes.active_color is not None
        )

    def execute(self, context):
        obj = context.active_object
        color_layer = obj.data.color_attributes.active_color
        for data in color_layer.data:
            data.color = (random.random(), random.random(), random.random(), 1.0)
        obj.data.update()
        self.report({"INFO"}, f"Randomized colors on '{obj.name}'")
        return {"FINISHED"}


class VIEW3D_PT_random_vertex_color(bpy.types.Panel):
    bl_label = "Vertex Color Tools"
    bl_idname = "VIEW3D_PT_random_vertex_color"
    bl_space_type = "VIEW_3D"
    bl_region_type = "UI"
    bl_category = "Tool"

    def draw(self, context):
        layout = self.layout
        layout.operator(MESH_OT_random_vertex_color.bl_idname, icon="COLOR")


classes = (
    MESH_OT_random_vertex_color,
    VIEW3D_PT_random_vertex_color,
)


def register():
    for cls in classes:
        bpy.utils.register_class(cls)


def unregister():
    for cls in reversed(classes):
        bpy.utils.unregister_class(cls)


if __name__ == "__main__":
    register()

Data and Properties

  • Register custom properties through PropertyGroup classes instead of stuffing loose global state into module-level variables, which don't survive file reload and aren't undo-safe.
  • Store add-on preferences (API keys, default paths, UI toggles that persist across files) in an `
阅读完整来源 ↗