Как создавать расширения

Creating an extension takes only a few steps:

  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. Compress the directory as a .zip file.

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

  5. Upload the zip file (this step requires 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

Примечание

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.

Манифест

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 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 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-2.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: build settings.
# https://docs.blender.org/manual/en/dev/advanced/extensions/command_line_arguments.html#command-line-args-extension-build
# [build]
# paths_exclude_pattern = [
#   "__pycache__/",
#   "/.git/",
#   "/*.zip",
# ]

Required values:

blender_версия_мин:

Minimum supported Blender version - use at least 4.2.0.

идентификатор:

Unique identifier for the extension.

лицензия:

List of licenses, use SPDX license identifier.

сопровождающий:

Сопровождающий расширения.

имя:

Полное имя расширения.

schema_version:

Internal version of the file format - use 1.0.0.

слоган:

One-line short description - cannot end with punctuation.

тип:

«add-on», «theme».

версия:

Version of the extension - must follow semantic versioning.

Необязательные значения:

blender_version_max:

Blender version that the extension does not support, earlier versions are supported.

веб-сайт:

Веб-сайт для расширения.

авторские права:

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

ярлыки:

List of tags. See the list of available tags.

platforms:

List of supported platforms. If omitted, the extension will be available in all operating systems. The available options are [«windows-x64», «windows-arm64», «macos-x64», «macos-arm64», «linux-x64»]

wheels:

List of relative file-paths Python Wheels.

допуски:

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 pontuation (.)).

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",
]

Примечание

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.

Примечание

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

See build docs.

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.

Third party extension sites

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.5-alpha+f52258de/download/",
       "blender_version_min": "4.2.0",
       "maintainer": "Blender Studio",
       "tags": ["Pipeline"],
       "license": ["SPDX:GPL-3.0-or-later"],
       "website": "https://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.

Примечание

Any remote repository is expected to follow the latest API.