scenario-unreal-performance

Unreal Engine 5.8 のパフォーマンスエンジニアリング

ここでいうエキスパートレベルとは、フレーム毎秒ではなく、各ステージにかかるミリ秒で評価することです。1 回の正確なキャプチャでボトルネックを分類し、待機するスレッドではなく、処理を行うスレッドに基づいて最悪のフレームを説明し、測定された規模の大きい問題から順に修正し、同じルートとビルドで実行を繰り返して結果を証明します。ヒッチは平均とは分けて評価します。パフォーマンスエンジニアは計測、診断、証明を担当し、修正の大半はコンテンツを担当するチームメイトに戻します。ここに記載されている関連スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください (npx skills add scenario-labs/skills --skill <name>)。自動で進める場合は、ツールのスキーマを基に作業し、不足しているスキルを明示します。

必須の背景知識： scenario-unreal-expert（チャンネル、レビューの反復、5.8 の落とし穴）。

ステータス（2026-09-24）： scripts/ue_perf.py は、まだ Unreal で実行されていません。純粋なレイヤーは tests/code/unreal-performance/run_all.sh のテスト（合成キャプチャを使用するオフラインテスト 50 件）に合格しています。Unreal の名称はすべて［要確認］です。最初に job_probe_perf.py を実行してください（手順 P0）。

姿勢（専門家から得られた知見）

• ステージごとのミリ秒を把握し、その後に適切なツールを使います。 60 fps では、ゲームスレッド、レンダースレッド、GPU はそれぞれ 16.6 ms の時間を使い、ゲーム N、レンダー N-1、GPU N-2 の順にパイプライン処理されます（W4R [00:05:17] [00:08:26]）。fps ではなく ms で報告します（ARI22 [00:14:44]）。stat unit で分類し、Insights で CPU のどこが原因かを調べ、GPU キャプチャで GPU の状況を把握し、計測だけでは原因を特定できなくなったらサンプリングプロファイラーを使います（KEN [00:04:04]；NORSE [00:17:30]）。
• 修正に取りかかる前に、正直なキャプチャを取得します。 ターゲットハードウェアで Cooked Test ビルドまたは Development ビルドを使い、ルートを固定します。動的解像度をロック（75%）し、パスの帰属を調べる場合に限って非同期コンピュートを無効にします。検証時には無効にしません（NORSE [00:44:40] [00:45:12]）。「予算内か」を確認するには簡易キャプチャを、「なぜか」を調べるには詳細キャプチャ（-statnamedevents、オーバーヘッド約 20%）を使います（NORSE [00:11:27]）。-NoVerifyGC と -handleensurepercent=0 により、Development ビルドで発生する見せかけのヒッチを取り除けます（NORSE [00:13:35] [00:16:23]）。
• 最も長いバーは多くの場合待ち時間であり、待ち時間も予算に含まれます。 アイドル、待機、フレーム同期のマーカーを除外し、依存先をたどって処理を行っているスレッドを確認します。フレーム N のレンダリングが遅いと、フレーム N+1 でゲームスレッドの待機として現れます（KEN [00:09:54] [00:16:30]）。アニメーションと移動の最終処理待ち（NPC 300 体で約 2 ms）は削減可能です（W4R [00:16:20]）。
• Epic のスケーラビリティ設定は 30 fps モードです。 High（2）が 60 fps の設定であり、60 fps のデバイスプロファイルを選択する仕組みは自分で構築しない限りありません（OZ26 [00:11:00] [00:16:50]；LVP）。解像度の連鎖（dynres で 800p から 1080p、TSR で 1440p、空間アップスケーリングで 4K）は、レンダリングにおける最大の単独調整項目です（OZ26 [00:14:41]；W4R [00:43:08]）。
• 機能ごとに予算を割り当て、差分を測り、階層をたどります。 Lumen GI と反射は 60 fps で約 4 ms かかります。Lumen を無効にしたときのフレーム差分として確認します（OZ24 [00:37:55]）。Nanite では、まず予算を確認し、次に Evaluate WPO と Pixel Programmable ビューを使い、Overdraw は最後に確認します。ビューで場所は特定できますが、原因の証明にはなりません（OZ24 [00:29:18] [00:32:13]）。VSM では、静的と動的の無効化のうち大きい方を追います（OZ24 [00:48:59]）。非同期コンピュートは機能ごとに A/B テストします。Witcher のデモでは全体で約 1.5 ms の効果がありましたが、Lumen の反射を再びグラフィックス処理に戻した方が、さらに大きな節約になりました（W4R [00:20:42] [00:21:48]）。
• デフォルト設定は使いやすさを優先しています。大きな改善につながるのはコンテンツ設定です。 あらゆる場所での複雑なコリジョン、ロード時のオーバーラップ、出力解像度いっぱいでの After DOF トランスルーセンシー、VSM と併用する DF シャドウ、3 回分のコストがかかる PDO または WPO フォリッジ（VisBuffer、VSM、カスタムデプス）、重なり合う影付きのローカルライト、Movable のままのプロップなどです（NORSE [00:38:53] [00:49:03] [00:53:48] [00:49:35]；FFW [00:52:59]；ARG [00:11:54]）。
• ヒッチは独立したパスとして対処します。 数百 ms の遅延はほぼ間違いなくブロッキングロードであり、オーサリング時にバリデーターで検出できます。GC のコストは UObject 数に応じて増加し、スポーンはインクリメンタルではありません。カメラカットではオクルージョン履歴が失われます。コンソールではランタイム PSO ヒッチは発生しませんが、PC と Mac はコールド状態でテストします（HITCH [00:43:07] [00:45:16] [00:38:31] [00:25:08] [00:35:50]；W4R [00:44:44]；PSO blog）。動的解像度ではヒッチを解消できません（W4R [00:43:38]）。
• 応急処置より先にコンテンツを修正します。 非同期物理初期化、インクリメンタル GC、dynres は増加を隠します（HITCH [00:22:56] [00:41:56]）。dynres でフレーム全体を緩和するのではなく、スパイクする機能だけを制限します（W4R [00:38:55]）。

まず確認すること

入力	変更点	指定がない場合のデフォルト
対象ハードウェアと、そこで計測する担当者	すべての数値。この Mac から開発キットにはデプロイできません（プラットフォーム SDK とソースビルド、PKG）	確認します。それまでは Mac の数値を代替値として明記します
フレーム目標、出力解像度	ステージの予算、解像度の連鎖	60 fps、コンソールでの 4K 出力
動的解像度ポリシー	プロファイリング中の固定設定、出荷時の範囲	オン。1440p のセカンダリの 55～75％（OZ26 [00:15:48]）
利用可能なビルド	Test での検証。メモリトレースには Development が必要（INS）。Launcher エンジンでは DebugGame、Development、Shipping のみをパッケージ化可能（PKG）	ソースエンジンでは Test、それ以外ではノイズフラグを指定して Development
経路	再現性	最も負荷の高いシーン、群衆、戦闘、最高の移動速度、カメラカットを、BugIt のウェイポイントとして記録
品質基準、トレードオフの承認者	同等性の判定基準	見た目（ライティング、アート）の責任者

ワークフロー

import ue_perf as P（エージェント側）。コマンドは scenario-unreal-expert のチャネルを通じて実行します。パッケージ化されたビルドで指定できるのは、起動フラグと Level Sequence のイベントトラックのみです。

0. ツールを調査します。 API 名と cvar については job_probe_perf.py を実行し、最初の TraceQuery 出力に対して P.schema_probe(jsonl) を実行します。ゲート：計画したすべての cvar の値が出力されていること。TraceQuery のキーが対応付けられていること。
1. 差を明確にし、予算を設定します。 38 fps は 26.3 ms で、16.67 ms を 9.6 ms 上回ります。 P.budget_table(platform, fps, pass_budgets)（OZ26 [00:45:55]）。ゲート：すべての行に根拠があること。各パスの合計がステージの予算内に収まること。
2. ルートを設定し、適切にキャプチャします。 P.route_from_bugit(log)（パッケージ化されたビルドの場合は P.route_event_track）、P.capture_plan("budget", ...) を実行し、3 回測定します。ゲート：負荷を抑えた測定が 3 回あること。ばらつきが把握されていること。測定条件が同一であること。
3. 分類します。 P.diagnose_bound(frames, 16.67, context=...) でボトルネック、差、注意点、次のキャプチャ内容を確認し、スケーラビリティの読み戻しを確認します（P.stat_sequence("scalability_readback")）。ゲート：ボトルネックが特定されていること。差が ms 単位で示されていること。注意点への回答があること。
4. まず設定を見直し、測定ごとに変更を 1 つだけ加えます。 スケーラビリティを 2 に設定し、それを有効にするセレクターを指定します。解像度の設定順序を確認します（P.day_one_60fps_cvars、P.device_profile_block、P.write_ini_section。まずバックアップを作成）。P.apply_ini_keys を通じて P.day_one_engine_ini() を適用します（Use Simple as Complex、ストリーミング中の NeverUpdate overlaps）。Performance Overview（OZ26 [00:41:56]）で読み取った Lumen のフォリッジしきい値を 0 に、ラフネスしきい値を 0.4 未満にします。Gen9 では r.GTSyncType 2 を設定します。ストリーミング時間は既定の 5 ms 未満に抑えます。各変更を P.ChangeLog に記録します。ゲート：LastSetBy DeviceProfile を読み戻して確認すること。変更ごとに測定すること。品質への影響を A/B 比較すること。
5. ボトルネックの詳細分析（手順 P6〜P7b）。 GPU：属性情報付きの ProfileGPU を P.gpu_pass_table、P.lumen_delta に入力し、その数値を P.feature_budget_check（RT シーン）、P.nanite_triage、P.vsm_triage で確認します。非同期コンピュートについては P.ab_plan(P.ASYNC_AB_VARIANTS) と P.ab_verdict を使用します。 ゲームスレッド：TraceQuery を P.analyze_trace に入力します（非待機タイマー、画面に対するカウント、game_wait、advice）。P.spawn_bursts、dumpticks grouped、obj list -countsort も確認します。 ストリーミング：World Partition Insights でセルごとのコストを確認し、最高速度での移動時にリクエストから表示までにかかる時間を測定します。P.STREAMING_AB_VARIANTS は A/B 比較にのみ使用します。ゲート：予算超過の各分類について、原因、アセット、担当者が特定されていること。
6. 監査し、修正を割り当てます。 P.perf_audit_level()、P.perf_audit_assets()（モビリティ、コリジョンのソース、WPO の境界、Displacement Fade）、P.change_requests(rows) を実行して担当者に依頼を出します。合意後にのみ適用します。同じ BugItGo ビューを使ってパリティを確認します（P.parity_pair）。ゲート：needs_eyes の各ペアを目視で判定すること。
7. ヒッチを確認します。 capture_plan("hitch") でコールド、次にウォームの状態をキャプチャします（コールドはコンソール外でのみ実施）。 P.hitch_snapshots(dir) を実行し、それぞれを P.analyze_trace に入力します。ルート上のカットには P.camera_cut_spikes を使用します。分類できなかったフレームはサンプリングプロファイラーで調査します。ゲート：コールドルートでスナップショットが 0 件であること。ゲームプレイ中にブロッキング読み込みがないこと。GC イベントが 2 ms 未満であること。UObject が 500k 未満であること。
8. 実証し、維持します。 同じルート、ビルド、デバイスで、それぞれ 3 回測定します。選択した非同期コンピュートを使用し、DRS は出荷時の状態に固定します。P.compare_runs を実行してから P.write_proof_report を実行します。Horde で推移を追跡する夜間自動パフォーマンステストを追加して維持します（OZ26 [00:47:43]）。ゲート：判定が stable_at_target であること。「not tested」の項目が記入されていること。

数値

項目	値	比較対象、出典
ステージ予算	各ステージ16.67 ms（30 fpsでは33.3）	ゲーム、レンダリング、GPU、W4R [00:05:17]
Lumen GIと反射	60 fpsで約4 ms、30 fpsで8 ms	フレーム差分、コンソールのHigh、OZ24 [00:37:55]；LVP
ラフネスのしきい値	デフォルトは0.4、コンテンツでは約0.35；0.4は無効時より3倍高速で、知覚できる差はない	OZ26 [00:41:56]；W4R [00:33:42]
HWRTシーン	アクティブなインスタンスは約100,000未満（コンソール、LVP）；Witcher：近距離範囲は約150 m、RTプールは約400 MB、更新は非同期で0.5 ms、1フレームあたりの動的トライアングルは約40,000	PS5、W4R [00:29:30] [00:30:37]
非同期コンピュート	全体で約1.5 ms短縮；グラフィックス上で反射が高速化	PS5、W4R [00:20:42] [00:21:48]
深水域のLumenカリング	1 ms超	PS5、W4R [00:35:18]
解像度チェーン	プライマリは800pから1080p、セカンダリは1440p（4Kの66.67%）、動的解像度は55～75%；セカンダリで約1 ms短縮	W4R [00:43:08]；OZ26 [00:15:48]
ストリーミング	エンジンのデフォルトは5 ms；統合後は2.5 msから1.5 ms（レイテンシーが40%減少）；最終値は0.8 ms；この例ではリクエストから表示まで51フレーム	OZ26 [00:25:25]；W4S [00:22:13] [00:23:55] [00:32:18]
群衆	NPCを300体から200体に削減：ゲームスレッドは11.5 ms、余裕は5 ms	PS5、W4R [00:16:53]
UObject、GC	500k未満なら良好、1M超は不適切；GCは1 msなら問題なし、2 msなら切り分け、10 msなら調査	HITCH [00:39:06] [00:39:39]
スポーン	フレームごとに複雑なアクターを1つ	ローエンドのターゲット、HITCH [00:25:29]

品質基準

測定可能な項目：ステージの中央値と、軽量ルートの各フレームが16.67 ms未満であること（NORSE [00:29:51]）、パーセンタイルとVSyncミスの割合（OZ26 [00:45:55]）；コールド状態でヒッチのスナップショットがゼロであること；P.feature_budget_check に説明のない over がないこと；変更したすべてのcvarを読み戻して確認すること；実行ごとのばらつきを超える差分があること、衛生基準が同じであること。ビジュアル：変更点ごとに同じカメラ位置の比較画像を用意すること；ヒッチスナップショットのスクリーンショット；ビューは位置を示すものとしてのみ使用すること。評価基準の全文：references/critique.md。

よくある間違い

よくある間違い	どのような症状か	対処法
PIE でプロファイリングする	Blueprint と CPU のコストが膨らむ	cooked の Test ビルドを使用します。GPU のトリアージにはエディターのみを使用します（FFW [00:04:29]）。
dynres を有効にしたまま GPU ms を計測する	解像度が下がる一方で、GPU は予算付近に留まる	75% に固定します（NORSE [00:44:40]）。
Async compute を当然のものとみなす	パスの合計がフレーム時間を超える。オーバーラップする処理がないパスのコストも増える	帰属の確認に限り r.RDG.AsyncCompute 0 を使用します。機能ごとに A/B テストを行います（W4R [00:21:48]）。
最も長いバーのせいにする	GameThreadWaitForTask が 34 ms	Render、RHI、またはワーカーまで追跡します（KEN [00:16:30]）。
60 fps の目標に Epic のスケーラビリティ設定を使う	sg.* の出力が 3	デバイスプロファイルとエディター設定でレベル 2 にします（OZ26 [00:12:01]）。
sg.ResolutionQuality=2	解像度が 2% になる	これはパーセンテージです［追加］。
TSR をそのまま 4K に適用する	ポスト処理パスが 4K になる	セカンダリ解像度を 1440p にし、空間アップスケーリングを使用します（W4R [00:42:33]）。
最初に Nanite Overdraw ビューを見る	白いピクセルを追いかける	まず予算、Evaluate WPO、Pixel Programmable を確認し、最後に Overdraw を確認します（OZ24 [00:32:13]）。
長い影の半分がアニメーションする	WPO の葉の影がクリップマップ境界で分断される	r.Shadow.Virtual.Clipmap.WPODisableDistance.LodBias を大きくします（OZ24 [00:46:49]）。
移動するキャラクターに対する VSM のローカルライト	動的ページが毎フレーム無効になる	それらのライトでレイトレーシングシャドウを A/B テストします（AVW [00:26:25]）。
雨や深い水	Lumen の反射と水のコストが増加する	雨天時に Performance Overview を再確認し、粗さを制限します。水には opaque-depth cutoff を設定します（OZ24 [00:40:40]; W4R [00:35:18]）。
PSO のせいにする、またはウォーム状態でテストする	誤った対処になる。2 回目の実行ではスタッターが「解消」される	トレースの特徴で分類します。-clearPSODriverCache を付けてコールド状態で実行します。コンソールではスキップします（PSO blog; HITCH [00:35:50]）。
1 フレームで大量のウェーブを生成する	SpawnActor のスパイク	1 フレームあたりの上限を設け、Tick Animation On Skeletal Mesh Init を有効にし、タイプごとのプールを用意します（HITCH [00:25:29] [00:27:26]）。
カット時のスパイク	カット後のフレームでオーバードローが発生する	r.Nanite.PrimeHZB（5.7）［要確認］を使用します（W4R [00:44:44]）。
多くの変更を一度に測定する	改善分の原因を特定できない	ChangeLog を使い、実行ごとに変更を 1 つにします。
衝突する葉に密度スケーリングを適用する	ゲームプレイが変わる	衝突しないタイプに限って適用します（FFW [00:32:48]）。
複雑なコリジョンをデフォルトにする	200 万三角形のフォールバックでポリゴン単位のクエリが発生する	初日から Use Simple as Complex を使用し、古いメッシュを一括更新し、Nanite のフォールバックを用意します（OZ26 [00:07:23] [00:37:15]; HITCH [00:15:58]）。
「Static」なプロップが Movable のままになっている	約 1,000 個のメッシュで 20% の低下が発生する	Mobility を監査します（ARG [00:11:54]）。

引き継ぎ

scenario-unreal-pipeline-automation からビルドとルーティングを受け取り、すべてのチームメイトからコンテンツを受け取ります。 測定した差分とパリティスクリーンショットを含む診断レポートと JSON 変更リクエストを納品します。

• scenario-unreal-world-building：コンポーネント数、Packed Level Actors、ISM cell transformer、 FastGeo、HLOD、モビリティ、コリジョン、フォリッジの距離。
• scenario-unreal-materials：マスク、PDO および WPO の Nanite マテリアル、最大 WPO ディスプレースメント、 Displacement Fade、シェーディングビン、After DOF の半透明、デカール。
• scenario-unreal-lighting-rendering：Lumen のしきい値、RT シーンと遠距離領域、Lumen Lite、VSM 設定、レイトレースによるローカルシャドウ、DF シャドウ。品質とのトレードオフを承認します。
• scenario-unreal-gameplay：ティック、重要度、スポーンとプール、ブロッキングロード、オーバーラップ、UObject 数。
• scenario-unreal-animation：Animation Budget Allocator（登録済みコンポーネント）、AnimBP の冗長性、 MetaHuman の LOD、群衆数。
• scenario-unreal-vfx：Effect Types、プーリング、Data Channels、GPU 読み戻し、エフェクト内の シャドウ付きライト。
• scenario-unreal-cinematics：カメラカット時のカクつき、シネマティックのスケーラビリティ。
• scenario-unreal-pipeline-automation：デバイスプロファイル、バリデーター（ブロッキングロードのノード、バインディング ルール）、夜間パフォーマンステスト。

UE 5.8 に関する注意事項

• 新しいツール：snapshothitches -start|-stop（stat default が必要）、TraceQuery JSONL（スキーマ [検証]）、UObject Count カウンター、World Partition Insights（Spatial Profiler）、stat unit の VRAM（ ディスクリート GPU のみ）、ProfileGPU のパイプ待機と r.ProfileGPU.TableFormatting 0（rn58、TL パート 2）。
• Lumen Lite は Medium でベータ版、MegaLights は本番運用可能、VSM の無効化遅延予算、5.7 以降はディレクショナルライトのレシーバーマスクがデフォルト、フォリッジタイプの Nanite Pixel Programmable Distance、5.7 以降の r.Nanite.PrimeHZB。
• FastGeo と 5.6 のストリーミング cvar は引き続き実験的機能です（プラグインブラウザーで確認してください）。
• Mac：Apple Silicon のみ。Nanite と VSM はベータ版、Lumen HWRT と MegaLights は実験的機能（M2 以降）。 Insights には ContextSwitch と、一覧表示されたメモリコールスタックがありません。GPU の「理由」は Xcode と Instruments で確認します（MOB）。

参考資料

• references/expert-notes.md：専門家ごとの原則、タイムスタンプ、意見の相違、判断条件。
• references/procedures.md：P0 から P11、および P5b、P6b（疑わしいツリー）、 P7b（ストリーミング）、P9b（カメラカット）。コード、テストパス、ステータスをすべて記載しています。
• references/critique.md：キャプチャ、診断、修正、証拠の評価基準。
• references/gui-paths.md：コンピューター操作エージェント向けの Insights、エディター、Xcode のパス。
• references/sources.md：ソース、認証情報、最適なタイムスタンプ、改訂履歴。
• scripts/ue_perf.py：プラン、A/B プラン、トレース分析、疑わしいツリー、パーサー、設定ライター、証拠、監査。