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

Создание расширения занимает всего несколько шагов:

  1. Открыть папку, содержащую код аддона или файл темы.

  2. Добавьте файл blender_manifest.toml со всеми необходимыми метаданными (имя, разработчик, …).

  3. Используйте инструмент командной строки Blender, чтобы собрать zip-файл расширения.

Как опубликовать на платформе расширений для Blender:

Расширение будет помещено на проверку и опубликовано после того, как команда модераторов одобрит его.

Файлы расширения

Расширение распространяется в виде архива .zip, содержащего файл манифеста и другие файлы. Ожидаемые файлы зависят от типа расширения.

Расширение аддона

Расширениям-аддонам необходимы как минимум манифест и файл __init__.py, в то время как более сложные расширения-аддоны имеют несколько различных файлов .py или wheel-файлов вместе.

my_extension-0.0.1.zip
├─ __init__.py
├─ blender_manifest.toml
└─ (...)

Расширение темы

Расширению темы необходимы только манифест и файл темы .xml.

my_extension-0.0.1.zip
├─ blender_manifest.toml
└─ theme.xml

Примечание

Расширения могут опционально иметь все свои файлы внутри папки (внутри архива). Это обычное поведение при сохранении репозитория в виде ZIP из систем контроля версий.

Манифест

Манифест — это файл, содержащий все метаданные, необходимые для обработки расширения. Пример ниже является хорошей отправной точкой для 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_версия_мин:

Минимальная поддерживаемая версия Blender - используйте как минимум 4.2.0.

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

Уникальный идентификатор расширения.

лицензия:

Список лицензий, используйте идентификатор лицензии SPDX.

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

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

имя:

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

schema_version:

Внутренняя версия формата файла — используйте 1.0.0.

слоган:

Краткое описание в одну строку, до 64 символов, не может заканчиваться знаком препинания.

тип:

«add-on», «theme».

версия:

Версия расширения - должна соответствовать семантическому версионированию.

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

blender_version_max:

Версия Blender, которую расширение не поддерживает, более ранние версии поддерживаются.

веб-сайт:

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

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

Некоторые лицензии требуют указания авторских прав, авторские права должны быть в формате «Год Имя» или «Год-Год Имя».

ярлыки:

Список тегов. См. список доступных тегов.

platforms:

Список поддерживаемых платформ. Если не указано, расширение будет доступно во всех операционных системах. Доступные варианты: [«windows-x64», «windows-arm64», «macos-x64», «macos-arm64», «linux-x64»]

wheels:

Список относительных путей к файлам Python wheels.

допуски:

Аддоны могут перечислять, какие ресурсы им требуются. Доступные варианты: files, network, clipboard, camera, microphone. За каждым разрешением должно следовать объяснение (короткое предложение в одно предложение, до 64 символов, без знаков препинания в конце).

Optional values for «build»:

Эти значения используются только подкомандой build.

paths:

Список путей к файлам относительно манифеста, которые нужно включить при сборке пакета.

paths_exclude_pattern:

Список шаблонов путей к файлам, которые нужно исключить при сборке пакета.

Список паттернов для иключения файлов, совместимый с форматом .gitignore.

Обратите внимание, что установка этого значения не поддерживается, если также задано значение paths.

Если таблица [build] не объявлена, используется следующее значение по умолчанию:

[build]
paths_exclude_pattern = [
  "__pycache__/",
  ".*",
  "*.zip",
]
Reserved:

Эти значения не должны быть объявлены в TOML и зарезервированы для внутреннего использования.

  • [build.generated]

Примечание

Все значения, присутствующие в файле манифеста, должны быть заполнены (т.е. не могут быть пустыми, ни текстом "", ни списком []).

Если вы не хотите устанавливать одно из необязательных значений, просто исключите его из манифеста.

Командная-строка

Расширения можно собирать, проверять и устанавливать с помощью командной строки.

Чтобы собрать пакет, определенный в текущем каталоге, используйте следующие команды:

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.

См. также

Аргументы командной строки расширений.

Third party extension sites

If you want to host the extensions yourself, see the Creating an Extensions Repository docs.