Profiler les performances dans Unreal Engine : guide des commandes stat et d’Insights

Lorsqu’un problème de performances apparaît dans un projet Unreal Engine, la première étape consiste à mesurer à quel stade il se produit. La documentation officielle d’Epic Games explique comment afficher les principales données de performances à l’aide de commandes stat saisies dans la console pendant l’exécution, puis comment examiner plus en détail les traces enregistrées avec Unreal Insights. Ce guide présente un flux de travail allant de la mesure à l’analyse, notamment pour la visualisation architecturale en temps réel et les scènes interactives.

1. Repérer d’abord le goulot d’étranglement général

Lancez le projet en mode Play In Editor (PIE), puis saisissez la commande suivante dans la console :

stat unit

Cette commande affiche des informations de performances sous les rubriques Frame, Game, Draw, GPU, RHIT et DynRes. Selon la documentation, Frame correspond au temps total nécessaire à la production d’une image. Si le temps Frame est proche du temps Game, le problème peut se situer du côté du Game thread ; s’il est proche du temps Draw, il peut se trouver du côté du render thread. Le temps GPU indique celui que la carte graphique consacre au rendu de la scène. Considérez ces valeurs comme des indicateurs permettant d’orienter une analyse plus approfondie, et non comme un diagnostic définitif.

Une autre commande de départ pour obtenir une vue d’ensemble est stat sceneRendering. Epic la présente comme un bon point de départ pour rechercher les domaines généraux où le rendu ralentit. Vous pourrez ensuite choisir une commande en fonction de la piste indiquée par les mesures : stat memory affiche l’utilisation de la mémoire, stat streaming fournit des informations générales sur les ressources en streaming, et stat lightRendering indique le temps consacré au traitement de l’éclairage et des ombres.

stat sceneRendering

Pour obtenir la liste des commandes, utilisez stat help dans la console. La documentation indique également qu’il est possible de trouver les commandes dans le menu Stat de l’éditeur, en cliquant sur la flèche déroulante à côté du bouton Viewport Setting.

2. Enregistrer les mesures PIE dans un fichier

Si les indicateurs en temps réel ne suffisent pas à repérer le problème, enregistrez les échantillons de statistiques dans un fichier. Dans la console PIE, lancez l’enregistrement à l’aide de la commande suivante :

stat startfile

L’enregistrement crée généralement un fichier .uestats sous Saved/Profiling/UnrealStats, dans le dossier du projet. Une fois l’opération terminée, arrêtez-le impérativement :

stat stopfile

Cette étape est importante : selon la documentation, l’enregistrement StartFile peut continuer en arrière-plan même après la fermeture de PIE. Si vous le laissez actif, de volumineux fichiers .uestats risquent d’être créés. Pour examiner le fichier obtenu, ouvrez Tools > Session Frontend dans le menu de l’Unreal Editor, sélectionnez l’onglet Profiler, puis choisissez le fichier avec l’option Load. Les données enregistrées s’affichent alors dans Profiler.

3. Examiner les traces avec Unreal Insights

Unreal Insights est un ensemble d’outils qui permet de capturer des événements à haut débit depuis un projet, puis d’analyser et de visualiser les données. Il peut être lancé depuis le widget Trace/Insights Status Bar de l’éditeur. Les sessions de trace sont stockées dans des fichiers .utrace ; les données associées peuvent se trouver dans des fichiers .ucache au même emplacement.

Pour lancer l’analyse, double-cliquez sur une session enregistrée dans Session Browser ou sélectionnez-la et cliquez sur Open Trace. Vous pouvez rechercher un fichier .utrace situé ailleurs à partir du menu Open Trace ; la documentation explique également qu’il est possible de glisser-déposer le fichier dans la fenêtre Unreal Insights. Les sessions en direct apparaissent avec le statut LIVE et se mettent à jour en temps réel pendant leur examen.

La fenêtre Timing Insights permet de visualiser les traces CPU et GPU, ainsi que la durée des opérations. Memory Insights sert à examiner l’utilisation de la mémoire et les piles d’appels ; Asset Loading Insights permet d’étudier le temps et l’ordre de chargement des ressources. Choisir l’outil en fonction du type de problème permet de cibler l’analyse.

4. Adapter le flux de travail à la visualisation architecturale

Si vous constatez des saccades, une réponse lente ou des attentes au chargement dans une scène architecturale interactive, commencez par mesurer avec stat unit. Notez si les résultats orientent vers Game, Draw ou GPU ; plutôt que de décider d’une optimisation à partir d’une seule mesure ponctuelle, effectuez de nouvelles mesures dans la même scène et dans des conditions d’utilisation similaires. En fonction du niveau de détail nécessaire, enregistrez ensuite les statistiques ou une trace Unreal Insights.

Pour suivre les transitions entre scènes et l’état de chargement des niveaux, vous pouvez utiliser stat levels. Cette commande indique si les niveaux sont actifs, visibles, en cours de chargement ou de déchargement, ou en préchargement, ainsi que le temps écoulé entre la demande de chargement et son achèvement. stat streaming peut aider à examiner l’utilisation mémoire des contenus en streaming, tandis que stat lightRendering concerne le traitement de l’éclairage et des ombres. Ces indicateurs aident les équipes d’architecture à choisir la scène ou l’étape de rendu à examiner ; à eux seuls, ils ne justifient pas la modification d’un paramètre particulier.

La documentation d’Unreal Insights précise que Trace Server est activé sur toutes les plateformes de bureau à partir d’UE 5.3. Il est possible de définir un autre dossier pour stocker les traces et d’ajouter des dossiers de suivi supplémentaires. Avant de partager des fichiers d’analyse, les équipes doivent vérifier quel dossier est utilisé et si l’enregistrement est terminé. Les étapes présentées ici s’appuient sur les commandes et outils de la documentation d’Unreal Engine d’Epic Games ; comme celle-ci ne précise pas d’exigences matérielles ni de conditions de licence particulières pour ce flux de travail, aucune recommandation spécifique à ce sujet ne peut en être tirée.

Erreurs fréquentes

• Oublier d’arrêter l’enregistrement après stat startfile : il peut continuer même après la fermeture de PIE. Une fois terminé, saisissez stat stopfile.

• Confondre les fichiers .uestats et .utrace : la documentation officielle les associe à des flux de travail différents. Les fichiers .uestats s’ouvrent dans Profiler de Session Frontend, tandis que les traces .utrace s’ouvrent dans Unreal Insights.

• Considérer la première valeur affichée comme la cause certaine du problème : stat unit indique des goulots d’étranglement possibles ; pour approfondir l’analyse, passez aux outils d’enregistrement et d’analyse appropriés.