Automatización del editor con Python en Unreal Engine: guía paso a paso

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

La compatibilidad con Python en Unreal Editor permite ejecutar tareas de producción repetitivas mediante scripts y facilitar los flujos de trabajo que conectan distintas aplicaciones 3D. Entre los ejemplos de la documentación de Epic se encuentran automatizar la gestión de recursos, generar LOD para Static Meshes y colocar contenido en un Level de forma procedimental. Python también permite crear interfaces personalizadas para el editor.

En esta guía, primero configuraremos el proyecto; después ejecutaremos un breve comando de Python y compararemos las opciones de automatización mediante scripts basados en archivos. Los métodos descritos están orientados a automatizar el editor: la compatibilidad con Python está disponible mientras Unreal Editor está abierto, pero no se puede utilizar cuando el juego se ejecuta en Play In Editor, Standalone Game o como ejecutable empaquetado.

Requisitos

Necesitarás un proyecto de Unreal Engine en el que puedas activar Python Editor Script Plugin y Unreal Editor. Según la guía de Epic, el complemento se activa por proyecto; para usar Python en otro proyecto, también tendrás que activarlo allí. Se recomienda habilitar asimismo Editor Scripting Utilities, que ofrece API simplificadas para operaciones habituales del editor.

Python Editor Script Plugin incorpora Python 3.11.8 en Unreal Editor. Por lo tanto, no hace falta instalar Python por separado para seguir esta guía. Para utilizar otra versión de Python, es necesario configurar la variable de entorno UE_PYTHON_DIR en el sistema operativo y volver a compilar Unreal Engine desde el código fuente.

La documentación de Python API de Epic marca Unreal Python 5.8 como “Experimental”. La guía principal también advierte que la función es experimental. Por eso, conviene validar los scripts primero en una copia del proyecto de producción o en un proyecto de pruebas controlado.

Paso a paso: activa el complemento y ejecuta el primer comando

1. Abre en Unreal Editor el proyecto en el que vas a trabajar. En el menú superior, ve a Edit > Plugins.

2. En la sección Scripting de la ventana de complementos, busca Python Editor Script Plugin y marca la casilla Enabled.

3. Activa también Editor Scripting Utilities en la misma ventana. Reinicia el editor después de aplicar los cambios.

4. Abre el panel Output Log y cambia la entrada de la consola al modo Python. Como alternativa, puedes abrir la barra de entrada de la consola con la tecla ~. Las líneas de código escritas en modo Python se ejecutan de inmediato en el editor.

5. Como primera prueba, usa la función print de Python para mostrar un mensaje en Output Log:

print("Python etkin")

La salida de print aparece en el panel Output Log. Para ejecutar varias líneas en la consola, puedes separarlas con Shift+Enter o pegar código multilínea. Este método es práctico para probar líneas individuales y hacer comprobaciones sencillas.

Opciones para ejecutar un archivo de script

Para tareas repetibles, resulta más ordenado guardar el código en un archivo Python. Puedes ejecutarlo indicando la ruta del archivo de script en la consola del editor:

py "C:\MyScripts\my_script.py"

La ruta mostrada es el ejemplo de la documentación de Epic; sustitúyela por la ubicación de tu script. Como alternativa, puedes seleccionar un script de tu equipo mediante File > Execute Python Script en la ventana principal. También es posible volver a ejecutar archivos usados anteriormente desde la lista Recent Python scripts. Como el editor vuelve a leer el archivo desde el disco, ejecutará también los últimos cambios guardados.

La ejecución desde la línea de comandos es otra opción para los equipos que quieran integrar scripts en su flujo de automatización. Puedes iniciar el editor completo y ejecutar el script una vez cargados el proyecto y el nivel de inicio predeterminado:

UnrealEditor-Cmd.exe "C:\projects\MyProject.uproject" -ExecutePythonScript="c:\my_script.py"

Para este método, Python Scripting Plugin y Editor Scripting Utilities deben estar habilitados en el proyecto. El editor se cerrará cuando termine el script.

Para una ejecución más rápida, sin interfaz, puedes usar el commandlet pythonscript:

UnrealEditor-Cmd.exe "C:\projects\MyProject.uproject" -run=pythonscript -script="c:\\my_script.py"

Este método no carga niveles automáticamente. Si el script necesita acceder al contenido de un Level concreto, puedes usar la llamada de carga que Epic incluye como primera línea en su documentación; la ruta corresponde al proyecto de ejemplo y debe adaptarse a la ruta del Level del proyecto real:

unreal.get_editor_subsystem(unreal.LevelEditorSubsystem).load_level("/Game/maps/UVlayoutTest.UVlayoutTest")

Errores frecuentes y limitaciones

El detalle que más se suele pasar por alto es que el complemento debe habilitarse en cada proyecto. No des por hecho que un script que funciona en un proyecto también lo hará en otro: primero comprueba el estado de los complementos correspondientes. Si utilizas el método de línea de comandos con el editor completo, recuerda también que se requiere Editor Scripting Utilities.

El commandlet y el inicio del editor completo no se comportan igual. Como el commandlet no carga niveles automáticamente, los scripts que dependen del contenido de un nivel deben incluir explícitamente el paso de carga. Con el método del editor completo, el script se ejecuta después de abrir el proyecto y cargar el nivel de inicio predeterminado.

Tampoco es adecuado intentar utilizar Python para la lógica del juego. La documentación de Epic indica que el entorno Python está disponible en Unreal Editor y que no se puede usar en los modos de ejecución. Los nodos de Blueprint para ejecutar Python también están disponibles únicamente en clases de Blueprint orientadas al editor, como Editor Utility Widget y Editor Utility Blueprint; no se pueden usar en clases normales de ejecución.

Impacto en los flujos de trabajo de arquitectura, interiorismo y archviz

Para los estudios de arquitectura y los equipos de visualización, la ventaja más directa es poder gestionar mediante scripts operaciones repetitivas con recursos dentro del editor. Organizar la gestión de recursos del proyecto, automatizar la generación de LOD o colocar contenido en un nivel son, por ejemplo, algunos de los casos de uso que se mencionan expresamente en la documentación. El uso de Python como lenguaje común de scripting en flujos de producción que incluyen varias aplicaciones 3D también puede ayudar a conectar los procesos.

En cambio, esta guía no ofrece garantías de compatibilidad con un complemento específico de archviz o un proyecto concreto, ni información sobre requisitos de hardware o modelos de licencia. En particular, hay que comprobar que las funciones que se vayan a usar en API marcadas como experimentales funcionen con la versión de Unreal del proyecto. No incorpores la automatización al proceso de producción sin probar cómo afecta la carga de niveles, los complementos del editor y la configuración del proyecto para otros usuarios del equipo.

Próximos pasos

Después de ejecutar el primer script, elige una tarea pequeña y reversible: por ejemplo, comprobar un comando desde el editor o automatizar de forma controlada un paso de producción existente. Luego guarda el proceso en un archivo y prueba Execute Python Script o el método adecuado desde la línea de comandos. En proyectos que usarán varias personas, también puedes considerar los scripts de inicio: init_unreal.py se puede colocar en la carpeta Content/Python del proyecto o del complemento, y el editor lo ejecuta automáticamente. También es posible definir scripts para que se ejecuten al inicio en la configuración del proyecto.

A medida que crezca el flujo de trabajo, consulta la documentación de Unreal Python API correspondiente a la versión que utilizas; sirve como referencia para módulos, tipos y encabezados de API. Amplía el alcance paso a paso, teniendo en cuenta que la función es experimental y que los scripts solo se ejecutan dentro del editor.

Fuentes y licencia

Esta guía se ha adaptado al turco a partir de la guía “Scripting the Unreal Editor Using Python” y la página “Unreal Python API Documentation” de Epic Games. Las fuentes están marcadas como de uso libre; el texto y la explicación de los ejemplos se han reorganizado.