Add-ons (modules supplémentaires)#

Les modules complémentaires (Add-ons) vous permettent d’étendre les fonctionnalités de Blender en utilisant Python. La plupart du temps, vous pouvez obtenir des modules complémentaires dans le cadre du système Extensions.

Astuce

Si le module complémentaire n’est pas opérationnel après activation, vérifiez la fenêtre Console quelle est l’erreur qui a pu se produire.

Chemin des modules complémentaires défini par l’utilisateur#

Vous pouvez créer un dossier personnel pour les nouveaux modules complémentaires et configurer le chemin de vos fichiers dans la section File Paths de Preferences. Pour créer un dossier personnel pour vos scripts :

  1. Créez un dossier vide à l’emplacement de votre choix (ex. my_scripts).

  2. Ajoutez un sous-dossier à my_scripts nommé addons (il doit avoir ce nom pour que Blender le reconnaisse).

  3. Ouvrez la section File Paths de Preferences.

  4. Définissez le chemin de fichier de Scripts pour pointer sur votre dossier de scripts (par ex. my_scripts).

  5. Enregistrez les préférences et redémarrez Blender pour qu’il reconnaisse l’emplacement des nouveaux add-ons.

Désormais, quand vous installez des modules complémentaires, vous pouvez sélectionner Target Path à l’installation de scripts de tierce partie. Blender va copier les modules complémentaires nouvellement installés dans le dossier sélectionné dans vos Preferences.

Accès Internet#

Si le module complémentaire doit utiliser Internet, il doit vérifier la propriété (en lecture seule) bpy.app.online_access. Cette option est contrôlée par les Préférences, qui peuvent être remplacées via la ligne de commande (--offline-mode / --online-mode).

Pour de meilleurs messages d’erreur, vous pouvez également vérifier bpy.app.online_access_overriden, pour déterminer si les utilisateurs peuvent activer ou non Allow Online Access (Autoriser l’accès en ligne) dans les préférences.

Blender lui-même ne bloque pas l’accès à Internet en fonction de ce paramètre. C’est aux modules complémentaires de le respecter.

Dépendances des paquets#

Pour que les modules complémentaires soient regroupés en tant qu’extensions, ils doivent être autonomes. Cela signifie qu’ils doivent être fournis avec toutes leurs dépendances. En particulier les modules Python tiers.

Il existe quelques options pour cela:

Bundle with Python Wheels.

C’est la méthode recommandée pour regrouper les dépendances.

Bundle other add-ons together.

Recommandé si un module complémentaire dépend d’un autre module complémentaire.

Assurez-vous que le module complémentaire individuel et combiné vérifie les types déjà enregistrés (opérateurs, panneaux,…). Cela évite la duplication des opérateurs et des panneaux sur l’interface si les modules complémentaires sont installés comme un paquet et individuellement.

Offre groupée avec Vendorize

Peut être utilisé comme moyen de regrouper des dépendances Python pures en tant que sous-module.

Cela présente l’avantage d’éviter les conflits de versions même si cela nécessite un certain travail pour configurer chaque package.

Modules complémentaires hérités vs extensions#

Avec l’introduction des extensions dans Blender 4.2, l’ancienne méthode de création de modules complémentaires est considérée comme obsolète. Bien que les changements soient plutôt mineurs, ils affectent les modules complémentaires existants.

Afin de permettre un processus de transition en douceur, les modules complémentaires dits hérités continueront à être pris en charge par Blender. Ils peuvent être installés via le bouton Install legacy Add-on dans les préférences utilisateur.

Tous les responsables de modules complémentaires sont invités à convertir les modules complémentaires qu’ils souhaitent partager, afin qu’ils résistent à l’épreuve du temps et puissent prendre en charge des fonctionnalités telles que la mise à jour à partir de la plate-forme d’extensions.

Conversion, en extension, d’un module complémentaire hérité#

  1. Créer un fichier manifeste.

  2. Supprimer les informations bl_info (elles se trouvent maintenant dans le manifeste).

  3. Remplacer toutes les références au nom du module par __package__.

  4. Effectuer toutes les importations de modules pour utiliser l’importation relative.

  5. Utiliser des wheels pour regrouper vos dépendances Python externes.

  6. N’oubliez pas de le tester minutieusement.

Note

Pour tester, il est important d’installer l’extension à partir du disque et de vérifier si tout fonctionne bien. Cela vous rapprochera le plus possible de l’expérience finale.

Extensions et Namespace (espace de nom)#

Si les modules complémentaires existants utilisaient leur nom de module pour accéder aux préférences cela pourrait conduire à un conflit de noms lorsque des extensions portant le même nom (provenant de référentiels différents) seraient installées. Pour éviter ce conflit, le nom du référentiel fait désormais partie de l’espace de noms.

Par exemple, désormais, au lieu de kitsu, le nom du module serait bl_ext.{repository_module_name}.kitsu.

Cela a quelques conséquences pour les préférences et les importations de modules.

Préférences utilisateur et __package__#

Les modules complémentaires peuvent définir leurs propres préférences et y accéder en utilisant le nom complet du module. Cela se fait en utilisant __package__.

Ceci était déjà pris en charge dans les modules complémentaires existants, mais n’est pas renforcé. En tant que tel, cela peut rompre la compatibilité ascendante.

Avant :

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

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

Maintenant :

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

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

Un module complémentaire qui définit des sous-packages (sous-répertoires avec leur propre fichier __init__.py) qui doit utiliser cet identifiant devra importer le package de niveau supérieur à l’aide d’une importation relative.

from .. import __package__ as base_package

Ensuite, base_package` peut être utilisé à la place de `__package__`. Les .. pour les importations relatives aux packages parents, les sous-sous-packages doivent utiliser ... et ainsi de suite.

Note

  • La valeur de __package__ varie selon les systèmes et ne doit donc jamais être remplacée par une chaîne littérale.

  • Les extensions ne doivent pas manipuler la valeur de __package__ car cela pourrait provoquer un comportement inattendu ou des erreurs.

Importations relatives#

avant:

from kitsu import utils

maintenant:

from . import utils

L’importation de packages dans le module complémentaire doit utiliser des chemins relatifs. Il s’agit d’une fonctionnalité Python standard et applicable uniquement aux modules complémentaires comportant plusieurs dossiers.

Ceci était déjà pris en charge dans les modules complémentaires existants, mais n’est pas renforcé. En tant que tel, cela peut rompre la compatibilité ascendante.