Automatiser Unreal Engine avec Python : activer le plugin et exécuter son premier script

Ce que vous allez apprendre

Pour commencer à utiliser Python dans Unreal Editor, il faut d’abord activer le plugin correspondant dans le projet, puis exécuter le code de la manière appropriée. Ce guide présente l’installation du plugin, l’exécution de code dans la console, le lancement d’un fichier Python et les options permettant de rendre l’automatisation reproductible. Epic Games présente Python dans l’éditeur comme un outil pour gérer des ressources, placer du contenu dans des niveaux et automatiser certaines tâches chronophages.

Il est important de bien cerner le périmètre : cet environnement Python est destiné à Unreal Editor. Le code Python n’est pas utilisable lorsque le projet s’exécute en mode Play In Editor, en jeu autonome ou sous la forme d’une application empaquetée. Les étapes décrites ici concernent donc l’automatisation de l’éditeur et de la production, et non la logique de gameplay.

Prérequis

• Un projet Unreal Engine et Unreal Editor.

• Python Editor Script Plugin, à activer pour le projet.

• Le plugin Editor Scripting Utilities, recommandé par le guide pour disposer d’API communes simplifiées destinées aux opérations de l’éditeur.

• Aucune installation distincte de Python n’est requise : selon la documentation d’Epic Games, Python Editor Script Plugin intègre Python 3.11.8.

La documentation de l’API Python d’Unreal est indiquée comme « 5.8 (Experimental) ». Epic Games avertit également que cette fonctionnalité est expérimentale et qu’il convient de l’utiliser avec prudence, notamment lors de la publication d’un produit. Il est donc préférable de tester d’abord les étapes décrites ici sur une copie du projet de production ou sur un projet de test. Les sources ne mentionnent par ailleurs aucune exigence de compte.

Étape par étape : activer Python et exécuter du code

1. Activez les plugins dans le projet

Ouvrez le projet concerné dans Unreal Editor, puis accédez à Edit > Plugins depuis le menu principal. Dans la section Scripting de la fenêtre des plugins, repérez Python Editor Script Plugin et cochez Enabled. Epic Games recommande également d’activer Editor Scripting Utilities, qui fournit des API simplifiées pour les opérations courantes dans l’éditeur.

Ce réglage doit être effectué séparément pour chaque projet. Après avoir activé les plugins, redémarrez l’éditeur. Ne sautez pas cette étape : le guide demande de redémarrer l’éditeur après l’installation du plugin.

2. Utilisez le mode Python de la console

Pour effectuer des essais ligne par ligne ou exécuter immédiatement un court extrait de code, passez la zone de saisie de la console du panneau Output Log en mode Python. Vous pouvez aussi ouvrir la barre de saisie de la console avec la touche ~. Les lignes saisies en mode Python s’exécutent immédiatement ; pour entrer plusieurs lignes, utilisez Shift+Enter ou collez un bloc multiligne depuis un éditeur de texte.

Cette méthode convient aux essais interactifs. Les sorties de la fonction print sont également dirigées vers le panneau Output Log. Lorsque la console de commandes est en mode Cmd, la commande py permet d’exécuter le reste de la ligne comme du code Python. Exemple d’appel d’un fichier de script existant :

py "C:\MyScripts\my_script.py"

Le chemin du fichier est un exemple donné dans le guide pour indiquer l’emplacement du script à exécuter ; adaptez-le à votre propre fichier.

3. Exécutez un fichier de script depuis le menu File

Pour sélectionner un fichier qui n’a pas encore été exécuté, utilisez File > Execute Python Script dans la fenêtre principale. Les fichiers déjà lancés peuvent être sélectionnés de nouveau dans la liste Recent Python scripts. Comme l’éditeur relit le fichier depuis le disque, cette méthode exécute aussi les dernières modifications apportées au script.

Cette option permet d’exécuter le code depuis un fichier sans le recoller sans cesse dans la console. La source ne mentionne pas de contrôle de sécurité ou de validation automatique du contenu du fichier ; vérifiez donc le script et le projet cible avant de l’exécuter.

4. Lancez l’éditeur complet depuis la ligne de commande

Si le script interagit avec le contenu du projet ou avec un niveau dont le chargement peut prendre du temps, vous pouvez utiliser une méthode qui lance Unreal Editor dans son intégralité. L’éditeur ouvre le projet, charge le niveau de démarrage par défaut puis exécute le script une fois l’environnement prêt. Voici l’exemple de ligne de commande Windows présenté dans le guide source :

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

Pour cette option, le plugin Editor Scripting Utilities doit être activé dans le projet ; Python Scripting Plugin doit également avoir été activé au préalable dans le projet indiqué dans la commande. Selon le guide, l’éditeur se ferme une fois le script terminé.

5. Envisagez l’option commandlet sans interface

La méthode commandlet permet une exécution rapide sans ouvrir l’interface de l’éditeur, c’est-à-dire en mode headless. Le guide montre l’utilisation de UnrealEditor-Cmd.exe avec les arguments -run=pythonscript et -script :

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

Cette méthode ne charge pas les niveaux automatiquement. Si le script a besoin d’un niveau, la source précise que l’appel de chargement du niveau doit être la première opération du script :

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

Les chemins du projet, du script et du niveau indiqués dans les exemples de commandlet sont des valeurs fournies dans la documentation ; ne les utilisez pas sans les remplacer par les emplacements correspondant à votre projet.

6. Exécutez des tâches récurrentes au démarrage

Lorsque l’équipe travaillant sur un même projet ou plugin a besoin d’exécuter le même code de préparation à chaque lancement, vous pouvez utiliser init_unreal.py. Si l’éditeur trouve un fichier portant ce nom dans les chemins Python configurés, il l’exécute automatiquement. Le guide précise que le fichier peut être placé dans le dossier Content/Python du projet ou du plugin.

Pour désigner un ou plusieurs fichiers à exécuter à chaque ouverture d’un projet, accédez aux paramètres Plugins > Python dans Edit > Project Settings, puis ajoutez les scripts dans le champ Startup scripts. Après avoir modifié ce réglage, redémarrez l’éditeur ; les scripts s’exécuteront au prochain lancement, une fois le niveau de démarrage par défaut entièrement chargé.

Erreurs fréquentes

• Penser qu’il suffit d’activer le plugin une seule fois : Python Editor Script Plugin doit être activé séparément pour chaque projet.

• Essayer d’utiliser Python pendant l’exécution du jeu : cette fonctionnalité est destinée à l’éditeur ; elle n’est pas disponible dans Play In Editor, Standalone Game ni dans une application empaquetée.

• Supposer que le commandlet chargera le niveau automatiquement : la source précise que le commandlet ne charge pas les niveaux de lui-même.

• Lancer le script trop tôt : le guide déconseille d’exécuter un script avec la commande py dans le paramètre de démarrage ExecCmd ; l’environnement de l’éditeur ou le niveau de démarrage risque de ne pas être prêt.

• Négliger le caractère expérimental : la prise en charge de Python est qualifiée d’expérimentale. Il convient de procéder à des tests contrôlés, notamment pour les projets destinés à être livrés ou publiés.

Conséquences pour les workflows d’architecture et de visualisation

Pour les architectes, architectes d’intérieur et équipes archviz qui créent des scènes dans Unreal Engine, Python peut servir de base à des scripts pour les tâches répétitives dans l’éditeur, la gestion du contenu et le placement d’éléments dans les niveaux. Les sources ne proposent toutefois aucun script d’automatisation architecturale précis : l’adaptation au workflow dépend du contenu du projet et du code à écrire. La console est un bon point de départ pour de brefs essais, tandis que l’exécution depuis un fichier se prête davantage aux scripts réutilisables.

Les sources ne mentionnent pas non plus de carte graphique puissante, de licence payante ou d’exigence de compte. Il est donc impossible d’en tirer une conclusion ferme sur les avantages matériels ou financiers. Pour les équipes, les principaux points à vérifier sont l’activation des plugins dans le projet, le contexte de l’éditeur dans lequel le script s’exécute et la compatibilité de cette fonctionnalité expérimentale avec le processus de livraison.

Étapes suivantes

Commencez par activer les plugins dans un projet de test, puis comparez les méthodes d’exécution depuis la console et le menu File. Transférez ensuite les opérations ponctuelles dans un fichier ; pour les tâches de préparation récurrentes, envisagez des scripts de démarrage du projet. Si vous devez utiliser Python avec Blueprint, gardez à l’esprit que les nœuds Python ne sont disponibles que dans des classes d’éditeur telles que Editor Utility Widget et Editor Utility Blueprint. Selon la source, le nœud Execute Python Script exécute un extrait de code, pas un fichier ; l’option Execute Python Command permet d’exécuter un fichier ou du code. Les messages d’erreur sont visibles dans le panneau Output Log.

Sources et licence

Ce guide a été préparé à partir des ressources d’Epic Games sur la prise en main de Python dans Unreal Editor et de la documentation de l’API Python. Les pages sources ont été fournies sous une licence libre pour ce contenu ; le texte a été réécrit et adapté en turc.