插件

Add-ons let you extend Blender’s functionality using Python. Most of the time you can get add-ons as part of the Extensions system.

Tip

If the Add-on does not activate when enabled, check the Console window for any errors that may have occurred.

用户自定义插件路径

用户还可以创建个人目录，存放新插件，然后在 偏好设置 的 文件路径 标签页配置文件路径。创建个人脚本目录，请执行以下操作：

  1. 在选择的位置创建一个空文件夹 (如 my_scripts)。

  2. 在 my_scripts 下创建子目录 addons (必须 使用这个名称，Blender才能识别)。

  3. 打开 偏好设置 的 文件路径 标签页。

  4. 设置 脚本 目录指向新建的脚本目录 (如 my_scripts)。

  5. 保存用户设置，重启Blender，这样就可以识别新的插件目录了。

现在，安装插件时，可以在安装第三方脚本时选择 目标路径。Blender会将新安装的插件复制到用户设置中的目标路径下。

互联网访问

If the add-on needs to use internet, it must check for the (read-only) property bpy.app.online_access. This option is controlled by Preferences, which can be overriding via command-line (--offline-mode / --online-mode).

For better error messages, you can check also for bpy.app.online_access_overriden, to determine whether users can turn Allow Online Access on the preferences, or not.

Note

Add-ons that follow this setting will only connect to the internet if enabled. However, Blender cannot prevent third-party add-ons from violating this rule.

打包依赖

For add-ons to be bundled as extensions, they must be self-contained. That means they must come with all its dependencies. In particular 3rd party Python modules.

There are a few options for this:

Bundle with Python Wheels.

This is the recommended way to bundle dependencies.

Bundle other add-ons together.

This is recommended if an add-on depends on another add-on.

Make sure that both the individual and the combined add-on check for already registered types (Operators, Panels, …). This avoids duplication of operators and panels on the interface if the add-ons are installed as a bundle and individually.

与 Vendorize 捆绑

This can be used as a way to bundle a pure Python dependencies as a sub-module.

This has the advantage of avoiding version conflicts although it requires some work to setup each package.

Local Storage

Add-ons must not assume their own directory is user writable since this may not be the case for “System” repositories. Writing files into the add-on’s directory also has the down side that upgrading the extension will remove all files.

Add-ons which need their own user directory should use a utility function provided for this purpose:

  1. extension_directory = bpy.utils.extension_path_user(__package__, path="", create=True)

If you wish create subdirectories, this can be done with the path argument.

This directory will be kept between upgrades but will be removed if the extension is uninstalled.

旧式 vs 扩展插件

With the introduction of Extensions in Blender 4.2, the old way of creating add-ons is considered deprecated. While the changes are rather small they impact existing add-ons.

In order to allow a smooth transition process, the so-called legacy add-ons will continue to be supported by Blender. They can be installed via Install legacy Add-on button in the User Preferences.

All add-on maintainers are urged to convert the add-ons they want to share, so they are future proof and can support features like updating from the extensions platform.

将一个旧式插件转换为扩展

  1. Create a manifest file.

  2. Remove the bl_info information (this is now in the manifest).

  3. Replace all references to the module name to __package__.

  4. Make all module imports to use relative import.

  5. Use wheels to pack your external Python dependencies.

  6. 记住要进行彻底的测试。

Note

For testing it is import to install the extension from disk and check if everything is working well. This will get you as close to the final experience as possible.

扩展与命名空间

The legacy add-ons would use their module name to access the preferences. This could lead to a name clash when extensions with the same name (from different repositories) would be installed. To prevent this conflict, the repository name is now part of the namespace.

For example, now instead of kitsu the module name would be bl_ext.{repository_module_name}.kitsu instead.

This has a few implications for preferences and module imports.

用户设置与 __package__

Add-ons can define their own preferences which use the package name as an identifier. This can be accessed using __package__.

This was already supported in the legacy add-ons, but not reinforced. As such this can break backward compatibility.

以前：

  1. class KitsuPreferences(bpy.types.AddonPreferences):
  2.     bl_idname = "kitsu"
  3.     # ... snip ...
  5. # Access with:
  6. addon_prefs = bpy.context.preferences.addons["kitsu"]

现在：

  1. class KitsuPreferences(bpy.types.AddonPreferences):
  2.     bl_idname = __package__
  3.     # ... snip ...
  5. # Access with:
  6. addon_prefs = bpy.context.preferences.addons[__package__]

Sub-packages

An add-on that defines sub-packages (sub-directories with their own __init__.py file) that needs to use this identifier will have to import the top-level package using a relative import.

  1. from .. import __package__ as base_package

Then base_package can be used instead of __package__. The .. imports relative to the packages parent, sub-sub-packages must use ... and so on.

Note

  • The value of __package__ will vary between systems so it should never be replaced with a literal string.

  • Extensions must not manipulate the value of __package__ as this may cause unexpected behavior or errors.

相对导入

以前:

from kitsu import utils

现在:

from . import utils

Importing packages within the add-on module need to use relative paths. This is a standard Python feature and only applicable for add-ons that have multiple folders.

This was already supported in the legacy add-ons, but not reinforced. As such this can break backward compatibility.