如何创建扩展

创建扩展只需几个步骤：

1. 打开包含插件代码或主题文件的目录。

2. 添加一个 blender_manifest.toml 文件，其中包含所有必要的元数据 (name, maintainer, ...)。

3. 使用 Blender 命令行工具来构建 .zip 扩展文件。

如何发布到 Blender 扩展平台：

• 从磁盘安装以测试是否一切正常。

• 上传 .zip 文件（此步骤需要 Blender ID）。

The extension will be held for review, and published once the moderation team approves it.

扩展文件

扩展以包含清单文件和其他文件的 .zip 压缩包的形式共享。预期文件取决于扩展类型。

插件扩展

插件至少需要清单和 __init__.py 文件，而更复杂的插件则需要几个不同的 .py 文件或 wheels.

my_extension-0.0.1.zip
├─ __init__.py
├─ blender_manifest.toml
└─ (...)

主题扩展

主题扩展只需要清单和 .xml 主题文件。

my_extension-0.0.1.zip
├─ blender_manifest.toml
└─ theme.xml

Note

Extensions can optionally have all its files inside a folder (inside the archive). This is a common behavior when saving a repository as ZIP from version-control platforms.

清单

清单是一个包含扩展处理所需的所有元数据的文件。本示例是 blender_manifest.toml 的良好起点，它应位于 .zip 内。

schema_version = "1.0.0"

# Example of manifest file for a Blender extension
# Change the values according to your extension
id = "my_example_extension"
version = "1.0.0"
name = "My Example Extension"
tagline = "This is another extension"
maintainer = "Developer name <email@address.com>"
# Supported types: "add-on", "theme"
type = "add-on"

# # Optional: link to documentation, support, source files, etc
# website = "https://extensions.blender.org/add-ons/my-example-package/"

# # Optional: tag list defined by Blender and server, see:
# # https://docs.blender.org/manual/en/dev/advanced/extensions/tags.html
# tags = ["Animation", "Sequencer"]

blender_version_min = "4.2.0"
# # Optional: Blender version that the extension does not support, earlier versions are supported.
# # This can be omitted and defined later on the extensions platform if an issue is found.
# blender_version_max = "5.1.0"

# License conforming to https://spdx.org/licenses/ (use "SPDX: prefix)
# https://docs.blender.org/manual/en/dev/advanced/extensions/licenses.html
license = [
  "SPDX:GPL-3.0-or-later",
]
# # Optional: required by some licenses.
# copyright = [
#   "2002-2024 Developer Name",
#   "1998 Company Name",
# ]

# # Optional: list of supported platforms. If omitted, the extension will be available in all operating systems.
# platforms = ["windows-x64", "macos-arm64", "linux-x64"]
# # Other supported platforms: "windows-arm64", "macos-x64"

# # Optional: bundle 3rd party Python modules.
# # https://docs.blender.org/manual/en/dev/advanced/extensions/python_wheels.html
# wheels = [
#   "./wheels/hexdump-3.3-py3-none-any.whl",
#   "./wheels/jsmin-3.0.1-py3-none-any.whl",
# ]

# # Optional: add-ons can list which resources they will require:
# # * files (for access of any filesystem operations)
# # * network (for internet access)
# # * clipboard (to read and/or write the system clipboard)
# # * camera (to capture photos and videos)
# # * microphone (to capture audio)
# #
# # If using network, remember to also check `bpy.app.online_access`
# # https://docs.blender.org/manual/en/dev/advanced/extensions/addons.html#internet-access
# #
# # For each permission it is important to also specify the reason why it is required.
# # Keep this a single short sentence without a period (.) at the end.
# # For longer explanations use the documentation or detail page.
#
# [permissions]
# network = "Need to sync motion-capture data to server"
# files = "Import/export FBX from/to disk"
# clipboard = "Copy and paste bone transforms"

# # Optional: advanced build settings.
# # https://docs.blender.org/manual/en/dev/advanced/extensions/command_line_arguments.html#command-line-args-extension-build
# [build]
# # These are the default build excluded patterns.
# # You only need to edit them if you want different options.
# paths_exclude_pattern = [
#   "__pycache__/",
#   "/.git/",
#   "/*.zip",
# ]

必需值：

blender_version_min:

Blender 的最低支持版本 - 至少使用 4.2.0。

id:

扩展的唯一标识符。

license:

列出许可证，使用 SPDX 许可证标识符。

maintainer:

扩展的维护者。

name:

扩展的完整名称。

schema_version:

文件格式的内部版本 - 使用 1.0.0。

tagline:

单行简短说明，最多 64 个字符 -- 不能以标点符号结尾。

type:

"插件"、"主题"。

version:

扩展的版本 - 必须遵循 semantic versioning。

可选值：

blender_version_max:

扩展不支持的 Blender 版本，支持更早的版本。

website:

扩展的网站。

copyright:

Some licenses require a copyright, copyrights must be "Year Name" or "Year-Year Name".

tags:

标签列表。请参阅可用标签的列表。

platforms:

支持的平台列表。如果省略，扩展将适用于所有操作系统。可用选项包括 ["windows-x64", "windows-arm64", "macos-x64", "macos-arm64", "linux-x64"]

wheels:

List of relative file-paths Python Wheels.

permissions:

插件可以列出它们需要的资源。可用选项包括 文件、网络、剪贴板、摄像头、麦克风。每个权限后都应有解释（简短的单句，最多 64 个字符，不含结尾标点符号）。

Optional values for "build":

These values are only used by the build sub-command.

paths:

A list of file-paths relative to the manifest to include when building the package.

paths_exclude_pattern:

A list of file-path patterns to exclude include when building the package.

The pattern matching is compatible with gitignore.

Note that setting this value isn't supported when paths is also declared.

If the [build] table isn't declared the following default is used:

[build]
paths_exclude_pattern = [
  "__pycache__/",
  ".*",
  "*.zip",
]

保留：

These values must not be declared in a TOML and are reserved for internal use.

• [build.generated]

Note

All the values present in the manifest file must be filled (i.e., cannot be empty, nor text "", nor list []).

If you don't want to set one of the optional values just exclude it from the manifest altogether.

命令行

扩展可通过命令行进行构建、验证和安装。

要构建当前目录下定义的程序包，请使用以下命令：

blender --command extension build

详见构建文档。

---

在不构建程序包的情况下验证清单：

blender --command extension validate

你可以直接验证一个插件包文件而无需提取它。

blender --command extension validate add-on-package.zip

详见验证文档。

See also

扩展的命令行参数。

第三方扩展站点

如果您想自己托管扩展，请参阅创建扩展存储库文档。