Guide utilisateur de FrameDoctor

FrameDoctor prend en charge Unreal Engine 5.5, 5.6, 5.7 et 5.8 sous Windows 64 bits. Choisissez le package du plugin correspondant à la version de votre moteur.

Si vous n’avez jamais ouvert Unreal

Ouvrez Epic Games Launcher → Unreal Engine → Library et lancez le moteur installé. Ouvrez un projet existant, ou choisissez Games → Blank → Blueprint, indiquez un nom et un dossier de projet, puis cliquez sur Create. Un projet contient votre jeu ; une map, aussi appelée niveau, contient une scène de ce projet.

Installation depuis Fab

1. Fermez Unreal Editor. Dans la Fab Library du lanceur, trouvez FrameDoctor et cliquez sur Install to Engine.
2. Sélectionnez la version du moteur utilisée par votre projet et terminez l’installation.
3. Ouvrez votre projet. Allez dans Edit → Plugins, recherchez FrameDoctor, activez-le et redémarrez l’éditeur lorsqu’il vous le demande.
4. Ouvrez Tools → FrameDoctor dans le menu principal de l’éditeur.

Installation depuis un ZIP fourni

1. Fermez l’éditeur et décompressez le plugin.
2. Placez son unique dossier FrameDoctor dans le dossier Plugins de votre projet. Créez Plugins s’il n’existe pas.
3. Vérifiez le chemin ci-dessous. Évitez un dossier imbriqué supplémentaire FrameDoctor/FrameDoctor.
4. Ouvrez le projet, activez le plugin dans Edit → Plugins, redémarrez, puis ouvrez Tools → FrameDoctor.

YourProject/
  YourProject.uproject
  Plugins/
    FrameDoctor/
      FrameDoctor.uplugin
      Content/
      Resources/
      Source/

Guide d’Epic : activer et installer des plugins.

Commencez avec une scène. Un scénario indique à FrameDoctor quand la scène est prête et quand la mesure peut commencer. Pour apprendre et examiner une scène, vous pouvez utiliser le scénario facultatif disponible dans le projet d’exemple séparé.

Avant l’étape 1 : Installez FrameDoctor pour votre version du moteur ; l’installation dans le moteur est recommandée. Téléchargez le projet d’exemple facultatif (UE 5.5–5.8, Win64) et décompressez-le. Ce projet ne contient que des assets, nécessite l’installation séparée du plugin et est associé à UE 5.5. Pour UE 5.6–5.8, faites d’abord un clic droit sur FrameDoctorExample.uproject, choisissez Switch Unreal Engine version et sélectionnez votre moteur. Ouvrez FrameDoctorExample.uproject avec ce moteur et vérifiez que FrameDoctor est activé.

1. Ouvrez et enregistrez une map. Dans le projet d’exemple, ouvrez une map ou choisissez File → New Level, enregistrez-la dans le dossier Content du projet, puis utilisez File → Save All.
2. Lancez Play. Cliquez sur le bouton triangulaire Play dans la barre d’outils de l’éditeur. C’est le mode Play In Editor, ou PIE. Appuyez sur Shift + F1 pour libérer la souris et utiliser l’éditeur pendant que le jeu continue.
3. Choisissez Capture. Ouvrez Tools → FrameDoctor → Capture. Laissez Use a packaged Development build décoché. PIE enregistre la map déjà en cours dans Play ; choisir une autre valeur dans le champ Map ne change pas ce monde.
4. Sélectionnez l’exemple. Dans Scenario, recherchez BP_ExploratoryScenario. Pour trouver son asset, ouvrez Content Browser ou Content Drawer avec Ctrl + Space et cherchez dans Content → FrameDoctorExample → Scenarios (/Game/FrameDoctorExample/Scenarios). Le scénario se sélectionne dans FrameDoctor ; vous ne le faites pas glisser dans le niveau.
5. Enregistrez. Gardez 10 secondes de préchauffage et 60 secondes de mesure. Lisez Preflight, puis cliquez sur Capture running PIE. Laissez Play actif et effectuez l’action à examiner. Le préchauffage est exclu du résultat mesuré.
6. Lisez Findings. Une fois la capture terminée, ouvrez Findings si cet onglet n’est pas déjà sélectionné. Lisez Capture quality and unavailable reasons, puis sélectionnez une portée CPU pour voir ses mesures.

Laissez le jeu actif jusqu’à la fin de l’enregistrement. Esc ou le bouton Stop de l’éditeur peut arrêter PIE et interrompre la capture. Utilisez Cancel dans FrameDoctor pour annuler sa tâche en cours.

Capture propose deux cibles. Lorsque Use a packaged Development build est décoché, il enregistre le monde PIE actuel. Lorsque l’option est cochée, FrameDoctor lance un jeu packagé distinct. Utilisez cette deuxième méthode pour des mesures avant/après reproductibles.

Le profil CPU normal utilise cpu,frame,bookmark. Les événements CPU décrivent le travail ; les événements frame délimitent les trames ; les bookmarks marquent l’intervalle de mesure. Un enregistrement externe déjà actif doit se terminer avant que FrameDoctor lance sa propre trace.

La disponibilité de la scène vient d’abord, puis le préchauffage, puis la mesure. Ready timeout et Maximum trace size se règlent dans Settings. Les enregistrements annulés ou interrompus sont conservés avec leur état ; ils ne constituent pas des références de comparaison terminées.

Ouvrir une trace existante

Cliquez sur Import trace, choisissez un fichier .utrace dont l’enregistrement est terminé et attendez Findings. Arrêtez l’enregistrement avant de l’importer. Gardez le fichier manifest.json voisin et les fichiers d’origine de l’exécution avec la trace lorsque vous avez besoin de sa provenance pour la comparaison. Lisez Capture quality and unavailable reasons pour vérifier les données CPU, de trames et de mesure disponibles.

Sans une paire unique et complète de marqueurs FrameDoctor de début et de fin de mesure, toute la trace est analysée comme un enregistrement exploratoire. Un manifeste d’exécution absent ou non pris en charge laisse l’exhaustivité de la capture non vérifiée. Vous pouvez examiner les événements disponibles, mais pas utiliser des données non vérifiées ou exploratoires comme référence A/B confirmée.

Commencez par l’état et la qualité de la capture. Ouvrez Capture quality and unavailable reasons si les données sont incomplètes ou si une valeur affiche Unavailable. Cela signifie que la valeur n’a pas pu être établie ; cela ne signifie pas zéro.

1. Lisez Game frame p95 et la durée mesurée. Comparez la courbe au budget de trame.
2. Utilisez Search scopes… pour rechercher un nom de timer, ou All threads pour sélectionner un thread. Un thread est un flux de travail sur le CPU ; GameThread exécute généralement la logique du jeu.
3. Cliquez sur une ligne de portée. Son panneau explique Measured (mesures), Interpretation (interprétation), Next experiment (prochaine expérience) et Behavior risk (risque pour le comportement du jeu).
4. Utilisez Copy evidence pour copier l’identité du timer, du thread et de l’intervalle sélectionnés. Utilisez Open in Insights pour ouvrir la même trace dans Unreal Insights et naviguer manuellement jusqu’à cet intervalle.

Exclusive / frame est la durée de la portée après soustraction de ses portées enfants sur le même thread, moyennée sur les trames valides. Calls compte les appels commencés pendant l’intervalle de mesure. Une portée peut inclure de l’attente. Son nom seul n’identifie pas un asset précis et ne prouve pas le coût d’un nœud Blueprint.

N’additionnez pas les temps inclusifs imbriqués ni les temps de threads parallèles pour estimer le coût d’une trame. Les trames du jeu, les trames de rendu et le contexte de la file GPU ont des significations différentes. En l’absence d’une valeur de trame GPU faisant autorité, celle-ci reste indisponible.

L’axe horizontal représente le temps pendant la mesure ; l’axe vertical représente la durée des trames en millisecondes. Les pics plus hauts correspondent à des trames plus lentes. La ligne de budget en pointillés représente l’objectif choisi : 16.67 ms correspond à environ 60 images par seconde.

• Zoomer : utilisez la molette sur le graphique ou faites glisser les poignées ambrées de la petite vue d’ensemble en dessous.
• Déplacer : faites glisser l’intérieur de l’intervalle sélectionné dans la vue d’ensemble. Lorsque le graphique a le focus clavier, les flèches gauche et droite déplacent l’intervalle visible.
• Examiner : déplacez le pointeur sur le graphique. L’affichage donne l’instant ou le groupe agrégé, le nombre d’échantillons et la durée minimale/maximale disponible.
• Réinitialiser : cliquez sur Reset view. Home ou Esc réinitialise aussi le graphique ayant le focus.

Avec une vue très dézoomée, plusieurs trames peuvent partager un même groupe de dessin. Lisez le nombre d’échantillons et l’étendue de ce groupe plutôt que de le traiter comme une seule trame. Les données de trame manquantes restent des lacunes.

Un build Development est un jeu packagé exécutable hors de l’éditeur, avec les fonctions de développement activées. Baseline A est votre build d’origine. Candidate B contient une modification prévue. Gardez chaque build complet dans un dossier distinct.

1. Enregistrez votre map et votre scénario prêt pour la comparaison. Activez FrameDoctor dans le projet.
2. Ouvrez Edit → Project Settings → Packaging. Incluez votre map dans List of maps to include in a packaged build. Assurez-vous que le Blueprint du scénario est lui aussi préparé : gardez une référence directe depuis du contenu inclus, ou ajoutez son dossier à Additional Asset Directories to Cook.
3. Dans les commandes de packaging Platforms → Windows de l’éditeur, choisissez Development comme configuration de compilation, puis packagez le projet. Le regroupement des menus peut varier selon la version du moteur. Conservez cette sortie complète comme build A.
4. Faites une modification manuelle à tester. Enregistrez et packagez le build B dans un autre répertoire. Gardez les mêmes scène, entrées, caméra, PNJ et paramètres de capture.
5. Dans Capture, cochez Use a packaged Development build. Parcourez les fichiers pour choisir l’exécutable de A, puis sélectionnez la map et entrez le chemin de la classe générée du scénario.

Map: /Game/Maps/TestMap
Scenario: /Game/Scenarios/BP_TestScenario.BP_TestScenario_C
Executable: BuildA/Windows/YourProject/Binaries/Win64/YourProject.exe

Utilisez vos propres noms d’assets. /Game désigne le dossier Content du projet vu par Unreal ; ce n’est pas un lecteur Windows. La classe Blueprint générée se termine par _C. Gardez tout le dossier packagé, y compris son contenu ; copier seulement l’exécutable ne suffit pas.

Preflight vérifie la configuration demandée. Seul le chargement réel prouve que le build externe contient cette map et ce scénario. Capture concerne les configurations de développement ; les builds Shipping et Test ne peuvent pas enregistrer de captures FrameDoctor.

Guide d’Epic : packager un projet Unreal.

1. Préparez A et B comme indiqué ci-dessus. Dans Compare, développez New Development comparison.
2. Choisissez Baseline Development executable et Candidate Development executable. Décrivez précisément votre modification dans Intended change.
3. Choisissez Primary metric avant le lancement : p95GameFrame pour les trames lentes, meanGameFrame pour la durée moyenne, ou p99GameFrame pour l’extrémité la plus lente de la distribution.
4. Commencez avec 5 paires, 10 secondes de préchauffage et 60 secondes de mesure. Gardez seulement gameBuildId comme différence normalement autorisée pour votre modification de build prévue. Faites correspondre résolution, réglages graphiques, VSync, limite d’images, scénario et instrumentation.
5. Cliquez sur Launch paired Development series. FrameDoctor exécute les builds conservés en alternant l’ordre AB/BA. Gardez les deux dossiers de build inchangés jusqu’à la fin de la série.
6. Lisez le verdict et ses raisons, l’écart apparié, le bruit, le seuil et chaque paire brute. Utilisez Open HTML report ou Open report folder pour consulter le résultat enregistré.

La confirmation nécessite au moins 5 paires complètes, 30 secondes mesurées et 300 trames complètes valides dans chaque exécution, ainsi que des conditions comparables. Des captures plus courtes peuvent aider à explorer. Le scénario exploratoire d’exemple ne peut pas confirmer un effet.

Moins de millisecondes est préférable. L’écart apparié est la médiane des différences B − A de chaque paire. Il peut différer de la soustraction des deux médianes affichées. L’effet doit dépasser la plus grande valeur parmi le seuil absolu, le seuil relatif et le bruit estimé, avec au moins 80% des paires allant dans le même sens. Les valeurs par défaut sont 0.5 ms et 5%. Ces vérifications aident à juger la stabilité ; elles n’établissent pas la cause à elles seules.

Pour rouvrir une série terminée, utilisez Import series and export report et sélectionnez son series.json. Les différences autorisées ne peuvent pas neutraliser une instrumentation ou des méthodes de calcul différentes.

Ouvrez Runs et cliquez sur Refresh saved runs. Sélectionnez une ligne pour lire les détails de sa source. Double-cliquez sur une exécution, ou cliquez sur Open selected evidence, pour rouvrir Findings. Une série ouvre son rapport apparié.

La sortie par défaut est <YourProject>/Saved/FrameDoctor ; Settings permet de choisir un autre dossier. Une exécution conserve sa source .utrace, son manifeste et son analyse. Une série conserve series.json, comparison.json, un rapport HTML et des références aux exécutions d’origine.

1. Chargez la série à partager.
2. Choisissez si vous souhaitez inclure les traces sources avec Include source traces in the export. Laissez Remove absolute paths and username from exported JSON activé lorsque c’est approprié.
3. Cliquez sur Export paired series bundle, choisissez un emplacement d’export et attendez la fin.
4. Vérifiez les fichiers exportés, puis envoyez le lot complet à la personne qui examine le résultat.

Promote current run to baseline enregistre une exécution admissible, complète et comparable dans <YourProject>/FrameDoctor/Baselines. Une capture courte ou exploratoire n’est pas admissible. Gardez les données d’origine tant que vous pouvez avoir besoin de les examiner ou de les reconfirmer.

Un profil est un ensemble enregistré de paramètres de capture et d’analyse. Dans Settings, choisissez un Profile ID et un nom, configurez les champs, puis utilisez Save profile. Utilisez Load profile pour rouvrir un fichier JSON de profil. Gardez les profils dans le dossier FrameDoctor/Profiles de votre projet pour les suivre dans son historique.

Utilisez le même profil des deux côtés A/B. Modifiez les seuils selon votre objectif avant de commencer l’expérience. Modifier le formulaire pendant une tâche ne réécrit pas les paramètres enregistrés pour celle-ci. Un profil issu d’un schéma plus récent non pris en charge s’ouvre en lecture seule ; utilisez un plugin compatible au lieu de changer manuellement son numéro de schéma.

Suivez ces étapes lorsque vous souhaitez confirmer une modification avant/après. Un scénario doit établir et décrire les conditions réelles de caméra, d’entrée, de PNJ et d’aléatoire. Les Blueprints peuvent implémenter ses hooks ; le C++ est facultatif pour créer un scénario.

Pour utiliser l’exemple séparé dans un projet existant, ouvrez le projet d’exemple, faites un clic droit sur BP_ExploratoryScenario dans Content Browser et choisissez Asset Actions → Migrate. Sélectionnez le dossier Content de votre propre projet comme destination et activez-y FrameDoctor. Vous pouvez aussi créer votre propre scénario avec les étapes ci-dessous.

1. Dans Content Browser, choisissez Add → Blueprint Class → All Classes. Recherchez FrameDoctorScenario et créez BP_TestScenario dans le contenu de votre projet.
2. Ouvrez ce Blueprint. Dans son menu Overrides, implémentez les hooks ci-dessous. Il s’agit d’un objet sélectionné par la capture, pas d’un Actor à placer dans le niveau.
3. Compilez et enregistrez le Blueprint et la map. Sélectionnez la classe dans FrameDoctor. Pour les captures packagées, incluez la map et le scénario dans le cook comme expliqué dans Préparer A et B.
4. Faites un court enregistrement exploratoire pour vérifier la disponibilité et le nettoyage avant de lancer une longue comparaison.

Ne supprimez pas les acteurs ou l’enregistrement d’un autre système pendant Cleanup. Vérifiez séparément le comportement du jeu après une modification de performances ; des conditions de chronométrage identiques ne prouvent pas que votre nouvelle logique est correcte.

Projet / map

L’espace de travail de votre jeu / un niveau ou une scène qui y est enregistré.

Blueprint

Un asset Unreal pour la programmation visuelle. Vous reliez des nœuds au lieu d’écrire du C++.

PIE

Play In Editor : le jeu s’exécute dans Unreal Editor.

Development / Shipping

Un build pour le développement / une configuration de distribution finale. Utilisez Development pour les captures packagées.

Trace / .utrace

Le fichier d’origine des événements chronométrés enregistrés.

Portée / timer / thread

Une portion de travail mesurée / son nom / le flux de travail CPU qui l’a exécutée.

ms / FPS

Millisecondes par trame / images par seconde. À 16.67 ms par trame, le jeu produit environ 60 images par seconde.

Moyenne / p95 / p99

Durée moyenne de trame / une durée que ne dépassent pas 95% / 99% des trames complètes. Un percentile plus élevé met l’accent sur les trames plus lentes.

Préchauffage / mesure

Temps de stabilisation exclu du résultat / intervalle utilisé pour le calculer.

Référence / candidat / paire

Le build d’origine / un build avec votre modification / une exécution de chacun utilisées ensemble.

Bruit / seuil

Variation entre répétitions / effet stable minimal nécessaire pour confirmer.

Cook

La préparation des assets par Unreal pour qu’ils puissent fonctionner dans un jeu packagé.

Manifeste / profil

Les conditions et l’état enregistrés d’une capture / les paramètres choisis pour un enregistrement.

FrameDoctor 1.0.0 · Unreal Engine 5.5, 5.6, 5.7 et 5.8 · Windows 64 bits.

Pour demander de l’aide, indiquez les versions du moteur et du plugin, si vous avez utilisé PIE ou Development, l’action sur laquelle vous avez cliqué, l’état et la raison enregistrés ainsi que le résultat attendu. Joignez une capture d’écran ou un lot de mesures vérifié si cela aide. Évitez de partager des chemins personnels ou des journaux bruts que vous n’avez pas relus.

Pour une erreur ou une instruction peu claire dans ce guide, ouvrez un ticket de documentation. Pour l’assistance du plugin, utilisez le contact d’assistance sur la page produit FrameDoctor ou votre canal d’achat.