UE5 SDK

This guide explains how to automatically collect performance telemetry using the Framedash UE5 SDK (C++ plugin).

Requirements

• Unreal Engine 5.3 or later
• C++ project (Blueprints Only is not supported)

Installation

Get the plugin from the Framedash UE5 SDK repository — download the latest release zip from the Releases page, or clone the public mirror:

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

Then add it to your project:

1. Place the plugin in the Plugins/Framedash directory
2. Add to your .uproject:

{
  "Plugins": [
    {
      "Name": "Framedash",
      "Enabled": true
    }
  ]
}

3. Add the module dependency to your Build.cs:

PrivateDependencyModuleNames.Add("Framedash");

4. Rebuild the project

Note

Without step 3, #include "FramedashSubsystem.h" will fail with a compile error. Enabling the plugin in .uproject alone is not enough.

Initial Setup

Option A: Auto Initialize (Recommended)

Add the following to DefaultGame.ini and the subsystem will initialize automatically on startup:

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

You can also set optional fields like EndpointUrl, BuildId, and SamplingRate:

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

These settings are also available in Project Settings > Plugins > Framedash.

No initialization code in C++ is required.

Caution

If you include secrets in DefaultGame.ini, either exclude this file from version control or use a mechanism to reference environment variables instead.

Option B: Manual Initialization from C++

You can initialize the SDK directly from code without using config files:

#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 also accepts optional EndpointUrl and BuildId parameters, useful in CI environments:

if (auto* Subsystem = GetGameInstance()->GetSubsystem<UFramedashSubsystem>())
{
    FString ApiKey = FPlatformMisc::GetEnvironmentVariable(TEXT("FRAMEDASH_API_KEY"));
    FString BuildId = FPlatformMisc::GetEnvironmentVariable(TEXT("CI_COMMIT_SHA"));
    // Pass an empty string for EndpointUrl to use the default value.
    Subsystem->InitializeTelemetry(ApiKey, TEXT(""), BuildId);
}

Automatically Collected Data

Once initialized, the following data is collected automatically:

• FPS / Frame Time — Equivalent to stat unit data
• GPU Time — Each stage of the rendering pipeline
• Memory — Physical memory + texture streaming

Custom Events

Basic Tracking

if (auto* Framedash = GetGameInstance()->GetSubsystem<UFramedashSubsystem>())
{
    Framedash->Track(TEXT("player_death"), TEXT("Map01"), PlayerLocation);
}

With Custom Attributes and Metrics

Use TrackWithData when you need to attach additional metadata:

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);
}

Next Steps

• Data Model — Telemetry data structure
• CI Profiling — Automated build testing