Extensions Index

Add-ons – Додатки#

Важливо

This page is part of Extensions, and is only available experimentally in daily builds of Blender 4.2. Please enable «Extensions» on the Experimental Preferences to help testing it.

For the deprecated information about individual add-ons bundled with Blender visit Add-ons.

Add-ons let you extend Blender’s functionality using Python. Most of the time you can get add-ons as part of the Extensions system.

Порада

Якщо Додаток не активується при увімкненні, то перевірте вікно консолі – Console window на будь-які помилки, що могли трапитися.

User-Defined Add-on Path – Визначений Користувачем Шлях до Додатків#

Ви можете також створити особисту директорію, що містить нові додатки, та сконфігурувати ваш шлях файлу в секції File Paths – «Шляхи Файлів» в уподобаннях Preferences. Для створення особистої директорії скриптів:

  1. Створіть порожній каталог у бажаній вами локації (наприклад, my_scripts).

  2. Додайте у ньому, my_scripts, підкаталог з іменем addons (це повинно бути саме це ім’я, щоб Blender розпізнавав його).

  3. Відкрийте секцію File Paths – «Шляхи Файлів» в уподобаннях Preferences.

  4. Задайте для устави Scripts – «Скрипти» шлях файлу, що вказує на вашу директорію зі скриптами (наприклад, my_scripts).

  5. Збережіть уподобання та перезапустіть Blender, щоб він розпізнав нову локацію для додатків.

Тепер, коли ви інсталюєте додатки, ви можете вибрати Target Path – «Цільовий Шлях» при інсталюванні сторонніх скриптів. Blender буде копіювати ново інстальовані додатки в директорію, вибрану у ваших уподобаннях Preferences.

Legacy vs Extension Add-ons#

With the introduction of Extensions in Blender 4.2, the old way of creating add-ons is considered deprecated. While the changes are rather small they impact existing add-ons.

In order to allow a smooth transition process, the so-called legacy add-ons will continue to be supported by Blender. They can be installed via Install legacy Add-on button in the User Preferences.

All add-on maintainers are urged to convert the add-ons they want to share, so they are future proof and can support features like updating from the extensions platform.

Converting a Legacy Add-on into an Extension#

  1. Create a manifest file.

  2. Remove the bl_info information (this is now in the manifest).

  3. Replace all references to the module name to __package__.

  4. Make all module imports to use relative import.

  5. Use wheels to pack your external Python dependencies.

  6. Remember to test it throughly.

Примітка

For testing it is import to install the extension from disk and check if everything is working well. This will get you as close to the final experience as possible.

Extensions and Namespace#

The legacy add-ons would use their module name to access the preferences. This could lead to a name clash when extensions with the same name (from different repositories) would be installed. To prevent this conflict, the repository name is now part of the namespace.

For example, now instead of kitsu the module name would be bl_ext.{repository_module_name}.kitsu instead.

This has a few implications for preferences and module imports.

User Preferences and __package__#

Add-ons can define their own preferences which use the package name as an identifier. This can be accessed using __package__.

This was already supported in the legacy add-ons, but not reinforced. As such this can break backward compatibility.

Before:

class KitsuPreferences(bpy.types.AddonPreferences):
    bl_idname = "kitsu"
    # ... snip ...

# Access with:
addon_prefs = bpy.context.preferences.addons["kitsu"]

Now:

class KitsuPreferences(bpy.types.AddonPreferences):
    bl_idname = __package__
    # ... snip ...

# Access with:
addon_prefs = bpy.context.preferences.addons[__package__]
Sub-packages

An add-on that defines sub-packages (sub-directories with their own __init__.py file) that needs to use this identifier will have to import the top-level package using a relative import.

from .. import __package__ as base_package

Then base_package can be used instead of __package__. The .. imports relative to the packages parent, sub-sub-packages must use ... and so on.

Примітка

  • The value of __package__ will vary between systems so it should never be replaced with a literal string.

  • Extensions must not manipulate the value of __package__ as this may cause unexpected behavior or errors.

Relative Imports#

before:

from kitsu import utils

now:

from . import utils

Importing packages within the add-on module need to use relative paths. This is a standard Python feature and only applicable for add-ons that have multiple folders.

This was already supported in the legacy add-ons, but not reinforced. As such this can break backward compatibility.

3rd Party Python Modules#

Extensions must be self-contained, and as such must come with all its dependencies.

Currently there is no general solution for this although support is planned using Python wheels.

Some options are listed here:

Bundle with Vendorize

This can be used as a way to bundle a pure Python dependencies as a sub-module.

This has the advantage of avoiding version conflicts although it requires some work to setup each package.

Import Wheel’s Directly

Wheels themselves can lead to version conflicts, since different add-ons could require different versions of the same library.

It is possible to load wheels that doesn’t permanently affect sys.modules or sys.path. This way an add-on can load its own version of an external library from its bundled wheel file.

See Flamenco add-on for an implementation example.

Попередження

While this method works in many cases, it can also fail for various reasons:

  • Access to files bundled with the module will fail.

  • Imports made by the module at runtime referencing it’s own modules will fail.

  • Mis-match between the wheel and the module name aren’t supported.

  • Wheels that depend on other wheels currently aren’t supported.

  • Different system-architectures aren’t supported.