Extensions Index

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@address.com>"
# Supported types: "add-on", "theme"
type = "add-on"

# 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)
# permissions = ["files", "network"]

# Optional link to documentation, support, source files, etc
# website = "http://extensions.blender.org/add-ons/my-example-package/"

# Optional list defined by Blender and server, see:
# https://docs.blender.org/manual/en/dev/extensions/tags.html
tags = ["Animation", "Sequencer"]

blender_version_min = "4.2.0"
# Optional: maximum supported Blender version
# blender_version_max = "5.1.0"

# License conforming to https://spdx.org/licenses/ (use "SPDX: prefix)
# https://docs.blender.org/manual/en/dev/extensions/licenses.html
license = [
  "SPDX:GPL-2.0-or-later",
]
# Optional: required by some licenses.
# copyright = [
#   "2002-2024 Developer Name",
#   "1998 Company Name",
# ]

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 maximale de Blender pouvant exécuter cela.

website:

Site Internet pour l’extension.

copyright:

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

permissions:

Les modules complémentaires peuvent répertorier les ressources dont ils ont besoin. Les options disponibles sont [“files”, “network”].

tags:

Liste des balises. Voir la liste des balises disponibles.

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#

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.0/download/",
       "blender_version_min": "4.2.0",
       "maintainer": "Blender Studio",
       "tags": ["Pipeline"],
       "license": ["SPDX:GPL-3.0-or-later"],
       "website": "http://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.