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:

These values must not be declared in a TOML and are reserved for internal use.

  • [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.

Sites d’extension tiers

Les sites tiers qui souhaitent prendre en charge les extensions dans Blender peuvent le faire de deux manières :

  1. Forkez l’intégralité du Extensions Website comme point de départ; ou

  2. Héberger un fichier JSON listant tous les packages de votre dépôt.

Pour générer un fichier JSON valide, vous pouvez utiliser l’outil en ligne de commande :

blender --command extension server-generate --repo-dir=/path/to/packages

Cela crée une liste de tous les packages trouvés à l’emplacement spécifié.

Voir les documents server-generate.

Exemple de ce à quoi devrait ressembler le JSON :

 {
   "version": "v1",
   "blocklist": [],
   "data": [
    {
       "id": "blender_kitsu",
       "name": "Blender Kitsu",
       "tagline": "Pipeline management for projects collaboration",
       "version": "0.1.5-alpha+f52258de",
       "type": "add-on",
       "archive_size": 856650,
       "archive_hash": "sha256:3d2972a6f6482e3c502273434ca53eec0c5ab3dae628b55c101c95a4bc4e15b2",
       "archive_url": "https://extensions.blender.org/add-ons/blender-kitsu/0.1.5-alpha+f52258de/download/",
       "blender_version_min": "4.2.0",
       "maintainer": "Blender Studio",
       "tags": ["Pipeline"],
       "license": ["SPDX:GPL-3.0-or-later"],
       "website": "https://extensions.blender.org/add-ons/blender-kitsu/",
       "schema_version": "1.0.0"
    }
    ]
}

Tout comme pour le fichier manifeste, les champs facultatifs (par exemple, blender_version_max) doivent soit avoir une valeur, soit être omis des entrées.

Pour la plateforme d’extensions officielle, la valeur website est la page de l’extension dans la plateforme en ligne. Même si le manifeste pointe vers le site Web spécifique au projet.

Note

Tout référentiel distant doit suivre la dernière API.