UE5 SDK

Framedash UE5 SDK (C++ 플러그인)를 사용하여 퍼포먼스 텔레메트리를 자동으로 수집하는 방법을 설명합니다.

요구 사항

Unreal Engine 5.3 이상
C++ 프로젝트 (Blueprints Only는 미지원)

설치

플러그인은 Framedash UE5 SDK 저장소에서 받습니다 — Releases 페이지에서 최신 릴리스 zip을 다운로드하거나, 퍼블릭 미러를 클론합니다:

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

그런 다음 프로젝트에 추가합니다:

플러그인을 Plugins/Framedash 디렉터리에 배치
.uproject에 추가:

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

Build.cs에 모듈 의존성 추가:

PrivateDependencyModuleNames.Add("Framedash");

프로젝트를 리빌드

초기 설정

방법 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++에서 수동 초기화

설정 파일을 사용하지 않고 코드에서 직접 초기화할 수도 있습니다:

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

자동 수집 데이터

초기화가 완료되면 다음 데이터가 자동으로 수집됩니다:

FPS / Frame Time — stat unit에 해당하는 데이터
GPU Time — 렌더링 파이프라인의 각 스테이지
Memory — 물리 메모리 + 텍스처 스트리밍

커스텀 이벤트

기본 트래킹

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

커스텀 속성 및 메트릭 포함

추가 메타데이터를 첨부하려면 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);
}

다음 단계

데이터 모델 — 텔레메트리 데이터의 구조
CI 프로파일링 — 자동 빌드 테스트