FrameDoctor 사용자 가이드

FrameDoctor는 Windows 64비트의 Unreal Engine 5.5, 5.6, 5.7, 5.8을 지원합니다. 사용하는 엔진 버전에 맞는 플러그인 패키지를 선택하세요.

Unreal을 처음 여는 경우

Epic Games Launcher → Unreal Engine → Library를 열고 설치된 엔진을 실행합니다. 기존 프로젝트를 열거나, Games → Blank → Blueprint를 선택하고 프로젝트 이름과 폴더를 입력한 뒤 Create를 클릭합니다. 프로젝트에는 게임이 저장되고, 레벨이라고도 부르는 맵에는 프로젝트 안의 씬 하나가 저장됩니다.

Fab에서 설치하기

1. Unreal Editor를 닫습니다. 런처의 Fab Library에서 FrameDoctor를 찾아 Install to Engine을 클릭합니다.
2. 프로젝트에 사용하는 엔진 버전을 선택하고 설치를 마칩니다.
3. 프로젝트를 엽니다. Edit → Plugins에서 FrameDoctor를 검색하여 활성화하고, 다시 시작하라는 안내가 나오면 에디터를 재시작합니다.
4. 에디터 기본 메뉴에서 Tools → FrameDoctor를 엽니다.

제공된 ZIP 설치하기

1. 에디터를 닫고 플러그인의 압축을 풉니다.
2. 압축을 푼 단일 FrameDoctor 폴더를 프로젝트의 Plugins 폴더에 넣습니다. Plugins가 없으면 만듭니다.
3. 아래 경로를 확인합니다. FrameDoctor/FrameDoctor처럼 불필요한 폴더가 한 겹 더 생기지 않게 합니다.
4. 프로젝트를 열고 Edit → Plugins에서 플러그인을 활성화합니다. 다시 시작한 뒤 Tools → FrameDoctor를 엽니다.

YourProject/
  YourProject.uproject
  Plugins/
    FrameDoctor/
      FrameDoctor.uplugin
      Content/
      Resources/
      Source/

Epic 가이드: 플러그인 활성화 및 설치.

씬 하나로 시작하세요. 시나리오는 씬이 준비되고 측정을 시작할 수 있는 시점을 FrameDoctor에 알려 줍니다. 사용법을 배우고 씬을 조사할 때는 별도 예제 프로젝트에서 제공되는 시나리오를 사용할 수 있습니다.

1단계 전에: 사용하는 엔진 버전에 맞는 FrameDoctor를 설치하세요. 엔진에 설치하는 방법을 권장합니다. 예제 프로젝트(UE 5.5–5.8, Win64)를 다운로드하고 압축을 풉니다. 이 프로젝트에는 콘텐츠만 들어 있으며 플러그인은 별도로 필요합니다. UE 5.5에 연결되어 있으므로 UE 5.6–5.8에서는 먼저 FrameDoctorExample.uproject를 마우스 오른쪽 버튼으로 클릭하고 Switch Unreal Engine version에서 사용할 엔진을 선택하세요. 해당 엔진으로 FrameDoctorExample.uproject를 열고 FrameDoctor가 활성화되어 있는지 확인합니다.

1. 맵을 열고 저장합니다. 예제 프로젝트에서 맵을 열거나 File → New Level로 만든 뒤 프로젝트의 Content 폴더에 저장하고 File → Save All을 실행합니다.
2. Play를 시작합니다. 에디터 도구 모음에서 삼각형 Play 버튼을 클릭합니다. 이를 Play In Editor, 줄여서 PIE라고 합니다. Shift + F1을 누르면 마우스가 해제되어 게임을 계속 실행하면서 에디터를 사용할 수 있습니다.
3. Capture를 선택합니다. Tools → FrameDoctor → Capture를 엽니다. Use a packaged Development build는 선택하지 않은 상태로 둡니다. PIE는 이미 Play로 실행 중인 맵을 기록합니다. Map 필드에서 다른 맵을 선택해도 실행 중인 월드가 바뀌지는 않습니다.
4. 예제를 선택합니다. Scenario에서 BP_ExploratoryScenario를 검색합니다. 에셋을 찾으려면 Content Browser를 열거나 Ctrl + Space로 Content Drawer를 열고 Content → FrameDoctorExample → Scenarios(/Game/FrameDoctorExample/Scenarios)를 살펴봅니다. 시나리오는 FrameDoctor에서 선택하며, 레벨로 끌어 놓지 않습니다.
5. 기록합니다. 워밍업 10초와 측정 60초를 유지합니다. Preflight를 읽고 Capture running PIE를 클릭합니다. Play를 계속 실행하며 조사하려는 동작을 수행합니다. 워밍업은 측정 결과에서 제외됩니다.
6. Findings를 읽습니다. 기록이 끝나면 Findings가 이미 선택되어 있지 않은 경우 엽니다. Capture quality and unavailable reasons를 읽고, CPU 스코프를 선택해 근거 데이터를 확인합니다.

기록이 끝날 때까지 게임을 계속 실행하세요. Esc나 에디터의 Stop 버튼은 PIE를 종료하고 기록을 중단시킬 수 있습니다. FrameDoctor의 현재 작업을 취소하려면 FrameDoctor에서 Cancel을 사용하세요.

Capture에는 두 가지 대상이 있습니다. Use a packaged Development build가 선택되지 않으면 현재 PIE 월드를 기록합니다. 선택하면 FrameDoctor가 패키징된 게임을 별도로 실행합니다. 재현 가능한 변경 전후 측정에는 패키징된 게임을 사용하세요.

일반 CPU 프로필은 cpu,frame,bookmark를 사용합니다. CPU 이벤트는 작업을 설명하고, frame 이벤트는 프레임 경계를 제공하며, bookmark는 측정 구간을 표시합니다. 외부 기록이 이미 실행 중이면 이를 끝내야 FrameDoctor가 자체 트레이스를 시작할 수 있습니다.

준비 완료, 워밍업, 측정 순서로 진행됩니다. Ready timeout과 Maximum trace size는 Settings에서 설정합니다. 취소되거나 중단된 기록은 상태와 함께 보관되지만, 완료된 비교 기준으로 사용할 수는 없습니다.

기존 트레이스 열기

Import trace를 클릭하고 기록이 끝난 .utrace 파일을 선택한 뒤 Findings가 표시될 때까지 기다립니다. 가져오기 전에 기록을 중지하세요. 비교의 출처를 확인해야 한다면 트레이스 옆의 manifest.json과 원래 실행 기록의 파일들을 트레이스와 함께 보관합니다. Capture quality and unavailable reasons를 읽고 사용 가능한 CPU, 프레임, 측정 데이터를 확인하세요.

FrameDoctor의 측정 시작 및 측정 종료 북마크가 하나의 완전한 쌍으로 유일하게 확인되지 않으면 전체 트레이스를 탐색용 기록으로 분석합니다. 실행 매니페스트가 없거나 지원하지 않는 형식이면 기록의 완전성은 검증되지 않은 상태로 남습니다. 사용 가능한 이벤트를 살펴볼 수는 있지만, 검증되지 않은 데이터나 탐색용 데이터를 확인된 A/B 기준으로 사용할 수는 없습니다.

먼저 기록 상태와 품질을 확인하세요. 데이터가 불완전하거나 값이 Unavailable로 표시되면 Capture quality and unavailable reasons를 엽니다. 이는 값을 확정할 수 없었다는 뜻이며, 0이라는 뜻이 아닙니다.

1. Game frame p95와 측정 시간을 읽습니다. 차트 곡선을 프레임 예산과 비교합니다.
2. Search scopes…로 타이머 이름을 찾거나 All threads로 스레드를 선택합니다. 스레드는 CPU에서 실행되는 작업의 흐름입니다. GameThread는 보통 게임 로직을 실행합니다.
3. 스코프 행을 클릭합니다. 패널에서 Measured(측정 내용), Interpretation(결과 해석), Next experiment(다음 실험), Behavior risk(동작에 미칠 위험) 설명을 확인합니다.
4. Copy evidence로 선택한 타이머·스레드·구간을 식별하는 정보를 복사합니다. Open in Insights로 같은 트레이스를 Unreal Insights에서 열고 해당 구간으로 직접 이동합니다.

Exclusive / frame은 같은 스레드의 하위 스코프 시간을 뺀 스코프 시간을 유효한 프레임 전체에서 평균한 값입니다. Calls는 측정 구간 안에서 시작된 호출 수입니다. 스코프에는 대기 시간이 포함될 수 있습니다. 이름만으로 특정 에셋을 식별하거나 Blueprint 노드 하나의 비용을 입증할 수는 없습니다.

프레임 비용을 추정하려고 중첩된 스코프의 포함 시간이나 병렬 스레드 시간을 더하지 마세요. 게임 프레임, 렌더 프레임, GPU 큐 문맥은 의미가 다릅니다. 신뢰할 수 있는 GPU 프레임 값이 없으면 해당 값은 계속 사용할 수 없는 상태로 남습니다.

가로축은 측정 중 흐른 시간이고, 세로축은 밀리초 단위의 프레임 시간입니다. 봉우리가 높을수록 느린 프레임입니다. 점선 예산선은 선택한 목표를 나타냅니다. 16.67 ms는 초당 약 60프레임에 해당합니다.

• 확대·축소: 차트 위에서 마우스 휠을 사용하거나, 아래쪽의 작은 전체 보기에서 호박색 핸들을 끕니다.
• 이동: 전체 보기에서 선택된 범위 안쪽을 끕니다. 차트에 키보드 초점이 있으면 왼쪽·오른쪽 화살표로 보이는 범위를 옮길 수 있습니다.
• 값 확인: 차트 위로 포인터를 움직입니다. 시간 또는 집계 버킷, 샘플 수, 확인 가능한 최소·최대 시간이 표시됩니다.
• 초기화: Reset view를 클릭합니다. Home 또는 Esc로도 초점이 있는 차트를 초기화할 수 있습니다.

넓은 시간 범위를 표시하면 여러 프레임이 하나의 그리기 버킷에 묶일 수 있습니다. 이를 한 프레임으로 보지 말고 버킷의 샘플 수와 범위를 읽으세요. 프레임 데이터가 없는 구간은 빈 곳으로 남습니다.

Development 빌드는 개발 기능이 활성화된 상태로 에디터 밖에서 실행할 수 있는 패키징된 게임입니다. Baseline A는 원래 빌드이고, Candidate B는 의도한 변경 한 가지를 포함합니다. 각 빌드 전체를 별도 폴더에 보관하세요.

1. 맵과 비교에 사용할 수 있는 시나리오를 저장합니다. 프로젝트에서 FrameDoctor를 활성화합니다.
2. Edit → Project Settings → Packaging을 엽니다. List of maps to include in a packaged build에 맵을 포함합니다. 시나리오 Blueprint도 쿠킹되도록 합니다. 포함되는 콘텐츠에서 하드 참조를 유지하거나, 해당 폴더를 Additional Asset Directories to Cook에 추가합니다.
3. 에디터의 Platforms → Windows 패키징 항목에서 빌드 구성으로 Development를 선택하고 프로젝트를 패키징합니다. 엔진 버전에 따라 메뉴가 다르게 묶여 있을 수 있습니다. 이 출력 전체를 빌드 A로 보관합니다.
4. 시험할 변경 한 가지를 직접 적용합니다. 저장하고 다른 디렉터리에 빌드 B를 패키징합니다. 씬, 입력, 카메라, NPC, 기록 설정을 일관되게 유지합니다.
5. Capture에서 Use a packaged Development build를 선택합니다. A의 실행 파일을 찾아 선택한 뒤 맵을 선택하고 시나리오의 생성 클래스 경로를 입력합니다.

Map: /Game/Maps/TestMap
Scenario: /Game/Scenarios/BP_TestScenario.BP_TestScenario_C
Executable: BuildA/Windows/YourProject/Binaries/Win64/YourProject.exe

에셋 이름은 자신의 프로젝트에 맞게 바꾸세요. /Game은 Unreal에서 보는 프로젝트의 Content 폴더이며, Windows 드라이브가 아닙니다. 생성된 Blueprint 클래스는 _C로 끝납니다. 콘텐츠를 포함해 패키징된 폴더 전체를 보관하세요. 실행 파일만 복사해서는 부족합니다.

Preflight는 요청한 설정을 검사합니다. 외부 빌드에 맵과 시나리오가 들어 있는지는 실제 로딩으로 확인됩니다. 기록은 개발용 구성을 위한 기능입니다. Shipping 및 Test 빌드는 FrameDoctor 기록을 할 수 없습니다.

Epic 가이드: Unreal 프로젝트 패키징.

1. 앞의 설명대로 A와 B를 준비합니다. Compare에서 New Development comparison을 펼칩니다.
2. Baseline Development executable과 Candidate Development executable을 선택합니다. Intended change에 무엇을 바꿨는지 정확히 적습니다.
3. 실행 전에 Primary metric을 선택합니다. 느린 프레임에는 p95GameFrame, 평균 프레임 시간에는 meanGameFrame, 특히 느린 꼬리 구간에는 p99GameFrame을 사용합니다.
4. 5쌍, 워밍업 10초, 측정 60초로 시작합니다. 의도한 빌드 변경에서 일반적으로 허용하는 차이는 gameBuildId만 남깁니다. 해상도, 그래픽 설정, VSync, 프레임 제한, 시나리오, 계측 설정을 일치시킵니다.
5. Launch paired Development series를 클릭합니다. FrameDoctor는 보존한 빌드를 AB/BA 순서로 번갈아 실행합니다. 시리즈가 끝날 때까지 두 빌드 폴더를 변경하지 마세요.
6. 판정과 그 이유, 쌍별 차이, 노이즈, 임곗값, 각 쌍의 원시 값을 읽습니다. 저장된 결과는 Open HTML report 또는 Open report folder로 엽니다.

효과를 확인하려면 비교 가능한 조건과 함께 최소 5개의 완전한 쌍, 각 실행에서 측정 시간 30초와 완전하고 유효한 프레임 300개가 필요합니다. 더 짧은 기록은 탐색에 도움이 될 수 있습니다. 예제 탐색 시나리오로는 효과를 확인할 수 없습니다.

밀리초 값은 낮을수록 좋습니다. 쌍별 차이는 각 쌍의 B − A 차이의 중앙값입니다. 화면에 표시된 두 중앙값을 빼는 것과 다를 수 있습니다. 효과는 절대 임곗값, 상대 임곗값, 추정 노이즈 중 가장 큰 값을 넘어야 하며, 최소 80%의 쌍에서 방향이 같아야 합니다. 기본값은 0.5 ms와 5%입니다. 이 검사는 안정성을 판단하는 데 도움을 주지만, 그 자체로 원인을 확정하지는 않습니다.

완료된 시리즈를 다시 보려면 Import series and export report를 사용하고 해당 series.json을 선택합니다. 허용 차이를 지정해도 계측 설정이나 계산 방법의 불일치를 무시할 수는 없습니다.

Runs를 열고 Refresh saved runs를 클릭합니다. 행을 선택하면 원본 세부 정보를 읽을 수 있습니다. 실행을 두 번 클릭하거나 Open selected evidence를 클릭하면 Findings가 다시 열립니다. 시리즈는 쌍별 비교 보고서가 열립니다.

기본 출력 위치는 <YourProject>/Saved/FrameDoctor이며, Settings에서 다른 출력 폴더를 선택할 수 있습니다. 단일 실행에는 원본 .utrace, 매니페스트, 분석이 보관됩니다. 시리즈에는 series.json, comparison.json, HTML 보고서, 원래 실행에 대한 참조가 보관됩니다.

1. 공유할 시리즈를 불러옵니다.
2. Include source traces in the export로 원본 트레이스를 포함할지 선택합니다. 상황에 맞게 Remove absolute paths and username from exported JSON을 켜 둡니다.
3. Export paired series bundle을 클릭하고 내보낼 위치를 선택한 뒤 완료될 때까지 기다립니다.
4. 내보낸 파일을 검토하고 결과를 검토할 사람에게 전체 번들을 보냅니다.

Promote current run to baseline은 조건을 충족하는 완료된 비교 가능 실행을 <YourProject>/FrameDoctor/Baselines에 저장합니다. 짧은 기록이나 탐색용 기록은 해당하지 않습니다. 더 이상 조사하거나 재확인할 필요가 없을 때까지 원본 데이터를 보관하세요.

프로필은 저장된 기록 및 분석 설정 모음입니다. Settings에서 Profile ID와 이름을 정하고 항목을 설정한 뒤 Save profile을 사용합니다. 프로필 JSON 파일을 다시 열려면 Load profile을 사용합니다. 프로젝트 이력으로 관리하려면 프로젝트의 FrameDoctor/Profiles 폴더에 프로필을 보관하세요.

A/B 양쪽에서 같은 프로필을 사용하세요. 실험을 시작하기 전에 목표에 맞게 임곗값을 바꾸세요. 작업 실행 중에 양식을 수정해도 해당 작업에 기록된 설정이 바뀌지는 않습니다. 지원하지 않는 새 스키마의 프로필은 읽기 전용으로 열립니다. 스키마 번호를 직접 고치지 말고 호환되는 플러그인을 사용하세요.

변경 전후의 효과를 확인할 준비가 되면 이 절차를 사용하세요. 시나리오는 실제 카메라, 입력, NPC, 난수 조건을 설정하고 설명해야 합니다. 훅은 Blueprint로 구현할 수 있습니다. 시나리오 작성에 C++는 필수가 아닙니다.

별도 예제를 기존 프로젝트에서 사용하려면 예제 프로젝트를 열고 Content Browser에서 BP_ExploratoryScenario를 마우스 오른쪽 버튼으로 클릭한 뒤 Asset Actions → Migrate를 선택합니다. 대상 위치로 자신의 프로젝트에 있는 Content 폴더를 지정하고 그 프로젝트에서도 FrameDoctor를 활성화하세요. 또는 아래 단계에 따라 자신만의 시나리오를 만들 수 있습니다.

1. Content Browser에서 Add → Blueprint Class → All Classes를 선택합니다. FrameDoctorScenario를 검색하고 프로젝트 콘텐츠에 BP_TestScenario를 만듭니다.
2. 해당 Blueprint를 엽니다. Overrides 메뉴에서 아래 훅을 구현합니다. 이 객체는 기록 시 선택하며, 레벨에 배치하는 Actor가 아닙니다.
3. Blueprint와 맵을 컴파일하고 저장합니다. FrameDoctor에서 클래스를 선택합니다. 패키징된 기록은 A와 B 준비의 설명대로 맵과 시나리오를 쿠킹에 포함합니다.
4. 긴 비교를 시작하기 전에 짧은 탐색 기록을 한 번 실행하여 준비 완료 확인과 정리 작업을 점검합니다.

Cleanup에서 다른 시스템의 액터나 기록을 제거하지 마세요. 성능을 변경한 뒤에는 게임플레이 동작을 별도로 확인하세요. 시간 측정 조건이 같다고 해서 새 로직이 올바르다는 뜻은 아닙니다.

Project / map — 프로젝트 / 맵

게임 작업 공간 / 그 안에 저장된 레벨 또는 씬 하나입니다.

Blueprint — 블루프린트

비주얼 스크립팅을 위한 Unreal 에셋입니다. C++ 코드를 쓰는 대신 노드를 연결합니다.

PIE

Play In Editor의 약자로, Unreal Editor 안에서 게임을 실행하는 것입니다.

Development / Shipping

개발용 빌드 / 최종 배포용 구성입니다. 패키징된 기록에는 Development를 사용합니다.

Trace / .utrace — 트레이스

기록된 시간 측정 이벤트의 원본 파일입니다.

Scope / timer / thread — 스코프 / 타이머 / 스레드

측정된 작업 구간 / 그 이름 / 해당 작업이 실행된 CPU 작업 흐름입니다.

ms / FPS

프레임당 밀리초 / 초당 프레임 수입니다. 프레임당 16.67 ms이면 게임은 초당 약 60프레임을 생성합니다.

Mean / p95 / p99 — 평균 / p95 / p99

평균 프레임 시간 / 완전한 프레임의 95% / 99%가 그 이하로 걸리는 시간입니다. 백분위수가 높을수록 느린 프레임을 더 강조합니다.

Warmup / measurement — 워밍업 / 측정

결과에서 제외되는 안정화 시간 / 결과 계산에 사용하는 구간입니다.

Baseline / candidate / pair — 기준 / 후보 / 쌍

원래 빌드 / 변경한 빌드 / 각각 한 번씩 실행해 함께 사용하는 묶음입니다.

Noise / threshold — 노이즈 / 임곗값

반복 실행 사이의 변동 / 확인에 필요한 최소한의 안정적인 효과입니다.

Cook — 쿠킹

에셋이 패키징된 게임에서 실행되도록 Unreal이 준비하는 과정입니다.

Manifest / profile — 매니페스트 / 프로필

기록에 저장된 조건과 상태 / 기록을 위해 선택한 설정입니다.

FrameDoctor 1.0.0 · Unreal Engine 5.5, 5.6, 5.7, 5.8 · Windows 64비트.

도움을 요청할 때는 엔진 및 플러그인 버전, PIE와 Development 중 무엇을 사용했는지, 클릭한 항목, 저장된 상태·이유, 기대한 결과를 알려 주세요. 도움이 되면 스크린샷이나 내용을 검토한 근거 데이터 번들을 첨부합니다. 개인 경로나 확인하지 않은 원시 로그는 공유하지 마세요.

이 가이드의 오류나 불명확한 설명은 문서 이슈로 등록해 주세요. 플러그인 지원은 FrameDoctor 제품 페이지 또는 구매 경로의 지원 연락처를 이용하세요.