6-1. 커맨드렛 개발 | UE5 Editor Tools Deep Dive

01

커맨드렛이란?

UI 없이 커맨드라인에서 실행하는 UE5 배치 도구

커맨드렛(Commandlet)은 에디터 UI 없이 커맨드라인에서 실행되는 배치 처리 프로그램입니다. UCommandlet을 상속하여 구현하며, CI/CD 파이프라인이나 자동화 스크립트에서 핵심 역할을 합니다.

특성	커맨드렛	에디터 도구
실행 환경	커맨드라인 (headless)	에디터 UI
UI	없음	Slate / UMG
용도	배치 처리, CI/CD, 데이터 마이그레이션	인터랙티브 도구
자동화	스크립트에서 직접 호출 가능	사용자 상호작용 필요

내장 커맨드렛 예시

커맨드렛	기능
`ResavePackages`	패키지 재저장 (버전 업그레이드)
`Cook`	에셋 쿠킹
`DiffPackages`	패키지 비교
`FixupRedirects`	리디렉터 정리

02

UCommandlet 구현

커스텀 커맨드렛 작성하기

                    UAssetAuditCommandlet.h
                    #pragma once

#include "Commandlets/Commandlet.h"
#include "UAssetAuditCommandlet.generated.h"

UCLASS()
class UAssetAuditCommandlet : public UCommandlet
{
    GENERATED_BODY()

public:
    UAssetAuditCommandlet();

    // 진입점
    virtual int32 Main(
        const FString& Params) override;

private:
    void AuditNamingConventions(
        const FString& RootPath);
    void AuditTextureSettings(
        const FString& RootPath);
    void GenerateReport(
        const FString& OutputPath);

    struct FAuditIssue
    {
        FString AssetPath;
        FString Category;
        FString Message;
        FString Severity; // Error, Warning, Info
    };

    TArray<FAuditIssue> Issues;
};
                

                    UAssetAuditCommandlet.cpp
                    #include "UAssetAuditCommandlet.h"
#include "AssetRegistry/AssetRegistryModule.h"
#include "Misc/FileHelper.h"

UAssetAuditCommandlet::UAssetAuditCommandlet()
{
    IsClient = false;
    IsEditor = true;
    IsServer = false;
    LogToConsole = true;
}

int32 UAssetAuditCommandlet::Main(
    const FString& Params)
{
    // 파라미터 파싱
    TArray<FString> Tokens;
    TArray<FString> Switches;
    TMap<FString, FString> ParamVals;
    ParseCommandLine(*Params,
        Tokens, Switches, ParamVals);

    FString RootPath = ParamVals.FindRef(
        TEXT("RootPath"));
    if (RootPath.IsEmpty())
        RootPath = TEXT("/Game");

    FString OutputPath = ParamVals.FindRef(
        TEXT("Output"));
    if (OutputPath.IsEmpty())
        OutputPath = FPaths::ProjectSavedDir()
            / TEXT("AuditReport.csv");

    UE_LOG(LogTemp, Log,
        TEXT("Starting asset audit on: %s"), *RootPath);

    // 감사 실행
    AuditNamingConventions(RootPath);
    AuditTextureSettings(RootPath);

    // 보고서 생성
    GenerateReport(OutputPath);

    UE_LOG(LogTemp, Log,
        TEXT("Audit complete. %d issues found. Report: %s"),
        Issues.Num(), *OutputPath);

    // 0 = 성공, 그 외 = 오류
    return Issues.Num() > 0 ? 1 : 0;
}

void UAssetAuditCommandlet::GenerateReport(
    const FString& OutputPath)
{
    FString CSV = TEXT("AssetPath,Category,Severity,Message\n");

    for (const FAuditIssue& Issue : Issues)
    {
        CSV += FString::Printf(
            TEXT("%s,%s,%s,%s\n"),
            *Issue.AssetPath,
            *Issue.Category,
            *Issue.Severity,
            *Issue.Message);
    }

    FFileHelper::SaveStringToFile(CSV, *OutputPath);
}
                

03

커맨드렛 실행

커맨드라인에서 커맨드렛 호출하기

                    Windows 커맨드 프롬프트
                    :: 기본 실행
UnrealEditor-Cmd.exe MyProject.uproject ^
    -run=AssetAudit ^
    -RootPath=/Game ^
    -Output=D:/Reports/audit.csv

:: 로그 레벨 지정
UnrealEditor-Cmd.exe MyProject.uproject ^
    -run=AssetAudit ^
    -log ^
    -LogCmds="global None, LogTemp Log"

:: 배치 파일 예시 (run_audit.bat)
@echo off
set UE_PATH=C:\Program Files\Epic Games\UE_5.5
set PROJECT=D:\Projects\MyGame\MyGame.uproject

"%UE_PATH%\Engine\Binaries\Win64\UnrealEditor-Cmd.exe" ^
    "%PROJECT%" ^
    -run=AssetAudit ^
    -RootPath=/Game ^
    -Output=D:\Reports\audit_%date:~0,4%%date:~5,2%%date:~8,2%.csv

if %ERRORLEVEL% NEQ 0 (
    echo Audit found issues!
    exit /b 1
)
echo Audit passed!
                

커맨드렛 네이밍 규칙

커맨드라인에서 -run=AssetAudit으로 호출할 때, UE5는 UAssetAuditCommandlet 클래스를 자동으로 찾습니다. 클래스 이름에서 U 접두사와 Commandlet 접미사가 자동 추가됩니다.

04

실전 커맨드렛 패턴

CI/CD에서 활용하는 커맨드렛 설계 패턴

커맨드렛	용도	CI/CD 활용
AssetAudit	네이밍/설정 검증	PR 머지 전 게이트 체크
DataValidation	데이터 테이블 유효성	데이터 변경 PR 검증
AssetMigration	에셋 구조 변환	버전 업그레이드 자동화
ReportGenerator	프로젝트 통계 보고서	일일/주간 보고 자동 생성

종료 코드 규약

커맨드렛의 Main() 반환값이 CI/CD 파이프라인의 성공/실패를 결정합니다. 0 = 성공, 1 = 경고(이슈 발견), 2+ = 오류. Jenkins/GitHub Actions에서 이 코드로 빌드 게이트를 제어합니다.

SUMMARY

핵심 요약

UCommandlet은 커맨드라인에서 UI 없이 실행되는 배치 처리 도구이며, CI/CD 파이프라인의 핵심 빌딩 블록입니다
Main()을 오버라이드하여 로직을 구현하고, ParseCommandLine으로 파라미터를 파싱합니다
-run=CommandletName으로 실행하며, 클래스 이름에서 U접두사와 Commandlet 접미사가 자동 처리됩니다
종료 코드를 활용하여 CI/CD에서 빌드 게이트(성공/실패)를 제어합니다
에셋 감사, 데이터 검증, 마이그레이션, 보고서 생성 등 반복적인 배치 작업을 자동화합니다

PRACTICE

도전 과제

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

실습 1: UCommandlet 기본 구현

UCommandlet을 상속받아 프로젝트의 모든 에셋을 순회하며 네이밍 규칙을 검증하는 커맨드렛을 구현하세요. Main() 함수에서 FAssetRegistryModule을 사용하여 에셋을 순회하고, 규칙 위반을 로그에 출력하세요. -run=MyCommandlet으로 실행하세요.

실습 2: 에셋 쿠킹 전처리 커맨드렛

패키징 전에 실행하는 커맨드렛을 만들어, 미사용 에셋 검출, 텍스처 크기 검증, 레퍼런스 무결성 검사를 자동으로 수행하세요. 검증 결과를 HTML 리포트로 출력하세요.

심화 과제: 병렬 처리 커맨드렛

FParallelFor를 활용하여 대량의 에셋을 병렬로 처리하는 고성능 커맨드렛을 구현하세요. 에셋 감사(audit), 썸네일 재생성, 레퍼런스 그래프 분석 등 시간이 오래 걸리는 작업을 멀티스레드로 가속하세요.