blender-python-scripting

Blender Python 脚本专家

概述

此技能为 Blender 5.x Python 脚本编写提供专家指导：编写自定义操作器、构建 UI 面板、开发插件、管理上下文、使用处理器和计时器、处理属性系统、进行批处理，以及访问 Blender 的数据模型。参考文件包含完整模板和数据模型层级结构。

MCP 优先方法

执行脚本、检查数据块，以及直接在运行中的 Blender 会话里修改场景状态时，优先使用 官方 Blender MCP 服务（Blender Lab，Blender 5.1+）。只有在 MCP 服务未连接时，才退而使用输出 Python 脚本的方式。

**检测：**会话开始时，查找名称与 execute_blender_code、get_objects_summary 或 search_api_docs 匹配的工具——这些工具属于官方 blender-mcp 服务。如果找到其中任何一个，即表示 MCP 可用。

此技能使用的工具：

• execute_blender_code — 在实时会话中运行 bpy Python（主要操作）
• get_objects_summary、get_object_detail_summary — 修改前检查场景状态
• get_blendfile_summary_datablocks / _missing_files / _of_linked_libraries / _path_info / _usage_guess — 检查文件内容
• search_api_docs、get_python_api_docs、search_manual_docs — 调用前确认正确的 API／操作器名称
• get_screenshot_of_window_as_image / _as_json、get_screenshot_of_area_as_image — 验证视觉效果
• jump_to_tab_by_name、jump_to_tab_by_space_type、jump_to_view3d_object_by_name、jump_to_view3d_object_data_by_name — 操控 UI，让修改效果可见
• render_thumbnail_to_path、render_viewport_to_path — 获取快速视觉反馈

**工作流：**使用 get_* / search_* 工具检查 → 通过 execute_blender_code 修改 → 使用截图或摘要工具验证。代码块应保持简短且可幂等执行，以便轻松定位故障。

设置方法：参见 docs/blender-mcp-setup.md。

任务决策树

• “创建自定义操作器” -> 参阅 references/python_api.md 中的操作器模板
• “构建 UI 面板” -> 查看 references/python_api.md 中的面板模板
• “开发 Blender 插件” -> 按照下方的插件结构部分操作
• “批量处理文件／渲染” -> 查看批处理模式
• “访问场景／对象数据” -> 参阅 references/data_model_reference.md
• “注册属性” -> 查看 references/python_api.md 中的属性系统
• “在帧更改／文件加载时运行代码” -> 查看 references/python_api.md 中的处理器模式
• “上下文错误／poll 失败” -> 查看下方的上下文管理

Blender 5.1 Python 变更

Python 3.13 升级

1. Blender 5.1 内置 Python 3.13（Blender 5.0 内置的是 3.12）
2. 在插件中将 bl_info["blender"] 更新为 (5, 1, 0)，以进行版本限制
3. 使用类型提示语法（int | None，而非 Optional[int]）——现已完全支持
4. CPython 3.13 的性能改进：函数调用更快，GC 更出色

已移除的操作器

1. bpy.ops.anim.convert_legacy_action — 已移除；分层动作会自动处理此事

API 新增内容

1. bpy.ops.pose.apply_to_basis() — 将当前姿势烘焙为静止姿势
2. 节点插槽类型：用于字体数据的 NodeSocketFont
3. 几何节点的体积网格节点类型（参见 blender-geometry-nodes 技能）

插件结构

规范的 Blender 插件采用以下布局：

my_addon/
├── __init__.py       # bl_info, register(), unregister()
├── operators.py      # Custom operators
├── panels.py         # UI panels
├── properties.py     # PropertyGroups
├── preferences.py    # AddonPreferences (optional)
└── utils.py          # Shared utilities

最小单文件插件

bl_info = {
    "name": "My Add-on",
    "author": "Author",
    "version": (1, 0, 0),
    "blender": (5, 0, 0),
    "location": "View3D > Sidebar > My Tab",
    "description": "Short description",
    "category": "Object",
}

import bpy

class MY_OT_my_operator(bpy.types.Operator):
    bl_idname = "my.my_operator"
    bl_label = "My Operator"
    bl_options = {'REGISTER', 'UNDO'}

    @classmethod
    def poll(cls, context):
        return context.active_object is not None

    def execute(self, context):
        # ... do work ...
        return {'FINISHED'}

class MY_PT_my_panel(bpy.types.Panel):
    bl_label = "My Panel"
    bl_idname = "MY_PT_my_panel"
    bl_space_type = 'VIEW_3D'
    bl_region_type = 'UI'
    bl_category = "My Tab"

    def draw(self, context):
        layout = self.layout
        layout.operator("my.my_operator")

classes = (MY_OT_my_operator, MY_PT_my_panel)

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

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

if __name__ == "__main__":
    register()

命名约定

• 操作器：ADDON_OT_name → bl_idname = "addon.name"
• 面板：ADDON_PT_name
• 菜单：ADDON_MT_name
• UILists：ADDON_UL_name
• PropertyGroups：ADDON_PG_name（约定俗成，并非强制）
• 标题栏：ADDON_HT_name

上下文管理

常见上下文问题

Blender 操作依赖当前上下文（活动对象、模式、区域类型）。许多 bpy.ops.* 调用在上下文不正确时会失败。

规则：调用运算符前始终检查上下文。使用 poll() 方法为运算符添加保护。

上下文覆盖（Blender 4.x+ / 5.x）

# Modern context override using temp_override (4.0+)
with bpy.context.temp_override(active_object=obj, selected_objects=[obj]):
    bpy.ops.object.delete()

# Override with area/region for UI-dependent ops
area = next(a for a in bpy.context.screen.areas if a.type == 'VIEW_3D')
region = next(r for r in area.regions if r.type == 'WINDOW')
with bpy.context.temp_override(area=area, region=region):
    bpy.ops.view3d.camera_to_view()

模式切换

# Safe mode switch
if bpy.context.object and bpy.context.object.mode != 'EDIT':
    bpy.ops.object.mode_set(mode='EDIT')

# Always return to object mode when done
bpy.ops.object.mode_set(mode='OBJECT')

常见上下文问题

1. 后台模式下的 bpy.ops：许多视口运算符在 --background 模式下会失败。请改用直接数据 API（bpy.data.*）。
2. 处理程序中的运算符上下文：处理程序在常规上下文之外运行。请使用 bpy.context.temp_override()，或避免在处理程序中使用 bpy.ops。
3. 活动对象为 None：操作前始终检查 context.active_object is not None。
4. 模式错误：对象模式运算符在编辑模式下会失败，反之亦然。请检查 context.object.mode。
5. 依赖图未更新：修改数据后，如有需要，请调用 bpy.context.view_layer.update() 或 depsgraph.update()。
6. display_type 的取值取决于对象类型：'PLAIN_AXES' 仅适用于空物体。网格对象使用 'BOUNDS'、'WIRE'、'SOLID' 或 'TEXTURED'。

批处理

批量渲染

import bpy, os

scenes_dir = "/path/to/blend/files"
output_dir = "/path/to/output"

for filename in os.listdir(scenes_dir):
    if filename.endswith(".blend"):
        filepath = os.path.join(scenes_dir, filename)
        bpy.ops.wm.open_mainfile(filepath=filepath)
        bpy.context.scene.render.filepath = os.path.join(
            output_dir, filename.replace(".blend", ".png")
        )
        bpy.ops.render.render(write_still=True)

批量处理对象

import bpy

for obj in bpy.data.objects:
    if obj.type == 'MESH':
        # Select only this object
        bpy.ops.object.select_all(action='DESELECT')
        obj.select_set(True)
        bpy.context.view_layer.objects.active = obj
        # Apply all modifiers
        for mod in obj.modifiers:
            bpy.ops.object.modifier_apply(modifier=mod.name)

命令行批处理

blender --background scene.blend --python my_script.py
blender --background --python batch_render.py -- --input /files --output /renders

在 -- 后访问自定义参数：

import sys
argv = sys.argv[sys.argv.index("--") + 1:]

调试技巧

1. 系统控制台：选择 Window > Toggle System Console（Windows），或从终端运行 Blender
2. Python 控制台：打开 Python 控制台编辑器区域，以便交互式测试
3. 信息编辑器：显示 GUI 操作对应的 Python 代码，可用于查找 API 调用
4. dir() 和 help()：在 Python 控制台中使用，以探索 API 对象
5. bpy.context.copy()：返回当前上下文的字典，以供检查
6. 模态运算符中的错误：添加 print() 语句，或在异常处理程序中使用 traceback.print_exc()

属性系统快速参考

类型	注册	取值
BoolProperty	bpy.props.BoolProperty()	True/False
IntProperty	bpy.props.IntProperty()	min、max、default、step
FloatProperty	bpy.props.FloatProperty()	min、max、default、precision
StringProperty	bpy.props.StringProperty()	default、maxlen、subtype
EnumProperty	bpy.props.EnumProperty()	items=[(id, name, desc)]
FloatVectorProperty	bpy.props.FloatVectorProperty()	size、default、subtype
IntVectorProperty	bpy.props.IntVectorProperty()	size、default
BoolVectorProperty	bpy.props.BoolVectorProperty()	size、default
PointerProperty	bpy.props.PointerProperty()	type=PropertyGroup
CollectionProperty	bpy.props.CollectionProperty()	type=PropertyGroup

属性子类型

• Float/Int：'PIXEL'、'PERCENTAGE'、'FACTOR'、'ANGLE'、'TIME'、'DISTANCE'
• FloatVector：'COLOR'、'TRANSLATION'、'DIRECTION'、'VELOCITY'、'ACCELERATION'、'EULER'、'QUATERNION'、'XYZ'
• String：'FILE_PATH'、'DIR_PATH'、'FILE_NAME'、'BYTE_STRING'、'PASSWORD'

Python API 参考

有关完整模板（包括运算符：基本、模态、文件对话框、带属性调用；面板：条件式、子面板、可折叠；PropertyGroup、处理程序、计时器、键位映射和上下文覆盖），请参阅 references/python_api.md。

数据模型参考

有关完整的 Blender 数据层级（bpy.data.*）、ID 类型、对象类型、网格/曲线/骨架数据访问模式以及依赖图用法，请参阅 references/data_model_reference.md。