如何创建扩展#

创建扩展只需几个步骤：

打开包含插件代码或主题文件的目录。
添加一个 blender_manifest.toml 文件，其中包含所有必要的元数据 (name, maintainer, ...)．
使用 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 protected]>"
# 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:

单行简短说明 - 不能以标点符号结尾。

type:

“插件”、“主题”。

version:

扩展的版本 - 必须遵循语义化版本控制。

可选值：

blender_version_max:

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

website:

扩展的网站。

copyright:

部分许可证要求提供版权信息，版权信息必须标注为 “年份名称” 或 “年份-年份名称”。

tags:

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

platforms:

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

wheels:

List of relative file-paths Python Wheels.

permissions:

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

"build" 的可选值：

这些值仅用于 build 子命令。

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.

若未声明 [build] 表，则默认采用以下设置：
[build]
paths_exclude_pattern = [
  "__pycache__/",
  ".*",
  "*.zip",
]

保留：

这些值严禁在 TOML 文件中声明，且仅限内部使用。

[build.generated]

Note

清单文件中所有数值字段必须完整填写（即不得为空值、文本 "" 或列表 []）。

若不想设置任一可选值，可直接将其从清单中排除。

命令行#

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

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

blender --command extension build

详见构建文档。

---

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

blender --command extension validate

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

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

详见验证文档。

第三方扩展站点#

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