Comment créer des extensions

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

  1. Ouvrez le répertoire contenant 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. Utilisez l'outil de ligne de commande Blender pour créer le fichier d’extension .zip.

Comment publier sur la plateforme d’extensions 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 = "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",
# ]

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, jusqu’à 64 caractères - ne peut pas se terminer par un signe de 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:

Les modules complémentaires peuvent répertorier les ressources dont ils ont besoin. Les options disponibles sont files, network, clipboard, camera, microphone (fichiers, réseau, presse-papiers, caméra, microphone). Chaque autorisation doit être suivie d’une explication (une courte phrase unique, jusqu’à 64 caractères, sans ponctuation finale).

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.

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 les Création d’un dépôt d’extensions docs.