在遊戲編輯器中用 3D 熱區圖查看事件分布

Framedash 的編輯器內 3D 熱區圖，可以將記錄到的事件分布疊加在實際關卡上。在 Unity、Unreal Engine 5 和 Godot (C#) 中，半透明方塊能協助你查看樓梯、出入口或上下重疊的樓層附近有哪些事件聚集，不必只靠俯視地圖推算位置。

使用前先確認顏色的意義：目前編輯器的疊加顯示以事件筆數著色。儀表板另有各種效能指標檢視，但 SDK 的編輯器控制項無法選擇 FPS、影格時間、GPU 時間或記憶體作為著色指標。紅色體素表示該格在這次取得的資料中記錄了較多事件，不能據此判定這裡有效能問題。

一個體素代表什麼

體素是代表一個彙總網格單元的小方塊。編輯器向 API 要求按 XYZ 三個軸彙總的資料，再將格子畫在對應的網格座標上。呈現的是事件分布，不是每筆事件的精確位置，也不是工作階段重播。

沿三個軸分組，有助於區分平面檢視中重疊的空間。例如，只要格子夠小，陽台上和下方中庭裡發生的事件就能落在不同格子；網格太粗時，兩者仍可能合併。不含 z 的舊版 API 回應，則會在設定的地圖基準面上繼續顯示為平面格子。

從藍到紅的五段漸層，以回應中的最大 weight 為基準。目前編輯器端點回傳的這個權重就是事件筆數。Unity 和 Godot 會在圖例旁顯示格子數與最大權重。比較截圖前先看這些數字：兩次取得的資料中，即使格子同樣是紅色，事件筆數也未必相同。

每次最多回傳 10,000 格，依權重由大到小排序。如果達到上限，部分事件較少的格子可能沒有被回傳。可以縮短時間範圍、依事件名稱篩選，或放大格子後重新取得資料。沒有記錄到符合條件的事件時，該區域也會留白；空白不能證明那裡的效能良好。

準備資料與讀取權限

疊加顯示需要帶有非空 map_id 和有效世界座標的事件，以及 Framedash 中已註冊的對應地圖。也要檢查地圖的世界座標邊界，範圍外的事件不會計入網格。如果已經在傳送符合條件的事件，就能使用現有資料。自動傳送的 perf_heartbeat 沒有位置，map_id 也是空的，因此只有心跳事件還無法產生這個空間網格。

在編輯器設定具有 analytics:read 權限的 Read API Key，以及對應的專案 ID。這和遊戲傳送事件時使用的唯寫金鑰不同。如果不想把讀取金鑰儲存在編輯器設定中，可以在啟動編輯器前設定 FRAMEDASH_ANALYTICS_API_KEY，並將金鑰欄位留白。三個 SDK 都支援這種方式；若欄位中已有金鑰，則優先使用輸入的值。

唯讀金鑰仍是認證資訊，不應出現在版本控制、匯出的遊戲、記錄檔或截圖中。API 基礎 URL 應指向實際存放資料的部署環境。

在各引擎中開啟熱區圖

以下操作是在 2026 年 7 月 24 日的 SDK 更新中加入的：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 分量直接對應 SceneView 的 X/Y/Z，不會為了配合地面而交換座標軸。Z Offset 只移動顯示位置，不會修正或改寫儲存的座標。

Unreal Engine 5 關卡視口

在 Project Settings > Plugins > Framedash Heatmap 設定 API URL、專案 ID、讀取金鑰與顯示選項。開啟 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 將 3D 編輯器攝影機對準已載入的格子。

面板也提供事件名稱篩選、不透明度與 Z 偏移設定。格子由快取的半透明網格繪製，遊戲執行時會隱藏疊加層。設定儲存在專案的編輯器中繼資料 .godot/editor/editor_layout.cfg，因此應將 .godot/ 排除在版本控制之外。熱區圖程式碼僅供編輯器使用。

如何搭配效能調查

儀表板和編輯器顯示的資料範圍不一定相同。目前編輯器可依地圖、時間範圍、格子大小和事件名稱篩選，不會沿用儀表板所選的建置版本、平台或效能指標。

調查效能問題時，可以依照下列順序使用：

1. 在儀表板選擇地圖、建置版本、目標平台與時間範圍，查看效能指標及其數值。熱區圖一次顯示一個建置版本；基準版本與待比較版本的數值對照則在 Regression 頁面進行。
2. 開啟對應關卡，取得編輯器的事件檢視，確認量測記錄到的活動分布在哪裡。如果所選時段包含多個建置版本或平台，就不能把這些體素視為儀表板所選版本的單獨結果。
3. 在適當的量測建置版本中重現可疑路線或場景，用引擎分析工具擷取資料，再依擷取結果調查算繪工作、指令碼或記憶體配置。體素出現在某項資源附近，不能證明負載來自該資源。
4. 修改後，在可比較的條件下重新量測，維持裝置、設定、路線與量測區間一致，再比較數值。編輯器顏色變冷，可能只是事件變少或相對最大值改變，不能據此確認修正有效。

事件密度也取決於記錄的位置與頻率。死亡事件熱區圖描述的是記錄到的死亡分布；定時擷取的位置事件描述的是取樣活動。兩者都不會自動成為停留時間圖。取樣率改變後，可供比較的資料也會改變。

沒有顯示或位置不對時

先檢查專案 ID 與金鑰權限，再核對已註冊的地圖 ID、時間範圍及事件名稱篩選條件。確認事件確實送達，座標符合預期，而且位於地圖邊界內。用 Frame 或 Frame Heatmap 找到已載入的資料，並檢查是否在停止播放時啟用了顯示開關。

如果疊加層偏移，先核對關卡與記錄資料的座標系統，再調整顯示偏移。若在記錄事件後移動了關卡幾何結構，舊資料即使正確對應舊配置，在目前場景中也可能看起來錯位。

第一次驗證時，選一張地圖和一種發生位置已知的事件。確認它出現在預期位置後，再擴大查詢範圍。

• 儀表板的指標與篩選方式請參閱效能熱區圖。
• SDK 安裝與設定請參閱 Unity、Unreal 和 Godot 指南。