マップ上のどこで FPS が落ちるかを見つける

フレームレートの平均値は、ビルドが遅いことは教えてくれますが、どこで遅いかは教えてくれません。 Framedash のパフォーマンスヒートマップは、各サンプルをワールド座標でプロットします。 そのため、マップ上の赤い領域が FPS の落ちる場所になります。 このガイドでは、マップに紐付いたテレメトリーを送信し、特定エリアの FPS ヒートマップを読み取る方法を示します。

ヒートマップの概念と表示できる指標は、パフォーマンスヒートマップを参照してください。

1. マップに紐付いたテレメトリーを送信する

ヒートマップは、各サンプルを map_id とワールド座標の position でプロットします。 そのため、サンプルがマップ上に載るのは、その両方を持つときだけです。 これらは Track にマップ識別子とプレイヤー位置を渡して付与します。 自動の perf_heartbeat は意図的に非空間で、空の map_id と位置なしで送信されます。 そのため perf_heartbeat は、マップのヒートマップではなく、CI 回帰ゲートとダッシュボードのグラフに使われます。 マップ上にパフォーマンスデータを載せるには、注目したい場所から位置付きの Track イベントを送信してください。

TelemetrySDK.Instance.Track(
    eventName: "player_death",
    mapId: "map_01",
    position: transform.position);

UE5 SDK は、サブシステム経由で同じ 3 つの引数を受け取ります。

if (auto* Framedash = GetGameInstance()->GetSubsystem<UFramedashSubsystem>())
{
    const FVector PlayerLocation(1000.0f, 2000.0f, 50.0f);
    Framedash->Track(TEXT("player_death"), TEXT("Map01"), PlayerLocation);
}

位置は position_x / position_y / position_z として保存され、map_id は最上位フィールドです。 これにより、すべてのサンプルが正しいマップ上に配置されます。 イベントスキーマの全体はデータモデルを参照してください。

2. マップ画像を登録する

ヒートマップは、レベルの背景画像の上に描画されます。 次の 2 つの方法のいずれかで登録します。

• ダッシュボードから、または API で画像をアップロードする。
• ビルドパイプラインからワールド座標メタデータ付きの画像を自動生成し、framedash map-capture --input-dir ./captures --upload でアップロードする。

3. FPS ヒートマップを読み取る

マップ詳細ページ（「プロジェクト」→「[プロジェクト]」→「マップ」→「[マップ]」）を開き、Heatmap モードに切り替えると、FPS、フレームタイム、GPU 時間、メモリがレベル上にオーバーレイ表示されます。 赤い領域が最もパフォーマンスの低い場所を示します。 表示はビルドバージョン、デバイスプロファイル、日時範囲、セッションで絞り込めます。 2 つのビルドを並べて、最適化がホットスポットを実際に動かしたかを確認することもできます。

同じデータをプログラムから取得するには、MCP の get_heatmap ツールか REST エンドポイントを使います。 get_heatmap は map_id（必須）に加えて cell_size、days、任意の event_name を受け取ります。 REST の対応は GET /v1/projects/{id}/heatmap です。 MCP で接続した AI エージェントは、このツールで「マップの FPS ヒートマップを表示して」に直接答えられます。 詳細は MCP サーバーリファレンスを参照してください。

次のステップ

• パフォーマンスヒートマップ：指標、フィルタリング、ビルド比較
• データモデル：位置、map_id、パフォーマンスフィールド
• MCP サーバー：自然言語でヒートマップを照会する