插件

插件 可以让您使用 Python 扩展 Blender 的功能。大多数情况下，您可以从扩展系统中获取插件。

Tip

如果启用后插件功能未激活，请打开控制台窗口，检查是否有错误发生。

互联网访问

如果插件需要使用互联网，则必须检查（只读）属性 bpy.app.online_access。该选项由偏好设置控制，可以通过命令行（--offline-mode / --online-mode）进行覆写。

为了更好地获取错误信息，还可以检查 bpy.app.online_access_overriden，以确定用户是否可以将允许联机访问打开。

Note

遵循此设置的插件只有在启用的情况下才会连接到互联网。然而，Blender 无法阻止第三方插件违反这一规则。

打包依赖

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.

将其他插件捆绑在一起。

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.

本地存储

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:

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 扩展插件

随着 Blender 4.2 中扩展功能的引入，创建插件的旧方法被认为已经过时。虽然变化不大，但对现有插件的影响却很大。

为了实现平稳过渡，Blender 将继续支持所谓的旧式插件。它们可以通过用户偏好设置中的安装旧式插件按钮安装。

我们敦促所有插件维护者转换他们想要分享的插件，以便它们能够适应未来的需要，并支持从扩展平台更新等功能。

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

  1. 创建一个清单文件。

  2. 删除 bl_info 信息（该信息现在在清单中）。

  3. 将所有对模块名称的引用替换为 __package__。

  4. 让所有模块导入都使用相对导入。

  5. 使用 wheels 打包您的外部 Python 依赖项。

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

Note

对于测试，重要的是从磁盘安装扩展并检查是否一切正常。这将使您尽可能接近最终体验。

扩展与命名空间

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.

以前：

class KitsuPreferences(bpy.types.AddonPreferences):
    bl_idname = "kitsu"
    # ... snip ...

# Access with:
addon_prefs = bpy.context.preferences.addons["kitsu"]

现在：

class KitsuPreferences(bpy.types.AddonPreferences):
    bl_idname = __package__
    # ... snip ...

# Access with:
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.

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.