6-4. 디버깅 도구 활용 | World Partition Deep Dive

01

콘솔 명령어

World Partition 디버그 CVar

                    World Partition 콘솔 명령어
# 런타임 해시 시각화
wp.Runtime.ToggleDrawRuntimeHash2D    # 2D 그리드 표시
wp.Runtime.ToggleDrawRuntimeHash3D    # 3D 그리드 표시

# 스트리밍 디버그
wp.Runtime.EnableServerStreaming 1    # 서버 스트리밍 활성화
wp.Runtime.ShowDebugStreaming 1       # 스트리밍 디버그 정보

# HLOD 디버그
wp.Runtime.ToggleHLODDebug           # HLOD 디버그 표시

# 셀 배치
wp.Runtime.RuntimeSpatialHashPlaceSmallActorsUsingLocation 1

# Data Layer 디버그
wp.DataLayers.ShowDebug 1            # Data Layer 디버그 정보

# 스트리밍 생성 로그
wp.Editor.DumpStreamingGenerationLog  # Saved/Logs/WorldPartition/에 저장

# 가비지 컬렉션
LevelStreaming.ShouldReuseUnloadedButStillAroundLevels 0
# 언로드된 레벨 즉시 GC (NavMesh 등)
                

02

에디터 시각화 도구

View Mode와 Outliner 활용

                    에디터 디버그 도구
1. HLOD 시각화
   View Mode > Level of Detail Coloration
   > Hierarchical LOD Coloration
   - 각 LOD 레벨이 다른 색상으로 표시

2. Data Layer Outliner
   Window > World Partition > Data Layer Outliner
   - 모든 Data Layer 목록
   - 런타임 상태 확인
   - 에디터 가시성 토글

3. World Partition Minimap
   - World Partition Minimap 액터 배치
   - 전체 맵을 커버하도록 스케일 조정
   - Build > Build World Partition Editor Minimap

4. 스트리밍 그리드 시각화
   - 콘솔: wp.Runtime.ToggleDrawRuntimeHash2D
   - 셀 경계, 로드 상태 표시
                

LOD Coloration

HLOD 전환 포인트 확인. 색상으로 현재 LOD 레벨 식별.

Data Layer Outliner

레이어별 액터 관리. 런타임 상태 모니터링.

03

성능 프로파일링

스트리밍 성능 분석

                    성능 분석 명령어
# 일반 렌더링 통계
stat scenerendering          # 드로우 콜, 프리미티브 수

# Nanite 통계
stat Nanite                  # Nanite 지오메트리 통계

# Nanite 디버그 뷰
r.Nanite.Visualize 1
# 0: Off
# 1: Triangles
# 2: Clusters
# 3: Instances

# 스트리밍 통계
stat streaming              # 레벨 스트리밍 상태

# 메모리 통계
stat memory                 # 전체 메모리 사용량
memreport -full            # 상세 메모리 리포트

# GPU 프로파일링
profilegpu                  # GPU 프레임 분석
                

프로파일링 팁

스트리밍 관련 히치(끊김)가 발생하면 stat streaming으로 로드 중인 레벨을 확인하세요. Loaded와 Visible 상태의 차이로 프리로딩 효과를 측정할 수 있습니다.

04

NavMesh 디버깅

Gameplay Debugger 활용

                    NavMesh 디버그
# Gameplay Debugger 활성화
' (작은따옴표) 키

# Navigation 뷰 전환
0 키 (Gameplay Debugger 활성 상태에서)

# NavMesh 표시
show navigation             # 에디터에서

# 상세 NavMesh 디버그
RecastNavMesh-Default
- Details > Debug Draw > 옵션 활성화

확인 항목:
├── NavMesh 타일 경계
├── 로드된/언로드된 영역
├── 경로 탐색 가능 영역
└── NavLink 연결 상태
                

05

로그 분석

스트리밍 생성 로그 활용

                    로그 분석
# 스트리밍 생성 로그 덤프
wp.Editor.DumpStreamingGenerationLog

# 결과 위치
Saved/Logs/WorldPartition/

# 로그 내용:
├── 생성된 셀 목록
├── 셀별 액터 수
├── 거대 셀 경고
├── Hard Reference 정보
└── Data Layer 할당 정보

# 분석 포인트:
1. 예상보다 큰 셀 확인
   → Hard Reference 체크

2. 특정 셀에 액터 집중
   → 그리드 설정 조정 고려

3. Data Layer 누락 액터
   → 할당 확인
                

                    C++ - 커스텀 로깅
// 런타임 스트리밍 상태 로깅
void AMyDebugActor::LogStreamingState()
{
    if (UWorld* World = GetWorld())
    {
        if (UWorldPartitionSubsystem* WPSubsystem =
            World->GetSubsystem<UWorldPartitionSubsystem>())
        {
            bool bComplete = WPSubsystem->IsStreamingCompleted();
            UE_LOG(LogTemp, Log,
                TEXT("Streaming Completed: %s"),
                bComplete ? TEXT("Yes") : TEXT("No"));
        }
    }
}

// Data Layer 상태 로깅
void LogDataLayerState(UDataLayerAsset* DataLayer)
{
    if (UWorld* World = GetWorld())
    {
        if (UDataLayerManager* Manager =
            UDataLayerManager::GetDataLayerManager(World))
        {
            EDataLayerRuntimeState State =
                Manager->GetDataLayerEffectiveRuntimeState(DataLayer);

            UE_LOG(LogTemp, Log,
                TEXT("DataLayer '%s' State: %d"),
                *DataLayer->GetName(), (int32)State);
        }
    }
}
                

SUMMARY

핵심 요약

wp.Runtime.* 명령어로 그리드, HLOD, 스트리밍 시각화
LOD Coloration으로 HLOD 전환 확인
stat streaming으로 로드 상태 모니터링
Gameplay Debugger로 NavMesh 디버그
DumpStreamingGenerationLog로 셀 생성 분석

PRACTICE

도전 과제

배운 내용을 직접 실습해보세요

실습 1: 콘솔 명령어 디버깅 실습

wp.Runtime.ToggleDrawRuntimeHash2D, wp.Runtime.ToggleDrawRuntimeHash3D, wp.Runtime.ToggleDrawStreamingSources 명령어를 실행하며 런타임 스트리밍 상태를 시각화하세요. 각 명령어의 출력을 분석합니다.

실습 2: World Partition 에디터 도구 활용

에디터의 World Partition 창에서 셀 필터링, 액터 검색, Data Layer 토글 기능을 활용하세요. 특정 그리드의 셀만 표시하거나, 로드되지 않은 액터를 검색하는 워크플로우를 익힙니다.

심화 과제

프로젝트 특화 World Partition 디버그 도구를 개발하세요. 런타임 셀 상태 히트맵, 스트리밍 소스 범위 3D 시각화, 셀 로드/언로드 이력 타임라인을 포함하는 에디터 유틸리티 위젯을 구현합니다.