Extensions Index

如何创建扩展#

创建扩展只需几个步骤：

  1. Create a directory for your extension and populate it with the add-on code or theme file.

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

  3. 将目录压缩为 .zip 文件。

  4. Install from Disk to test if everything is working well.

  5. `上传 zip 文件 <https://extensions.blender.org/submit/>`__（此步骤需要 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 behaviour 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 = "Test Extension"
tagline = "This is another extension"
maintainer = "Developer name <email@address.com>"
# Supported types: "add-on", "theme"
type = "add-on"

# Optional: add-ons can list which resources they will require:
# * "files" (for access of any filesystem operations)
# * "network" (for internet access)
# * "camera" (to capture photos and videos)
# * "microphone" (to capture audio)
permissions = ["files", "network"]

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

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

blender_version_min = "4.2.0"
# Optional: maximum supported Blender version
# blender_version_max = "5.1.0"

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

必需值：

blender_version_min:

Minimum supported Blender version - use at least 4.2.0.

id:

扩展的唯一标识符。

license:

许可证 列表，使用 SPDX license identifier。

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".

permissions:

Add-ons can list which resources they require. The available options are ["files", "network", "camera", "microphone"].

tags:

标签列表。另见 可用标签的列表。

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.

Note

Extension commands currently require a daily build of Blender with extensions enabled in the preferences.

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 validate docs.

See also

扩展的命令行参数。

第三方扩展站点#

Third party sites that wish to support extensions in Blender can do so in two ways:

  1. Fork the entire Extensions Website as a start point; or

  2. Host a JSON file listing all the packages of your repository.

To generate a valid JSON file you can use the command-line tool:

blender --command extension server-generate --repo-dir=/path/to/packages

This creates a listing from all the packages found in the specified location.

See server-generate docs.

Example of what the JSON is expected to look like:

 {
   "version": "v1",
   "blocklist": [],
   "data": [
    {
       "id": "blender_kitsu",
       "name": "Blender Kitsu",
       "tagline": "Pipeline management for projects collaboration",
       "version": "0.1.5-alpha+f52258de",
       "type": "add-on",
       "archive_size": 856650,
       "archive_hash": "sha256:3d2972a6f6482e3c502273434ca53eec0c5ab3dae628b55c101c95a4bc4e15b2",
       "archive_url": "https://extensions.blender.org/add-ons/blender-kitsu/0.1.0/download/",
       "blender_version_min": "4.2.0",
       "maintainer": "Blender Studio",
       "tags": ["Pipeline"],
       "license": ["SPDX:GPL-3.0-or-later"],
       "website": "http://extensions.blender.org/add-ons/blender-kitsu/",
       "schema_version": "1.0.0"
    }
    ]
}

Just like for the manifest file, the optional fields (e.g., blender_version_max) are either to have a value or should be omitted from the entries.

For the official Extensions Platform, the website value is the page of the extension in the online platform. Even if the manifest points to the project specific website.

Note

Any remote repository is expected to follow the latest API.