该技能面向以扩展(Extension)形式开发 Blender 5.3 插件的场景,说明执行模型位于 blender-core,建议从 assets/addon_template/ 模板起步,该模板包含 blender_manifest.toml、init.py、operators.py、ui.py,并已在 CI 中完成校验、构建与注册。
使用方式与主要流程:
- 复制模板,设置清单字段:id(小写下划线且永久不变)、name、tagline(无结尾句号、不超过 64 字符)、maintainer、version(semver)、license(使用 bpy 的代码用 SPDX 的 GPL-3.0-or-later),以及 blender_version_min = "4.2.0" 或更高(使用较新 API 时相应提高,如 GN properties.inputs API 用 "5.2.0")。
- 类名前缀约定:MYTOOL_OT_x(操作符)、PT(面板)、MT(菜单)、PG(属性组)、AP(偏好)、UL(UI 列表);操作符 bl_idname 形如 my_tool.verb_noun。
- 校验与构建命令:blender --command extension validate ./my_tool;mkdir -p dist && blender --command extension build --source-dir ./my_tool --output-dir ./dist(dist 需先存在);blender --command extension install-file -r user_default -e ./dist/my_tool-1.0.0.zip,注意 install-file 即使失败也返回 0,需检查输出是否包含 "Installed"。
- 无界面测试:在进程内注册包,用 temp_override 调用操作符并对数据断言,参见仓库 tests/test_addon.py。
扩展时代(5.x)规则:仅用相对导入(from . import ops);包名由 Blender 决定,偏好中使用 bl_idname = package;不使用 bl_info,全部写入清单;导入/注册时禁止网络或文件访问,需在 [permissions] 声明 files、network、clipboard、camera、microphone 及理由,网络调用前检查 bpy.app.online_access;第三方 Python 包将 .whl 放入 ./wheels/ 并在 wheels = [...] 中列出,禁止运行时 pip install,平台相关 wheel 需 platforms = [...]。
属性(5.0+):bpy.props 值为属性而非字典条目(scene["my_prop"] 不再可达);只读属性用 options={'READ_ONLY'};get_transform/set_transform 可在保持存储的同时适配值;用 PointerProperty(type=PG) 注册到 ID 类型,注销时 del。
操作符与 UI:bl_options={"REGISTER","UNDO"} 提供撤销与重做面板;poll() 守护上下文;返回 {"FINISHED"}/{"CANCELLED"};用 self.report({"WARNING"}, msg) 反馈;有数据 API 时不要在循环中调用其它操作符。layout.use_property_split = True 提供现代对齐;N 面板用 bl_region_type="UI" + bl_category;用 VIEW3D_MT_*.append(func) 追加菜单项并在注销时移除。
注销与运行时:按相反顺序注销所有内容(类、属性、菜单、处理器、计时器、快捷键、绘制处理器),泄漏会破坏重载。覆盖层绘制用 gpu 模块与 gpu_extras.batch,bgl 已在 5.0 移除,纹理来自 gpu.texture.from_image(img),场景线性图像用 draw_texture_2d(..., is_scene_linear_with_rec709_srgb_target=True)。长任务用带计时器的模态操作符(wm.event_timer_add)或 bpy.app.timers.register 分块处理,不得阻塞 UI 数秒。持久化处理器加 @bpy.app.handlers.persistent 并保持轻量。快捷键加入 wm.keyconfigs.addon,保存 (km, kmi) 对并在注销时移除。国际化用 bpy.app.translations.register(package, dict)。
发布:通过 Blender ID 账号上传构建 zip 到 extensions.blender.org,要求清单有效、GPL 兼容许可、无混淆代码、无无源码的捆绑二进制、已声明权限;截图/README 放在网站列表页;更新时提高版本号。
限制与常见陷阱:某些编辑器绘制函数中 context.scene 可能为 None,需守护;在 Python 全局变量中保存 Blender 数据引用(bpy.types.ID)会在撤销或加载文件后崩溃,应存名称或 session_uid 再查找;注解中对属性用 = 而非 : 会导致 register_class 失败;5.0 将若干内置模块私有化(rna_info、bl_ui_utils 等)不应导入;5.1 默认不再加载用户 site-packages,应打包 wheel;5.2 中 PreferencesFilePaths.active_asset_library 索引有偏移("All"/"Essentials" 在前),UILayout.template_palette(color=) 移除,新增 UILayout.link、UILayout.textbox、bpy.data.all_ids、Window.screenshot;5.3 中 bpy.data.all_ids 顺序为实现细节,新增 UILayout.label_multiline()、invoke_popup/popover 的 auto_keymap=、只读 window_manager.undo_stack、constraints.new(type, name=)、KDTree(n, dimensions=2)、gpu.types.GPUStorageBuf 及捆绑 OpenEXR/opentimelineio 模块,Windows/Linux 默认 GPU 后端为 Vulkan,需在此测试 gpu 绘制。