ue5-performance-packaging

クイックスタート

• 対象プラットフォームとビルド構成を確認します。
• 現在のパフォーマンス上の症状とパッケージ化の目標を収集します。
• パッケージ化前チェックリストと測定計画を出力します。

API の基準項目（UE5.6-UE5.8）

• 実行時の品質とフレーム予算の基準項目：
  • UGameUserSettings::SetOverallScalabilityLevel(...)
  • UGameUserSettings::SetFrameRateLimit(...)
  • UGameUserSettings::ApplySettings(...)
• パッケージ化設定の基準項目：
  • UProjectPackagingSettings
  • BuildConfiguration、MapsToCook、DirectoriesToAlwaysCook
  • UsePakFile、bUseIoStore、bGenerateChunks
• アセット依存関係の検証に関する基準項目：
  • FAssetRegistryModule、IAssetRegistry
  • GetAssetsByPath(...)
  • GetDependencies(...)、GetReferencers(...)
• プロファイリング計測の基準項目：
  • TRACE_CPUPROFILER_EVENT_SCOPE(...)
  • DECLARE_CYCLE_STAT(...)
• 実用的な実行時統計コマンド：
  • stat unit、stat gpu、stat scenerendering、memreport -full

パフォーマンスとパッケージ化の要件

• すべてのパフォーマンス／パッケージ化タスクで、以下を定義する必要があります：
  • 対象プラットフォーム＋ビルド構成＋テスト用マップ
  • 再現可能なキャプチャシナリオ（カメラパス、時間、ネットワークモード）
  • ベースラインのメトリクスと合格しきい値
  • パッケージ化設定一式と依存関係スキャンの範囲
  • 明確な阻害要因を記載した実施可否の結論
• 項目が不足している場合、準備状況の評価は不完全です。

ワークフロー

1）再現可能なベースラインのキャプチャ

• テスト用マップ、カメラパス、スケーラビリティ、ネットワークモードを固定します。
• 同じシナリオで stat unit と stat gpu を繰り返しキャプチャします。
• 単一フレームの急増値ではなく、中央値またはパーセンタイルのメトリクスを使用します。

2）ホットスポットの切り分け

• キャプチャ期間中にコストが最も高いゲームプレイ／レンダリングシステムを特定します。
• コストの高いアクター／アセットをシーンの状況と照合します。
• 原因が明確でないカスタムシステムには、スコープ付き CPU マーカーを追加します。

3）アセットと依存関係の検証

• 対象パスをスキャンし、アセット参照の欠落や破損を確認します。
• 問題のあるアセットの依存関係と参照元を照会します。
• 必須のマップ／ゲームモードのアセットがパッケージ化の対象範囲に含まれていることを検証します。

4）パッケージ化設定の検証

• UProjectPackagingSettings のフィールドが対象リリースポリシーに適合しているか確認します。
• 調理対象マップ、常に調理するディレクトリ、ビルド構成を検証します。
• Pak／IoStore／チャンクの戦略が配布要件に適合しているか検証します。

5）パッケージ準備の試行

• パッケージ化前チェックリストを実施し、ドライラン形式で検証します。
• 最初に発生したパッケージ化を阻害するエラーと依存関係チェーンを切り分けます。
• 未解決の阻害要因を、担当者とリスクとともに記録します。

6）実施可否の判断

• メトリクスとパッケージ化チェックがしきい値を満たした場合にのみ承認します。
• 残っているリスクと推奨する緩和策を報告します。
• 承認の証拠として使用したシナリオと設定を固定します。

制約事項

• 測定可能な変更前／変更後のデータなしに、最適化の効果を主張しないでください。
• プロファイリングシナリオ（マップ、カメラパス、ネットワークモード）は再現可能な状態に保ちます。
• エディターのオーバーヘッドと、パッケージ化した実行環境での動作を区別します。
• 品質スケーラビリティ設定を変更する場合は、必ずその旨を報告します。
• パッケージ化チェックは決定論的に行い、承認時に場当たり的な設定の切り替えを避けます。
• メトリクスの単位（ms、fps、メモリ）とキャプチャ時間を必ず報告します。

失敗への対処

• 症状：実行ごとにパフォーマンスデータのばらつきが大きくなります。
  • 確認箇所：シナリオ設定の非決定性とバックグラウンド処理による変動です。
  • 対処法：シナリオを固定し、ウォームアップ実行を行い、中央値やパーセンタイル値を比較します。
• 症状：最適化の効果を再現できません。
  • 確認箇所：品質設定、マップ、またはランタイムモードの不一致です。
  • 対処法：正確なキャプチャ設定を公開し、同じ条件で最適化前後の実行をやり直します。
• 症状：パッケージのビルドで大量のエラーが連鎖して発生します。
  • 確認箇所：最初にビルドを妨げているエラーと、その直接的な依存関係です。
  • 対処法：最初のブロッカーを先に解決し、再実行して次のブロッカーを確認します。
• 症状：パッケージ化したビルドの起動時にアセットが見つかりません。
  • 確認箇所：クック対象リストの網羅性と依存関係グラフの不足です。
  • 対処法：不足しているマップやディレクトリを含め、壊れた参照を解決します。
• 症状：パッケージ化したビルドのパフォーマンスがPIEのベースラインより低下します。
  • 確認箇所：パッケージ化時のみの設定差異とランタイムのコンテンツパスです。
  • 対処法：パッケージ化した設定をベースラインと比較し、スケーラビリティ設定とデバイス設定を一致させます。
• 症状：コンテンツの多いシーン付近でメモリ使用量が悪化します。
  • 確認箇所：メモリ使用量の多いアセットとストリーミングポリシーの動作です。
  • 対処法：常駐アセットの負荷を軽減し、ストリーミング／クックの戦略を調整します。

パッケージング運用

• リリースビルドでは、暗黙的な検出より明示的なマップ／クック対象リストを優先します。
• パッケージ化の前にAssetRegistryクエリを使用して依存関係を検証します。
• ターゲットプロファイルごとに、リリース用パッケージ設定の信頼できる唯一の情報源を維持します。
• UE5.8では、Zenserverのクック済み出力をイテレーション用ストアとして扱い、配布ビルドではPak/IoStoreのステージング検証を維持します。
• UE5.8のインクリメンタルクッキングはベータ版のイテレーション用パスとして扱い、クリーンなフルクックによるリリースチェックも維持します。
• パッケージ設定を変更した後は、レディネスチェックを再実行します。

UE5.6-UE5.8の互換性に関する注意事項

• 上記のUGameUserSettings、UProjectPackagingSettings、およびAssetRegistry APIは、UE5.6-UE5.8で安定しています。
• ProjectPackagingSettings.hは、UE5.6-UE5.8を通じてDeveloper/DeveloperToolSettingsにあります。
• UE5.8では、サポート対象のイテレーションワークフロー向けに、Zenserverがクック済み出力ストアとしてデフォルトで有効になります。これは、リリースコンテナーの検証に代わるものではありません。

エスカレーション

• パフォーマンスのボトルネックにエンジンレベルのプロファイリングやレンダラーの変更が必要な場合は、エスカレーションしてください。
• パッケージングの問題がサードパーティ製プラグインのビルド失敗に起因する場合は、エスカレーションしてください。