エディタ内の 3D ヒートマップで、イベントの発生位置を確認する

Framedash のエディタ内 3D ヒートマップでは、記録したイベントの分布を実際のレベルに重ねられます。 対応するのは Unity、Unreal Engine 5、Godot (C#) です。 階段や出入り口、上下に重なる空間のどこにイベントが集まっているかを、レベルを開いたまま確認できます。

まず、色の意味を確認しておきます。 現在のエディタ表示で色の基準になるのは、イベントの件数です。 ダッシュボードには性能指標ごとの表示がありますが、SDK のエディタ側には FPS、フレームタイム、GPU 時間、メモリを色の指標として選ぶ機能はありません。 赤いボクセルは取得範囲内でイベントが多かったセルを表し、性能が悪い場所を直接示すものではありません。

ボクセルから読み取れること

ボクセルは、集計したグリッドの 1 セルを表す小さな箱です。 エディタは API に XYZ での集計を要求し、返されたセルをグリッドの座標に描きます。 表示するのはイベントの分布であり、個々のイベントの正確な位置やセッションの再生ではありません。

三つの軸で集計すると、平面表示で重なっていた空間を分けて見られます。 たとえば、セルサイズが十分に小さければ、バルコニーとその下の吹き抜けで起きたイベントを分けられます。 大きなセルでは同じ区画にまとまる場合があるため、階層を見分けるにはセルサイズにも注意が必要です。 z を含まない古い API レスポンスは、設定されたマップの基準面に平面セルとして表示されます。

青から赤への 5 段階のパレットは、レスポンス内の最大 weight を基準にしています。 現在のエディタ用エンドポイントでは、この値はイベント件数です。 Unity と Godot では、凡例の横にセル数と最大値も表示されます。 取得条件が変われば色の基準も変わるため、別々のスクリーンショットで同じ赤に見えても、件数が同じとは限りません。

1 回の取得で返るのは、件数が多い順に最大 10,000 セルです。 上限に達した場合、件数の少ないセルが表示から漏れる可能性があります。 期間やイベント名で絞るか、セルサイズを大きくして再取得します。 イベントを記録していない場所にもセルは出ないので、空白を「性能に問題がない場所」と読むことはできません。

取得前に確認するデータと読み取り権限

必要なのは、空でない map_id と実際のワールド座標を持つイベント、それに対応する登録済みのマップです。 マップのワールド座標の範囲も確認します。 範囲外のイベントは集計に入りません。 この条件を満たすイベントをすでに送っていれば、そのデータを使えます。 自動送信される perf_heartbeat は map_id が空で位置も持たないため、ハートビートだけではグリッドは埋まりません。

エディタには、analytics:read スコープの Read API Key と対応するプロジェクト ID を設定します。 ゲームが送信に使う書き込み専用のキーとは別のものです。 読み取りキーをエディタ設定に保存したくない場合は、起動前に FRAMEDASH_ANALYTICS_API_KEY を設定し、キーの入力欄を空にします。 三つの SDK ともこの環境変数に対応しており、入力欄にキーがあればそちらを優先します。

読み取り専用でも、キーは認証情報です。 ソース管理、配布するゲーム、ログ、スクリーンショットに含めないようにします。 API のベース URL は、データを保存した環境に合わせて指定します。

エンジンごとの表示手順

ここで扱う操作は、2026年7月24日の Unity 0.1.7、UE5 0.1.13、Godot 0.1.8 の更新で導入されました。 これらは機能が加わった時点のバージョンで、各 SDK の最新版を示すものではありません。

Unity の SceneView

1. Window > Framedash Heatmap を開き、読み取りキー、プロジェクト ID、API のベース URL を設定します。
2. マップ一覧を更新して対象を選び、期間、セルサイズ、必要ならイベント名のフィルタを指定します。Play モードの外で Fetch を押します。
3. SceneView の Framedash Heatmap オーバーレイで、Show は表示切り替え、Frame はデータ全体への視点移動、Controls は設定ウィンドウを開く操作です。

設定ウィンドウを閉じても、オーバーレイは残ります。 選択したマップと表示設定はプロジェクトごとに保存され、Play モード中は表示が止まります。

Unity の Vector3 の X/Y/Z は、そのまま SceneView の X/Y/Z に対応します。 地面に合わせるための軸の入れ替えは行いません。 Z Offset は表示位置だけをずらす設定で、記録済みの座標を修正するものではありません。

Unreal Engine 5 のレベルビューポート

API の URL、プロジェクト ID、読み取りキー、表示設定は Project Settings > Plugins > Framedash Heatmap にあります。 Window > Framedash > Framedash Heatmap を開き、マップと取得条件を選んで Play In Editor（PIE）の外で取得します。

表示したいレベルビューポートで Show > Framedash Heatmap を有効にします。 このフラグは既定で無効です。 ビューポートごとに独立しているため、一方を編集用、もう一方を分布の確認用に使えます。 取得パネルを閉じても、取得済みのオーバーレイは消えません。

通常の F9 と高解像度のビューポートスクリーンショットには、ヒートマップも写ります。 問題の報告に添付するときは、マップ、期間、セルサイズ、イベント名のフィルタを併記すると、別の開発者も色の意味を判断できます。 PIE 中は表示を中断し、終了後に元のビューポート設定へ戻ります。

Godot (C#) の 3D エディタ

C# アドオンをビルドして有効にすると、Framedash Heatmap ドックが使えます。 読み取りキー、プロジェクト ID、API のベース URL を入力し、期間とセルサイズを選びます。 Refresh Maps で一覧を更新してマップを選び、Fetch Heatmap で取得します。 Show を有効にし、Frame Heatmap で読み込んだセル全体にカメラを合わせます。

イベント名のフィルタ、不透明度、Z オフセットもドックで設定できます。 セルはキャッシュされた半透明のメッシュとして描画され、ゲーム実行中は非表示になります。 設定の保存先は、プロジェクトごとのエディタメタデータ .godot/editor/editor_layout.cfg です。 .godot/ はバージョン管理から外します。 ヒートマップのコードはエディタ専用です。

性能調査に組み合わせる手順

ダッシュボードとエディタでは、同じ条件でデータを取得しているとは限りません。 現在のエディタで指定できるのは、マップ、期間、セルサイズ、イベント名です。 ダッシュボードで選んだビルド、プラットフォーム、性能指標は引き継がれません。

性能を調べるときは、次の順で使い分けます。

1. ダッシュボードでマップ、ビルド、対象のプラットフォームと期間を選び、性能指標の数値を確認します。ヒートマップは一度に一つのビルドを表示します。ベースラインと候補ビルドの数値比較には Regression ページを使います。
2. 対応するレベルを開き、エディタでイベント分布を取得します。計測した活動がレベルのどこに集まっているかを確認します。期間内に複数のビルドやプラットフォームが混ざる場合、そのセルをダッシュボードで選んだビルドだけの結果とは扱えません。
3. 調査対象の経路や場面を適切な計測ビルドで再現し、エンジンのプロファイラで記録します。その結果をもとに描画処理、スクリプト、メモリ確保を調べます。アセットの近くにボクセルがあっても、そのアセットが負荷の原因だと特定できたことにはなりません。
4. 修正後は、端末、設定、経路、計測区間をそろえて再計測し、数値を比較します。エディタの色が寒色に変わる理由には、イベント件数の減少や相対的な最大値の変化もあります。色の変化だけでは修正の効果を確認できません。

イベントの密度は、どこで、どの頻度で記録したかにも左右されます。 死亡イベントなら記録された死亡の分布、一定間隔の位置イベントならサンプリングした活動の分布です。 どちらも、そのまま滞在時間を表すものではありません。 サンプリング率を変えれば、比較に使えるデータも変わります。

表示されない、位置が合わないとき

まずプロジェクト ID とキーのスコープを確認し、登録したマップ ID、期間、イベント名のフィルタを見直します。 意図した座標でイベントが届いているか、マップの範囲内に入っているかも確認します。 Frame または Frame Heatmap で読み込んだデータを探し、Play モードの外で表示トグルが有効になっているかを調べます。

位置がずれている場合は、表示オフセットを変える前に、レベルと記録データの座標系を照合します。 記録後にレベルの構造を移動していれば、古い配置に対して正しいセルでも、現在のシーンには合いません。

最初は一つのマップと、発生位置が分かる一種類のイベントで確認します。 想定した位置に表示できたら、取得範囲を広げます。

• ダッシュボードの指標と絞り込みはパフォーマンスヒートマップを参照してください。
• SDK の導入と設定は Unity、Unreal、Godot の各ガイドにあります。