Unreal Engine 모듈 · 플러그인 개발LESSON 31

플러그인 테스트, 로그, 크래시 원인 추적

난이도심화

예상 시간170분

선수지식28~30강의 Runtime Plugin과 22~27강의 Editor Tool

31강. 플러그인 테스트, 로그, 크래시 원인 추적

1. 이번 강의에서 해결할 문제

Editor에서 한 번 실행된 Plugin이 Game, Commandlet, Shipping, 다른 프로젝트에서도 안전하다는 보장은 없습니다. Live Coding의 이전 DLL 때문에 수정 사항이 반영된 것처럼 보이거나, Module 종료 뒤 Delegate가 호출되어 Editor를 닫을 때만 크래시가 날 수도 있습니다. 테스트는 기능뿐 아니라 Target·수명·배포 조합을 다뤄야 합니다.

2. 학습 목표

3. 핵심 개념

오류 시점을 먼저 분류하면 진단 범위가 크게 줄어듭니다.

시점	대표 증상	우선 확인
UHT	generated.h, Reflection 오류	Macro, Include 순서, 지원 타입
Compile	Header 없음, 타입 미정의	Build.cs, Public/Private, Forward Declaration
Link	unresolved external	API Macro, Module 의존, 구현 누락
Load	Missing Module, 비활성 Plugin	Descriptor, Binary 버전, Module 이름
Runtime	null, 잘못된 수명	로그, ensure, World·Actor 유효성
Shutdown	종료 시 Crash	Delegate·Menu·Tab·Customization 해제

4. 단계별 실습

먼저 검증 행렬을 고정합니다.

조합	ReusableInteraction	DataGuard	기대 결과
Editor Target	켬	켬	Runtime 기능과 Editor 도구 사용
Editor Target	켬	끔	Runtime 기능 정상, 메뉴 없음
Development Game	켬	켬	DataGuardEditor 미포함, Runtime 정상
Shipping	켬	끔	Editor 의존 없이 패키징·실행
Commandlet	선택	켬	Data Validation 로그 생성
빈 C++ 프로젝트	켬	켬	활성화·컴파일·실행·검사 성공

자동 테스트 코드는 별도 ReusableInteractionTests Module에 둡니다.

ReusableInteractionTests.Build.cs
using UnrealBuildTool;

public class ReusableInteractionTests : ModuleRules
{
    public ReusableInteractionTests(ReadOnlyTargetRules Target) : base(Target)
    {
        PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;
        PrivateDependencyModuleNames.AddRange(new[]
        {
            "Core",
            "CoreUObject",
            "Engine",
            "ReusableInteraction"
        });
    }
}

Private/InteractionSettingsSpec.cpp
#if WITH_DEV_AUTOMATION_TESTS

#include "Misc/AutomationTest.h"
#include "Settings/InteractionSettings.h"

IMPLEMENT_SIMPLE_AUTOMATION_TEST(
    FInteractionSettingsDefaultsTest,
    "ReusableInteraction.Settings.SafeDefaults",
    EAutomationTestFlags::EditorContext |
    EAutomationTestFlags::EngineFilter)

bool FInteractionSettingsDefaultsTest::RunTest(const FString& Parameters)
{
    const UInteractionSettings* Settings =
        GetDefault<UInteractionSettings>();

    TestNotNull(TEXT("Settings CDO exists"), Settings);
    if (Settings)
    {
        TestTrue(
            TEXT("Trace distance is positive"),
            Settings->DefaultTraceDistance >= 50.0f);
    }
    return true;
}

#endif

Module Loading과 종료 로그에 Plugin 버전, Target, Module 이름을 남기되 사용자 정보나 절대 개인 경로는 기록하지 않습니다. Crash가 발생하면 가장 위 프레임만 보지 말고 처음으로 Plugin 코드에 진입한 프레임과 직전 경고를 함께 봅니다.

Missing Module 진단 순서는 다음과 같습니다.

Plugin이 Project의 Plugins 화면과 .uproject에서 활성화되었는지 확인
.uplugin Module 이름과 Source/<Module>/<Module>.Build.cs 클래스명 일치 확인
현재 Engine 버전과 Target으로 전체 종료 후 Clean Build
Binaries의 오래된 DLL이 소스와 섞였는지 확인
Build 로그의 마지막 오류가 아니라 첫 오류 확인
Plugin 비활성화 상태로 Project가 열리는지 확인해 범위 격리

5. 코드가 동작하는 이유

테스트 Module이 Runtime 제품 Module을 소비하므로 제품 코드에 자동화 의존성이 역류하지 않습니다. 조합 행렬은 Editor 성공 하나로 가려지는 Game·Shipping·Shutdown 실패를 드러냅니다. 로그와 Stack을 단계별로 분류하면 무작정 프로젝트 파일을 재생성하는 대신 실제 경계 오류를 찾을 수 있습니다.

6. 자주 하는 실수와 해결법

7. 직접 실습

8. 이해 점검 질문 3개

9. 핵심 요약

MINI QUIZ