Diseño 3D • • 5-8 minutos

Tu primera extensión de Blender: de blender_manifest.toml al panel

Diego Cortés
Diego Cortés
Full Stack Developer & SEO Specialist
Compartir:
Tu primera extensión de Blender: de blender_manifest.toml al panel
Imagen generada con IA

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"]
CampoPara qué sirve
schema_versionVersión del formato del manifest. Hoy es 1.0.0.
idIdentificador único en minúsculas. Es la carpeta de la extensión y la clave con la que Blender guarda sus preferencias.
versionVersión del add-on. Subirla es lo que dispara una actualización en la plataforma.
name y taglineNombre visible y una línea de descripción. El tagline se corta, así que va directo al grano.
maintainerQuién responde por el paquete, con correo entre paréntesis angulares.
typeadd-on o theme.
licenseLicencia en formato SPDX. Para publicar en la plataforma tiene que ser compatible con GPL.
blender_version_minVersión mínima de Blender. El mínimo útil es 4.2.0, cuando nació el formato.
tagsCategorí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 dist

El 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() sin unregister() 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.

Categorías