其他技能
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
- Scaffold the add-on — Create a package with
__init__.pyas the entry point, and ablender_manifest.toml(Blender 4.2+ extensions) orbl_infodict (legacy add-ons) describing name, version, and supported Blender version. - Define data — Create
PropertyGroupclasses for grouped settings and register them on the appropriate ID type (e.g.,bpy.types.Scene.my_addon = PointerProperty(type=MyAddonSettings)). - Implement operators — Subclass
bpy.types.Operatorfor each user action; implementpoll()for availability,invoke()for interactive setup, andexecute()for the actual work. - Build UI panels — Subclass
bpy.types.Panelto expose operators and properties in the appropriate editor (3D viewport sidebar, properties editor, etc.). - Register everything — List all classes in a
classestuple and register/unregister them in matchingregister()/unregister()functions; register property pointers alongside their classes. - 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. - Package and ship — Zip the add-on folder (or build a
.zipextension 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__.pywith clearregister()andunregister()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) orblender_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.translationsor the"Category"/label conventions so user-facing text can be localized where the project supports it.
API Usage
- Use
bpy.types.Operatorfor actions,bpy.types.Panelfor UI layout, andbpy.types.PropertyGroupfor grouped, related settings. - Define
bl_idname(lowercase,category.actionformat, e.g.object.apply_custom_modifier),bl_label, andbl_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) andexecute()for the actual operation;invoke()should callself.execute(context)when it doesn't need extra interaction. - Return
{'FINISHED'}on success or{'CANCELLED'}on failure/user-abort consistently — never return a bareNoneor an unrecognized string. - Use
bpy.context.evaluated_depsgraph_get()andobject.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
PropertyGroupclasses 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 `