Système d'outils scriptables

Le système d'outils scriptables offre des fonctions et un mode Éditeur permettant de créer des outils interactifs personnalisés. L'objectif de ce système est de permettre aux programmeurs qui n'utilisent pas le langage C++ de créer des outils interactifs dans l'Unreal Engine.

Le principal point de référence pour un outil interactif est le mode Modélisation de l'éditeur. Cependant, le système d'outils scriptables n'a pas de connexion directe avec le mode Modélisation ou le plug-in Geometry Scripting.

Le plug-in du système d'outils scriptables expose le framework d'outils interactifs à Blueprint (BP), afin de donner aux créateurs et aux artistes techniques les moyens de concevoir des outils qui se comportent de la même manière que le mode Modélisation.

Nous vous recommandons de vous familiariser avec les principes fondamentaux concernant des blueprints avant de commencer à créer des outils scriptables. Pour en savoir plus, consultez la rubrique Introduction aux blueprints.

En créant des sous-classes de blueprint (BP) des classes de base, vous pouvez ajouter des outils personnalisés au mode Éditeur des Outils scriptables. Le mode Éditeur permet aux artistes d'accéder à ces outils personnalisés pour leurs projets.

À quoi sert un outil scriptable ?

Vous pouvez utiliser un outil scriptable dans les cas suivants :

• Exécuter des graphiques de blueprint (BP) arbitraires lors de la configuration et de l'arrêt de l'outil, ainsi que lors du tick.
• Générer la géométrie 3D de base (par exemple, lignes et points) et la géométrie de l'ATH 2D (par exemple, texte à des emplacements 3D projetés).
• Ajouter des ensembles de propriétés à un outil, définis via des blueprints, qui font office de paramètres d'outil visibles par l'utilisateur.
• Écouter les modifications apportées à ces paramètres d'ensembles de propriétés et y répondre.
• Créer un ou plusieurs gadgets 3D, contrôler leurs positions et répondre aux modifications de transformation.
• Fournissez des commentaires à l'utilisateur.
• Ajouter des comportements d'appareil d'entrée, comme le clic de souris, le survol de la souris et les observateurs de clavier, et exécuter des graphiques de blueprint sur leurs événements clés.
• S'intégrer aux widgets Blueprint Slate (UMG) pour fournir une interface utilisateur (IU) personnalisée, comme dans les widgets de hublot.
• Définir les conditions personnalisées de démarrage de l'outil en fonction des sélections de scène en cours.

Vous pouvez associer les outils scriptables à d'autres fonctionnalités du moteur, notamment la génération procédurale de contenu (PCG) et Motion Design.

Pour obtenir un aperçu du système et de la façon dont les développeurs l'utilisent avec d'autres fonctionnalités pour créer un donjon, regardez la vidéo Geometry Scripting and Scriptable Tools | Unreal Fest 2024.

Accéder au mode Éditeur et aux nœuds des outils scriptables

Activer le plug-in

Pour utiliser le mode Éditeur des outils scriptables et accéder aux nœuds, vous devez activer le plug-in associé.

Pour activer le plug-in ou vous assurer qu'il est activé, procédez comme suit :

1. Dans la barre de menus, sélectionnez Modifier > Plug-ins.

2. Dans la barre de recherche, saisissez "scriptable tools".

3. Activez le plug-in Scriptable Tools Editor Mode et sélectionnez Oui dans la boîte de dialogue contextuelle.

Vous n'avez pas besoin d'activer le module Scriptable Tools Framework Le mode Éditeur l'inclut automatiquement.

Mode Éditeur

Vous accédez à tous les outils scriptables à partir du mode Éditeur Outils scriptables. Pour ouvrir le mode Éditeur, cliquez sur le menu déroulant Mode de sélection dans l'éditeur de niveau.

Chaque outil apparaît dans une palette d'outils gérée automatiquement dans le mode Éditeur, et les ensembles de propriétés d'un outil actif apparaissent dans le panneau des paramètres. Pour en savoir plus sur les modes de l'éditeur, consultez la rubrique Modes de l'éditeur de niveau.

La palette d'outils comprend une option de filtre qui affiche les outils en fonction d'une balise de groupe. Cette fonctionnalité permet de regrouper les outils et de sélectionner les groupes d'outils à charger dans le mode Éditeur. Le regroupement permet donc d'organiser un projet comportant plusieurs outils, ce qui peut réduire la charge cognitive qu'implique l'affichage de tous les outils.

Nœuds de blueprint

Pour créer des outils qui apparaissent dans le mode Éditeur, utilisez les fonctions d'outil scriptable exposées dans les blueprints. Vous pouvez utiliser une classe de blueprint ou le blueprint d'utilitaire d'éditeur pour accéder à la classe de base de l'outil scriptable. Pour en savoir plus sur la classe de base et la sous-classe, consultez la rubrique Classes de l'outil scriptable de cette page.

Dans l'éditeur de blueprint, tous les nœuds des outils scriptables se trouvent dans le sous-menu Scritpable Tool (Outil scriptable).

Sous-menu Scriptable Tool (Outil scriptable) dans l'éditeur de blueprint.

Pour obtenir une liste complète des fonctions, consultez la documentation de l'API Blueprint et Python

Différences entre l'outil scriptable et le widget Utilitaire d'éditeur

Un widget Utilitaire d'éditeur (EUW) est une fenêtre de dialogue non modale contenant une interface utilisateur personnalisée créée avec un constructeur d'interface utilisateur graphique visuelle, où vous pouvez créer tout type de script d'éditeur. Bien qu'il s'agisse d'une fonctionnalité extrêmement puissante, elle présente certaines limites du fait qu'elle est disponible dans une fenêtre non modale.

Un outil interactif (la pierre angulaire des outils scriptables) est modal. Modal signifie qu'aucun autre outil ne peut être activé lorsque l'outil est actif et que l'état de l'éditeur est géré de manière plus stricte. Par exemple, l'outil s'arrête automatiquement avant d'enregistrer, de changer de niveau ou de démarrer Play In Editor (PIE), et l'enregistrement automatique est différé jusqu'à ce que vous quittiez l'outil. Cette fonctionnalité signifie qu'il est plus sûr d'effectuer certaines tâches au sein d'un outil qu'autrement. Par exemple, si vous créez des acteurs temporaires dans un niveau, puis les détruisez lors de l'arrêt de l'outil, ils ne sont pas enregistrés par accident.

De même, en tant qu'état modal, un outil peut capturer la souris plus efficacement.

En matière d'interface utilisateur, un outil scriptable est plus structuré qu'un EUW. Vous pouvez définir les ensembles en tant qu'objets BP distincts avec des variables publiques. Ces variables publiques sont ensuite affichées dans un panneau de paramètres standard du mode Éditeur.

Bien que les outils scriptables soient disponibles lors de l'exécution, certaines infrastructures supplémentaires doivent être configurées pour pouvoir les utiliser dans un projet UE.

Par ailleurs, les outils scriptables offrent un emplacement plus centralisé pour découvrir tous les outils disponibles dans le projet et y accéder, tandis que les EUW sont principalement accessibles à partir du navigateur de contenu, laissant à l'utilisateur le soin de gérer la découverte et l'organisation.

Classes des outils scriptables

UScriptableInteractiveTool est la classe de base pour tous les outils scriptables. Cette classe inclut des événements, des paramètres généraux tels que le nom de l'outil, des options de rendu, des gadgets, des fonctions de message, des options d'arrêt de l'outil et d'autres fonctions pour la sous-classe. Vous pouvez utiliser sa variante dans l'éditeur, UEditorScriptableInteractiveTool, pour donner accès aux fonctions BP réservées à l'éditeur.

UScriptableModularBehaviorTool et UEditorScriptableModularBehaviorTool sont les sous-classes permettant de prendre en charge les interactions de la souris et du clavier au sein de l'outil. Ces deux classes constituent les classes communes à utiliser, à moins que le comportement de la souris et du clavier ne soit pas nécessaire.

UScriptableClickDragTool est obsolète, mais les outils que vous avez précédemment créés à partir de cette classe continuent de fonctionner dans la dernière version de l'éditeur.

Lorsque vous créez une classe de blueprint ou un blueprint de widget d'utilitaire, vous devez sélectionner l'une des classes ci-dessus pour accéder aux nœuds des outils scriptables. Pour en savoir plus sur ces classes, consultez la rubrique Outil de base modulaire de cette page.

Paramètres des outils scriptables

La classe de base expose divers paramètres qui concernent principalement l'interface utilisateur du mode Éditeur des outils scriptables, mais elle contrôle également le comportement de l'outil. Lorsque vous ouvrez votre blueprint, le panneau Détails de l'outil contient les options suivantes.

Événements des outils scriptables

La classe Outil scriptable fournit un ensemble d'événements standard permettant à votre outil d'exécuter différentes tâches à différents moments. Il existe des événements standard pour chaque classe d'outil, et diverses fonctions supplémentaires sont disponibles dans les outils de base.

• Event On Script Setup (Événement lors de la configuration du script) : s'exécute une seule fois lors du lancement de l'outil. C'est généralement à cette étape que vous ajoutez des ensembles de propriétés, créez des objets d'aperçu, etc.

• Event On Script Tick (Événement lors du script avec tick) : exécute chaque tick de l'éditeur, comme les autres ticks.

• Event On Script Shutdown (Événement lors de l'arrêt du script) : s'exécute à l'arrêt de l'outil. Par exemple, lorsque l'utilisateur ferme explicitement l'outil, le mode le force à s'arrêter ou l'outil s'arrête tout seul.

• Event On Script Draw HUD (Événement sur l'ATH de génération du script) : exécute chaque image et s'exécute là où l'outil peut afficher un ATH 2D à partir d'un objet d'API d'ATH. Pour en savoir plus, consultez la section ci-dessous.

Event On Script Render (Événement lors du rendu du script) est une ancienne méthode de génération. L'événement s'exécute à chaque image et permet à l'outil de générer une géométrie 3D simple, comme des lignes et des points. Vous pouvez utiliser l'ancienne fonctionnalité, mais devez noter les points suivants :

• Dans la mesure où l'événement s'exécute en temps réel, les lignes sont nouvellement générées à chaque appel du mode de rendu.

• Il n'existe aucune référence persistante liée à la géométrie. Vous devez donc gérer les manipulations des primitives dans le blueprint.

Conditions personnalisées

Vous pouvez ajouter des conditions personnalisées basées sur les sélections de scène actuelles pour démarrer l'outil. Définissez les conditions personnalisées dans Class Defaults (Valeurs par défaut de la classe) > Details panel (panneau Détails) > Scriptable Tool Settings (Paramètres des outils scriptables) > Tool Setup Requirements (Conditions de configuration des outils) > Custom (Personnalisé).

La classe personnalisée contient les fonctions suivantes :

• OnCanBuildTool : doit être exécutée à chaque tick.

• OnSetupTool : s'exécute après les clics de l'utilisateur et avant l'exécution de l'outil.

Le graphique du générateur d'outils est exécuté à chaque tick, il est donc possible que des conditions complexes puissent ralentir les performances de l'éditeur.

Rendu des outils

Il est courant qu'un outil fournisse un retour visuel. L'une des façons de définir ce retour est de générer des acteurs temporaires. Par exemple, vous pouvez générer des acteurs de maillage dynamique temporaires avec des maillages générés de manière procédurale par Geometry Scripting. Néanmoins, une ligne ou un libellé de texte est souvent plus efficace.

Les outils scriptables prennent en charge ce rendu en fournissant des objets d'API avec un ensemble de nœuds UFunction.

Options de rendu

L'API Dessin des outils scriptables inclut des ensembles d'options de rendu pour les lignes, les points et les triangles. Chaque ensemble comprend des options relatives supplémentaires dans la catégorie Dessin.

Ces options de dessin sont allouées par l'outil et contiennent la géométrie. Grâce à ces ensembles, vous pouvez ajouter et supprimer la géométrie respective à tout moment de la durée de vie de l'outil et les mettre à jour selon vos besoins.

Le nœud Add Triangle Set inclut une option pour les quadrilatères.

Anciennes options

Vous exécutez les anciennes commandes de rendu dans le nœud d'événement Event On Script Render (Événement lors du rendu du script).

Comme nous l'avons indiqué précédemment avec cet événement :

• Vous pouvez remplacer à l'aide de l'API de rendu.

• Vous pouvez dessiner des lignes et des points.

• L'exécution se fait à chaque tick et disparaît au tick suivant.

• Aucune persistance.

Les événements de dessin ATH 2D et de rendu 3D sont appelés respectivement avec les objets DrawHUDAPI et RenderAPI. L'outil crée et gère ces objets d'API en interne. Le seul emplacement où vous pouvez y accéder est à partir de ces événements, car ils dépendent des informations d'état temporaires par image fournies par l'outil.

BP dispose également d'une bibliothèque standard de fonctions de débogage de dessin. Vous pouvez les utiliser comme alternative aux fonctions de dessin ATH et de rendu et les appeler à tout moment. Elles sont toutefois en phase de développement, et les API de rendu de l'outil offrent pour l'instant davantage de fonctionnalités.

Gadgets

Une autre fonctionnalité de la classe de base Outils scriptables est la possibilité de créer plusieurs gadgets de transformation 3D. Ce widget n'est pas le gadget d'éditeur standard, mais plutôt le gadget du mode Modélisation. Un ensemble de fonctions est fourni pour développer et gérer des gadgets et un événement pour répondre aux changements du gadget.

Les objets de gadget ne sont pas directement exposés aux blueprints. Au lieu de cela, vous générez un gadget avec une chaîne Identificateur, et les fonctions et événements du gadget fonctionnent à partir de cet identificateur.

Le gadget TRS de base combine des éléments de translation, de rotation et d'échelle pour tous les axes. Cependant, en personnalisant les options de gadget, vous pouvez créer des gadgets plus simples pour des tâches spécifiques, par exemple, activer uniquement la translation et la rotation dans le plan XY en désactivant les autres sous-éléments du gadget.

Messages de l'outil

L'API BP de l'outil scriptable standard offre diverses fonctions de message à l'utilisateur.

• Display User Help Message (Afficher le message d'aide à l'utilisateur) : met à jour une chaîne d'aide au bas de l'interface utilisateur de l'éditeur.

  

• Display User Warning Message (Afficher le message d'avertissement à l'utilisateur) : met à jour une chaîne dans le panneau Paramètres de l'outil.

  
• Clear User Messages (Effacer les messages à l'utilisateur) : efface les messages d'aide ou d'avertissement en cours.
• Add Log Message (Ajouter un message de journal) : affiche actuellement un message dans le journal de l'éditeur.

Les messages ci-dessus étant des chaînes FText, ils sont localisables. Actuellement, seul un avertissement peut s'afficher. Nous améliorerons cette fonction dans de prochaines versions.

Divers

Un outil scriptable s'exécute toujours dans le contexte d'un monde actuel. Par exemple, dans l'éditeur de niveau, il s'agit du monde du niveau standard. Vous pouvez utiliser la fonction Get Tool World (Obtenir le monde de l'outil) pour accéder à ce monde dans le contexte d'un outil.

Arrêt de l'outil

La procédure standard pour quitter un outil scriptable consiste à cliquer sur un bouton Accepter, Annuler ou Terminer disponible dans l'IU, mais vous pouvez arrêter explicitement un outil scriptable à partir de la fonction Request tool Shutdown (Demander l'arrêt de l'outil), que l'outil peut appeler lui-même. Cette fonction requiert un indicateur bAccept, qui n'est pertinent que pour les outils disposant de l'option Accepter ou Annuler l'arrêt et d'un message contextuel facultatif à l'attention de l'utilisateur.

Ensembles de propriétés de l'outil

Un outil scriptable peut exposer des widgets d'IU à l'utilisateur à partir des UObjects de l'ensemble de propriétés, qui s'affichent dans le panneau de paramètres d'un outil standard. Actuellement, il n'existe aucun moyen de personnaliser cette IU dans les blueprints. Seuls les paramètres de propriété standard (semblables à ceux d'un BP d'acteur) sont donc disponibles.

Pour créer un ensemble de propriétés, créez une sous-classe BP de type ScriptableInteractivetoolPropertySet, comme indiqué ci-dessous.

Vous pouvez ensuite ouvrir le BP de sous-classe de l'ensemble de propriétés en vue de le modifier et d'ajouter des variables membres publiques. Dans l'exemple ci-dessous, un type de variable booléenne, de nombre entier et d'énumération est ajouté.

Pour créer l'ensemble de propriétés dans un outil scriptable particulier, utilisez la fonction Add Property Set of Type (Ajouter un ensemble de propriétés de type). Cette fonction est généralement utilisée dans Event On Script Setup (Événement lors de la configuration du script), mais vous pouvez l'utiliser à tout moment.

Vous devez sélectionner le type de classe correspondant au paramètre Property Set Type (Type d'ensemble de propriétés). Choisissez le nom du type de la sous-classe de BP que vous avez créée ci-dessus. Vous devez aussi définir un identificateur unique pour chaque ensemble de propriétés (vous pouvez combiner plusieurs ensembles de propriétés dans un seul outil). Vous devrez probablement accéder à cet objet d'ensemble de propriétés ultérieurement. Nous vous recommandons de projeter la sortie d'Add Property Set Of Type (Ajouter un ensemble de propriétés de type) sur votre type de sous-classe de BP et de la stocker dans une variable locale.

Lorsque l'utilisateur crée une instance de votre outil scriptable, les variables membres publiques de votre ensemble de propriétés figurent dans le panneau de paramètres Outils scriptables situé à gauche, à côté de la palette d'outils.

(w:600)

La classe Outil scriptable dispose de diverses fonctions d'assistance pour travailler avec des ensembles de propriétés. Vous pouvez utiliser la fonction Remove Property Set by Name (Supprimer un ensemble de propriétés par nom) pour supprimer un ensemble de propriétés. Notez toutefois que cette action n'est pas nécessaire dans la plupart des cas. Si vous souhaitez simplement masquer ou afficher un ensemble de propriétés en fonction de certains critères ou d'un autre changement de paramètre, utilisez Set Property Set Visible by Name (Définir un ensemble de propriétés visible par nom).

De plus, vous pouvez utiliser l'option Save Property Set Settings (Enregistrer les paramètres de l'ensemble de propriétés) à l'arrêt de l'outil pour stocker les valeurs actuelles d'un ensemble de propriétés, et l'option Restore Property Set Settings (Restaurer les paramètres de l'ensemble de propriétés) pour récupérer les valeurs enregistrées lors de la configuration de l'outil. Par défaut, les mêmes valeurs sont restituées dans n'importe quel outil utilisant la classe Ensemble de propriétés. Cependant, une touche Enregistrer peut être fournie pour enregistrer ou restaurer différentes valeurs dans différents outils, voire au sein du même outil.

Observateurs de propriétés

L'une des fonctions courantes que vous souhaiterez probablement exécuter avec un ensemble de propriétés est de réagir aux changements de valeurs de propriété. La seule solution totalement fiable est d'interroger les changements de valeur dans la fonction de tick. Cependant, comme il s'agit d'un modèle courant, le système Outil scriptable offre des fonctions utilitaires d'observateur de propriétés capables d'effectuer automatiquement cette interrogation.

Vous pouvez utiliser les fonctions ci-dessous dans un outil scriptable pour surveiller les changements dans une propriété spécifique d'un ensemble de propriétés et appeler un événement lorsque la valeur est modifiée.

Dans BP, il est actuellement impossible de détecter automatiquement un type UProperty à partir d'une référence de variable. Pour configurer la détection :

• Assurez-vous d'utiliser la fonction qui correspond au type de la variable publique dans l'ensemble de propriétés.
• Transmettez le bon nom de propriété (c'est-à-dire le nom de la variable publique dans l'ensemble de propriétés).

Si le type n'est pas simple (Int, Float, Bool, String, FName, Enum ou propriété d'objet), utilisez la version à usage général Watch Property (Propriété d'observation). Son événement de rappel est néanmoins plus limité.

Vous trouverez ci-dessous un exemple de la fonction Watch Enum Property (Propriété Enum d'observation). Il s'agit du plus complexe des types simples, car le type Enum est inconnu. Le paramètre Nouvelle valeur transmis à l'événement de rappel est un uint8 et doit être explicitement projeté sur le bon type UEnum (en l'occurrence, EGeometryScriptAxis). Il n'est actuellement pas possible de vérifier les erreurs ici. L'éditeur projette la fonction sur n'importe quel type d'énumération.

Dans le cas de paramètres complexes, par exemple une UStruct imbriquée comme une variable de membre FVector, vous pouvez utiliser la fonction Watch Property (Propriété d'observation). Cette fonction peut détecter les changements dans presque toute variable UProperty, mais l'événement de rappel ne recevra pas de paramètre Nouvelle valeur, comme les autres champs. Si vous créez une variable membre pour l'ensemble de propriétés dans votre outil, vous pouvez aller chercher directement la valeur de propriété dans l'événement. Ce type d'observateur est également plus coûteux en matière de calcul. Utilisez-le uniquement lorsque cela est nécessaire.

Outil de base modulaire

Les outils de base sont des sous-classes C++ du framework de l'outil interactif scriptable qui fournissent des fonctionnalités intégrées supplémentaires pour gérer les cas courants et exposer des fonctionnalités supplémentaires telles que la gestion et la capture de l'appareil d'entrée. Choisissez un outil de base en fonction du type d'outil que vous souhaitez créer. La version Éditeur de l'outil de base donne accès aux fonctions de BP propres à l'éditeur.

La classe Scriptable Modular Behavior Tool (Outil de comportement modulaire scriptable) et son instance d'éditeur donnent accès aux fonctions de comportement, paramétrées par une liste de rappels. Ce système remplace les événements intégrés et fournit les moyens de mélanger et d'associer des comportements, potentiellement même avec duplication. Ce remplacement est utile, car vous pouvez créer plusieurs comportements de clic au sein d'un seul outil qui déclenche différentes conditions. Par exemple, un clic avec le bouton gauche de la souris, un autre avec le bouton droit et un autre avec le bouton gauche + la touche Ctrl.

Les comportements exposés incluent les suivants :

• Clic et glissement
• Survol
• Molette de la souris
• Clic multiple
• Clic ou glissement
• Commandes clavier simples et multiples

Comportements d'entrée des outils scriptables.

Activer les plug-ins pour l'éditeur uniquement

Dans l'Unreal Engine, vous pouvez définir des dépendances de plug-in pour les modules et les plug-ins de projet.

Dans les fichiers .uproject et .uplugin qui nécessitent UScriptabletoolsFramework ou UScriptabletoolsEditorMode pour une utilisation dans l'éditeur, configurez la section TargetAllowList sur Editor. Pour en savoir plus sur la configuration des plug-ins et des fichiers, consultez la section Plug-ins.

		{

			"Nom": "ScriptabletoolsEditorMode",

			"Enabled": true,

			"TargetAllowList": [

				"Editor"

			]

		},	
Copy full snippet

{ "Nom": "ScriptabletoolsEditorMode", "Enabled": true, "TargetAllowList": [ "Editor" ] },

Étapes suivantes

Il vous suffit de comprendre les bases du système d'outils scriptables pour commencer à créer vos outils avec le tutoriel Creating a Scriptable Tool (Créer un outil scriptable).