如何创建扩展

创建扩展只需几个步骤：

  1. Open the directory containing the add-on code or theme file.

  2. Add a blender_manifest.toml file with all the required meta-data (name, maintainer, ...).

  3. Use the Blender command-line tool to build the extension .zip file.

如何发布到 Blender 扩展平台：

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.

  1. my_extension-0.0.1.zip
  2. ├─ __init__.py
  3. ├─ blender_manifest.toml
  4. └─ (...)

主题扩展

A theme extension only needs the manifest and the .xml theme file.

  1. my_extension-0.0.1.zip
  2. ├─ blender_manifest.toml
  3. └─ 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.

  1. schema_version = "1.0.0"
  3. # Example of manifest file for a Blender extension
  4. # Change the values according to your extension
  5. id = "my_example_extension"
  6. version = "1.0.0"
  7. name = "My Example Extension"
  8. tagline = "This is another extension"
  9. maintainer = "Developer name <[email protected]>"
  10. # Supported types: "add-on", "theme"
  11. type = "add-on"
  13. # # Optional: link to documentation, support, source files, etc
  14. # website = "https://extensions.blender.org/add-ons/my-example-package/"
  16. # # Optional: tag list defined by Blender and server, see:
  17. # # https://docs.blender.org/manual/en/dev/advanced/extensions/tags.html
  18. # tags = ["Animation", "Sequencer"]
  20. blender_version_min = "4.2.0"
  21. # # Optional: Blender version that the extension does not support, earlier versions are supported.
  22. # # This can be omitted and defined later on the extensions platform if an issue is found.
  23. # blender_version_max = "5.1.0"
  25. # License conforming to https://spdx.org/licenses/ (use "SPDX: prefix)
  26. # https://docs.blender.org/manual/en/dev/advanced/extensions/licenses.html
  27. license = [
  28.   "SPDX:GPL-3.0-or-later",
  29. ]
  30. # # Optional: required by some licenses.
  31. # copyright = [
  32. #   "2002-2024 Developer Name",
  33. #   "1998 Company Name",
  34. # ]
  36. # # Optional: list of supported platforms. If omitted, the extension will be available in all operating systems.
  37. # platforms = ["windows-x64", "macos-arm64", "linux-x64"]
  38. # # Other supported platforms: "windows-arm64", "macos-x64"
  40. # # Optional: bundle 3rd party Python modules.
  41. # # https://docs.blender.org/manual/en/dev/advanced/extensions/python_wheels.html
  42. # wheels = [
  43. #   "./wheels/hexdump-3.3-py3-none-any.whl",
  44. #   "./wheels/jsmin-3.0.1-py3-none-any.whl",
  45. # ]
  47. # # Optional: add-ons can list which resources they will require:
  48. # # * files (for access of any filesystem operations)
  49. # # * network (for internet access)
  50. # # * clipboard (to read and/or write the system clipboard)
  51. # # * camera (to capture photos and videos)
  52. # # * microphone (to capture audio)
  53. # #
  54. # # If using network, remember to also check `bpy.app.online_access`
  55. # # https://docs.blender.org/manual/en/dev/advanced/extensions/addons.html#internet-access
  56. # #
  57. # # For each permission it is important to also specify the reason why it is required.
  58. # # Keep this a single short sentence without a period (.) at the end.
  59. # # For longer explanations use the documentation or detail page.
  60. #
  61. # [permissions]
  62. # network = "Need to sync motion-capture data to server"
  63. # files = "Import/export FBX from/to disk"
  64. # clipboard = "Copy and paste bone transforms"
  66. # # Optional: advanced build settings.
  67. # # https://docs.blender.org/manual/en/dev/advanced/extensions/command_line_arguments.html#command-line-args-extension-build
  68. # [build]
  69. # # These are the default build excluded patterns.
  70. # # You only need to edit them if you want different options.
  71. # paths_exclude_pattern = [
  72. #   "__pycache__/",
  73. #   "/.git/",
  74. #   "/*.zip",
  75. # ]

必需值：

blender_version_min:

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

id:

扩展的唯一标识符。

license:

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

maintainer:

扩展的维护者。

name:

扩展的完整名称。

schema_version:

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

tagline:

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

类型:

“插件”、”主题”。

版本:

扩展的版本 - 必须遵循 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, up to 64 characters, 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:

  1. [build]
  2. paths_exclude_pattern = [
  3.   "__pycache__/",
  4.   ".*",
  5.   "*.zip",
  6. ]

保留：

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:

  1. blender --command extension build

详见构建文档。

-—

To validate the manifest without building the package:

  1. blender --command extension validate

You may also validate a package without having to extract it first.

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

详见验证文档。

See also

扩展的命令行参数。

第三方扩展站点

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