FrameDoctor ユーザーガイド

FrameDoctor は、Windows 64 ビット上の Unreal Engine 5.5、5.6、5.7、5.8に対応しています。使用するエンジンのバージョンに合ったプラグインパッケージを選んでください。

Unreal を初めて開く場合

Epic Games Launcher → Unreal Engine → Libraryを開き、インストール済みのエンジンを起動します。既存のプロジェクトを開くか、Games → Blank → Blueprintを選び、プロジェクト名とフォルダーを入力してCreateをクリックします。プロジェクトにはゲーム全体を保存します。マップはレベルとも呼ばれ、その中の 1 つのシーンを保存します。

Fab からインストールする

1. Unreal Editor を閉じます。ランチャーのFab Libraryで FrameDoctor を見つけ、Install to Engineをクリックします。
2. プロジェクトで使うエンジンのバージョンを選び、インストールを完了します。
3. プロジェクトを開きます。Edit → PluginsでFrameDoctorを検索して有効にし、再起動を求められたらエディタを再起動します。
4. エディタのメインメニューからTools → FrameDoctorを開きます。

提供された ZIP からインストールする

1. エディタを閉じ、プラグインを展開します。
2. 展開した単一のFrameDoctorフォルダーを、プロジェクトのPluginsフォルダーに配置します。Pluginsがなければ作成してください。
3. 下記のパスを確認します。FrameDoctor/FrameDoctorのように余分に入れ子にならないようにします。
4. プロジェクトを開き、Edit → Pluginsでプラグインを有効にします。再起動してからTools → FrameDoctorを開きます。

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

Epic のガイド：プラグインの有効化とインストール。

最初は 1 つのシーンを使います。シナリオは、シーンの準備が整い、測定を開始できるタイミングを FrameDoctor に伝えます。操作を学び、シーンを調査するには、別途配布されるサンプルプロジェクトのシナリオを任意で利用できます。

手順 1 の前に：使用するエンジンのバージョンに合った FrameDoctor をインストールしてください。エンジンへのインストールを推奨します。別途配布のサンプルプロジェクト（UE 5.5–5.8、Win64）をダウンロードして展開します。このプロジェクトにはコンテンツのみが含まれ、プラグインは別途必要です。UE 5.5 に関連付けられているため、UE 5.6–5.8 では先にFrameDoctorExample.uprojectを右クリックし、Switch Unreal Engine versionから使用するエンジンを選びます。そのエンジンでFrameDoctorExample.uprojectを開き、FrameDoctor が有効であることを確認してください。

1. マップを開いて保存します。サンプルプロジェクト内でマップを開くか、File → New Levelで作成し、プロジェクトのContentフォルダーに保存してからFile → Save Allを実行します。
2. Play を開始します。エディタのツールバーにある三角形のPlayボタンをクリックします。これが Play In Editor、略して PIE です。Shift + F1を押すとマウスが解放され、ゲームを動かしたままエディタを操作できます。
3. Capture を選びます。Tools → FrameDoctor → Captureを開きます。Use a packaged Development buildはオフのままにします。PIE は、すでに Play で実行しているマップを記録します。Map 欄で別のマップを選んでも、そのワールドは切り替わりません。
4. サンプルを選びます。ScenarioでBP_ExploratoryScenarioを検索します。アセットを探すには、Content Browser、またはCtrl + Spaceで Content Drawer を開き、Content → FrameDoctorExample → Scenarios（/Game/FrameDoctorExample/Scenarios）を確認します。シナリオは FrameDoctor で選択します。レベルにドラッグする必要はありません。
5. 記録します。ウォームアップを 10 秒、測定を 60 秒のままにします。Preflight を読み、Capture running PIEをクリックします。Play を動かしたまま、調べたい操作を行います。ウォームアップは測定結果に含まれません。
6. Findings を読みます。記録が完了したら、まだ選択されていなければFindingsを開きます。Capture quality and unavailable reasonsを読んでから、CPU スコープを選び、その検証データを確認します。

記録が終わるまでゲームを動かし続けてください。Escやエディタの Stop ボタンで PIE が終了し、記録が中断される場合があります。FrameDoctor の現在の処理をキャンセルするには、FrameDoctor 内のCancelを使います。

Captureには 2 つの対象があります。Use a packaged Development buildがオフなら、現在の PIE ワールドを記録します。オンなら、FrameDoctor が別のパッケージ化されたゲームを起動します。再現可能な変更前後の測定には、パッケージ化したゲームを使ってください。

通常の CPU プロファイルはcpu,frame,bookmarkを使用します。CPU イベントは処理を表し、frame イベントはフレームの境界を示し、bookmark は測定区間を示します。外部での記録がすでに進行中の場合は、それを終了してから FrameDoctor 自身のトレースを開始する必要があります。

準備完了、ウォームアップ、測定の順に進みます。Ready timeoutとMaximum trace sizeはSettingsで設定します。キャンセルまたは中断された記録は、その状態とともに保持されます。比較用の完了済みベースラインとしては使用できません。

既存のトレースを開く

Import traceをクリックし、記録が終了した.utraceファイルを選んで、Findings が表示されるまで待ちます。インポートの前に記録を停止してください。比較の出所を確認する必要がある場合は、トレースと同じ場所のmanifest.jsonおよび元の実行記録のファイル一式を、トレースとともに保持します。Capture quality and unavailable reasonsを読み、利用可能な CPU、フレーム、測定のデータを確認してください。

FrameDoctor の測定開始と測定終了を示すブックマークが、完全な 1 組として一意に特定できない場合、トレース全体が探索用の記録として解析されます。実行のマニフェストがない場合や対応していない形式の場合は、記録の完全性が未検証のままになります。利用可能なイベントは調べられますが、未検証のデータや探索用のデータを、確認済みの A/B ベースラインとして使うことはできません。

まず、記録の状態と品質を確認します。データが不完全な場合や値がUnavailableの場合は、Capture quality and unavailable reasonsを開きます。Unavailable は値を確定できなかったという意味であり、ゼロという意味ではありません。

1. Game frame p95と測定時間を確認します。グラフの曲線をフレーム予算と比較します。
2. Search scopes…でタイマー名を探すか、All threadsでスレッドを選択します。スレッドは CPU 上の処理の流れです。GameThread は通常、ゲームロジックを実行します。
3. スコープの行をクリックします。パネルにはMeasured（測定内容）、Interpretation（結果の解釈）、Next experiment（次に試す検証）、Behavior risk（動作への影響リスク）の説明が表示されます。
4. Copy evidenceで選択中のタイマー、スレッド、区間を特定する情報をコピーします。Open in Insightsで同じトレースを Unreal Insights に開き、該当区間へ手動で移動します。

Exclusive / frameは、同じスレッド上の子スコープの時間を差し引いたスコープ時間を、有効なフレームで平均した値です。Callsは、測定区間内で開始した呼び出しを数えます。スコープには待機時間が含まれる場合があります。名前だけで特定のアセットを識別したり、1 つの Blueprint ノードのコストを証明したりはできません。

フレームのコストを見積もるために、入れ子の包含時間や並列スレッドの時間を足し合わせないでください。ゲームフレーム、レンダーフレーム、GPU キューの文脈は、それぞれ意味が異なります。信頼できる GPU フレーム値がなければ、その値は利用不可のままです。

横軸は測定中の経過時間、縦軸はミリ秒単位のフレーム時間です。山が高いほどフレームが遅くなっています。破線の予算線は選択した目標値です。16.67 msは、およそ毎秒 60 フレームに相当します。

• 拡大・縮小：グラフ上でマウスホイールを使うか、その下の小さな全体表示にある琥珀色のハンドルをドラッグします。
• 表示範囲の移動：全体表示の選択範囲の内側をドラッグします。グラフにキーボードフォーカスがあるときは、左右の矢印キーでも表示範囲を移動できます。
• 値の確認：グラフ上でポインターを動かします。時間または集約されたバケット、サンプル数、取得可能な最短・最長時間が表示されます。
• リセット：Reset viewをクリックします。フォーカス中のグラフは、HomeまたはEscでもリセットできます。

広い範囲を表示すると、複数のフレームが 1 つの描画用バケットにまとめられる場合があります。1 フレームと見なさず、バケットのサンプル数と値の範囲を読んでください。フレームデータが欠けている箇所は、空白のまま表示されます。

Development ビルドは、開発用機能を有効にした状態でエディタの外から実行できる、パッケージ化されたゲームです。Baseline Aは元のビルド、Candidate Bは意図した変更を 1 つ含むビルドです。完全なビルド一式を、それぞれ別のフォルダーに保持してください。

1. マップと比較に使えるシナリオを保存します。プロジェクトで FrameDoctor を有効にします。
2. Edit → Project Settings → Packagingを開きます。List of maps to include in a packaged buildにマップを追加します。シナリオの Blueprint もクックされるようにしてください。含めるコンテンツからのハード参照を保持するか、Additional Asset Directories to Cookにそのフォルダーを追加します。
3. エディタのPlatforms → Windowsにあるパッケージ化の操作項目で、ビルド構成にDevelopmentを選び、プロジェクトをパッケージ化します。エンジンのバージョンにより、メニューのまとまり方は異なる場合があります。出力一式をビルド A として保存します。
4. 試したい変更を手動で 1 つ加えます。保存し、別のディレクトリにビルド B をパッケージ化します。シーン、入力、カメラ、NPC、記録設定を同じ条件に保ちます。
5. CaptureでUse a packaged Development buildをオンにします。A の実行ファイルを参照して選び、マップを選択し、シナリオの生成クラスパスを入力します。

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

アセット名は自分のものに置き換えてください。/Gameは Unreal から見たプロジェクトの Content フォルダーであり、Windows のドライブではありません。生成された Blueprint クラスの末尾には_Cが付きます。コンテンツを含むパッケージフォルダー全体を保持してください。実行ファイルだけのコピーでは不十分です。

Preflight は指定された設定を確認します。その外部ビルドにマップとシナリオが含まれているかは、実際の読み込みで確認されます。記録は開発用構成が対象です。Shipping と Test ビルドでは FrameDoctor の記録は行えません。

Epic のガイド：Unreal プロジェクトのパッケージ化。

1. 前述の手順で A と B を用意します。CompareでNew Development comparisonを展開します。
2. Baseline Development executableとCandidate Development executableを選びます。Intended changeに、何を変更したかを正確に記述します。
3. 起動前にPrimary metricを選びます。遅いフレームにはp95GameFrame、平均フレーム時間にはmeanGameFrame、特に遅い末尾側のフレームにはp99GameFrameを使います。
4. 最初は5 ペア、ウォームアップ 10 秒、測定 60 秒にします。意図したビルド変更について、通常の許容差分はgameBuildIdのみとします。解像度、グラフィックス設定、VSync、フレーム上限、シナリオ、計測設定を一致させます。
5. Launch paired Development seriesをクリックします。FrameDoctor は保存済みのビルドを AB/BA の交互順で実行します。シリーズが終わるまで、両方のビルドフォルダーを変更しないでください。
6. 判定とその理由、ペア差分、ノイズ、しきい値、各ペアの生データを読みます。保存された結果はOpen HTML reportまたはOpen report folderで開けます。

効果の確認には、比較可能な条件に加えて、少なくとも 5 つの完全なペア、各実行で 30 秒の測定、300 個の完全かつ有効なフレームが必要です。短い記録も探索には役立ちます。付属の探索用シナリオでは、効果を確認できません。

ミリ秒の値は低いほど良好です。ペア差分は、各ペアのB − Aの差の中央値です。表示された 2 つの中央値を引いた値とは異なる場合があります。効果は、絶対しきい値、相対しきい値、推定ノイズのうち最大のものを超え、少なくとも 80% のペアで方向が一致する必要があります。既定値は 0.5 ms と 5% です。これらの確認は安定性の判断を助けますが、それだけで原因を特定するものではありません。

完了したシリーズを開き直すには、Import series and export reportを使い、そのseries.jsonを選択します。許容差分を設定しても、計測設定や計算方法の不一致は許容できません。

Runsを開き、Refresh saved runsをクリックします。行を選ぶと、元データの詳細を確認できます。実行結果をダブルクリックするか、Open selected evidenceをクリックすると Findings が再び開きます。シリーズの場合はペア比較レポートが開きます。

既定の出力先は<YourProject>/Saved/FrameDoctorです。Settings で別の出力フォルダーを選べます。単一の実行には、元の.utrace、マニフェスト、解析が保持されます。シリーズにはseries.json、comparison.json、HTML レポート、元の実行への参照が保持されます。

1. 共有したいシリーズを読み込みます。
2. Include source traces in the exportで、元のトレースを含めるかを選びます。状況に応じてRemove absolute paths and username from exported JSONをオンのままにします。
3. Export paired series bundleをクリックし、出力先を選んで完了を待ちます。
4. エクスポートされたファイルを確認し、結果を確認する相手にバンドル一式を送ります。

Promote current run to baselineは、条件を満たす完了済みかつ比較可能な実行を<YourProject>/FrameDoctor/Baselinesに保存します。短い記録や探索用の記録は対象になりません。調査や再確認が不要になるまで、元のデータを保持してください。

プロファイルは、保存した記録・解析設定の組み合わせです。Settingsで Profile ID と名前を選び、各項目を設定してSave profileを使います。プロファイルの JSON ファイルを開き直すにはLoad profileを使います。プロジェクトの履歴で管理したい場合は、プロジェクトのFrameDoctor/Profilesフォルダーにプロファイルを保持します。

A/B の両方で同じプロファイルを使います。実験を始める前に、目的に合うようしきい値を変更してください。処理の実行中にフォームを編集しても、その処理に記録された設定は書き換わりません。対応していない新しいスキーマのプロファイルは、読み取り専用で開きます。スキーマ番号を手動で変えるのではなく、互換性のあるプラグインを使用してください。

変更前後の効果を確認する準備ができたら、この手順を使います。シナリオでは、実際のカメラ、入力、NPC、ランダム性の条件を設定し、記述する必要があります。フックは Blueprint で実装できます。シナリオの作成に C++ は必須ではありません。

別途配布されるサンプルを既存のプロジェクトで使う場合は、サンプルプロジェクトを開き、Content Browser でBP_ExploratoryScenarioを右クリックしてAsset Actions → Migrateを選びます。移行先には自分のプロジェクトのContentフォルダーを指定し、そのプロジェクトでも FrameDoctor を有効にしてください。または、次の手順で独自のシナリオを作成できます。

1. Content Browser でAdd → Blueprint Class → All Classesを選びます。FrameDoctorScenarioを検索し、プロジェクトのコンテンツにBP_TestScenarioを作成します。
2. その Blueprint を開きます。Overridesメニューから、下記のフックを実装します。これは記録時に選択するオブジェクトであり、レベルに配置する Actor ではありません。
3. Blueprint とマップをコンパイル・保存します。FrameDoctor でクラスを選びます。パッケージ化した記録では、A と B の準備の説明に従い、マップとシナリオをクックの対象に含めます。
4. 長い比較を始める前に、短い探索用の記録を 1 回行い、準備完了の判定と後片付けを確認します。

Cleanup で別のシステムの Actor や記録を削除しないでください。性能を変更した後は、ゲームプレイの動作を別途確認します。時間測定の条件が同じでも、新しいロジックの正しさが保証されるわけではありません。

Project / map（プロジェクト／マップ）

ゲームの作業領域／その中に保存した 1 つのレベルまたはシーン。

Blueprint

ビジュアルスクリプティング用の Unreal アセット。C++ を書く代わりにノードを接続します。

PIE

Play In Editor。Unreal Editor 内でゲームを実行すること。

Development / Shipping

開発用ビルド／最終配布用の構成。パッケージ化したゲームの記録には Development を使います。

Trace / .utrace（トレース）

記録されたタイミングイベントの元ファイル。

Scope / timer / thread（スコープ／タイマー／スレッド）

測定対象の処理区間／その名前／処理が実行された CPU 上の流れ。

ms / FPS

1 フレーム当たりのミリ秒数／1 秒当たりのフレーム数。1 フレーム当たり 16.67 ms なら、ゲームは毎秒およそ 60 フレームを生成します。

Mean / p95 / p99（平均／p95／p99）

平均フレーム時間／完全なフレームの 95%／99% がその値以下に収まる時間。高いパーセンタイルほど、遅いフレームを重視します。

Warmup / measurement（ウォームアップ／測定）

結果に含めない、安定するまでの待機時間／結果の計算に使う区間。

Baseline / candidate / pair（ベースライン／候補／ペア）

元のビルド／変更を加えたビルド／両方をそれぞれ 1 回実行して組み合わせたもの。

Noise / threshold（ノイズ／しきい値）

繰り返しごとの変動／確認に必要な最小限の安定した効果。

Cook（クック）

パッケージ化したゲームでアセットを実行できるようにする、Unreal の準備処理。

Manifest / profile（マニフェスト／プロファイル）

記録に保存された条件と状態／記録用に選んだ設定。

FrameDoctor 1.0.0 · Unreal Engine 5.5、5.6、5.7、5.8 · Windows 64 ビット。

サポートを依頼するときは、エンジンとプラグインのバージョン、PIE と Development のどちらを使ったか、クリックした操作、保存された状態と理由、期待した結果を含めてください。役立つ場合は、スクリーンショットや内容を確認済みの検証データバンドルを添付します。個人のパスや、内容を確認していない生ログの共有は避けてください。

このガイドの誤りや分かりにくい説明については、ドキュメントの Issue を作成してください。プラグインのサポートには、FrameDoctor の製品ページまたは購入先に記載されたサポート窓口を利用してください。