Cómo escribir un complemento de Python para Blender: crea tu primer operador

¿Qué aprenderás en esta guía?

En esta guía, convertirás un sencillo script de Python que funciona en Blender en un operador y, después, en un complemento que se puede cargar. La herramienta del ejemplo mueve todos los objetos de la escena activa 1 unidad en el eje X. El objetivo no es ofrecer una herramienta de producción lista para usar, sino explicar paso a paso cómo Blender define, registra y ejecuta los operadores.

Un complemento es un módulo de Python que contiene información adicional para que Blender pueda reconocerlo y mostrarlo en su lista. El diccionario bl_info indica datos como el nombre y la categoría del complemento, además de la versión mínima de Blender necesaria para ejecutarlo. Un operador, por su parte, permite invocar una acción desde Blender. En este ejemplo, ejecutaremos la acción desde la búsqueda de operadores.

Un detalle importante: el ejemplo afecta a todos los objetos de la escena activa, no solo a los seleccionados. Por eso, es más seguro hacer las primeras pruebas en una escena de prueba o en una copia del archivo, no en un proyecto importante.

Requisitos

Se espera que conozcas el uso básico de Blender y sepas ejecutar un script en el Editor de texto. También se recomienda tener familiaridad con tipos básicos de Python, como números, valores booleanos, cadenas de texto, listas, tuplas, diccionarios y conjuntos. La guía aconseja, además, tener conocimientos básicos sobre módulos y clases de Python.

En los datos del complemento del ejemplo de la guía, la versión de Blender se indica como (2, 80, 0). Este valor es la versión mínima especificada en los metadatos del ejemplo; no significa que se haya probado el código en versiones actuales de Blender. Es necesario verificar el comportamiento de la API en la versión que utilices. No se indican requisitos de cuenta de usuario, características de hardware ni licencias de pago.

Ejecutar Blender desde una terminal es una opción para depurar. La guía también señala que activar las Extensiones para desarrolladores en las preferencias puede facilitar el proceso de desarrollo de complementos.

Paso a paso: escribe tu primer operador

1. Añade el código al Editor de texto

En el siguiente ejemplo, la clase ObjectMoveX define el operador. Al ejecutar execute(), se recorren los objetos de la escena activa y se suma 1.0 a la coordenada X de cada uno. La opción UNDO de bl_options permite utilizar el operador con la función de deshacer.

bl_info = {
    "name": "Move X Axis",
    "blender": (2, 80, 0),
    "category": "Object",
}

import bpy

class ObjectMoveX(bpy.types.Operator):
    """My Object Moving Script"""
    bl_idname = "object.move_x"
    bl_label = "Move X by One"
    bl_options = {'REGISTER', 'UNDO'}

    def execute(self, context):
        scene = context.scene
        for obj in scene.objects:
            obj.location.x += 1.0
        return {'FINISHED'}

def register():
    bpy.utils.register_class(ObjectMoveX)

def unregister():
    bpy.utils.unregister_class(ObjectMoveX)

if __name__ == "__main__":
    register()

Este sencillo ejemplo registra la clase del operador, pero no añade un elemento de interfaz a un menú. unregister() elimina la clase registrada. bl_idname especifica el identificador único del operador, mientras que bl_label define el nombre que aparece en la interfaz y en las búsquedas de Blender. Cuando la operación termina correctamente, la función execute() devuelve el resultado FINISHED.

2. Ejecuta el script e invoca el operador

Pega el código en el Editor de texto de Blender y ejecútalo. El script registra el operador; en este momento, no mueve los objetos por sí solo. Después, abre la búsqueda de operadores, busca Move X by One y ejecuta el operador. La acción desplaza 1 unidad en la dirección X todos los objetos de la escena activa.

Es importante utilizar el parámetro context de execute(self, context). Blender puede ejecutar operadores en determinados casos con un contexto especial. Por eso, la guía recomienda utilizar el valor context que se pasa al operador, en lugar de acceder directamente al contexto global.

3. Guarda el archivo y cárgalo como complemento

Guarda el script que has probado en un archivo. Elige un nombre válido para un módulo de Python y añade la extensión .py. En las preferencias de Blender, abre la sección Complementos, elige la opción para instalar, selecciona el archivo y activa el complemento en la lista. Si quieres que siga activo después de reiniciar, puedes usar la opción Guardar como predeterminado que aparece en la guía.

Al activar el complemento, Blender ejecuta el módulo y realiza las operaciones de registro incluidas en register(). Al desactivarlo, Blender llama a la función unregister(); en este ejemplo, eso significa eliminar la clase del operador. Durante la instalación, las carpetas de origen y destino pueden aparecer en la consola. La guía también explica cómo consultar las rutas de los complementos en la Consola de Python mediante addon_utils.paths().

Uso en flujos de trabajo de arquitectura y visualización

Este ejemplo muestra los fundamentos para que artistas técnicos o desarrolladores conviertan tareas repetitivas en un operador dentro de Blender. En escenas arquitectónicas, un enfoque similar puede servir como punto de partida para diseñar herramientas personalizadas para operaciones que se puedan definir con claridad y repetir con frecuencia. Sin embargo, este código no es una herramienta de oficina lista para usar directamente en una escena de producción: cambia la posición de todos los objetos de la escena activa.

Para la primera prueba, utiliza una copia de la escena y comprueba a qué objetos afecta el operador. Antes de compartir el complemento con el equipo, verifica también la versión de Blender de destino y la compatibilidad de los elementos de la API utilizados. La fuente no especifica requisitos de hardware, por lo que no es posible extraer recomendaciones al respecto. También es necesario evaluar las condiciones de licencia y la compatibilidad de versiones antes de distribuirlo.

Errores frecuentes

• Esperar que los objetos se muevan en cuanto se ejecuta el script: La primera ejecución registra el operador. Para modificar los objetos, hay que elegir Move X by One en la búsqueda de operadores.

• Pasar por alto el alcance de la acción: El código no se limita a los objetos seleccionados; procesa todos los objetos de la escena activa.

• Olvidar el formato del archivo: Guarda el archivo del complemento con la extensión .py y elige un nombre válido para un módulo de Python.

• Confundir guardar con activar: Guardar el archivo no activa el complemento por sí solo. Hay que cargarlo desde las preferencias y activarlo en la lista.

Próximos pasos

Primero, ejecuta el ejemplo en una escena de prueba y observa el resultado del operador. Después, revisa por separado la función de bl_info, la clase del operador, execute() y las funciones de registro. En una siguiente etapa de desarrollo, puedes explorar cómo convertir valores fijos en propiedades del operador que el usuario pueda ajustar; la continuación de la guía de Blender aborda este tema y otro ejemplo que crea duplicados vinculados de objetos.

Si aparecen mensajes de error, revisar la salida de la consola de Blender puede ayudar a identificar en qué paso se produce el problema. La descripción general de la API de Blender y la documentación de bpy.context y bpy.types.Operator también se encuentran entre los recursos de referencia que señala la guía para profundizar en los conceptos utilizados.

Fuente y licencia

Esta guía se ha adaptado al turco a partir del documento oficial de Blender “Add-on Tutorial” y su ejemplo de complemento y operador. La fuente está bajo la licencia CC BY-SA 4.0.