Automatiser l’éditeur Unreal Engine avec Python : guide de démarrage pas à pas

Ce que vous allez apprendre dans ce guide

La prise en charge de Python dans Unreal Editor permet d’exécuter des tâches de production répétitives à l’aide de scripts et de faciliter les pipelines de production faisant intervenir plusieurs applications 3D. Parmi les exemples cités dans la documentation d’Epic figurent l’automatisation de la gestion des assets, la génération de LOD pour les Static Meshes et le placement procédural du contenu d’un Level. Python permet également de créer des interfaces personnalisées pour l’éditeur.

Dans ce guide, nous allons d’abord configurer le projet, puis exécuter une courte commande Python et comparer différentes options d’automatisation à partir de scripts enregistrés dans des fichiers. Ces méthodes sont destinées à l’automatisation de l’éditeur : Python est utilisable quand Unreal Editor est ouvert, mais pas lorsque le jeu tourne dans Play In Editor, Standalone Game ou un exécutable packagé.

Prérequis

Vous devez disposer d’un projet Unreal Engine et d’Unreal Editor pour activer le plugin Python Editor Script Plugin. Selon le guide d’Epic, ce plugin s’active projet par projet ; pour utiliser Python dans un autre projet, il faut aussi l’y activer. Il est également recommandé d’activer le plugin Editor Scripting Utilities, qui fournit des API simplifiées pour les opérations courantes de l’éditeur.

Python Editor Script Plugin intègre Python 3.11.8 à Unreal Editor. Il n’est donc pas nécessaire d’installer Python séparément pour suivre ce guide. L’utilisation d’une autre version de Python nécessite de définir la variable d’environnement UE_PYTHON_DIR dans le système d’exploitation et de recompiler Unreal Engine à partir des sources.

La documentation de l’API Python d’Epic indique que la version Unreal Python 5.8 est « Experimental ». Le guide d’utilisation principal précise également que la fonctionnalité est expérimentale. Il est donc préférable de tester les scripts sur une copie du projet de production ou dans un projet de test contrôlé.

Pas à pas : activer le plugin et exécuter la première commande

1. Ouvrez le projet dans lequel vous souhaitez travailler dans Unreal Editor. Dans le menu supérieur, allez dans Edit > Plugins.

2. Dans la section Scripting de la fenêtre des plugins, repérez Python Editor Script Plugin et cochez Enabled.

3. Activez également le plugin Editor Scripting Utilities dans la même fenêtre. Redémarrez l’éditeur après ces modifications.

4. Ouvrez le panneau Output Log et passez la saisie de la console en mode Python. Vous pouvez aussi ouvrir la barre de saisie de la console avec la touche ~. Les lignes de code saisies en mode Python sont exécutées immédiatement dans l’éditeur.

5. Pour un premier essai, utilisez la fonction Python print afin d’afficher un message dans Output Log :

print("Python etkin")

La sortie de print s’affiche dans le panneau Output Log. Pour exécuter plusieurs lignes dans la console, séparez-les avec Shift+Enter ou collez du code sur plusieurs lignes. Cette méthode convient pour tester des lignes individuellement et effectuer des vérifications simples.

Options pour exécuter un fichier de script

Pour les tâches répétitives, conserver le code dans un fichier Python permet de travailler de façon plus organisée. Vous pouvez lancer le script en indiquant son chemin dans la console de l’éditeur :

py "C:\MyScripts\my_script.py"

Le chemin indiqué ici est un exemple tiré de la documentation d’Epic ; remplacez-le par l’emplacement de votre script. Vous pouvez également choisir un script sur votre ordinateur à l’aide de File > Execute Python Script dans la fenêtre principale. Les fichiers déjà exécutés peuvent aussi être relancés depuis la liste Recent Python scripts. Comme l’éditeur relit le fichier sur le disque, les dernières modifications apportées à celui-ci sont également prises en compte.

L’exécution depuis la ligne de commande constitue une autre option pour les équipes qui souhaitent intégrer leurs scripts à un pipeline d’automatisation. Le script peut être exécuté après le démarrage complet de l’éditeur, le chargement du projet et celui du niveau de démarrage par défaut :

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

Pour cette méthode, Python Scripting Plugin et Editor Scripting Utilities doivent être activés dans le projet. Une fois le script terminé, l’éditeur se ferme.

Pour une exécution plus rapide, sans interface, vous pouvez utiliser le commandlet pythonscript :

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

Cette méthode ne charge pas automatiquement les niveaux. Si le script doit accéder au contenu d’un Level spécifique, vous pouvez utiliser l’appel de chargement indiqué par Epic en première ligne ; le chemin qu’il contient appartient à un projet d’exemple et doit être adapté au chemin du Level dans le projet concerné :

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

Erreurs courantes et limitations

L’oubli le plus fréquent consiste à ne pas tenir compte de l’activation du plugin projet par projet. Ne partez pas du principe qu’un script fonctionnant dans un projet marchera aussi dans un autre : vérifiez d’abord l’état du plugin concerné. Avec la méthode de lancement de l’éditeur complet depuis la ligne de commande, n’oubliez pas non plus la nécessité d’activer Editor Scripting Utilities.

Le commandlet et le lancement de l’éditeur complet ne se comportent pas de la même manière. Comme le commandlet ne charge pas automatiquement le niveau, les scripts qui dépendent du contenu d’un niveau doivent gérer explicitement son chargement. Avec la méthode de l’éditeur complet, le script est exécuté après l’ouverture du projet et le chargement du niveau de démarrage par défaut.

Utiliser Python pour la logique de gameplay n’est pas non plus un usage adapté. La documentation d’Epic précise que l’environnement Python est disponible dans Unreal Editor et ne peut pas être utilisé dans les modes d’exécution du jeu. Les nœuds Blueprint permettant d’exécuter Python sont eux aussi réservés aux classes Blueprint destinées à l’éditeur, comme Editor Utility Widget et Editor Utility Blueprint ; ils ne sont pas utilisables dans les classes d’exécution classiques.

Conséquences pour les workflows d’architecture, d’architecture intérieure et d’archviz

Pour les agences d’architecture et les équipes de visualisation, l’avantage le plus direct est de pouvoir gérer par script les opérations répétitives sur les assets dans l’éditeur. Organiser la gestion des assets d’un projet, automatiser la génération de LOD ou placer du contenu dans un niveau font partie des usages explicitement mentionnés dans la documentation. L’utilisation de Python comme langage de script commun dans les pipelines faisant intervenir plusieurs applications 3D peut aussi contribuer à relier les processus.

En revanche, ce guide ne garantit ni la compatibilité avec un plugin d’archviz précis ou un projet donné, ni ne fournit d’informations sur les exigences matérielles ou le modèle de licence. Pour les API signalées comme expérimentales, il convient notamment de vérifier que les fonctions utilisées sont compatibles avec la version d’Unreal du projet. Ne déployez pas l’automatisation en production sans avoir testé ses effets sur le chargement des niveaux, les plugins de l’éditeur et les paramètres du projet des autres membres de l’équipe.

Étapes suivantes

Après avoir exécuté votre premier script, choisissez une tâche modeste et réversible : par exemple, vérifier une commande depuis l’éditeur ou automatiser de façon contrôlée une étape de production existante. Enregistrez ensuite l’opération dans un fichier et essayez Execute Python Script ou une méthode en ligne de commande appropriée. Pour les projets utilisés par plusieurs personnes, vous pouvez également envisager des scripts de démarrage : init_unreal.py peut être placé dans le dossier Content/Python du projet ou du plugin, puis exécuté automatiquement par l’éditeur. Il est aussi possible de définir des scripts à exécuter au démarrage dans les paramètres du projet.

À mesure que le workflow se développe, consultez la documentation de l’API Unreal Python en fonction de la version utilisée ; elle sert de référence pour les modules, les types et les en-têtes d’API. Élargissez progressivement le périmètre, en tenant compte du statut expérimental de la fonctionnalité et du fait que les scripts ne s’exécutent que dans l’éditeur.

Source et licence

Ce guide a été adapté en turc à partir du guide « Scripting the Unreal Editor Using Python » et de la page « Unreal Python API Documentation » d’Epic Games. Les sources sont indiquées comme libres d’utilisation ; le texte et la présentation des exemples ont été remaniés.