Automatiser Unreal Engine avec Python : démarrer dans l’éditeur

Ce que vous apprendrez dans ce guide

Vous apprendrez à activer Python dans Unreal Editor, à exécuter un script simple et à choisir la méthode d’automatisation qui convient à votre tâche. La documentation d’Epic Games indique que la prise en charge de Python est expérimentale et recommande la prudence, en particulier lors de la publication d’un produit. L’usage présenté ici concerne donc les tâches de production et de gestion de contenu dans l’éditeur, et non le code de gameplay exécuté pendant le jeu.

Python peut servir de langage de script commun pour relier différents logiciels 3D dans les workflows de production. Dans Unreal Editor, il est également possible d’automatiser la gestion des assets, d’effectuer des tâches chronophages comme la génération de LOD pour des Static Meshes, de placer du contenu dans des niveaux de façon procédurale et de créer des interfaces dédiées à l’éditeur. Il s’agit d’exemples d’utilisation mentionnés dans la documentation, et non de la garantie qu’une automatisation prête à l’emploi existe pour chaque projet.

Prérequis et préparation du projet

Les fonctionnalités Python sont fournies par Python Editor Script Plugin dans Unreal Editor. Le plugin doit être activé projet par projet : son activation dans un projet ne s’applique pas automatiquement aux autres. Epic Games recommande également d’activer Editor Scripting Utilities, qui propose des API simplifiées pour les tâches courantes de l’éditeur.

L’éditeur utilise Python 3.11.8, fourni avec le plugin. Il n’est donc pas nécessaire d’installer Python séparément sur l’ordinateur pour exécuter des scripts dans Unreal Editor. Pour intégrer une autre version de Python, il faut définir la variable d’environnement UE_PYTHON_DIR sur le système d’exploitation et recompiler Unreal Engine à partir du code source ; cette étape n’est pas nécessaire pour débuter.

Étape par étape : activer Python et lancer un premier script

1. Ouvrez le projet Unreal que vous souhaitez utiliser. Dans le menu principal, allez dans Edit > Plugins.

2. Dans la section Scripting de la fenêtre Plugins, activez Python Editor Script Plugin. Comme le recommande Epic Games, vous pouvez également activer Editor Scripting Utilities.

3. Redémarrez Unreal Editor. Activer le plugin ne suffit pas : l’éditeur doit être redémarré avant d’exécuter un script.

4. Pour un premier essai, ouvrez le panneau Output Log et passez la saisie de la console en mode Python. Vous pouvez aussi ouvrir la console avec la touche accent grave (). Les lignes Python saisies dans ce mode sont exécutées immédiatement ; utilisez **Shift + Enter** pour saisir plusieurs lignes. Les sorties de print` s’affichent également dans le panneau Output Log.

5. Pour lancer un script depuis un fichier, sélectionnez-le sur votre ordinateur via File > Execute Python Script dans le menu principal. Vous pouvez relancer des scripts déjà exécutés à partir de la liste Recent Python scripts. Cette liste lit la version actuelle du fichier.

En mode commande normal de la console, vous pouvez également lancer une ligne ou un fichier Python avec la commande py. Voici l’exemple de fichier donné dans la documentation :

py "C:\MyScripts\my_script.py"

Remplacez le chemin de cet exemple par l’emplacement du script à exécuter. Si le script attend des arguments supplémentaires en ligne de commande, vous pouvez les fournir après le nom du fichier.

Automatiser les tâches répétitives

Deux méthodes sont à privilégier si vous souhaitez exécuter un script à chaque ouverture. Dans les Project Settings propres au projet, vous pouvez ajouter des scripts au paramètre Startup scripts, dans Plugins > Python. Unreal Editor exécute ces scripts une fois le niveau de démarrage par défaut entièrement chargé. Après avoir apporté des modifications, redémarrez l’éditeur ; les scripts s’exécuteront à la prochaine ouverture du projet.

L’autre méthode consiste à placer un fichier nommé init_unreal.py dans le dossier Content/Python du projet ou du plugin. Si l’éditeur trouve un script portant ce nom dans l’un des chemins configurés, il l’exécute automatiquement. Epic Games présente cette approche pour les situations où des personnes travaillant sur le même contenu ont besoin d’exécuter un code de démarrage commun à chaque lancement de l’éditeur.

La ligne de commande permet d’exécuter des opérations reproductibles ou de lancer des scripts sans ouvrir l’interface. La méthode avec l’éditeur complet charge le projet et le niveau de démarrage par défaut avant d’exécuter le script ; selon la documentation, les deux plugins concernés doivent être activés dans le projet pour utiliser cette méthode. La méthode avec commandlet peut s’exécuter sans interface et est plus rapide. Toutefois, elle ne charge pas les niveaux automatiquement ; si le script a besoin du contenu d’un niveau, le chargement doit être pris en charge séparément. Dans les deux méthodes en ligne de commande, Unreal Editor se ferme une fois le script exécuté.

Les équipes qui utilisent Blueprint peuvent aussi s’appuyer sur les nœuds d’exécution Python ; ceux-ci ne sont toutefois disponibles que dans les classes dédiées à l’éditeur, comme Editor Utility Widget et Editor Utility Blueprint. La documentation recommande le nœud Execute Python Script pour appeler Python depuis Blueprint. Les entrées de ce nœud peuvent être lues avant l’exécution du script, et ses sorties peuvent être définies une fois l’exécution terminée. Le résultat est indiqué par la sortie Return Value ; les détails des erreurs figurent dans Output Log. Ce nœud n’exécute pas de fichier, mais des lignes Python.

Problèmes courants et limites

La distinction la plus importante est celle entre l’automatisation de l’éditeur et l’exécution du jeu. L’environnement Python est disponible dans Unreal Editor, mais pas dans Play In Editor (PIE), Standalone Game ni dans un exécutable packagé. Python ne doit donc pas être considéré comme un langage de script pour le gameplay.

Un autre problème courant est d’avoir activé le plugin dans un autre projet seulement. Chaque projet nécessite une activation et un redémarrage distincts. Supposer qu’un script lancé avec commandlet chargera automatiquement un niveau peut également entraîner des erreurs. Enfin, si l’exécution d’un script échoue dans un nœud Blueprint, consultez Output Log pour obtenir le message d’erreur.

Pour aller plus loin : workflows d’architecture et de visualisation

Pour les équipes d’architecture, de design d’intérieur et d’archviz, Python peut contribuer à réduire les tâches répétitives de gestion de contenu dans Unreal Editor et à relier des processus de production faisant intervenir différentes applications 3D. Par exemple, automatiser les étapes de gestion des assets propres à une équipe ou le placement de contenu dans un niveau correspond aux cas d’usage décrits dans la documentation. Cela ne garantit ni l’existence d’un transfert BIM particulier ni la compatibilité avec un logiciel spécifique ; l’intégration doit être conçue en fonction du contenu du projet.

Pour commencer, choisissez une petite tâche pouvant être vérifiée dans l’éditeur, puis testez le script depuis la console ou avec Execute Python Script. Si l’opération est répétée, passez ensuite aux scripts de démarrage ou à l’exécution en ligne de commande. Tenez compte, dans votre plan de production, de l’avertissement indiquant que la prise en charge de Python est expérimentale, de l’activation du plugin requise pour chaque projet et de l’impossibilité de l’utiliser à l’exécution du jeu. La documentation Unreal Python 5.8 API constitue une référence pour consulter les sections et types d’API disponibles.

Sources et licence

Ce guide est une adaptation en français du guide Scripting the Unreal Editor using Python d’Epic Games et de la page Unreal Python 5.8 API Documentation. Ces deux sources sont des documents officiels d’Epic Games.