FrameDoctor-Benutzerhandbuch

FrameDoctor unterstützt Unreal Engine 5.5, 5.6, 5.7 und 5.8 unter Windows 64-Bit. Wähle das Plugin-Paket für deine Engine-Version.

Wenn du Unreal noch nie geöffnet hast

Öffne Epic Games Launcher → Unreal Engine → Library und starte deine installierte Engine. Öffne ein bestehendes Projekt oder wähle Games → Blank → Blueprint, gib Projektname und Ordner an und klicke auf Create. Ein Projekt enthält dein Spiel; eine Map, auch Level genannt, enthält darin eine Szene.

Installation über Fab

1. Schließe Unreal Editor. Suche in der Fab Library des Launchers nach FrameDoctor und klicke auf Install to Engine.
2. Wähle die Engine-Version deines Projekts und schließe die Installation ab.
3. Öffne dein Projekt. Gehe zu Edit → Plugins, suche nach FrameDoctor, aktiviere es und starte den Editor auf Aufforderung neu.
4. Öffne Tools → FrameDoctor im Hauptmenü des Editors.

Installation aus einer bereitgestellten ZIP-Datei

1. Schließe den Editor und entpacke das Plugin.
2. Lege den einzelnen Ordner FrameDoctor im Ordner Plugins deines Projekts ab. Erstelle Plugins, falls er noch fehlt.
3. Prüfe den folgenden Pfad. Vermeide einen zusätzlichen verschachtelten Ordner FrameDoctor/FrameDoctor.
4. Öffne das Projekt, aktiviere das Plugin unter Edit → Plugins, starte neu und öffne Tools → FrameDoctor.

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

Epics Anleitung: Plugins aktivieren und installieren.

Beginne mit einer Szene. Ein Szenario sagt FrameDoctor, wann die Szene bereit ist und die Messung beginnen kann. Zum Lernen und Untersuchen kannst du das optionale Szenario aus dem separaten Beispielprojekt verwenden.

Vor Schritt 1: Installiere FrameDoctor für deine Engine-Version; die Installation in der Engine wird empfohlen. Lade das optionale Beispielprojekt herunter (UE 5.5–5.8, Win64) und entpacke es. Das Projekt enthält nur Inhalte, benötigt das separat installierte Plugin und ist UE 5.5 zugeordnet. Für UE 5.6–5.8 klicke zuerst mit der rechten Maustaste auf FrameDoctorExample.uproject, wähle Switch Unreal Engine version und deine Engine. Öffne FrameDoctorExample.uproject mit dieser Engine und stelle sicher, dass FrameDoctor aktiviert ist.

1. Map öffnen und speichern. Öffne im Beispielprojekt eine Map oder wähle File → New Level, speichere sie im Content-Ordner des Projekts und verwende dann File → Save All.
2. Play starten. Klicke auf die dreieckige Schaltfläche Play in der Editor-Werkzeugleiste. Das heißt Play In Editor, kurz PIE. Mit Shift + F1 gibst du die Maus frei und kannst den Editor bedienen, während das Spiel weiterläuft.
3. Capture auswählen. Öffne Tools → FrameDoctor → Capture. Lass Use a packaged Development build deaktiviert. PIE zeichnet die bereits in Play laufende Map auf; ein anderer Wert im Feld Map wechselt diese Welt nicht.
4. Beispiel auswählen. Suche unter Scenario nach BP_ExploratoryScenario. Um das Asset zu finden, öffne den Content Browser oder Content Drawer mit Ctrl + Space und suche unter Content → FrameDoctorExample → Scenarios (/Game/FrameDoctorExample/Scenarios). Du wählst das Szenario in FrameDoctor aus; du ziehst es nicht in das Level.
5. Aufzeichnen. Behalte 10 Sekunden Aufwärmzeit und 60 Sekunden Messdauer bei. Lies Preflight und klicke auf Capture running PIE. Lass Play laufen und führe die Aktion aus, die du untersuchen möchtest. Die Aufwärmzeit geht nicht in das Messergebnis ein.
6. Findings lesen. Öffne nach Ende der Aufnahme Findings, falls es noch nicht ausgewählt ist. Lies Capture quality and unavailable reasons und wähle dann einen CPU-Scope, um seine Messdaten zu sehen.

Lass das Spiel laufen, bis die Aufnahme beendet ist. Esc oder die Stop-Schaltfläche des Editors können PIE beenden und die Aufnahme unterbrechen. Mit Cancel in FrameDoctor brichst du dessen aktuellen Auftrag ab.

Capture hat zwei Ziele. Ist Use a packaged Development build deaktiviert, wird die aktuelle PIE-Welt aufgezeichnet. Ist es aktiviert, startet FrameDoctor ein separates paketiertes Spiel. Verwende diesen Weg für wiederholbare Vorher-Nachher-Messungen.

Das normale CPU-Profil verwendet cpu,frame,bookmark. CPU-Ereignisse beschreiben Arbeit; Frame-Ereignisse liefern Framegrenzen; Bookmarks markieren das Messintervall. Eine bereits laufende externe Aufzeichnung muss enden, bevor FrameDoctor seine eigene Trace startet.

Zuerst kommt die Bereitschaft, dann die Aufwärmzeit und schließlich die Messung. Ready timeout und Maximum trace size werden unter Settings festgelegt. Abgebrochene oder unterbrochene Aufnahmen bleiben mit ihrem Status erhalten; sie sind keine abgeschlossenen Vergleichsbaselines.

Eine vorhandene Trace öffnen

Klicke auf Import trace, wähle eine fertig aufgezeichnete .utrace-Datei und warte auf Findings. Beende die Aufzeichnung, bevor du sie importierst. Bewahre die danebenliegende manifest.json und die ursprünglichen Aufnahmedateien zusammen mit der Trace auf, wenn du ihren Ursprung für Vergleiche belegen musst. Lies Capture quality and unavailable reasons, um die verfügbaren CPU-, Frame- und Messdaten zu prüfen.

Ohne genau ein eindeutiges, vollständiges Paar von FrameDoctor-Bookmarks für Messbeginn und Messende wird die gesamte Trace als explorative Aufnahme analysiert. Fehlt das Aufnahmemanifest oder wird es nicht unterstützt, bleibt die Vollständigkeit der Aufnahme ungeprüft. Du kannst die verfügbaren Ereignisse untersuchen, aber ungeprüfte oder explorative Daten nicht als bestätigte A/B-Baseline verwenden.

Beginne mit Status und Qualität der Aufnahme. Öffne Capture quality and unavailable reasons, wenn Daten fehlen oder ein Wert als Unavailable erscheint. Das heißt, dass der Wert nicht ermittelt werden konnte; es bedeutet nicht null.

1. Lies Game frame p95 und die Messdauer. Vergleiche die Kurve mit dem Framebudget.
2. Suche mit Search scopes… nach einem Timer-Namen oder wähle mit All threads einen Thread aus. Ein Thread ist ein Arbeitsablauf auf der CPU; GameThread führt normalerweise die Spiellogik aus.
3. Klicke auf eine Scope-Zeile. Ihr Bereich erläutert Measured (Messwerte), Interpretation (Deutung), Next experiment (nächster Versuch) und Behavior risk (Risiko für das Spielverhalten).
4. Mit Copy evidence kopierst du die Kennung von ausgewähltem Timer, Thread und Intervall. Mit Open in Insights öffnest du dieselbe Trace in Unreal Insights und navigierst manuell zu diesem Intervall.

Exclusive / frame ist die Dauer des Scopes nach Abzug seiner untergeordneten Scopes auf demselben Thread, gemittelt über gültige Frames. Calls zählt die im Messintervall gestarteten Aufrufe. Ein Scope kann Wartezeit enthalten. Sein Name allein identifiziert kein bestimmtes Asset und belegt nicht den Aufwand eines einzelnen Blueprint-Knotens.

Addiere keine verschachtelten inklusiven Zeiten oder Zeiten paralleler Threads, um den Frameaufwand abzuschätzen. Game-Frames, Render-Frames und der Kontext der GPU-Warteschlange bedeuten unterschiedliche Dinge. Fehlt ein maßgeblicher GPU-Framewert, bleibt er nicht verfügbar.

Die waagerechte Achse zeigt den Verlauf der Messzeit; die senkrechte Achse zeigt die Framedauer in Millisekunden. Höhere Spitzen bedeuten langsamere Frames. Die gestrichelte Budgetlinie entspricht deinem gewählten Ziel: 16.67 ms entsprechen ungefähr 60 Bildern pro Sekunde.

• Zoomen: Nutze das Mausrad über dem Diagramm oder ziehe die bernsteinfarbenen Griffe in der kleinen Übersicht darunter.
• Verschieben: Ziehe innerhalb des ausgewählten Übersichtsbereichs. Hat das Diagramm den Tastaturfokus, verschieben Pfeil links und rechts den sichtbaren Bereich.
• Untersuchen: Bewege den Zeiger über das Diagramm. Die Anzeige zeigt den Zeitpunkt oder zusammengefassten Darstellungsbereich, die Anzahl der Stichproben und die verfügbare minimale/maximale Dauer.
• Zurücksetzen: Klicke auf Reset view. Auch Home oder Esc setzt das fokussierte Diagramm zurück.

Bei weit herausgezoomter Ansicht können mehrere Frames in einen Darstellungsbereich fallen. Beachte dessen Stichprobenanzahl und Wertebereich, statt ihn als einzelnen Frame zu betrachten. Fehlende Framedaten bleiben als Lücken sichtbar.

Ein Development-Build ist ein paketiertes Spiel, das außerhalb des Editors mit aktivierten Entwicklungsfunktionen läuft. Baseline A ist dein ursprünglicher Build. Candidate B enthält eine beabsichtigte Änderung. Bewahre jeden vollständigen Build in einem eigenen Ordner auf.

1. Speichere deine Map und dein vergleichstaugliches Szenario. Aktiviere FrameDoctor im Projekt.
2. Öffne Edit → Project Settings → Packaging. Trage deine Map unter List of maps to include in a packaged build ein. Stelle sicher, dass auch der Szenario-Blueprint aufbereitet wird: Behalte eine feste Referenz aus eingebundenen Inhalten bei oder füge seinen Ordner unter Additional Asset Directories to Cook hinzu.
3. Wähle in den Paketierungsoptionen des Editors unter Platforms → Windows die Buildkonfiguration Development und paketiere das Projekt. Je nach Engine-Version können die Menüs anders angeordnet sein. Bewahre die vollständige Ausgabe als Build A auf.
4. Nimm eine manuelle Änderung vor, die du testen möchtest. Speichere und paketiere Build B in einem anderen Verzeichnis. Halte Szene, Eingabe, Kamera, NPCs und Aufnahmeeinstellungen gleich.
5. Aktiviere in Capture die Option Use a packaged Development build. Wähle die ausführbare Datei von A, dann die Map, und gib den Pfad zur generierten Szenarioklasse ein.

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

Verwende deine eigenen Assetnamen. /Game bezeichnet den Content-Ordner des Projekts aus Sicht von Unreal, kein Windows-Laufwerk. Die generierte Blueprint-Klasse endet auf _C. Behalte den gesamten paketierten Ordner samt Inhalten; nur die ausführbare Datei zu kopieren reicht nicht.

Preflight prüft die angeforderte Konfiguration. Erst das tatsächliche Laden zeigt, ob der externe Build diese Map und dieses Szenario enthält. Capture ist für Entwicklungskonfigurationen bestimmt; Shipping- und Test-Builds können keine FrameDoctor-Aufnahmen erstellen.

Epics Anleitung: ein Unreal-Projekt paketieren.

1. Bereite A und B wie oben vor. Klappe unter Compare den Bereich New Development comparison auf.
2. Wähle Baseline Development executable und Candidate Development executable. Beschreibe unter Intended change genau, was du geändert hast.
3. Wähle vor dem Start die Primary metric: p95GameFrame für langsamere Frames, meanGameFrame für die durchschnittliche Framedauer oder p99GameFrame für die besonders langsamen Frames am Verteilungsende.
4. Beginne mit 5 Paaren, 10 Sekunden Aufwärmzeit und 60 Sekunden Messdauer. Behalte nur gameBuildId als normalerweise erlaubten Unterschied für deine beabsichtigte Buildänderung bei. Gleiche Auflösung, Grafikeinstellungen, VSync, Framebegrenzung, Szenario und Instrumentierung ab.
5. Klicke auf Launch paired Development series. FrameDoctor führt die aufbewahrten Builds abwechselnd in der Reihenfolge AB/BA aus. Lass beide Buildordner unverändert, bis die Serie beendet ist.
6. Lies das Urteil mit Begründungen, die gepaarte Differenz, das Rauschen, den Schwellenwert und jedes einzelne Rohdatenpaar. Über Open HTML report oder Open report folder öffnest du das gespeicherte Ergebnis.

Eine Bestätigung erfordert mindestens 5 vollständige Paare, 30 gemessene Sekunden und 300 vollständige gültige Frames in jeder Aufnahme sowie vergleichbare Bedingungen. Kürzere Aufnahmen können der Erkundung dienen. Das explorative Beispielszenario kann keinen Effekt bestätigen.

Weniger Millisekunden sind besser. Die gepaarte Differenz ist der Median der Differenzen B − A aller Paare. Sie kann vom Ergebnis abweichen, das du durch Subtraktion der beiden angezeigten Mediane erhältst. Der Effekt muss den größten Wert aus absolutem Schwellenwert, relativem Schwellenwert und geschätztem Rauschen überschreiten; mindestens 80% der Paare müssen dieselbe Richtung zeigen. Die Standardwerte sind 0.5 ms und 5%. Diese Prüfungen helfen, die Stabilität einzuschätzen; allein belegen sie keine Ursache.

Um eine abgeschlossene Serie erneut zu öffnen, verwende Import series and export report und wähle ihre series.json. Erlaubte Unterschiede können abweichende Instrumentierung oder Berechnungsmethoden nicht außer Kraft setzen.

Öffne Runs und klicke auf Refresh saved runs. Wähle eine Zeile, um die Quelldetails zu lesen. Öffne eine Aufnahme per Doppelklick oder mit Open selected evidence erneut in Findings. Bei einer Serie öffnet sich der Paarvergleichsbericht.

Die Standardausgabe liegt unter <YourProject>/Saved/FrameDoctor; in Settings kannst du einen anderen Ausgabeordner wählen. Eine Einzelaufnahme bewahrt ihre Quell-.utrace, ihr Manifest und ihre Analyse auf. Eine Serie bewahrt series.json, comparison.json, einen HTML-Bericht und Verweise auf die ursprünglichen Aufnahmen auf.

1. Lade die Serie, die du teilen möchtest.
2. Wähle, ob du mit Include source traces in the export die Quell-Traces einbeziehen möchtest. Lass Remove absolute paths and username from exported JSON aktiviert, wenn das sinnvoll ist.
3. Klicke auf Export paired series bundle, wähle einen Exportort und warte auf den Abschluss.
4. Prüfe die exportierten Dateien und sende dann das vollständige Paket an die Person, die das Ergebnis beurteilt.

Promote current run to baseline speichert eine geeignete vollständige und vergleichbare Aufnahme unter <YourProject>/FrameDoctor/Baselines. Eine kurze oder explorative Aufnahme ist dafür nicht geeignet. Behalte die Originaldaten, bis du sie nicht mehr untersuchen oder erneut bestätigen musst.

Ein Profil ist ein gespeicherter Satz von Aufnahme- und Analyseeinstellungen. Wähle unter Settings eine Profile ID und einen Namen, fülle die Felder aus und verwende Save profile. Mit Load profile öffnest du eine Profil-JSON-Datei erneut. Bewahre Profile im Projektordner FrameDoctor/Profiles auf, wenn du sie mit der Projekthistorie verfolgen möchtest.

Verwende auf beiden A/B-Seiten dasselbe Profil. Passe Schwellenwerte vor Versuchsbeginn an dein Ziel an. Änderungen am Formular während eines laufenden Auftrags überschreiben dessen erfasste Einstellungen nicht. Ein Profil mit neuerem, nicht unterstütztem Schema öffnet sich schreibgeschützt; verwende ein kompatibles Plugin, statt die Schemanummer manuell zu ändern.

Verwende dies, wenn du eine Vorher-Nachher-Änderung bestätigen möchtest. Ein Szenario muss die tatsächlichen Kamera-, Eingabe-, NPC- und Zufallsbedingungen herstellen und beschreiben. Die Hooks lassen sich mit Blueprints implementieren; C++ ist zum Erstellen von Szenarien optional.

Um das separate Beispiel in einem bestehenden Projekt zu verwenden, öffne das Beispielprojekt, klicke im Content Browser mit der rechten Maustaste auf BP_ExploratoryScenario und wähle Asset Actions → Migrate. Wähle den Content-Ordner deines eigenen Projekts als Ziel und aktiviere dort FrameDoctor. Alternativ erstellst du mit den folgenden Schritten ein eigenes Szenario.

1. Wähle im Content Browser Add → Blueprint Class → All Classes. Suche nach FrameDoctorScenario und erstelle BP_TestScenario im Content deines Projekts.
2. Öffne diesen Blueprint. Implementiere in seinem Menü Overrides die folgenden Hooks. Es handelt sich um ein für die Aufnahme ausgewähltes Objekt, nicht um einen im Level zu platzierenden Actor.
3. Kompiliere und speichere Blueprint und Map. Wähle die Klasse in FrameDoctor. Schließe für paketierte Aufnahmen Map und Szenario in den Cook ein, wie unter A und B vorbereiten beschrieben.
4. Erstelle eine kurze explorative Aufnahme, um Bereitschaft und Aufräumen vor einem langen Vergleich zu prüfen.

Entferne während Cleanup keine Actors oder Aufzeichnungen anderer Systeme. Prüfe nach einer Leistungsänderung das Spielverhalten separat; gleiche Zeitmessbedingungen belegen nicht, dass deine neue Logik korrekt ist.

Projekt / Map

Der Arbeitsbereich deines Spiels / ein darin gespeichertes Level oder eine Szene.

Blueprint

Ein Unreal-Asset für visuelle Programmierung. Du verbindest Knoten, statt C++ zu schreiben.

PIE

Play In Editor: das Spiel läuft innerhalb von Unreal Editor.

Development / Shipping

Ein Entwicklungsbuild / eine Konfiguration für die endgültige Auslieferung. Verwende Development für paketierte Aufnahmen.

Trace / .utrace

Die Originaldatei der aufgezeichneten Zeitereignisse.

Scope / Timer / Thread

Ein gemessener Arbeitsabschnitt / sein Name / der CPU-Arbeitsablauf, auf dem er lief.

ms / FPS

Millisekunden pro Frame / Bilder pro Sekunde. Bei 16.67 ms pro Frame entstehen etwa 60 Bilder pro Sekunde.

Mittelwert / p95 / p99

Durchschnittliche Framedauer / eine Dauer, die 95% / 99% der vollständigen Frames nicht überschreiten. Ein höheres Perzentil betont langsamere Frames.

Aufwärmzeit / Messung

Vom Ergebnis ausgeschlossene Stabilisierungszeit / das für die Berechnung verwendete Intervall.

Baseline / Kandidat / Paar

Der ursprüngliche Build / ein Build mit deiner Änderung / je eine gemeinsam ausgewertete Aufnahme beider Builds.

Rauschen / Schwellenwert

Schwankung zwischen Wiederholungen / der minimale stabile Effekt für eine Bestätigung.

Cook

Unreals Aufbereitung von Assets, damit sie in einem paketierten Spiel laufen können.

Manifest / Profil

Gespeicherte Bedingungen und Status einer Aufnahme / die gewählten Aufnahmeeinstellungen.

FrameDoctor 1.0.0 · Unreal Engine 5.5, 5.6, 5.7 und 5.8 · Windows 64-Bit.

Gib bei einer Supportanfrage Engine- und Plugin-Version an, ob du PIE oder Development verwendet hast, die angeklickte Aktion, den gespeicherten Status samt Begründung und das erwartete Verhalten. Füge bei Bedarf einen Screenshot oder ein geprüftes Messdatenpaket bei. Teile keine persönlichen Pfade oder ungeprüften Rohprotokolle.

Bei einem Fehler oder einer unklaren Anweisung in diesem Handbuch erstelle ein Dokumentationsticket. Nutze für Plugin-Support den Supportkontakt auf der FrameDoctor-Produktseite oder deinen Kaufkanal.