Comment créer des extensions#

La création d’une extension ne prend que quelques étapes :

  1. Créez un répertoire pour votre extension et remplissez-le avec le code complémentaire ou le fichier de thème.

  2. Ajoutez un fichier blender_manifest.toml avec toutes les méta-données requises (name, maintainer, ...).

  3. Compressez le répertoire sous forme de fichier .zip.

  4. Installer à partir du disque pour tester si tout fonctionne bien.

  5. Télécharger le fichier zip (cette étape nécessite l’ID Blender).

L’extension sera conservée pour examen et publiée une fois que l’équipe de modération l’aura approuvée.

Extension files#

Une extension est partagée sous forme d’archive .zip contenant un fichier manifeste et d’autres fichiers. Les fichiers attendus dépendent du type d’extension.

Add-on extension#

Les Add-ons (modules complémentaires) nécessitent au moins le manifeste et un fichier __init__.py, tandis que les modules complémentaires plus complexes comportent plusieurs fichiers ou wheels .py différents.

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

Theme extension#

Une extension de thème n’a besoin que du manifeste et du fichier de thème .xml.

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

Note

Les extensions peuvent éventuellement avoir tous leurs fichiers dans un dossier (à l’intérieur de l’archive). Il s’agit d’un comportement courant lors de l’enregistrement d’un référentiel au format ZIP à partir de plates-formes de contrôle de version.

Manifest#

Un manifeste est un fichier contenant toutes les métadonnées nécessaires au traitement d’une extension. Cet exemple est un bon point de départ pour le fichier blender_manifest.toml qui devrait se trouver à l’intérieur du .zip.Un manifeste est un fichier contenant toutes les métadonnées nécessaires au traitement d’une extension. Cet exemple est un bon point de départ pour le fichier blender_manifest.toml qui devrait se trouver à l’intérieur du .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",
# ]

Les valeurs requises :

blender_version_min:

Version minimale de Blender prise en charge - utilisez au moins la version 4.2.0.

id:

Identifiant unique de l’extension.

licence:

Liste des licenses, utilise SPDX license identifier.

maintainer:

Responsable de l’extension.

name:

Nom complet de l’extension.

schema_version:

Version interne du format de fichier - utilise 1.0.0.

tagline:

Brève description d’une ligne - ne peut pas se terminer par une ponctuation.

Type:

“add-on”, “theme”.

version:

Version de l’extension - doit suivre le versionnement sémantique.

Valeurs facultatives :

blender_version_max:

Version de Blender que l’extension ne prend pas en charge, les versions antérieures sont prises en charge.

website:

Site Internet pour l’extension.

copyright:

Certaines licences nécessitent un copyright, les copyrights doivent être “Year Name” ou “Year-Year Name”.

tags:

Liste des balises (tags). Voir la liste des balises disponibles.

platforms:

Liste des plateformes prises en charge. En cas d’omission, l’extension sera disponible dans tous les systèmes d’exploitation. Les options disponibles sont [“windows-x64”, “windows-arm64”, “macos-x64”, “macos-arm64”, “linux-x64”]

wheels:

Liste des chemins de fichiers relatifs Python Wheels.

permissions:

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

Valeurs optionnelles pour “build” :

Ces valeurs ne sont utilisées que par la sous-commande build.

paths:

Une liste de chemins de fichiers relatifs au manifeste à inclure lors de la création du package.

Select Pattern:

Une liste de chemins de fichiers relatifs au manifeste à inclure lors de la création du package.

La correspondance de modèles est compatible avec gitignore.

Notez que la définition de cette valeur n’est pas prise en charge lorsque les paths (chemins) sont également déclarés.

Si la table [build] n’est pas déclarée, la valeur par défaut suivante est utilisée :

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

Ces valeurs ne doivent pas être déclarées dans un TOML et sont réservées à un usage interne.

  • [build.generated]

Note

Toutes les valeurs présentes dans le fichier manifeste doivent être remplies (c’est-à-dire qu’elles ne peuvent pas être vides, ni texte '', ni liste []).

Si vous ne souhaitez pas définir l’une des valeurs facultatives, excluez-la simplement du manifeste.

Ligne de commande#

Les extensions peuvent être créées, validées et installées via la ligne de commande.

Note

Les commandes d’extension nécessitent actuellement une construction quotidienne de Blender (daily build) avec les extensions activées dans les préférences.

Pour construire le package défini dans le répertoire courant, utilisez les commandes suivantes :

blender --command extension build

Voir build pour plus de détails.

—

Pour valider le manifeste sans construire le package :

blender --command extension validate

Vous pouvez également valider un package sans avoir à l’extraire au préalable.

blender --command extension validate add-on-package.zip

Voir validate pour plus de détails.

Voir aussi

Arguments de la ligne de commande des extensions.

Sites d’extension tiers#

Si vous souhaitez héberger les extensions vous-même, consultez la documentation «  « Création d’un dépôt d’extensions.