Abstract
디버거는 게임 화면 위에 뜨는 개발자용 창입니다. Unity 에디터의 Console·Profiler 를 게임 안으로 가져온 것이라고 보면 됩니다. 가장 큰 쓸모는 에디터가 없는 곳 — 폰에 설치한 빌드, 테스터의 PC — 에서 로그와 상태를 바로 볼 수 있다는 점입니다.
실무에서 필요한 순간
•
폰 빌드에서만 나는 버그. USB 를 연결해 logcat 을 뒤지는 대신 화면에서 바로 로그를 본다
•
QA 가 "뭔가 느려요"라고 할 때 FPS 와 메모리를 그 자리에서 확인
•
풀이 새는지(엔티티가 회수되지 않고 쌓이는지) 눈으로 확인
•
테스터의 기기 사양(GPU, 해상도, OS)을 스크린샷 한 장으로 받기
ToyboxNightmare 에서 바로 확인하기
예제를 실행하면 화면 왼쪽 위에 DEBUGGER 와 현재 FPS(예: FPS: 60.00)가 적힌 작은 상자가 떠 있습니다. 그것이 디버거의 아이콘 모드입니다. 클릭하면 전체 창이 열리고, 창 제목 줄을 끌어 옮길 수 있습니다.
알고 싶은 것 | 열 탭 | ToyboxNightmare 에서 보이는 것 |
방금 무슨 로그가 찍혔나 | Console | ProcedureMain: Enter 등 Log.Info 출력 |
엔티티가 풀로 잘 돌아가나 | Profiler → Object Pool | 엔티티 그룹 5개의 인스턴스 풀. 적을 잡으면 Used 가 줄고 Unused 가 는다 |
이벤트 인자·엔티티 데이터가 새나 | Profiler → Reference Pool | EnemyData, ScoreChangedEventArgs 등 타입별 Acquire / Release 횟수. 둘의 차이가 계속 벌어지면 반납 누락이다 |
메모리를 무엇이 먹나 | Profiler → Memory | 텍스처·메시·오디오 클립별 사용량 |
일시정지가 제대로 걸렸나 | Information → Other → Time | Time Scale 값 (일시정지 중 0) |
기기 정보 | Information → System / Graphics | OS, CPU, GPU, 그래픽 API |
출시 빌드에서 끄기
GameFramework.prefab 의 Debugger 오브젝트에서 Active Window 를 바꿉니다. 예제는 AlwaysOpen 으로 두었습니다(학습용). 출시할 때는 OnlyOpenWhenDevelopment 로 바꾸면 Development Build 에서만 뜹니다.
이 에디션에서 다른 점
•
원작에 들어 있던 전용 GUI 스킨이 없어 Unity 기본 IMGUI 스킨으로 그려집니다. 본문 스크린샷과 모양이 조금 다릅니다. Debugger 오브젝트의 Skin 필드에 직접 만든 GUISkin 을 넣으면 바뀝니다.
•
IMGUI 기반이라 고해상도 폰에서는 글자가 작게 보입니다. Other → Settings 탭에서 창 배율(Scale)을 키울 수 있습니다.
•
로그가 하나도 안 보인다면 디버거 문제가 아니라 로그가 컴파일에서 빠진 것입니다. Scripting Define Symbols 에 ENABLE_LOG 계열이 있어야 Log.Info 가 살아납니다(
01. 프로젝트 세팅 — 프레임워크가 켜지는 최소 조건).
01. 프로젝트 세팅 — 프레임워크가 켜지는 최소 조건).Debugging Tools (디버깅 도구)
Relevant source files (관련 소스 파일)
•
Scripts/Editor/Inspector/ReferencePoolComponentInspector.cs.meta
•
Scripts/Runtime/Debugger/DebuggerActiveWindowType.cs
•
Scripts/Runtime/Debugger/DebuggerComponent.GraphicsInformationWindow.cs
•
Scripts/Runtime/Debugger/DebuggerComponent.ProfilerInformationWindow.cs
•
Scripts/Runtime/Debugger/DebuggerComponent.SceneInformationWindow.cs
•
Scripts/Runtime/Debugger/DebuggerComponent.cs
•
Scripts/Runtime/FileSystem/AndroidFileSystemStream.cs
•
Scripts/Runtime/ReferencePool.meta
•
Scripts/Runtime/ReferencePool/ReferencePoolComponent.cs
•
Scripts/Runtime/ReferencePool/ReferencePoolComponent.cs.meta
•
Scripts/Runtime/ReferencePool/ReferenceStrictCheckType.cs
•
Scripts/Runtime/ReferencePool/ReferenceStrictCheckType.cs.meta
Overview (개요)
Unity Game Framework은 런타임에서 게임을 모니터링, 분석, 문제 해결할 수 있도록 포괄적인 디버깅 도구 모음을 제공합니다.
이 도구들은 성능 지표, 메모리 사용량, 객체 풀, 시스템 정보 등 게임의 다양한 측면에 대한 실시간 통찰을 제공합니다.
Activation Methods (활성화 방식)
디버거 컴포넌트는 DebuggerActiveWindowType 열거형을 통해 다른 환경에서 사용 가능 여부를 설정할 수 있습니다.
Activation Type | 설명 |
AlwaysOpen | 항상 디버거 사용 가능 |
OnlyOpenWhenDevelopment | 개발 빌드에서만 사용 가능 (Debug.isDebugBuild == true) |
OnlyOpenInEditor | Unity 에디터에서만 사용 가능 |
AlwaysClose | 항상 비활성화 |
User Interface (사용자 인터페이스)
디버깅 인터페이스는 두 가지 주요 모드로 구성됩니다:
1.
Floating Icon Mode (플로팅 아이콘 모드)
•
작은 드래그 가능한 FPS 카운터
•
클릭 시 전체 디버거 창 열림
2.
Full Window Mode (전체 창 모드)
•
다중 탭과 패널을 갖춘 포괄적인 디버깅 인터페이스
Available Debugging Windows (사용 가능한 디버깅 창)
Console Window (콘솔 창)
•
게임에서 발생한 로그, 경고, 에러 표시
•
필터링, 검색, 복사 지원
Information Windows (정보 창)
•
System Information: 플랫폼, CPU, 메모리
•
Environment Information: 실행 환경 정보
•
Screen Information: 해상도 및 화면 데이터
•
Graphics Information: GPU 및 렌더링 기능
•
Input Information: 터치, 위치, 가속도, 자이로스코프, 나침반
•
Scene Information: 현재 씬과 관리 정보
•
Path Information: 애플리케이션에서 사용하는 파일 시스템 경로
•
Time Information: 시간 관련 지표
•
Quality Information: 품질 설정 정보
•
Web Player Information: Web Player 환경일 때 전용 정보
Profiler Windows (프로파일러 창)
•
Profiler Summary: 성능 지표 요약
•
Memory Profiler: 텍스처, 메시, 머티리얼 등 카테고리별 메모리 사용량
•
Object Pool Profiler: 오브젝트 풀 통계
•
Reference Pool Profiler: 레퍼런스 풀 통계
•
Network Profiler: 네트워크 활동 모니터링
Settings and Operations (설정 및 작업 창)
•
Settings Window: 디버거 설정 변경
•
Operations Window: 다양한 디버깅 작업 수행
Using the Debugger at Runtime (런타임에서 디버거 사용하기)
Accessing the Debugger (디버거 접근)
디버거는 화면 모서리에 작은 플로팅 아이콘을 추가하며, 현재 FPS를 표시합니다.
아이콘 색상은 로그 상태를 반영합니다:
•
White (흰색): 문제 없음
•
Yellow (노란색): 경고 있음
•
Red (빨간색): 에러 있음
•
Magenta (자홍색): 치명적 에러 있음
아이콘을 클릭하면 전체 디버거 인터페이스가 열립니다.
Navigating the Debugger Interface (인터페이스 탐색)
•
툴바 기반 네비게이션 사용
•
카테고리/하위 카테고리 구조로 창 정리
Common Debugging Tasks (일반적인 디버깅 작업)
•
Monitoring Performance (성능 모니터링)
◦
FPS 카운터 (플로팅 아이콘 및 프로파일러 요약)
◦
메모리 사용량 (Memory Profiler)
◦
렌더링 통계 (Graphics Information, Profiler)
•
Inspecting Memory Usage (메모리 사용 검사)
◦
리소스 타입별 상세 분석
◦
메모리 누수 탐지 및 최적화 기회 확인
•
Monitoring Resource Pools (리소스 풀 모니터링)
◦
오브젝트 풀 / 레퍼런스 풀 상태
◦
활성 객체, 풀 크기, 사용량
Reference Pool Strict Checking (레퍼런스 풀 엄격 검사)
레퍼런스 풀 시스템은 잠재적 객체 참조 문제를 탐지하기 위한 Strict Checking 모드를 제공합니다.
ReferenceStrictCheckType 열거형으로 설정 가능합니다.
Check Type | 설명 |
AlwaysEnable | 항상 엄격 검사 활성화 |
OnlyEnableWhenDevelopment | 개발 빌드에서만 활성화 |
OnlyEnableInEditor | 에디터에서만 활성화 |
AlwaysDisable | 항상 비활성화 |
성능에 큰 영향을 줄 수 있으며 디버깅 전용 기능입니다.Extending the Debugger (디버거 확장)
디버거는 RegisterDebuggerWindow 메서드를 통해 커스텀 디버깅 창을 지원합니다.
void RegisterDebuggerWindow(string path, IDebuggerWindow debuggerWindow, params object[] args)
C#
복사
•
path는 "Category/Subcategory/WindowName" 형식으로 네비게이션 계층 구조를 정의합니다.
Related Components (관련 컴포넌트)
디버깅 도구 시스템은 다른 프레임워크 컴포넌트와 통합됩니다:
•
Unity 로그 (Application.logMessageReceived): 콘솔 창에 로그 표시. 별도의 LogComponent 는 없으며, Log.Info 등으로 찍은 로그가 Unity 로그를 거쳐 여기로 들어온다
•
ObjectPoolComponent: 오브젝트 풀 창에서 모니터링
•
ReferencePoolComponent: 레퍼런스 풀 창에서 모니터링
•
NetworkComponent: 네트워크 창에서 모니터링
자세한 내용은 [Object Pooling], [Reference Pooling], [Network System] 문서 참조.