如何创建扩展#
创建扩展只需几个步骤:
Open the directory containing the add-on code or theme file.
Add a blender_manifest.toml file with all the required meta-data
(name, maintainer, ...)
.Use the Blender command-line tool to build the extension .zip file.
如何发布到 Blender 扩展平台:
从磁盘安装以测试是否一切正常。
上传 .zip 文件(此步骤需要 Blender ID)。
The extension will be held for review, and published once the moderation team approves it.
扩展文件#
An extension is shared as a .zip
archive containing a manifest file and other files.
The expected files depend on the extension type.
插件扩展#
Add-ons need at least the manifest and an __init__.py
file,
while more complex add-ons have a few different .py files or wheels together.
my_extension-0.0.1.zip
├─ __init__.py
├─ blender_manifest.toml
└─ (...)
主题扩展#
A theme extension only needs the manifest and the .xml theme file.
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.
Manifest#
A manifest is a file with all the meta-data required for an extension to be processed.
This example is a good starting point to the blender_manifest.toml
that should be inside the .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:
One-line short description - cannot end with punctuation.
- 类型:
"插件"、"主题"。
- 版本:
扩展的版本 - 必须遵循 semantic versioning。
可选值:
- blender_version_max:
扩展不支持的 Blender 版本,支持更早的版本。
- 网站:
扩展的网站。
- 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:
Add-ons can list which resources they require. The available options are files, network, clipboard, camera, microphone. Each permission should be followed by an explanation (short single-sentence with no end punctuation (
.
)).
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.
命令行#
Extensions can be built, validated & installed via command-line.
To build the package defined in the current directory use the following commands:
blender --command extension build
详见构建文档。
---
To validate the manifest without building the package:
blender --command extension validate
You may also validate a package without having to extract it first.
blender --command extension validate add-on-package.zip
详见验证文档。
See also
第三方扩展站点#
如果您想自己托管扩展,请参阅创建扩展存储库文档。