跳到內容
Framedash Docs

UE5 SDK

說明如何使用 Framedash UE5 SDK（C++ 外掛程式）自動收集效能遙測資料。

需求

Section titled “需求”
  • Unreal Engine 5.3 以上
  • C++ 專案（不支援純 Blueprints 專案）

安裝

Section titled “安裝”

從 Framedash UE5 SDK 儲存庫 取得外掛程式 —— 在 Releases 頁面 下載最新的發行 zip，或複製公開鏡像儲存庫：

git clone https://github.com/crane-valley/framedash-ue5-sdk.git

接著將其加入專案：

  1. 將外掛程式放置於 Plugins/Framedash 目錄
  2. 在 .uproject 中新增：
{
  "Plugins": [
    {
      "Name": "Framedash",
      "Enabled": true
    }
  ]
}
  1. 在 Build.cs 中新增模組依賴：
PrivateDependencyModuleNames.Add("Framedash");
  1. 重新建置專案

初始設定

Section titled “初始設定”

方法 A：自動初始化（建議）

Section titled “方法 A：自動初始化（建議）”

在 DefaultGame.ini 中新增以下內容，子系統將在啟動時自動初始化：

[/Script/Framedash.FramedashSettings]
ApiKey=your-api-key
bAutoInitialize=True

也可以設定可選欄位，如 EndpointUrl、BuildId 和 SamplingRate：

[/Script/Framedash.FramedashSettings]
ApiKey=your-api-key
bAutoInitialize=True
EndpointUrl=https://ingest.framedash.dev/v1/events
BuildId=1.0.0
SamplingRate=1.0

這些設定也可以在 Project Settings > Plugins > Framedash 中編輯。

無需撰寫 C++ 初始化程式碼。

方法 B：透過 C++ 手動初始化

Section titled “方法 B：透過 C++ 手動初始化”

您也可以不使用設定檔，直接透過程式碼初始化：

#include "FramedashSubsystem.h"


void AMyGameMode::BeginPlay()
{
    Super::BeginPlay();


    if (auto* Subsystem = GetGameInstance()->GetSubsystem<UFramedashSubsystem>())
    {
        FString ApiKey = FPlatformMisc::GetEnvironmentVariable(TEXT("FRAMEDASH_API_KEY"));
        Subsystem->InitializeTelemetry(ApiKey);
    }
}

InitializeTelemetry 還接受可選的 EndpointUrl 和 BuildId 參數，在 CI 環境中很有用：

if (auto* Subsystem = GetGameInstance()->GetSubsystem<UFramedashSubsystem>())
{
    FString ApiKey = FPlatformMisc::GetEnvironmentVariable(TEXT("FRAMEDASH_API_KEY"));
    FString BuildId = FPlatformMisc::GetEnvironmentVariable(TEXT("CI_COMMIT_SHA"));
    // 傳遞空字串給 EndpointUrl 以使用預設值
    Subsystem->InitializeTelemetry(ApiKey, TEXT(""), BuildId);
}

自動收集資料

Section titled “自動收集資料”

初始化完成後，以下資料將自動收集：

  • FPS / Frame Time — 相當於 stat unit 的資料
  • GPU Time — 渲染管線各階段
  • Memory — 實體記憶體 + 紋理串流

自訂事件

Section titled “自訂事件”

基本追蹤

Section titled “基本追蹤”
if (auto* Framedash = GetGameInstance()->GetSubsystem<UFramedashSubsystem>())
{
    Framedash->Track(TEXT("player_death"), TEXT("Map01"), PlayerLocation);
}

攜帶自訂屬性與指標

Section titled “攜帶自訂屬性與指標”

需要附加額外中繼資料時，使用 TrackWithData:

if (auto* Framedash = GetGameInstance()->GetSubsystem<UFramedashSubsystem>())
{
    TMap<FString, FString> Attributes;
    Attributes.Add(TEXT("cause"), TEXT("fall_damage"));


    TMap<FString, double> Metrics;
    Metrics.Add(TEXT("health"), 0.0);


    Framedash->TrackWithData(
        TEXT("player_death"), TEXT("Map01"),
        PlayerLocation, Attributes, Metrics);
}

下一步

Section titled “下一步”