跳转到内容
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 “下一步”