Как создавать расширения#
Создание расширения занимает всего несколько шагов:
Открыть папку, содержащую код аддона или файл темы.
Добавьте файл blender_manifest.toml со всеми необходимыми метаданными
(имя, разработчик, …)
.Используйте инструмент командной строки Blender, чтобы собрать zip-файл расширения.
Как опубликовать на платформе расширений для Blender:
Выполните установку с диска, чтобы проверить, всё ли работает хорошо.
Загрузите файл .zip (для этого шага требуется Blender ID).
Расширение будет помещено на проверку и опубликовано после того, как команда модераторов одобрит его.
Файлы расширения#
Расширение распространяется в виде архива .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
.- слоган:
One-line short description - cannot end with punctuation.
- тип:
«add-on», «theme».
- версия:
Версия расширения - должна соответствовать семантическому версионированию.
Необязательные значения:
- blender_version_max:
Версия Blender, которую расширение не поддерживает, более ранние версии поддерживаются.
- веб-сайт:
Веб-сайт для расширения.
- авторские права:
Некоторые лицензии требуют указания авторских прав, авторские права должны быть в формате «Год Имя» или «Год-Год Имя».
- ярлыки:
Список тегов. См. список доступных тегов.
- platforms:
Список поддерживаемых платформ. Если не указано, расширение будет доступно во всех операционных системах. Доступные варианты: [«windows-x64», «windows-arm64», «macos-x64», «macos-arm64», «linux-x64»]
- wheels:
Список относительных путей к файлам 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 punctuation (
.
)).
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.