Programmer l'Unreal Editor avec Python

Dans cette page, nous vous expliquons comment utiliser Python dans l'Unreal Editor.

Pourquoi choisir Python ?

Ces dernières années, Python est devenu le langage de facto pour les pipelines de production et l'interopérabilité entre les applications 3D, en particulier dans l'industrie du multimédia et du divertissement. Cela est probablement dû au fait que de nombreuses applications prennent en charge ce langage. Alors que la complexité des pipelines de production continue de croître et que le nombre d'applications impliquées ne cesse d'augmenter, disposer d'un langage de programmation commun facilite la création et la maintenance de systèmes de gestion des ressources à grande échelle.

Même sans ces considérations externes, ou sans la nécessité de travailler avec d'autres applications, Python est un excellent choix si vous cherchez à automatiser vos flux de travail dans l'Unreal Editor. Relativement facile à prendre en main pour les débutants en programmation, Python offre la possibilité de créer des interfaces utilisateur complexes et riches en fonctionnalités grâce à des modules tels que PySide ; par ailleurs, de nombreux autres modules utiles sont disponibles gratuitement aux membres de la communauté afin de leur faciliter la tâche.

Vous pouvez utiliser Python dans l'Unreal Editor pour effectuer les opérations suivantes :

• Créer des pipelines ou des flux de travail de gestion des ressources à plus grande échelle, qui associent l'Unreal Editor à d'autres applications 3D que vous utilisez dans votre organisation.

• Automatiser les tâches de gestion des ressources chronophages dans l'Unreal Editor, notamment la génération des maillages de niveau de détail (LOD) pour les maillages statiques.

• Disposer de façon procédurale du contenu dans un niveau.

• Contrôler l'Unreal Editor à partir d'interfaces utilisateur créées dans Python.

Configurer votre projet pour utiliser Python

La prise en charge de Python dans l'Unreal Editor est assurée par le plug-in Python Script Editor. Vous devez activer ce plug-in sur le projet sur lequel vous travaillez avant de pouvoir exécuter des scripts Python dans l'éditeur.

Pour activer le plug-in :

1. Ouvrez votre projet et choisissez Modifier > Plug-ins dans le menu principal.

2. Dans la fenêtre Plug-ins, accédez à la section Programmation.
   Recherchez le plug-in Python Script Editor dans le panneau de droite et cochez la case Activé.

   

   Vous devez également activer le plug-in Editor Scripting Utilities, qui propose des API simplifiées pour de nombreuses tâches courantes dans l'éditeur. Pour en savoir plus, consultez la page Scripting and Automating the Editor (Programmer et automatiser l'éditeur).

3. Redémarrez l'éditeur.

Python 3.11.8

Le plug-in Python Script Editor contient une version intégrée de Python 3.11.8.

Autrement dit, vous n'avez pas besoin d'installer Python séparément sur votre ordinateur.

Modes d'exécution du code Python dans l'Unreal Editor

Il existe différentes façons d'exécuter des scripts Python dans l'Unreal Editor, chacune étant conçue pour un cas d'utilisation différent. Vous pouvez choisir la méthode qui correspond le mieux à vos besoins.

La console Python dans le journal de sortie

Vous pouvez utiliser l'option de la barre de commandes de la console de l'Unreal Editor pour accepter le code Python plutôt que les commandes de la console Unreal.

Pour cela, vous pouvez soit utiliser le panneau Journal de sortie, comme indiqué ci-dessus, soit afficher la barre de commandes de la console en appuyant sur la touche ~.

Lorsque la console est en mode Python :

• Vous pouvez saisir des lignes de code Python dans cette console et demander à l'éditeur de les exécuter immédiatement, exactement comme si vous utilisiez une console Python interactive dans une fenêtre de commande. C'est la seule façon d'exécuter du code Python ligne par ligne ; toutes les autres approches répertoriées ci-dessous exécutent le fichier de script que vous spécifiez.

• Vous pouvez exécuter plusieurs lignes de code à la fois en utilisant les touches Maj + Entrée pour séparer chaque ligne, ou en collant un bloc multiligne copié depuis un éditeur de texte.

• Pour exécuter des fichiers de script Python, il vous suffit de saisir le nom du fichier dans la console. Si votre script Python nécessite des arguments de ligne de commande supplémentaires, ajoutez-les après le nom du script.

La commande py de la console

Lorsque la console est en mode Cmd, vous pouvez utiliser la commande py pour exécuter le reste de la ligne en tant que code Python, exactement comme si vous l'aviez saisi dans la console Python décrite ci-dessus.

Par exemple, la commande suivante exécute le fichier de script spécifié :

Ligne de commande

py "C:\MyScripts\my_script.py"

Le menu Fichier

Le menu Fichier de la fenêtre principale de l'Unreal Editor propose de nouvelles options qui permettent d'exécuter les fichiers de script Python.

• Utilisez l'option Exécuter le script Python pour accéder à un nouveau fichier de script sur votre ordinateur que vous n'avez pas encore exécuté.

• Utilisez la liste Scripts Python récents pour réexécuter un script préalablement exécuté. Le fichier est relu depuis le disque de sorte que, si vous avez modifié le script entre-temps, c'est la nouvelle version qui est exécutée.

La ligne de commande

Si vous lancez l'Unreal Editor à partir de la ligne de commande ou via un script, vous pouvez spécifier un fichier de script Python dans les arguments de ligne de commande. Si votre script Python nécessite des arguments de ligne de commande supplémentaires, ajoutez-les après le nom du script.

Il existe deux façons d'exécuter un script Python à partir de la ligne de commande. Dans les deux cas, l'éditeur s'arrête immédiatement après l'exécution de votre script Python.

Option 1 : Éditeur complet Dans cette approche, la version intégrale de l'Unreal Editor est lancée, le projet spécifié s'ouvre, le niveau de démarrage par défaut se charge, et votre script Python est exécuté une fois tous les éléments chargés et prêts. Cette approche est intéressante si votre script doit interagir avec le contenu de votre projet ou d'un niveau dont le chargement peut prendre un certain temps.

Ajoutez l'argument ExecutePythonScript dans la ligne de commande et définissez sa valeur sur le chemin et le nom du script Python à exécuter. Par exemple :

Ligne de commande

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

Option 2 : Applet de commande Très rapide à mettre en œuvre, cette approche permet en outre d'exécuter vos scripts sans passer par l'interface utilisateur de l'éditeur.

Ajoutez les arguments suivants à la ligne de commande pour UnrealEditor-Cmd.exe : -run=pythonscript -script=<script_file_or_code>. <script_file_or_code> prend l'une des valeurs suivantes :

• Le chemin et le nom de fichier d'un script Python que vous souhaitez exécuter.

• Les instructions et commandes Python que vous souhaitez exécuter. Le cas échéant, vous pouvez utiliser \n dans la chaîne pour échapper les sauts de ligne.

Par exemple :

Ligne de commande

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

or:

Ligne de commande

> UnrealEditor-Cmd.exe "C:\projects\MyProject.uproject" -run=pythonscript -script="a=5 \nb=10 \nc=a+b \nf=open('D:\myfile.txt','w+') \nf.write(str(c)) \nf.close()"

Cet applet de commande ne charge pas automatiquement les niveaux. Par conséquent, lorsque vous rédigez votre script, commencez par ajouter la ligne suivante :

Ligne de commande

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

Le fichier init_unreal.py

Si l'éditeur détecte un fichier de script appelé init_unreal.py dans l'un des chemins pour lesquels il est configuré (consultez la section "Chemins Python dans l'Unreal Editor" ci-dessous), il exécute automatiquement ce script.

Cette approche est utile lorsque vous travaillez sur un projet ou un plug-in et que vous savez que tous les utilisateurs de ce contenu doivent exécuter le même code d'initialisation à chaque démarrage de l'éditeur. Vous pouvez placer votre code d'initialisation dans un script portant ce nom, puis le placer dans le dossier Content/Python de ce projet ou plug-in.

Scripts de démarrage

Dans les paramètres du projet, vous pouvez préciser le nombre de scripts Python que vous souhaitez exécuter chaque fois que vous ouvrez ce projet. L'éditeur exécute ces scripts une fois le niveau de démarrage par défaut complètement chargé.

Sélectionnez Modifier > Paramètres du projet…. Dans la liste Plug-ins, sélectionnez Python. Ensuite, ajoutez vos scripts au paramètre Scripts de démarrage :

Redémarrez l'Unreal Editor au terme de cette procédure. La prochaine fois que l'éditeur charge votre projet, il doit exécuter vos nouveaux scripts de démarrage.

Blueprints réservés à l'éditeur

Le plug-in Python Script Editor expose de nouveaux nœuds au système de programmation visuelle Blueprint, que vous pouvez utiliser pour exécuter des extraits de code Python ou des fichiers Python lors de l'évaluation d'un graphique Blueprint.

Les nœuds suivants sont disponibles dans la section Python > Exécution de la palette Blueprint.

	Execute Python Script	Exécute le code Python littéral que vous fournissez ou que vous saisissez dans l'entrée Commande Python. Nous vous recommandons de choisir cette méthode pour appeler Python à partir de blueprints, qui remplace la création d'un nouveau type BlueprintFunctionLibrary(BPFL) dans Python. La méthode BPFL mentionnée ci-dessus pose des problèmes lors de l'enregistrement ou du chargement d'une ressource, car les types générés par Python sont transitoires. Cette méthode n'est donc plus officiellement prise en charge. Le nœud Execute Python Script peut comporter des broches d'entrée et de sortie personnalisées, qui sont disponibles en tant que variables dans le script Python sur le nœud et peuvent être ajoutées par les propriétés du nœud. -Les entrées sont définies avant l'exécution du script Python sur le nœud et peuvent être lues dans le script. -Les sorties sont lues après l'exécution du script Python sur le nœud et peuvent être définies dans le script. Le nœud Execute Python Script peut contenir plusieurs lignes de code Python ; vous pouvez saisir de nouvelles lignes en utilisant les touches Maj + Entrée. La sortie Réussite ? est définie sur true si le code Python a été correctement exécuté, ou sur false dans le cas contraire. Si la valeur est définie sur false, les erreurs sont consignées dans le journal de sortie. Ce nœud ne peut pas exécuter de fichiers. Il peut exécuter uniquement des lignes de code Python.
	Execute Python Command	Ce nœud exécute le fichier ou le code Python que vous transmettez ou saisissez dans l'entrée Script Python. Le nœud tente de déterminer, en fonction de votre saisie, s'il s'agit d'un code littéral ou d'un nom de fichier. -La sortie Valeur de retour est définie sur true si le code ou le fichier Python a été correctement exécuté, ou sur false dans le cas contraire. Si la valeur est définie sur false, les erreurs sont consignées dans le journal de sortie.
	Execute Python Command (Advanced)	Ce nœud exécute le fichier ou le code Python que vous transmettez ou saisissez dans l'entrée Script Python. Ce nœud est similaire au nœud Execute Python Command, mais il propose des entrées et des sorties supplémentaires qui peuvent être utiles dans certains cas. Mode d'exécution indique la façon dont vous souhaitez interpréter l'entrée Script Python. Sélectionnez Exécuter le fichier pour forcer la commande à traiter votre entrée comme le nom d'un fichier, et à tenter de rechercher et d'exécuter ce fichier. Les valeurs renvoyées par ce script sont consignées dans le journal. Sélectionnez Exécuter le script pour forcer la commande à traiter votre entrée comme un véritable code Python et à l'exécuter tel quel. Les valeurs renvoyées par ce script sont consignées dans le journal. Sélectionnez Évaluer le script pour forcer la commande à traiter votre entrée comme code Python littéral, à l'évaluer tel quel et à renvoyer toutes les valeurs générées par le script dans la sortie Résultat de la commande. Si vous transmettez un nom de fichier à l'entrée Script Python, le champ Étendue du fichier d'exécution détermine si le fichier est exécuté dans l'étendue globale (publique) ou dans une étendue en bac à sable (privée). Si vous souhaitez que le code de votre fichier puisse accéder aux variables, fonctions, etc., déjà définies dans l'environnement Python, vous devez sélectionner Publique. Notez cependant que cette étendue permet également au fichier Python de redéfinir des variables et des fonctions. Cette approche peut entraîner un comportement inattendu. Par conséquent, il peut être plus sûr d'utiliser l'étendue Privée. La sortie Résultat de la commande dépend du mode d'exécution. Lorsque l'entrée Script Python est correctement exécutée ou évaluée et que le mode d'exécution est défini sur Évaluer le script, cette sortie renvoie la valeur générée par le script. Lorsque l'entrée Script Python est correctement exécutée ou évaluée et que le mode d'exécution est défini sur Exécuter le fichier ou Exécuter le script, cette sortie renvoie Aucun. Si l'entrée Script Python n'est pas correctement exécutée ou évaluée, cette sortie contient des informations sur l'erreur. La sortie de journal permet d'accéder à la liste complète des messages consignés dans le journal Python durant l'exécution du script ou du fichier d'entrée. Vous pouvez parcourir cette matrice si vous avez besoin de rechercher des messages spécifiques écrits par le script. La sortie Valeur de retour est définie sur true si le code Python a été correctement exécuté, ou sur false dans le cas contraire. Si la valeur est définie sur false, les erreurs sont consignées dans le journal de sortie du moteur, dans la broche de sortie Sortie du journal et dans le résultat de commande.

Environnement et chemins Python dans l'Unreal Editor

Lorsque vous utilisez un chemin relatif pour exécuter un script Python ou pour importer un autre module de script à l'aide de la commande Importer dans l'un de vos scripts, le script que vous exécutez ou importez peut se trouver dans n'importe quel chemin répertorié dans la variable sys.path de votre environnement Python.

L'Unreal Editor ajoute automatiquement plusieurs chemins à cette liste sys.path :

• Le sous-dossier Content/Python du dossier de votre projet.

• Le sous-dossier Content/Python dans l'installation principale de l'Unreal Engine.

• Le sous-dossier Content/Python dans le dossier de chaque plug-in activé.

• Le dossier Documentation/UnrealEngine/Python dans votre répertoire utilisateur. Par exemple, sous Windows 10, il s'agit de C:/Users/nom d'utilisateur/Documents/UnrealEngine/Python.

Vous pouvez également ajouter vos propres chemins à cette liste en procédant de l'une des façons suivantes :

• Dans le menu Paramètres du projet. Sélectionnez Modifier > Paramètres du projet…. Dans la liste Plug-ins, sélectionnez Python. Il suffit ensuite d'ajouter les chemins au paramètre Chemins supplémentaires. Redémarrez l'Unreal Editor au terme de cette procédure.

  

• Ajoutez les chemins d'accès à la valeur de la variable d'environnement UE_PYTHONPATH (ou PYTHONPATH si vous avez désactivé l'option d'environnement d'interpréteur isolé de l'éditeur) de votre système d'exploitation, puis redémarrez l'Unreal Editor.

• Ajoutez les chemins directement à la liste sys.path dans un script Python ou dans la console Python.

Pour en savoir plus, consultez la documentation de l'option Python sys.path.

Par défaut, l'interpréteur Python intégré à l'Unreal Engine fonctionne en mode isolé. Vous pouvez désactiver le mode isolé en sélectionnant Modifier > Paramètres du projet > Plug-ins > Python > Isoler l'environnement d'interpréteur

Pour en savoir plus, consultez la documentation de l'option de ligne de commande Python -l.

La variable d'environnement UE_PYTHONPATH est toujours analysée par le moteur et son contenu est ajouté à sys.path, quelles que soient les options du mode d'isolement sélectionnées. La variable UE_PYTHONPATH a la même fonction que la variable PYTHONPATH, mais elle ne doit jamais être modifiée par un logiciel tiers.

À propos de l'API Python de l'Unreal Editor

Le plug-in Python Script Editor expose un grand nombre de classes et de fonctions que vous pouvez utiliser pour interagir avec l'Unreal Editor, les ressources de votre projet et le contenu de vos niveaux. Cette API est entièrement contenue dans le module Unreal. Pour y accéder, importez ce module au début de n'importe quel script Python que vous exécutez dans l'environnement Python de l'éditeur :

import unreal

Le module Unreal expose pratiquement tous les éléments exposés en C++ aux blueprints dans l'environnement de votre éditeur. Il n'est pas préalablement généré ; il réplique automatiquement tous les éléments disponibles dans les blueprints de votre éditeur. Lorsque vous activez de nouveaux plug-ins dans l'Unreal Editor, tous les éléments que ces plug-ins exposent aux blueprints deviennent également disponibles dans Python. Il en va de même pour le code C++ que vous rédigez dans votre projet et exposez dans les blueprints.

L'API Python s'efforce d'exposer les API natives d'Unreal de la manière la plus conviviale possible pour les développeurs Python. Par exemple :

• Les types de données simples sont convertis de manière transparente entre Python et les types natifs chaque fois que cela est nécessaire.
  Lorsque vous transmettez une liste, un ensemble ou un dictionnaire Python, cet élément est automatiquement converti en matrice, en ensemble ou en carte Unreal. Lorsque vous récupérez une liste, un ensemble ou un dictionnaire renvoyé par une fonction d'API, vous obtenez en réalité une instance d'une classe Unreal, mais son API est totalement cohérente avec la liste, l'ensemble ou le dictionnaire de base Python.

• Les classes Python conservent la même hiérarchie d'héritage que les types natifs qu'elles représentent. Autrement dit, vous pouvez utiliser les fonctions Python intégrées isinstance() et type() pour vérifier si un objet dérive d'une classe donnée ou correspond à une classe spécifique.

• L'API tente de trouver un bon équilibre entre les conventions d'affectation de noms utilisées dans l'Unreal Engine pour C++ et Blueprints d'une part, et les conventions d'affectation de noms de Python d'autre part. Les classes et les objets de l'API Python portent les mêmes noms que dans Blueprints. Ils sont généralement identiques à leur type natif, sans le préfixe (par exemple : U ou T). Les noms de fonction et de propriété sont automatiquement exposés au format snake_case, en minuscules. Ainsi, par exemple, vous appelez généralement des fonctions telles que unreal.StaticMeshActor.get_actor_transform(). Les noms des valeurs d'énumération sont automatiquement exposés au format SNAKE_CASE, en majuscules.

• Toutes les fonctions exposées peuvent accepter soit des paramètres ordonnés, soit des paramètres nommés dans n'importe quel ordre. Par exemple, les deux appels de fonction suivants sont exactement équivalents :

  C++

  unreal.get_editor_subsystem(unreal.StaticMeshEditorSubsystem).join_static_mesh_actors(list_of_actors, my_options)
      unreal.get_editor_subsystem(unreal.StaticMeshEditorSubsystem).join_static_mesh_actors(join_options=my_options, actors_to_join=list_of_actors)

  Copy full snippet(2 lines long)

Référence d'API

Pour en savoir plus sur l'ensemble des classes et fonctions exposées par l'API Python d'Unreal, consultez la référence d'API suivante :

Référence d'API Python de l'Unreal Editor

Pratiques recommandées pour utiliser l'API Python

Dans cette section, nous abordons plusieurs thèmes qu'il est important de garder à l'esprit lorsque vous utilisez l'API Python.

Utilisation des ressources

Si vous devez utiliser des ressources dans votre projet, veillez à toujours faire appel aux fonctions de l'API Python d'Unreal. N'utilisez jamais de module de gestion de fichiers intégré à Python pour travailler directement avec vos fichiers de ressources sur disque. Par exemple, si vous devez déplacer une ressource vers un dossier différent, n'utilisez pas les fonctions Python telles que os.rename ou shutil.move. Les ressources et projets Unreal contiennent des recommandations de contenu internes que vous pouvez rompre si vous ne respectez pas cette règle.

Nous vous recommandons plutôt d'utiliser l'API Unreal.EditorAssetLibrary, fournie par le plug-in Editor Scripting Utilities, ou la classe Unreal.AssetTools intégrée à l'API Python d'Unreal.

Modifier les propriétés de l'éditeur

Vous pouvez utiliser Python pour accéder aux objets de votre projet et paramétrer de nombreuses propriétés de configuration pour ces objets par programmation. Par exemple, votre script Python peut accéder aux acteurs de maillage statique dans le niveau actuel et définir différentes propriétés, notamment déterminer si les acteurs peuvent subir des dégâts ou s'ils doivent être masqués dans le jeu. Vous pouvez également récupérer leurs composants de maillage statique et configurer des propriétés sur ces composants, par exemple leurs paramètres Lightmass, voire la ressource de maillage statique à laquelle ils sont liés.

Ces propriétés peuvent être exposées dans Python de deux façons :

• Les objets avec l'indicateur BlueprintReadOnly ou BlueprintReadWrite sont exposés en tant que propriétés simples sur l'objet.
  Vous pouvez lire et modifier ces propriétés de la même façon que vous accédez à n'importe quelle propriété d'objet Python.

• Les objets avec l'indicateur ViewAnywhere ou EditAnywhere sont exposés en tant que "propriétés d'éditeur".
  Vous pouvez lire ces valeurs et les écrire à l'aide d'une paire de fonctions spéciales exposée par chaque objet, à savoir set_editor_property() et get_editor_property().

La référence d'API de chaque classe comporte une liste des propriétés d'éditeur, située juste après la description de la classe. Il s'agit de toutes les valeurs que vous pouvez définir et obtenir avec ces fonctions set_editor_property() et get_editor_property() Chaque fois que vous devez définir ou obtenir une propriété de configuration sur un objet, consultez d'abord cette liste pour savoir si la propriété souhaitée y figure.

• Lorsque vous devez lire une valeur qui est exposée à la fois comme propriété d'objet et comme propriété d'éditeur, le résultat de l'accès direct à la propriété est généralement le même que celui obtenu en appelant la fonction get_editor_property(). Toutefois, la fonction get_editor_property() permet généralement d'accéder à des propriétés qui ne sont pas exposées directement sur l'objet Python.

• Lorsque vous devez définir une valeur qui est exposée à la fois comme propriété d'objet et comme propriété d'éditeur, vous devez, dans la plupart des cas, utiliser la fonction set_editor_property() pour définir la valeur plutôt que de définir la valeur directement sur l'objet. Lorsque vous modifiez les propriétés dans l'interface utilisateur, l'éditeur effectue fréquemment des opérations supplémentaires en arrière-plan, à savoir des modifications pré et post-édition. Ces opérations répondent généralement aux choix que vous effectuez et synchronisent l'interface utilisateur de l'éditeur avec l'état de l'objet dans le monde du jeu. Si vous modifiez ces propriétés directement sur l'objet Python, le code de l'éditeur n'est pas exécuté automatiquement. D'autre part, lorsque vous appelez set_editor_property() pour définir l'état d'une propriété, vous déclenchez ce code de pré et post-édition, exactement comme si vous aviez modifié le paramètre dans le panneau Détails de l'interface utilisateur de l'éditeur.

Par exemple, les objets du lecteur multimédia disposent d'un paramètre Lire à l'ouverture :

Celui-ci est exposé dans la classe unreal.MediaPlayer du membre de classe play_on_open :

import unreal
		obj = unreal.MediaPlayer()
		# Modifying a property directly can have different results
		# than changing settings in the Editor UI.
		# Generally you'll want to avoid setting these values directly, like this:
		obj.play_on_open = True
		# This way of accessing the property will have exactly the same
		# result as changing the setting in the Editor UI:
		obj.set_editor_property("play_on_open", True)
		# Both ways of reading the value are equivalent.

Utiliser les types Unreal autant que possible

Si vous devez recourir aux utilitaires disponibles dans l'API Python d'Unreal, tels que les classes pour les opérations mathématiques ou la manipulation de coordonnées 3D, nous vous recommandons d'utiliser les utilitaires d'Unreal plutôt que vos propres implémentations. Les versions Unreal sont optimisées pour offrir les meilleures performances dans l'environnement du moteur.

Par exemple, pour manipuler les coordonnées dans un espace 3D, utilisez la classe unreal.Vector :

import unreal
    v1 = unreal.Vector()
    v1.x = 10
    v2 = unreal.Vector(10, 20, 30)
    v3 = (v1 + v2) * 2
    print(v3)

Journalisation et commentaires

L'objet unreal expose des fonctions que vous pouvez utiliser dans votre code pour envoyer des messages de journalisation, d'avertissement et d'erreur via le système de messagerie utilisé par tous les sous-systèmes du moteur et de l'éditeur. Nous vous recommandons d'utiliser ce framework de journalisation standardisé chaque fois que votre script doit envoyer un message à l'utilisateur.

• Utilisez unreal.log() pour les messages d'information. Pour plus de commodité, la fonction print() de Python a également été implémentée pour passer par unreal.log() en interne.

• Utilisez unreal.log_warning() pour informer les utilisateurs de problèmes potentiels.

• Utilisez unreal.log_error() pour les problèmes graves qui empêchent votre script de s'exécuter comme prévu.

Vos messages s'affichent dans le panneau Journal de sortie, y compris les messages envoyés par d'autres sous-systèmes :

Prise en charge du système Annuler et Répéter

Vos scripts peuvent tirer pleinement parti du système Annuler/Répéter intégré à l'Unreal Editor.

Chaque transaction que vous définissez peut contenir un nombre illimité d'opérations Python. Ces transactions vous permettent de regrouper des opérations volumineuses ou des opérations sur plusieurs objets différents en une seule entrée dans l'historique d'annulation/de répétition. En règle générale, si votre script a pour but d'effectuer une modification spécifique sur plusieurs objets, évitez d'enregistrer chaque modification séparément dans l'historique d'annulation/de répétition. Il est préférable de disposer d'une seule entrée pour annuler toutes les modifications apportées à tous les objets.

Pour définir une transaction, utilisez l'étendue unreal.ScopedEditorTransaction. Par exemple, si vous exécutez ce code :

import unreal
	obj = unreal.MediaPlayer()
	with unreal.ScopedEditorTransaction("My Transaction Test") as trans:
		obj.set_editor_property("play_on_open", False)
		obj.set_editor_property("vertical_field_of_view", 80)

Le panneau Historique d'annulation de l'éditeur répertorie désormais cette transaction par nom :

En règle générale, vos transactions contenues dans une étendue peuvent inclure toutes les opérations pouvant également être annulées dans l'interface utilisateur de l'éditeur. Cependant, toutes les opérations de l'éditeur ne peuvent pas être annulées. Par exemple, vous ne pouvez pas annuler l'importation d'un modèle dans l'interface utilisateur de l'éditeur ; par conséquent, tenter d'importer un modèle dans une étendue unreal.ScopedEditorTransaction risque d'entraîner un comportement inattendu.

Boîtes de dialogue de progression pour les opérations lentes

Si vos scripts doivent agir sur plusieurs ressources ou acteurs au cours d'une même opération, leur exécution peut prendre un certain temps. Cependant, lorsque l'Unreal Editor exécute un script Python, son interface utilisateur se bloque et ne répond plus aux interactions des autres utilisateurs. Pour informer l'utilisateur de la progression d'une tâche volumineuse et éviter que l'éditeur se bloque, vous pouvez utiliser l'étendue unreal.ScopedSlowTask.

Par exemple :

import unreal
    total_frames = 100
    text_label = "Working!"
    with unreal.ScopedSlowTask(total_frames, text_label) as slow_task:
        slow_task.make_dialog(True)               # Makes the dialog visible, if it isn't already
        for i in range(total_frames):
            if slow_task.should_cancel():         # True if the user has pressed Cancel in the UI
                break
            slow_task.enter_progress_frame(1)     # Advance progress by one frame.
                                                # You can also update the dialog text in this call, if you want.