デバッギングの実行

概要:フレームレートのデバッグ方法の問題とUnreal Engine での障害について

ドキュメントの変更ログ:Mike Fricker により作成および更新。

ゲームパフォーマンス概要

次のセクションではパフォーマンス問題、ボトルネックや障害を追跡するのに最も役に立つツールの習得ができるようになっています。

通常、はじめの命令はフレーム場CPU または GPU パフォーマンスにより制限されているかいないかで決定します。

コマンドが多すぎるため CPU の実行が遅い場合は、これを助けるデバッギングツールが入手可能です。時折、単にアクタが多すぎ、フレームを遅くしてるその他の「動いている部分」があったり、またはAI クラスがフレームごとに何千もの放射線を発動していることがあります。少し時間をかけると、それらのパフォーマンス問題を個別のレベルアクタにまで追跡することができます。

GPU パフォーマンスには、描画イベントまたはシェーダパフォーマンスを解析するため PIX を使わなければいけません。また、ゲーム内可視化モードおよびHUD 統計値も同様です。それらの問題はコンテンツレイアウトおよびライティングプロパティにも追跡することができます。

どちらにしても、持続フレームレート問題、またはヒッチ（大きなフレームタイムの大幅な変化）問題に対応することになります。低い持続フレームレートには、単独フレームキャプチャーツール(TRACE コマンドなど)やプロファイラ(VTune など)のサンプリングなどが非常に役立ちます。ヒッチには、コールグラフを使っている履歴フレームを解析する StatsViewer ツールを使ってください。

コンソールは通常PCとはことなるパフォーマンスでバッギングツールを持ちますが、Unreal の多くのツールは複数のプラットフォームで動作します。

デバッギングの実行:手順

デバッグの準備

1. まず最初に、ゲームを実行中に STAT UNIT があるということを確認する。
2. ビルド環境 を設定する。パフォーマンスを測定時、 ShippingDebugConsole (LTCG) ビルドを、パフォーマンスをデバッギング時は Release ビルドを使用する。
3. ログスパムをオフ またはパフォーマンス結果を損なうデバッグコードを確認する。
4. ヒッチングの原因となるため、 ガーベジコレクション検証 をオフにする。
5. 最終リリース モードのスクリプトをコンパイル。
6. VSyncを無効 にする。これによりボトルネックを認識することができる。敏速なフレームにも有効。

ボトルネックのタイプの分離

• なぜフレームが遅いのかを決定するため STAT UNIT を使う。
  • CPU または GPU に問題があるかを分離する。

CPU – 遅い C++ または UnrealScricpt コードの追跡:

• CPU でのヒッチを認識する STAT SLOW をオンにする * STAT SLOW を使用時に、 ScriptTime でヒッチが見られる場合は、スクリプトタイミングデータまで掘り下げるよう、 StatsViewerJP または ScriptProfilerJP を使うようにしてみる。
• プラットフォーム CPU サンプリングツール を使っているC++ コードのプロファイリングデータをキャプチャする。
• UnrealScript 呼び出しおよび StatsViewerJP で使う統計値ベースのタイミングデータをキャプチャする。
  • これはヒッチおよびパフォーマンスバグの追跡に最高！
• UnrealScript コードでホットスポットを検索するため ScriptProfilerJP を使う。

GPU - レンダリングのパフォーマンスが低い原因を決定する。

• 遅い描画呼び出し、コストの高いシェーダや不正はリソース処理などを見つけるのに GPU プロファイリングツール を使う。

典型的なUnreal Engine パフォーマンス問題を解決に向けてガイド:

• MoveActor 呼び出し: MoveActor() の呼び出しは包括時に特によく見られる。

• SkeletalMeshComponent アップデート: SkeletalMeshComponent::Tick の呼び出しは包括時に特によく見られる。
• LineChecks^?: SingleLineCheck/MultiLineCheckに多くの時間がかかりすぎている。

レベルコンテンツとアセットが最適化されていることを確認する:

• しばしば、パフォーマンス問題は変更やレベルまたはアセットの最適化を解決する必要がある。 ヘルプで利用可能はツールについては コンテンツの最適化 をご覧ください。

パフォーマンス参照

フレーム/スレッド/GPU 時間 (STAT UNIT)の表示

フレームタイムボトルネックがどこにあるのかを特定するため STAT UNIT コマンドを使います。 *STAT UNIT*は、フレームタイム、ゲームスレッドタイム、レンダースレッド(描画)タイムおよびGPUタイム（可能ならば）を表示するオンスクリーンHUDをトグルします。 これはパフォーマンス問題を追跡するのに非常に有益な最初のステップです。このコマンドは常にオンにしておくと良いでしょう。

また、スクリーンでフレームレートやフレームタイムを表示するには STAT FPS を使います。

ビルドコンフィギュレーション

パフォーマンステスト時には、 Release または ShippingDebugConsole (LTCG)のビルドコンフィギュレーションを使います。 ShippingDebugConsole は出荷タイトルの近い数を割り出します。しかし特定のメトリクスやデバッギング機能(Stats キャプチャーなど)の実行は可能ではありません。 ちょっとした調節には、 相対的 に結果を見ない限り、 Release ビルドがパフォーマンスおよびメモリテストにおいて十分でしょう。

ビルドでテストをする場合、コマンドで抑制するかコンパイルタイムで #ifdef'ing することにより外部のロギングをオフにするよう注意してください。例えば、 "suppress AILog" コマンドはC++ およびスクリプトルーチンを遅くするゲーム固有のAIロギングをオフにします。

ガーベジコレクション検証をオフにする

パフォーマンスの作業時には、 GC 検証 を常にオフにしします。そうでないと Release ビルドに最低30秒ごとにひどいヒッチングが起こります。次のメソッドのひとつを使いこれを行うことができます。:

• _UnObjGC.cpp_で、 VERIFY_DISREGARD_GC_ASSUMPTIONS が 0 になっている。
• -NoVerifyGC コマンドライン引数を渡す。

最終リリースモードでのスクリプトのコンパイル

ロギングやアサーションが有効時は、UnrealScript のパフォーマンスは著しく異なります。出荷タイトルに近いパフォーマンスを得る一番簡単な方法は、 Final Release モードでスクリプトをコンパイルすることです。これはコンパイルされたバイトコードからのコストの高い呼び出しを自動的にストリップします。次のメソッドの1つから Final Release スクリプトをビルドすることができます:

• Unreal Frontend で Cooking タブを選択し "Cook Final Release Scripts" チェックボックスを有効にする。次にクッカを実行時、または UFEでゲームを立ち上げ時、 Final Release スクリプトはコンパイルされ使われます。
• -Final_Release コマンドラインパラメータを make コマンドレットに渡す。

VSyncの無効化

一番良い結果を得るには、 VSync (フレームの表示前に頂点のリトレースを待つ)をオフにします。 そうでないと、フレームタイムはゲームのリフレッシュレートに埋め込まれてしまい、正確な図を得ることが難しくなってしまいます。 VSync のオフの仕方:

• -NoVSync コマンドラインオプションをゲームに渡す。 f Unreal Frontend の *Game タブにある "No VSync" チェックボックスを有効にする。

STAT SLOW を使う

パフォーマンススパイクを検出するため、 STAT SLOW コマンドを使います。フレーム(デフォルトで10秒)で特定の期間以外は実行しないサイクル統計値を報告することによりヒッチを絞り込むことができます。 ゆっくりと実行する統計値はしばらくの間 HUD で表示され、スクリーン上のゲームビヘイビアとスパイクを容易に関連付けます。

これを使うには、閾値が秒(10秒は0.01になる)で示すと何になるか、また、一度スパイクされた統計値がレンダリングにどのくらいかかるかを、任意の引数とともにをコンソールに入力します。デフォルトで10秒です。

例: STAT SLOW 0.01 10

これは、最後の10秒で10秒以下になっているすべてのサイクル統計値をレンダリングします。

CPU のプロファイリング化

CPUパフォーマンス問題としてフレームボトルネックを個別にしたあと、次の段階としてC++ コードのどの部分で時間が費やされるかを決定します。 また、非表示のLoad-Hit-Stores やキャッシュミスのようなパフォーマンスコストの検索をしても良いでしょう。

たいていのプラットフォームはロバストCPUサンプルツールがついており、詳細なコードメトリクスやライブセッションでキャプチャーされたデータを用いたC++用の呼び出しグラフさえも提供することができます。例えば、Windows プラットフォーム上では、ホットスポットを隔離するよう短い期間でサンプルデータをキャプチャするため Intel VTune を使うことでしょう。 コンソールプラットフォームには同様なツールがあり、しばしば開発ツールチェーンとともに含まれます。

それらのアプリケーションに慣れたい場合は開発過程において広く使用することです。

あるコンソールでは、Unrealには単独フレームCPU/GPUサンプリングキャプチャの実行を助けるユーティリティ機能が付いていることに留意してください。 CPUトレースを起動するには TRACE GAME と入力し、GPUデータをキャプチャーするには TRACE RENDER と入力してください。

ほとんどのCPUプロファイラはサンプリングデータのキャプチャーや短期間のコールグラフデータをサポートします。 これは抑制された低いフレームレート関連のデバッギング実行問題に最適です。 Sampling captures は関数にC++ コードでホットスポットの呼び出しをさせます。 これは時々役に立ちますが、 Call Graph capture よりは使い勝手がよくないことに気づくでしょう。

はキャプチャータイムオーバーヘッドがよくありますが、ホットスポット関数の 呼び出し者 についての詳細な情報を提供します。これは問題の原因となっているものにダイレクトに導いてくれます。 多くのオブジェクト/アクタが、遅くなっている原因の単独の関数を呼び出している時でさえも、コールグラフは特定のアクタクラス名や原因となるような他のものに導いてくれます。

時々、コールグラフは UnrealScript が時間をとっているように表示します( ProcessEvent CallFunction に呼び出す)。その場合は、そのコールに掘り下げてみるよう、 StatsViewerJP または ScriptProfilerJP キャプチャを実行します。

フレームヒッチを処理中、 CPU プロファイラは比較的低サンプリングなため扱いにくい時があります。ヒッチがゲームで容易に再生成される場合、短期のCPUプロファイリングセッションをキャプチャー時に、できるだけ頻繁に(理想的にはフレームごとに何回も)ヒッチを起こすようにすることが良い方法といえます。もし、ヒッチが予測不可の場合は、 StatsViewerJP のキャプチャデータを使用します。これは多数のフレームで履歴コールグラフデータを提供します。

StatsViewer を使ったプロファイリングコード

CPU パフォーマンス問題の追跡には StatsViewer を使います。また、 UnrealScript コードの詳細プロファイリングツールとして作動します。

StatsViewer は、PIXでするような同様のソートやデータを表示したりできるグラフタイムラインに沿って、 UnrealScriptすべての関数呼び出し および * ゲームStat* (値カウンタ、サイクルタイマーなど)を表示します。さらに重要なことに、スコープされたサイクルStatやスクリプト関数の 階層コールグラフ を表示します。これにより既存のフレームで 「何が遅いのか」がわかります。 (グラフウィンドウにあるフレームをダブルクリックしてください)

準備:

• 使っているビルドで STATS が 1 に設定されているよう確認する (UnBuild.h)。
  • デバッグおよびリリースビルドでデフォルトで有効化されている。 スクリプトコードをプロファイルするには、 *STATS_SLOW が 1 になっていることを確認する (UnStats.h)。
  • これはプロファイリングを遅くするが、UnrealScript 呼び出しの詳細なコールグラフを提供する。

Statデータをディスクにキャプチャするには(推奨)：

• ディスクにStatをキャプチャリングし始めるようコンソールで "STAT StartFile" と入力する。
• それが終わったら、ロギングを中止し統計ファイルを終了するよう "STAT StopFile" と入力する。
• app スタートアップで直ちにStatのキャプチャリングを始めるには、 "-StartStatsFile" パラメータを渡す。
• コンソールで、必ず -DisableHDDCache コマンドラインオプションを渡す。
  • これはHDD (統計ファイル書き込みで競う)へのテクスチャミップマップのキャッシングをオフにする
• Statファイルは \UnrealEngine3\\Profiling\ folder に吹き出される。
  • コンソールで、StatデータはUnrealConsoleにより自動的に PC に転送される。
• StatsViewer を実行し、ファイルを読み込む(例：-07.15-18.58.ustats)

実行しているゲームからライブStatをキャプチャするには:

• ゲームをロードアップする。
• Connect to IP を使用しているXenon セッションに StatsViewer を接続する。
  • Xenon で、Xenon の "Title IP Address"(タイトルIP アドレス)を使う。"Debug Channel IP Address" (デバッグチャンネル IPアドレス) ではない。
    • [Show All Target Information]（すべてのターゲット情報を表示）をクリックすることで UFEにてこれを見つけることができる。
  • ポート番号が必ず 13002 に設定されていること。
• ライブStatは UDP 接続を通してストリーミングを開始する。
• ファイル -> 保存でキャプチャされたデータをディスクに保存できる。

Statデータを見る:

• ツールに .ustats ファイルをロードアップするかライブゲームセッションに 接続 する。
• 対話型グラフは最初にフレームタイムを表示するためヒッチや傾向を見ることができる。
• Statデータを表示するには、左のカラムからグラフにStatを ドラッグアンドドロップ する。
• フレームを選択するにはグラフを クリック し、そのフレームのStatデータを見る。
• フレームの Call Graph(コールグラフ)を開く には グラフを ダブルクリック する。
• 左側のカラムにあるStatを "View Frames by Criteria"(分類別にフレームを表示する)ため右クリックする(例：FPS < 20でのフレームのみ)。
• 表示モードを切り替えるのにメニューオプションを使う(フレーム番号に対してのタイム。範囲限定/全体のデータ)。

その他：

• LTCGモードでは動作しない(ローカルで #define STATS しない限り) リリースを使う。 * ライブStatキャプチャは未だにバグの気配がある(フレーム落ちやスクロールなど、やや微妙)

リアルタイム Stat キャプチャについての更なる情報は このページ をご覧ください。

UnrealScript パフォーマンスの調整に ScriptProfiler を使う

ScriptProfiler はスクリプトコードで高くつく関数についてのすばらしい情報をたくさん提供してくれます。 極めて早くプロファイリングデータをキャプチャし、短いサンプリング期間でホットスポットへのアクセスが即時にできます。

スクリプトプロファイラデータのキャプチャをするには:

• データをキャプチャリングし始めるようコンソールで "PROFILESCRIPT START" と入力する。
• それが終了したら、キャプチャリングを中止するため "PROFILESCRIPT STOP" と入力し、ディスクにデータを保存する。
• Statファイルは \UnrealEngine3\\Profiling\ folder に吹き出される。
  • コンソールで、StatデータはUnrealConsoleにより自動的に PC に転送される。
• ScriptProfiler を実行し、ファイルを読み込む(例：-07.15-18.58.uprof)

更なる情報については ScriptProfilerJP ドキュメンテーションを参照。

注記: 多くのケースにおいて、 StatsViewerJP ツールは、ランタイムオーバーヘッドのコストで、 ScriptProfiler よりさらに多くの詳細なスクリプトプロファイリングデータを提供することができます。 Stat データをキャプチャリング時、#define STAT SLOW を必ず 1 にしてください。また、StatsViewer はフレームの UnrealScript コールグラフすべてを表示します。

コンソールでの実行

コンソール固有実行情報はサブページにあります。

統計コマンドの完全なリストは、 統計の説明 ページを参照してください。

コンソールコマンドの完全なリストは、 コンソールコマンド ページを参照してください。