6-2. 디버깅 도구 | UE5 Mass Entity Deep Dive

01

Mass Debugger

Mass Entity 전용 디버그 윈도우

Mass Debugger는 Mass Entity의 내부 상태를 시각적으로 확인할 수 있는 에디터 도구입니다.

                    Mass Debugger 열기
                    // 에디터 메뉴:
// Window → Developer Tools → Mass Entity Debugger
//
// Mass Debugger 탭 구성:
//
// 1. Archetypes 탭
//    - 모든 Archetype 목록
//    - 각 Archetype의 Fragment/Tag 구성
//    - Archetype당 엔티티 수
//    - Chunk 수와 메모리 사용량
//
// 2. Processors 탭
//    - 등록된 모든 Processor 목록
//    - 각 Processor의 Phase, Group
//    - 실행 순서 (의존성 그래프)
//    - Query 요구사항
//    - 처리한 엔티티 수
//    - 실행 시간 (ms)
//
// 3. Entity Details 탭
//    - 특정 엔티티의 Fragment 데이터 조회
//    - Tag 목록 확인
//    - 소속 Archetype 확인
                

Archetype 탭 활용

Archetype 탭에서 예상치 못한 Archetype이 보이면 의도하지 않은 Fragment/Tag 변형이 발생한 것입니다. Archetype 수가 과도하게 많으면 파편화 문제를 의심하세요.

02

콘솔 명령어 (CVar)

런타임에서 Mass Entity를 제어하는 콘솔 변수

명령어	기능
`mass.SimulationTickingEnabled 0/1`	시뮬레이션 전체 활성화/비활성화
`mass.debug.DebugEntity [Index]`	특정 엔티티의 디버그 정보 표시
`mass.debug.LogArchetypes`	모든 Archetype 정보를 로그에 출력
`mass.debug.LogProcessors`	Processor 실행 순서 로그 출력
`mass.debug.Representation`	표현 타입별 색상 오버레이
`mass.debug.LOD`	LOD 레벨 시각화
`stat Mass`	Mass Entity 성능 통계

                    디버깅 시나리오별 명령어 조합
                    // 시나리오 1: 성능 문제 조사
stat Mass                    // 전체 통계 확인
mass.debug.LogProcessors     // 어떤 Processor가 오래 걸리나?

// 시나리오 2: 엔티티가 보이지 않을 때
mass.debug.Representation    // 표현 타입 확인
mass.debug.LOD               // LOD 레벨 확인 (Off인가?)

// 시나리오 3: AI 행동이 이상할 때
mass.debug.DebugEntity 42    // 특정 엔티티 상세 조사
mass.SimulationTickingEnabled 0  // 시뮬 일시정지

// 시나리오 4: Archetype 파편화 확인
mass.debug.LogArchetypes     // Archetype 목록 출력
                

03

Gameplay Debugger

인게임에서 Mass Entity 상태를 오버레이로 확인

UE5의 Gameplay Debugger에 Mass Entity 전용 카테고리가 있습니다. 플레이 중에 실시간으로 엔티티 상태를 확인할 수 있습니다.

                    Gameplay Debugger 사용법
                    // 활성화 조건:
// - WITH_GAMEPLAY_DEBUGGER 매크로 활성화
// - WITH_MASSGAMEPLAY_DEBUG 매크로 활성화
//
// 단축키: ' (작은따옴표) 또는 Numpad 키
//
// Mass Entity 디버그 정보:
// - 선택한 엔티티의 Fragment 데이터 실시간 표시
// - StateTree 현재 상태/전환 내역
// - Navigation 경로 시각화
// - Avoidance 벡터 표시
// - LOD 정보
                

Visual Logger (VLog)

                    C++ - Visual Logger 사용
                    // Processor에서 VLog로 시각적 디버그 정보 기록
void UMyDebugProcessor::Execute(
    FMassEntityManager& EntityManager,
    FMassExecutionContext& Context)
{
    DebugQuery.ForEachEntityChunk(EntityManager, Context,
        [](FMassExecutionContext& Ctx)
    {
        auto Transforms = Ctx.GetFragmentView
            <FTransformFragment>();

        for (int32 i = 0; i < Ctx.GetNumEntities(); ++i)
        {
#if ENABLE_VISUAL_LOG
            // 주의: VLog에는 고유한 Owner가 필요
            UE_VLOG_LOCATION(Owner, LogMass,
                Log,
                Transforms[i].Transform.GetLocation(),
                20.0f,
                FColor::Green,
                TEXT("Entity %d"), i);
#endif
        }
    });
}
                

디버그 빌드 성능

디버그 시각화는 성능에 큰 영향을 줍니다. 수만 개의 엔티티에 대해 디버그 드로잉을 활성화하지 마세요. 필요한 엔티티만 선택적으로 디버깅하거나, 엔티티 수를 줄인 상태에서 테스트하세요.

04

빌드 설정과 스텝 디버깅

Mass Entity 소스 코드를 단계별로 디버깅하는 방법

                    Build.cs - 디버그 최적화 비활성화
                    // Mass 모듈의 코드 최적화를 비활성화하여
// DebugGame에서 스텝 디버깅 가능하게 설정

// MyProject.Build.cs
public MyProject(ReadOnlyTargetRules Target)
    : base(Target)
{
    // Mass 모듈 의존성
    PublicDependencyModuleNames.AddRange(
        new string[] {
            "MassEntity",
            "MassCommon",
            "MassSpawner",
        });

    // DebugGame에서 최적화 비활성화
    if (Target.Configuration ==
        UnrealTargetConfiguration.DebugGame)
    {
        // 이 설정으로 Mass 엔진 내부까지
        // 브레이크포인트와 스텝 실행이 가능
        OptimizeCode = CodeOptimization.Never;
    }
}
                

효과적인 디버깅 전략

1. 엔티티 수를 줄여 테스트 (10~100개)
2. mass.SimulationTickingEnabled 0으로 일시정지
3. Mass Debugger에서 Archetype/Processor 상태 확인
4. 문제 Processor에 브레이크포인트 설정
5. mass.SimulationTickingEnabled 1로 한 틱씩 진행

SUMMARY

핵심 요약

Mass Debugger는 Archetype, Processor, Entity 상태를 시각적으로 확인하는 에디터 도구이다
CVar(mass.debug.*, stat Mass)로 런타임에서 디버그 정보를 확인하고 시뮬레이션을 제어한다
Gameplay Debugger와 Visual Logger로 인게임에서 실시간 디버깅이 가능하다
Build.cs에서 OptimizeCode = Never로 설정하면 Mass 엔진 내부까지 스텝 디버깅할 수 있다
디버깅 시 엔티티 수를 줄이고, 시뮬레이션을 일시정지하여 상태를 분석하는 것이 효과적이다
수만 개 엔티티에 대한 디버그 시각화는 성능에 치명적이므로 선택적으로 사용한다

PRACTICE

도전 과제

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

실습 1: Mass Entity Debug Drawing

MassGameplayDebug 플러그인을 활성화하고, 에디터에서 Gameplay Debugger(')를 열어 Mass Entity 카테고리를 활성화하세요. 엔티티의 Fragment 값, Archetype, Processor 실행 상태를 실시간으로 확인하세요.

실습 2: 로그 기반 디버깅

UE_LOG와 UE_VLOG를 사용하여 Processor 내부에서 특정 엔티티의 Fragment 값을 출력하세요. Visual Logger로 엔티티의 이동 경로와 상태 변화를 시각적으로 추적하세요.

심화 과제: 커스텀 디버그 HUD

ImGui 또는 UMG로 Mass Entity 전용 디버그 HUD를 만드세요. 총 엔티티 수, Archetype별 엔티티 분포, Processor별 실행 시간, 메모리 사용량을 실시간으로 표시하세요.