该技能围绕 Blender 5.x 的扩展(Extension,即 Add-on)开发生命周期展开,内容以流程规则和注意事项为主,未提供额外示例代码或价格等信息。
用途 用于指导编写符合扩展规范的 Blender 插件,涵盖清单、类结构、属性、操作符、界面、绘制、长任务、快捷键、翻译与发布。执行模型部分指出应在 blender-core 中查看,实际起点是仓库中的 assets/addon_template(已在 CI 中验证、构建并注册),其包含 blender_manifest.toml、init.py、operators.py、ui.py。
主要能力与流程
- 从模板复制后设置清单字段:id(小写下划线、永久不变)、name、tagline(无结尾句点、不超过 64 字符)、maintainer、version(semver)、license(使用 bpy 的代码用 SPDX 的 GPL-3.0-or-later),以及 blender_version_min,使用较新 API 时需设为 "4.2.0" 或更高(例如使用 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 blender --command extension build --source-dir ./my_tool --output-dir ./dist blender --command extension install-file -r user_default -e ./dist/my_tool-1.0.0.zip 无头测试方式:在进程内注册包,用 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 包:在 ./wheels/ 中随附 .whl 文件并在 wheels = [...] 下列出,禁止在运行时 pip install。平台相关 wheel 需要 platforms = [...]。
- 属性(5.0+):bpy.props 的值是属性而非字典项(scene["my_prop"] 不再能访问到它们)。只读属性使用 options={'READ_ONLY'}。get_transform/set_transform 在保留存储的同时转换值。在 ID 类型上用 PointerProperty(type=PG) 注册,并在注销时删除。
- 操作符:使用 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) 对,并在注销时移除。
- 翻译/i18n:bpy.app.translations.register(package, dict)。
发布 通过 Blender ID 账号上传构建好的 zip 到 extensions.blender.org。要求包括:有效清单、GPL 兼容许可证、无混淆代码、无无源码的捆绑二进制、已声明权限。截图/README 放在网站列表中。更新时使用更高版本号。
注意事项
- 绘制函数中的 context.scene 在某些编辑器中可能为 None,需加以防护。
- 在 Python 全局变量中存储 Blender 数据引用(bpy.types.ID)会在撤销或加载文件后崩溃,应存储名称或 session_uid 并重新查找。
- 若注解中用 = 而非 : 声明属性,bpy.utils.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。
限制 资料未提供示例插件的完整源码、具体测试断言内容、发布审核时长、收费或价格等信息,暂未提供。