Debugging & Profiling
블루프린트 디버거, 시각적 디버깅, 프로파일러 도구를 마스터합니다
Breakpoint (중단점)
노드 실행을 중단하고 상태를 검사하기
Breakpoint는 특정 노드에서 실행을 일시 중단하여, 해당 시점의 변수 값과 실행 흐름을 검사하는 디버깅 도구입니다.
// Breakpoint 설정/해제
방법 1: 노드 우클릭 > Add Breakpoint
방법 2: 노드 선택 후 F9 키
// Breakpoint 상태
빨간 원 = 활성 Breakpoint
빨간 원 (빗금) = 비활성 Breakpoint (F9로 토글)
// 디버깅 실행
F5 = Continue (다음 Breakpoint까지 실행)
F10 = Step Over (다음 노드로 이동)
F11 = Step Into (함수/매크로 내부로 진입)
Shift+F11 = Step Out (함수/매크로에서 빠져나옴)
Breakpoint 도달 시 확인 가능한 정보
| 정보 | 확인 방법 |
|---|---|
| 핀 값 | 데이터 핀에 마우스를 올리면 현재 값이 표시됨 |
| 변수 값 | My Blueprint 패널에서 변수 옆 값 확인, 또는 Watch 추가 |
| 실행 경로 | 실행된 와이어가 파란색 애니메이션으로 표시됨 |
| Call Stack | 디버그 탭에서 호출 스택 확인 가능 |
Breakpoint를 우클릭하여 Edit Breakpoint Condition을 설정할 수 있습니다. 예: Health < 50이면 특정 조건에서만 중단됩니다. 수백 번 호출되는 곳에서 특정 조건만 디버깅할 때 유용합니다.
시각적 디버깅 도구
Print String, Draw Debug, Watch 창 활용
Print String
// 기본 사용
[Print String]
├─ In String: "Health: {0} / {1}"
├─ Print to Screen: True
├─ Print to Log: True
├─ Text Color: (1, 0, 0, 1) // 빨강
└─ Duration: 2.0
// 값 포함 출력 (Append 노드로 문자열 결합)
[Get Health] ──> [Append] ("HP: " + Health) ──> [Print String]
// 키별 출력 (같은 키 = 업데이트, 줄 추가 안 됨)
[Print String]
└─ Key: 1 // 같은 Key의 이전 메시지를 덮어씀
Draw Debug 노드
// 3D 공간에 디버그 도형 표시
[Draw Debug Sphere]
├─ Center: Location
├─ Radius: 100
├─ Color: Red
└─ Duration: 5.0
[Draw Debug Line]
├─ Line Start, Line End
├─ Color: Green
└─ Duration: 0.0 (한 프레임만)
[Draw Debug Arrow] // 방향 표시
[Draw Debug Box] // 영역 표시
[Draw Debug Capsule] // 캡슐 (충돌 범위)
[Draw Debug String] // 3D 텍스트
// 활용 예: AI 시야 범위 시각화
[Event Tick] ──> [Draw Debug Cone]
├─ Origin: EyeLocation
├─ Direction: ForwardVector
├─ Length: SightRadius
└─ Angle: PeripheralAngle
Watch 창
변수를 우클릭 > Watch this value하면, 디버깅 중 해당 변수의 실시간 값이 별도 창에 표시됩니다. 여러 변수를 동시에 모니터링할 때 유용합니다.
Blueprint Profiler
블루프린트 성능 병목을 측정하고 분석하기
Blueprint Profiler는 블루프린트 노드별 실행 시간을 측정하여 성능 병목을 식별합니다.
Profiler 열기
// 방법 1: 에디터 메뉴
Window > Developer Tools > Blueprint Profiler
// 방법 2: 콘솔 명령
stat blueprints // 화면에 BP 실행 시간 표시
stat game // 게임 스레드 통계
// Profiler 사용법:
1. PIE 실행
2. Blueprint Profiler 창에서 Record 클릭
3. 게임 플레이 (병목 상황 재현)
4. Stop 클릭
5. 결과 분석: 시간순, 호출 횟수순 정렬 가능
Profiler 결과 해석
| 항목 | 설명 | 개선 기준 |
|---|---|---|
| Inclusive Time | 해당 노드 + 하위 호출 시간 | 함수 전체 비용 |
| Exclusive Time | 해당 노드만의 실행 시간 | 노드 자체 비용 |
| Call Count | 프레임당 호출 횟수 | 높으면 캐싱 검토 |
| Average Time | 평균 실행 시간 | >0.1ms면 주의 |
더 상세한 프로파일링이 필요하면 Unreal Insights를 사용하세요. -trace=default,blueprint 커맨드라인 인수로 실행하면 블루프린트 실행을 포함한 전체 엔진 프로파일을 캡처합니다. Insights Viewer에서 타임라인 기반으로 분석할 수 있습니다.
일반적인 디버깅 패턴
자주 발생하는 문제와 해결 전략
자주 발생하는 블루프린트 오류
| 증상 | 원인 | 해결 |
|---|---|---|
| "Accessed None" 에러 | null 참조 접근 | IsValid 체크 추가, Optional pin 확인 |
| 이벤트가 발생하지 않음 | 바인딩 누락, Collision 설정 오류 | Generate Overlap Events, Collision Response 확인 |
| 무한 루프 (에디터 멈춤) | WhileLoop 조건 미변화, 재귀 호출 | ForLoop 사용, 탈출 조건 확인 |
| Cast 항상 실패 | 잘못된 타입, GameMode가 다른 클래스 | 실제 타입 Print로 확인, World Settings 확인 |
| 변수가 기본값으로 초기화 안 됨 | 컴파일 안 함 | F7로 컴파일 후 Class Defaults에서 설정 |
| Timer가 동작하지 않음 | Actor 파괴로 Timer 무효화 | Timer Handle 유효성 확인, Is Timer Active |
디버깅 전략 흐름
문제 상황 반복
범위 좁히기
Breakpoint/Print
원인 해결
재현 확인
stat fps - FPS 표시
stat unit - Game/Render/GPU 시간
stat blueprints - BP 실행 시간
stat memory - 메모리 사용량
showdebug ai - AI 디버그 정보
show collision - 충돌 볼륨 표시
show navigation - NavMesh 표시
obj list class=BlueprintGeneratedClass - 로드된 BP 목록
핵심 요약
- Breakpoint(F9)로 노드 실행을 중단하고, F10(Step Over), F11(Step Into)로 단계별 실행한다
- Print String의 Key 파라미터를 사용하면 같은 위치의 메시지를 덮어써 화면을 깔끔하게 유지한다
- Draw Debug 노드로 3D 공간에 구체, 선, 박스 등을 표시하여 시각적으로 디버깅한다
- Blueprint Profiler로 노드별 실행 시간과 호출 횟수를 측정하여 병목을 식별한다
- "Accessed None" 에러는 IsValid 체크로 방지하고, Cast 실패는 실제 타입을 Print로 확인한다
- stat blueprints, stat unit 콘솔 명령으로 런타임 성능을 실시간 모니터링한다
도전 과제
배운 내용을 직접 실습해보세요
의도적으로 버그가 있는 BP(잘못된 변수 값으로 인한 무한 루프)를 만들고, Breakpoint를 설정하세요. F9로 노드에 중단점을 걸고, PIE에서 실행하여 Step Into/Step Over로 한 노드씩 진행하면서 변수 값을 Watch 창에서 관찰하세요.
복잡한 블루프린트 로직에 Print String을 전략적으로 배치하세요. 각 분기 경로에 다른 색상의 메시지를 출력하고, Append 노드로 변수 값을 함께 표시하세요. 디버그 Draw Line과 Draw Debug Sphere로 공간 정보를 시각화하세요.
Blueprint Profiler(Window > Developer Tools > Blueprint Profiler)를 열고 프로젝트의 모든 BP Tick 비용을 분석하세요. 가장 비용이 높은 노드를 식별하고, stat game 콘솔 명령으로 게임 스레드 시간을 모니터링하면서 최적화 전후 성능을 정량적으로 비교하세요.