Com crear extensions¶

La creació d’una extensió només requereix uns pocs passos:

Obriu el directori que contingui el complement o el document de tema.
Afegiu un document blender_manifest.toml amb totes les metadades necessàries (name, maintainer, ...).
Empreu l'Eina de línia d’ordres de Blender per confegir el document d’extensió .zip.

Com publicar a la Plataforma d’extensions de Blender:

Instal·leu des del disc per comprovar si tot rutlla bé.
Carregueu el document .zip (aquest pas requereix l’ID del Blender).

L’extensió quedarà pendent de revisió i es publicarà una vegada l’equip de moderadores l’aprovi.

Documents d’extensió¶

Una extensió es comparteix com un document .zip que conté un document manifest i altres documents. Els documents que s’esperen depenen del tipus d’extensió.

Extensió del complement¶

Els Complements requereixen almenys el manifest i un document __init__.py, mentre que els complements més complexos apleguen uns quants documents .py o wheels.

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

Extensió de tema¶

A una extensió de tema només li cal el manifest i el document de tema .xml.

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

Nota

Les extensions poden opcionalment tenir tots els seus documents dins d’una carpeta (dins de l’arxiu). Aquest és un comportament habitual quan es desa un repositori com a ZIP des de plataformes de control de versions.

Manifest¶

Un manifest és un document amb totes les metadades necessàries per a processar una extensió. Aquest exemple és un bon punt de partida per al blender_manifest.toml i que hauria d’estar dins del .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"
# 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",
# ]

Valors requerits:

blender_version_min:: Versió mínima amb suport de Blender - empreu almenys 4.2.0.
id:: Identificador únic de l’extensió.
license:: Llista de llicències, utilitzeu identificador de llicència SPDX.
maintainer:: Mantenidor de l’extensió.
name:: Nom complet de l’extensió.
schema_version:: Versió interna del format de document - useu 1.0.0.
tagline:: Breu descripció d’una línia, fins a 64 caràcters - no pot acabar amb cap puntuació.
type:: «complement», «tema».
version:: Versió de l’extensió - ha de seguir el versionat semàntic.

Valors opcionals:

blender_version_max:: Versió de Blender que l’extensió no admet, admet versions anteriors.
website:: Lloc web de l’extensió.
copyright:: Algunes llicències requereixen un copyright. Els copyrights han de ser «Any nom» o bé «Any-any nom».
tags:: Llista d’etiquetes. Vegeu la llista d’etiquetes disponibles.
platforms:: Llista de plataformes compatibles. Si no es diu res, l’extensió estarà disponible en tots els sistemes operatius. Les opcions disponibles són [«windows-x64», «windows-arm64», «macos-x64», «macos-arm64», «linux-x64»]
wheels:: Llista de rutes relatives de documents Python Wheels.
permissions:: Els complements poden llistar els recursos que requereixen. Les opcions disponibles són documents, xarxa, porta-retalls, càmera, micròfon. Cada permís hauria d’estar seguit d’una explicació (una frase molt curta, màxim 64 caràcters, sense puntuació final).

Valors opcionals per «compilació»:

Aquests valors només els fa servir la subordre build.

paths:

Una llista de rutes de document relatives al manifest que s’han d’incloure en compilar el paquet.

paths_exclude_pattern:

Una llista de patrons de ruta de document que s’han d’excloure quan es compila el paquet.

El conlligat de patrons és compatible amb gitignore.

Tingueu present que no es pot definir aquest valor quan també es declaren paths.

Si la taula [build] no està declarada, s’utilitza la següent predeterminada:

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

Reservat:

Aquests valors no s’han de declarar en un TOML i es reserven per a ús intern.

[build.generated]

Nota

S’han d’omplir tots els valors presents al document manifest (p. ex. no pot quedar buit, ni amb el text "", ni amb la llista []).

Si no voleu definir un dels valors opcionals, simplement excloeu-lo del tot del manifest.

Línia d’ordres¶

Les extensions es poden crear, validar i instal·lar mitjançant la línia d’ordres.

Compilar¶

Per compilar el paquet definit al directori actual, utilitzeu les ordres següents:

blender --command extension build

Vegeu els documents de compilació.

Validar¶

Per validar el manifest sense compilar el paquet:

blender --command extension validate

També podeu validar un paquet sense haver-lo d’extreure abans.

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

Consulteu els documents de validate.

Vegeu també

Arguments de línia d’ordres d’extensions.

Publicar¶

Per automatitzar la publicació d’actualitzacions a la Plataforma de complements, doneu un cop d’ull a Documentació de CI/CD.

Webs d’extensions de terceres¶

Si voleu allotjar les extensions vosaltres mateixes, consulteu els documents Creació d’un repositori d’extensions.