Tu primera extensión de Blender: de blender_manifest.toml al panel
Blender 5.3 ya está en la calle y la plataforma de extensiones acepta ahora también bibliotecas de assets. Lo que se sigue pidiendo, sin embargo, es lo de siempre: un add-on propio con panel, atajo y .zip instalable. Aquí está completo, paso a paso.
Qué es una extensión y qué cambió con Blender 5.3
Desde Blender 4.2, un add-on se distribuye como extensión: una carpeta con un archivo blender_manifest.toml en la raíz y el código Python dentro. Es el mismo paquete comprimido que se sube a extensions.blender.org, y la diferencia con los add-ons antiguos es que el manifest reemplaza al viejo bl_info como ficha técnica del add-on.
Los add-ons con bl_info siguen instalándose desde disco y no hay fecha anunciada para retirarlos. La recomendación oficial es convertirlos, porque el manifest es lo que lee la plataforma para validar, listar y actualizar el paquete.
Blender 5.3, publicado el 10 de noviembre de 2026, añadió un detalle que se pasó por alto en la cobertura del lanzamiento: la plataforma de extensiones ya no es solo para add-ons y temas, también admite bibliotecas de assets. El formato de paquete se consolida, y conviene aprenderlo una vez bien.
Lo que no cambia: tus operadores y paneles siguen siendo Python con bpy, y el intérprete de Blender 5.x es Python 3.13. Puedes confirmar la versión exacta con sys.version desde la consola de Python del programa.
Paso 1: el blender_manifest.toml
El manifest es un archivo de texto en la raíz del paquete. No tiene lógica: es la declaración de qué es la extensión, para qué versión de Blender funciona y qué permisos necesita. El validador lo lee antes que el código, y si algo falta, el paquete no entra.
Este es el manifest de un add-on real y pequeño, que renombra objetos seleccionados con un prefijo y numeración:
schema_version = "1.0.0"
id = "batch_rename"
version = "1.0.0"
name = "Batch Rename"
tagline = "Rename selected objects with a prefix and numbering"
maintainer = "Tu Nombre <tu@correo.com>"
type = "add-on"
license = ["SPDX:GPL-3.0-or-later"]
blender_version_min = "4.2.0"
tags = ["Object"]| Campo | Para qué sirve |
|---|---|
schema_version | Versión del formato del manifest. Hoy es 1.0.0. |
id | Identificador único en minúsculas. Es la carpeta de la extensión y la clave con la que Blender guarda sus preferencias. |
version | Versión del add-on. Subirla es lo que dispara una actualización en la plataforma. |
name y tagline | Nombre visible y una línea de descripción. El tagline se corta, así que va directo al grano. |
maintainer | Quién responde por el paquete, con correo entre paréntesis angulares. |
type | add-on o theme. |
license | Licencia en formato SPDX. Para publicar en la plataforma tiene que ser compatible con GPL. |
blender_version_min | Versión mínima de Blender. El mínimo útil es 4.2.0, cuando nació el formato. |
tags | Categorías de la tienda, tomadas de una lista cerrada. |
Los permisos y por qué el validador los mira
Si la extensión abre conexiones de red, escribe fuera de sus carpetas o usa el portapapeles, tiene que declararlo en una lista permissions dentro del manifest. No es burocracia: la revisión de la plataforma rechaza paquetes que hacen cosas no declaradas, y el usuario ve el aviso antes de instalar. Un add-on que descarga modelos sin pedir red es exactamente el tipo de cosa que no pasa el filtro.
Paso 2: el operador que hace el trabajo
El operador es la acción. Tiene un identificador interno, una etiqueta visible y un conjunto de opciones; la más importante es UNDO, que registra el cambio para que Ctrl+Z lo deshaga como cualquier otra acción nativa.
import bpy
class OBJECT_OT_batch_rename(bpy.types.Operator):
bl_idname = "object.batch_rename"
bl_label = "Renombrar seleccionados"
bl_options = {"REGISTER", "UNDO"}
def execute(self, context):
prefs = context.preferences.addons[__package__].preferences
seleccion = sorted(context.selected_objects, key=lambda o: o.name)
for i, obj in enumerate(seleccion, start=prefs.start_index):
obj.name = "tmp_rename_%04d" % i
for i, obj in enumerate(seleccion, start=prefs.start_index):
obj.name = "%s%0*d" % (prefs.prefix, prefs.padding, i)
return {"FINISHED"}Dos pasadas, no una. La primera deja todos los objetos con un nombre temporal que no puede chocar con nada; la segunda aplica el nombre final. Es la forma barata de esquivar el problema de la sección siguiente.
Por qué el sufijo .001 te va a morder
Blender no permite dos objetos con el mismo nombre: si asignas uno que ya existe, añade .001 al final. En un renombrado en serie eso se convierte en una cadena de errores, porque el objeto que renombras primero puede ocupar el nombre que le toca a otro después. El resultado es una escena con Prop_01, Prop_01.001 y Prop_02 mezclados.
La solución tiene dos partes: renombrar en dos pasadas, como arriba, y ordenar la selección por algo estable antes de numerar. context.selected_objects no garantiza orden, así que ordenar por nombre evita que el resultado dependa del orden en que hiciste clic.
Paso 3: el panel en la barra lateral
El panel es solo interfaz. Se declara con el espacio y la región donde vive; en este caso la barra lateral del visor 3D, que el usuario abre con la tecla N. La propiedad bl_category es la que crea la pestaña nueva.
class VIEW3D_PT_batch_rename(bpy.types.Panel):
bl_space_type = "VIEW_3D"
bl_region_type = "UI"
bl_category = "Batch"
bl_label = "Renombrar en serie"
def draw(self, context):
prefs = context.preferences.addons[__package__].preferences
layout = self.layout
layout.prop(prefs, "prefix")
layout.prop(prefs, "start_index")
layout.prop(prefs, "padding")
layout.operator("object.batch_rename", icon="SORTALPHA")layout.prop enlaza un campo de las preferencias directamente al panel, sin código intermedio: lo que el usuario cambia ahí se guarda solo. Y si necesitas mostrar un texto largo que no cabe en una línea, Blender 5.3 trae layout.label_multiline(), que envuelve el texto en vez de cortarlo con puntos suspensivos.
Paso 4: las preferencias del add-on
Las preferencias son el lugar correcto para los ajustes persistentes. Van en una clase aparte, y la clave es que bl_idname apunte al paquete, no a un nombre inventado: es lo que permite encontrarlas después desde el operador.
class BatchRenamePreferences(bpy.types.AddonPreferences):
bl_idname = __package__
prefix: bpy.props.StringProperty(name="Prefijo", default="Prop_")
start_index: bpy.props.IntProperty(name="Desde", default=1, min=0)
padding: bpy.props.IntProperty(name="Dígitos", default=2, min=1, max=6)Desde cualquier parte del add-on se llega a ellas con context.preferences.addons[__package__].preferences. Ese acceso es la razón por la que conviene no duplicar valores en variables globales: la preferencia es la única fuente de verdad.
Paso 5: el atajo de teclado
El atajo se registra en el keymap del add-on, dentro de register(). Hay un detalle que se olvida casi siempre: si no guardas la referencia al elemento creado, no puedes borrarlo al desactivar la extensión y el atajo queda fantasma, apuntando a un operador que ya no existe.
addon_keymaps = []
def register():
bpy.utils.register_class(OBJECT_OT_batch_rename)
bpy.utils.register_class(VIEW3D_PT_batch_rename)
bpy.utils.register_class(BatchRenamePreferences)
kc = bpy.context.window_manager.keyconfigs.addon
if kc:
km = kc.keymaps.new(name="Object Mode", space_type="EMPTY")
kmi = km.keymap_items.new(
"object.batch_rename", "R", "PRESS", ctrl=True, shift=True
)
addon_keymaps.append((km, kmi))
def unregister():
for km, kmi in addon_keymaps:
km.keymap_items.remove(kmi)
addon_keymaps.clear()
bpy.utils.unregister_class(BatchRenamePreferences)
bpy.utils.unregister_class(VIEW3D_PT_batch_rename)
bpy.utils.unregister_class(OBJECT_OT_batch_rename)El registro de clases va en un orden y el borrado en el inverso. Si registras las clases en bucle, recórrelas con reversed() al desregistrar.
Paso 6: compilar el .zip y probarlo como usuario
El paquete se construye con la línea de comandos, apuntando al directorio que contiene el manifest:
blender --command extension build --source-dir batch_rename --output-dir distEl resultado es un .zip con el manifest, el código y lo que hayas metido en la carpeta. Para probarlo como lo haría otra persona, entra en Preferencias, pestaña Extensiones, menú desplegable y elige instalar desde disco. Durante el desarrollo el ciclo es más corto: deja el código en la carpeta de usuario y usa Recargar scripts cada vez que cambies algo, en vez de reinstalar el zip en cada iteración.
Dónde guardar los datos del usuario
Nunca escribas dentro del directorio de la extensión. Al actualizar, ese directorio se reemplaza y te llevas por delante la configuración del usuario. El camino correcto es bpy.utils.extension_path_user(__package__, create=True), que devuelve una carpeta propia por extensión y por perfil, fuera del paquete.
Los cinco errores que rompen una extensión
- Versión mínima mal puesta. Declarar 4.2 cuando usas una función que llegó en 5.3 hace que la extensión se instale y falle al usarla. Es peor que no instalarse.
- Imports con rutas relativas. Dentro de un paquete, importa por nombre de módulo del paquete, no por ruta de archivo.
register()sinunregister()simétrico. Deja clases, atajos y handlers vivos tras desactivar.- Escribir en la carpeta de la extensión. Se pierde en la primera actualización.
- Permisos sin declarar. La revisión lo detecta y el paquete no se publica.
Publicar en extensions.blender.org
Publicar es el último paso y el más aburrido: crear cuenta, subir el zip, esperar la revisión de un moderador. Se revisa que el manifest sea coherente, que la licencia sea compatible con GPL y que el add-on haga lo que dice el tagline. Las actualizaciones no se suben como paquete nuevo: se sube el mismo id con una version mayor, y los usuarios que lo tengan instalado ven el aviso.
Si no quieres pasar por la revisión, el .zip también se reparte por tu cuenta y se instala desde disco. Es lo que hace la mayoría de los add-ons internos de estudio: mismo formato, sin tienda.
Conclusión
Al terminar tienes las cuatro piezas que aparecen en cualquier extensión de verdad: un operador que hace el trabajo, un panel que lo expone, preferencias que persisten y un atajo que se limpia solo. El resto es ampliar el ejemplo: sustituir el renombrado por la operación que necesites y volver a compilar el zip. Si quieres el contexto del lanzamiento que abrió la plataforma a las bibliotecas de assets, está en el análisis de las novedades de Blender 5.3. Y si prefieres empezar por algo más pequeño, en el blog seguimos publicando trucos de Python para Blender que no necesitan manifest.
