game-performance-profiler

ゲームパフォーマンスプロファイラー

主な疑問が 「どのパケットを信頼すべきか、最も可能性の高いボトルネックの種類は何か、次に作成する価値のあるキャプチャまたはレビュー成果物は何か」 である場合に、このスキルを使用します。

目的は、一般的な最適化のアドバイスを並べることではありません。 目的は、現在のパケットを整理し、動作モードを1つ選び、主要なボトルネックの種類を1つ特定し、確度を高めるために必要な最小限の次回キャプチャを推奨し、チームが実際に活用できるプロファイリング成果物を1つ作成することです。

見慣れない形式の依頼に対応する前に、references/mode-selection-and-route-outs.mdをお読みください。 再現可能なパスを設計する前に、references/capture-packets-and-benchmark-routes.mdをお読みください。 携帯機または対象デバイスのレビューでエディターの数値を信頼する前に、references/device-review-and-steam-deck.mdをお読みください。 証拠が不十分または曖昧な場合に分類する前に、references/profiling-patterns.mdをお読みください。 スクリーンショットや統計パケットから、さらに踏み込んだエンジンツールや GPU ツールに進む前に、references/escalation-ladder.mdをお読みください。

このスキルを使用する場面

• ボトルネックをまだ特定できていない、FPS低下、フレームタイムの急増、カクつき、パフォーマンスの低下が発生している Unity または Unreal プロジェクト
• 解釈が必要なプロファイラーのスクリーンショット、stat unit / stat gpu の出力、Unreal Insights のトレース、オーバーレイのキャプチャ、ルートのメモ、ベンチマークに関する報告
• エディター上の印象よりも、パッケージ化してデバイス上で動作させた際の挙動が重要となる、Steam Deck、携帯機、モバイル、コンソール、VR、低スペック環境のレビュー依頼
• すぐにコードを変更するのではなく、プロファイリング計画、ベンチマークルート、デバイスレビューパケット、CPU/GPU の切り分けメモ、エスカレーションの判断が求められる依頼
• 次に担当するべき人がまだ明確でないパフォーマンス関連の混在パケットで、最初にクイックパケット、詳細なトレース、隣接するゲーム関連スキルのどれに進むかを選ぶ場合

このスキルを使用しない場面

• 主な問題が、実行時のフレームタイム診断ではなく、Unity/Unreal のビルド、クック、パッケージ化、エディター、CI の失敗である場合 → game-build-log-triage を使用します
• 主な問題が、エンジン固有の実行時キャプチャの解釈ではなく、一般的な Web/アプリ/サービスのパフォーマンスである場合 → performance-optimization を使用します
• 本来の作業が、バグ、プレイテストのメモ、ローンチ目標、ロードマップのトレードオフにまたがる、マイルストーンまたは制作全般の調整である場合 → bmad-gds を使用します
• パケットの大部分がプレイテスト／デモ／コミュニティからのフィードバックで、優先して修正すべき項目を判断することが課題である場合 → game-demo-feedback-triage を使用します
• 原因が確認済みで、次の作業がすでに踏み込んだ実装変更である場合。プロファイリング概要を作成した後、実装スキルに引き継ぎます

手順

ステップ1：パケットの概要を把握する

診断を始める前に、最低限必要なコンテキストを記録します。

記録項目：

• エンジン：Unity | Unreal | Unknown
• 対象：PC | Steam Deck / 携帯機 | コンソール | モバイル | VR | 低スペックのノート PC | 不明
• 環境：エディター | パッケージ化済み／開発ビルド | リリース／出荷ビルド | 不明
• 症状：平均 FPS の低下 | 突発的なカクつき | 移動中のカクつき | 戦闘中の急増 | 読み込みの停止 | 熱による性能変動 | 不明
• 利用可能な証拠：プロファイラーのスクリーンショット、トレース／キャプチャファイル、統計コマンドのスクリーンショット、オーバーレイのスクリーンショット、動画、ベンチマークのメモ、再現手順
• 再現条件：正確なシーン、セーブスロット、遭遇イベント、移動経路、メニュー、カットシーン、または不明
• 品質に関する変数：解像度、プリセット、フレーム上限、アップスケーラーの状態、電源モード、該当する場合はバッテリーの状態

概要：

Engine: Unreal
Target: Steam Deck
Environment: packaged build unknown
Symptom: traversal hitch after two minutes in market square
Evidence: `stat unit` screenshot + overlay photo
Repro: route not yet fixed

ルール：パケットの情報が少ない場合は確度を低く保ち、次回のキャプチャは対象範囲を広げず、より絞り込みます。

Step 2: 主要モードを1つ選ぶ

references/mode-selection-and-route-outs.mdを使用してください。

主要モードを正確に1つ選びます。

• quick-triage-packet
• bottleneck-classification
• benchmark-route-plan
• device-review
• tool-escalation

ルール：主要モードは1つ、補足は任意で1つです。すべてのモードを一度に扱おうとしないでください。

Step 3: 修正案を提案する前に、考えられるボトルネックの系統を示す

主要な系統を1つ選び、任意で副次的な系統を1つ選びます。

主要な系統：

• cpu-gameplay-scripting
• cpu-render-thread-draw-call-pressure
• gpu-rendering-shaders-postfx
• memory-gc-allocation-churn
• loading-streaming-io
• physics-animation-simulation
• platform-config-thermal-device-specific
• unknown-needs-better-capture

適切なボトルネックの説明：

• 「最も強い兆候は、安定時のGPU負荷ではなく、移動中のストリーミング／IOによるカクつきを示しています。」
• 「このパケットは、レンダリングの飽和よりも、戦闘中のGC／アロケーションのスパイクを示唆しています。」
• 「チームがパッケージ済みビルドを対象デバイスで実行した証拠ではなく、エディターでの印象に頼っているため、デバイス／設定に依存しているようです。」

避ける表現：「全体的にパフォーマンスが悪いです。」

Step 4: 最小限の次回キャプチャを推奨する

考えられる原因を実質的に切り分けられる、最も手軽なキャプチャを選びます。

次回キャプチャの一般例：

• 代表的なプレイヤービルドで取得する、より適切なUnity ProfilerのCPU／GPU／Memoryパケットを1つ
• 正確なUnreal再現ルートで取得する、stat unitとstat gpuの1組
• ウォームアップと反復回数を決めた、固定の移動ルートを1つ
• エディターのスクリーンショットを追加するのではなく、デバイス上でパッケージ済みビルドをキャプチャすることを1回
• より詳細なトレース（Unreal Insights、GPU Visualizer、Frame Debugger、または外部GPUツール）は、最初のパケットで必要性が示された後にのみ行います

ルール：パケットからすでにレンダリング経路に特有の問題が明確に読み取れる場合を除き、ベンダー製GPUツールよりもエンジン標準のキャプチャを優先してください。

Step 5: ルートとデバイスの条件を明示する

再現性に欠ける場合は、最小限の再現可能なテストを定義します。

以下を指定します。

• セーブスロット／チェックポイント／シーン
• 開始地点と移動経路
• ウォームアップの回数
• 計測する反復回数または時間
• グラフィックプリセット／フレーム上限／電源モード
• パケットがエディターのみ、パッケージ済みビルドのみ、または対象デバイスのいずれか

「市場エリアの動作が重い」という感覚を、再現性のあるベンチマークルートとして扱わないでください。

Step 6: プロファイリングの概要を1つ返す

必ず、以下の形式で簡潔な成果物を1つ返します。

# Game Performance Profiling Brief

## Scope
- Mode: ...
- Engine: ...
- Target: ...
- Environment: ...
- Symptom: ...
- Confidence: high | medium | low

## Evidence packet
- What exists now: ...
- What's missing: ...
- Editor vs packaged / device note: ...

## Primary bottleneck hypothesis
- Bucket: ...
- Why it fits: ...
- Evidence: ...

## Secondary hypothesis
- Bucket: ...
- Why it still matters: ...

## Next capture
1. ...
2. ...
3. ...

## Benchmark route / device review
- Repro route or save: ...
- Repeat / warm-up guidance: ...
- Device or packaged-build checks: ...

## Escalation path
- Stay with quick packet | move to engine profiler | escalate to GPU tool
- Why: ...

## Recommended next artifact
- Choose one: quick triage packet | profiling plan | benchmark route brief | CPU/GPU split note | memory/GC checklist | streaming hitch checklist | device review brief

## What not to do yet
- 1-3 bullets that prevent premature optimization or blind rewrites

出力形式

必須要件：

• 修正について述べる前に、ボトルネックを分類する
• 証拠と仮説を分ける
• 膨大なバックログではなく、次のキャプチャ、ルート、またはデバイスレビューの手順を推奨する
• エディターとパッケージ済みビルドの違い、およびパケットとトレースの境界を明示する
• ユーザーから追加の要望がない限り、レポートはおよそ300～550語にする
• Unity Profiler、Frame Debugger、Unreal Insights、stat unit、stat gpu、フレーム時間、ドローコールの負荷、GC、ストリーミング、パッケージ済みビルドなど、エンジン標準の用語を使う

例

例1：Unityの戦闘中のスパイク

入力：「Unityのゲームで、戦闘中にFPSが120から45まで低下します。Profilerのスクリーンショットがあり、GCのスパイクではないかと疑っている人がいます。まず何を調べるべきかトリアージしてください。」

期待する形式： memory-gc-allocation-churnまたはcpu-gameplay-scriptingを中心に分類し、現在のスクリーンショットを実際のパケットとして扱い、最小限の次回キャプチャを推奨します。最初からレンダリング関連の助言に飛びつかないでください。

例2：Unrealのオープンワールド移動中のカクつき

入力：「Unrealは屋内では問題ありませんが、オープンワールドのエリアでフレーム時間が急激に増加します。CPU、GPU、ストリーミング、シェーダーのどれが原因か、トリアージを手伝ってください。」

期待する形式： bottleneck-classificationまたはbenchmark-route-planを使用し、適切にstat unit／stat gpuまたはUnreal Insightsを推奨します。修正案を推測するのではなく、再現可能な移動ルートを定義してください。

例 3：Steam Deck のレビュー資料

入力：「デモ版のリリース前に、Steam Deck のパフォーマンスレビュー計画が必要です。エディター上では粗削りに感じますが、パッケージ化したビルドを実機でまだプロファイリングしていません。」

期待される形式： device-review を選択し、確信度を限定的に保ち、パッケージ化したビルドを実機で確認した証拠を優先して、デバイスレビューブリーフまたはベンチマークルートブリーフを返します。

例 4：ビルド失敗のトリアージへの振り分け

入力：「Unreal のパッケージ化したビルドがクック中にクラッシュし、ランタイムの数値もまだありません。」

期待される形式： これがすでにプロファイリングの問題であるかのように扱わず、game-build-log-triage に振り分けます。

ベストプラクティス

1. すぐに理想的なトレースを要求せず、チームがすでに持っている資料から始めます。
2. 最適化について話し合う前に、主要なボトルネックの種類を1つ挙げます。
3. 再現性を診断の一部として扱い、任意の追加事項にしません。
4. リリース対象が携帯型デバイスまたはリソースに制約のあるマシンの場合、エディターでの印象よりも、パッケージ化したビルドを実機で確認した証拠を優先します。
5. スクリーンショットや統計情報の資料から、GPU ベンダーのツールに飛びつくのではなく、エンジン標準のプロファイラーへ段階的に進みます。
6. 膨大な最適化のバックログではなく、次に用意すべき資料を1つ推奨します。
7. ゲームパフォーマンスの作業が、ビルドのトリアージ、一般的なアプリのチューニング、本番環境の調整にまで広がらないよう、振り分けを明確にします。

参考資料

• Unity Profiler
• Unity Frame Debugger
• Unreal Performance and Profiling Overview
• Unreal stat commands
• Unreal Insights
• GPUOpen Unreal Engine Performance Guide
• Steam Deck のドキュメント