Automatización con Python en Unreal Engine: primeros pasos

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

Aprenderás a activar Python en Unreal Editor, ejecutar un script sencillo y elegir el método de automatización que mejor se adapte a tu trabajo. La documentación de Epic Games indica que la compatibilidad con Python es experimental y recomienda prudencia, especialmente al publicar productos. Por eso, el uso que se describe aquí no es código de juego que se ejecuta mientras se juega, sino tareas de producción y gestión de contenido dentro del editor.

Python puede utilizarse como lenguaje de scripting común en procesos de producción que conectan diferentes aplicaciones 3D. También permite automatizar flujos de gestión de recursos en Unreal Editor, realizar tareas laboriosas como generar LOD para Static Meshes, colocar contenido en niveles de forma procedimental y preparar interfaces específicas del editor. Son ejemplos de uso indicados en la documentación; no significa que haya una automatización lista para cada proyecto.

Requisitos y preparación del proyecto

Las funciones de Python se ofrecen mediante Python Editor Script Plugin en Unreal Editor. El plugin debe activarse para cada proyecto; habilitarlo en uno no lo activa automáticamente en los demás. Epic Games también recomienda activar Editor Scripting Utilities, que ofrece API simplificadas para tareas habituales del editor.

El editor utiliza Python 3.11.8, incluido en el plugin. Por tanto, no es necesario instalar Python por separado en el equipo para ejecutar scripts únicamente en Unreal Editor. Quienes quieran integrar otra versión de Python deben configurar la variable de entorno UE_PYTHON_DIR en el sistema operativo y volver a compilar Unreal Engine desde el código fuente; no es un paso necesario para empezar.

Paso a paso: activa Python y ejecuta tu primer script

1. Abre el proyecto de Unreal que vayas a utilizar. En el menú principal, ve a Edit > Plugins.

2. Busca la sección Scripting en la ventana Plugins y activa Python Editor Script Plugin. Siguiendo la recomendación de Epic Games, también puedes activar Editor Scripting Utilities.

3. Reinicia Unreal Editor. Activar el plugin no es suficiente por sí solo: hay que reiniciar antes de ejecutar un script.

4. Para la primera prueba, abre el panel Output Log y cambia la entrada de la consola al modo Python. También puedes abrir la consola con la tecla de acento grave (). Las líneas de Python que escribas en este modo se ejecutan de inmediato; puedes usar **Shift + Enter** para varias líneas. Los resultados de print` aparecen en el panel Output Log.

5. Para ejecutar un script desde un archivo, usa la opción File > Execute Python Script del menú principal y selecciona el script en el equipo. Puedes volver a ejecutar archivos usados anteriormente desde la lista Recent Python scripts. La lista lee la versión actual del archivo.

También puedes ejecutar una línea o un archivo de Python con el comando py cuando la consola está en el modo de comandos habitual. Este es el ejemplo de la documentación para un archivo:

py "C:\MyScripts\my_script.py"

Sustituye la ruta del ejemplo por la ubicación del script que quieras ejecutar. Si el script espera argumentos adicionales de línea de comandos, puedes indicarlos después del nombre del archivo.

Automatiza tareas repetitivas

Si quieres que un script se ejecute cada vez que se inicia el editor, tienes dos opciones principales. En Project Settings, específicas del proyecto, puedes añadir scripts en Plugins > Python, dentro del ajuste Startup scripts. Unreal Editor ejecuta estos scripts una vez que se ha cargado por completo el nivel de inicio predeterminado. Reinicia el editor después de los cambios; los scripts se ejecutarán la próxima vez que abras el proyecto.

La otra opción es colocar un archivo llamado init_unreal.py en la carpeta Content/Python del proyecto o del plugin. Si el editor encuentra un script con ese nombre en alguna de las rutas configuradas, lo ejecuta automáticamente. Epic Games describe este método para los casos en que varias personas trabajan con el mismo contenido y necesitan ejecutar un código de inicio común cada vez que se inicia el editor.

La línea de comandos ofrece una opción para procesos repetibles o para ejecutar scripts sin abrir la interfaz. El método de editor completo ejecuta el script después de cargar el proyecto y el nivel de inicio predeterminado; según la documentación, ambos plugins relacionados deben estar activados en el proyecto para utilizar este método. El método con commandlet puede ejecutarse sin interfaz y es más rápido. Sin embargo, no carga niveles por sí solo; si el script necesita contenido de un nivel, hay que gestionar su carga por separado. En ambos métodos de línea de comandos, Unreal Editor se cierra después de ejecutar el script.

Los equipos que usan Blueprints también pueden aprovechar los nodos para ejecutar Python, pero estos solo están disponibles en clases específicas del editor, como Editor Utility Widget y Editor Utility Blueprint. La documentación recomienda el nodo Execute Python Script para llamar a Python desde un Blueprint. Las entradas de este nodo pueden leerse antes de ejecutar el script y las salidas pueden definirse después. El estado de éxito se consulta en la salida Return Value; los detalles de los errores aparecen en Output Log. Este nodo ejecuta líneas de Python, no archivos.

Errores frecuentes y limitaciones

La distinción más importante es la que existe entre la automatización del editor y el tiempo de ejecución del juego. El entorno de Python está disponible en Unreal Editor, pero no se puede utilizar en Play In Editor (PIE), Standalone Game ni en ejecutables empaquetados. Por tanto, Python no debe considerarse un lenguaje de scripting para la lógica de juego.

Otro problema habitual es haber activado el plugin en otro proyecto. Cada proyecto requiere una activación y un reinicio independientes. También puede dar lugar a errores suponer que los scripts ejecutados mediante commandlet cargarán los niveles automáticamente. Además, si un script falla en un nodo de Blueprint, consulta Output Log para ver el mensaje de error.

Siguientes pasos: flujos de trabajo de arquitectura y visualización

Para los equipos de arquitectura, diseño de interiores y archviz, Python puede ayudar a reducir las tareas repetitivas de gestión de contenido en Unreal Editor y conectar procesos de producción que utilizan diferentes aplicaciones 3D. Por ejemplo, automatizar los pasos de gestión de recursos o la colocación de contenido en niveles se corresponde con los usos descritos en la documentación. Esto no garantiza la compatibilidad con una importación BIM concreta ni con un software específico; la integración debe diseñarse según el contenido del proyecto.

En la primera etapa, elige una tarea pequeña que puedas validar en el editor y prueba el script desde la consola o mediante Execute Python Script. Después, si el proceso se repite, pasa a los scripts de inicio o a la ejecución desde la línea de comandos. Incorpora a tu planificación la advertencia de que la compatibilidad con Python es experimental, el requisito de activar el plugin para cada proyecto y la imposibilidad de usarlo durante el tiempo de ejecución del juego. La documentación Unreal Python 5.8 API es un recurso para consultar las secciones y los tipos de API disponibles.

Fuentes y licencia

Esta guía se ha adaptado al español a partir de Scripting the Unreal Editor using Python y de la página Unreal Python 5.8 API Documentation de Epic Games. Ambas fuentes son documentación oficial de Epic Games.