25강. 커스텀 Asset, Factory, Asset Definition 만들기

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

검사 경로와 이름 규칙을 C++에 하드코딩하면 프로젝트마다 Plugin 소스를 수정해야 합니다. Config는 단순 값에 적합하지만 여러 규칙 묶음, 클래스 필터, 설명을 편집하기에는 부족합니다. 그렇다고 규칙 에셋 클래스를 Runtime에 넣으면 게임 실행에 필요 없는 Editor 정책까지 패키지 계약에 포함됩니다.

이번 강의에서는 Editor에서만 사용하는 규칙 에셋을 만들고 Runtime 콘텐츠가 이를 참조하지 못하게 경계를 분명히 합니다.

✓2. 학습 목표

✓이 강의를 마치면

• 검사 규칙용 UObject Asset 타입을 설계합니다.
• Factory로 Content Browser 생성 흐름을 제공합니다.
• Asset Definition으로 이름·색상·분류를 등록합니다.
• Editor 전용 에셋의 저장·참조 제한을 설명합니다.

◇3. 핵심 개념

커스텀 Asset 기능은 세 책임으로 나눕니다.

• Asset 클래스: 직렬화할 데이터 계약
• Factory: 새 Asset 인스턴스를 만드는 방법
• Asset Definition: Content Browser에서의 표시와 동작 메타데이터

UE5 버전에 따라 기존 FAssetTypeActions_Base와 최신 Asset Definition API의 적용 범위가 다를 수 있습니다. 사용하는 엔진의 UAssetDefinitionDefault 헤더와 샘플을 확인하고 한 방식만 선택합니다.

✎4. 단계별 실습

Editor 전용 규칙 에셋을 정의합니다.

Private/Rules/DataGuardRuleSet.h

#pragma once

#include "Engine/DataAsset.h"
#include "DataGuardRuleSet.generated.h"

USTRUCT(BlueprintType)
struct FDataGuardPathRule
{
    GENERATED_BODY()

    UPROPERTY(EditAnywhere, Category="Rule")
    FDirectoryPath RootPath;

    UPROPERTY(EditAnywhere, Category="Rule")
    FString RequiredPrefix;

    UPROPERTY(EditAnywhere, Category="Rule")
    bool bRecursive = true;
};

UCLASS(BlueprintType)
class UDataGuardRuleSet final : public UDataAsset
{
    GENERATED_BODY()

public:
    UPROPERTY(EditAnywhere, Category="Validation")
    TArray<FDataGuardPathRule> PathRules;
};

이 클래스가 DataGuardEditor Module에 있으므로 다른 Runtime Module의 Public API, Blueprint, Primary Asset에서 참조하면 안 됩니다. 규칙 Asset은 /Game/Developers 또는 팀이 정한 Editor 전용 폴더에 두고 Cook 대상에서 제외합니다.

Private/Rules/DataGuardRuleSetFactory.h

#pragma once

#include "Factories/Factory.h"
#include "DataGuardRuleSetFactory.generated.h"

UCLASS()
class UDataGuardRuleSetFactory final : public UFactory
{
    GENERATED_BODY()

public:
    UDataGuardRuleSetFactory();

    virtual UObject* FactoryCreateNew(
        UClass* Class,
        UObject* InParent,
        FName Name,
        EObjectFlags Flags,
        UObject* Context,
        FFeedbackContext* Warn) override;
};

Private/Rules/DataGuardRuleSetFactory.cpp

#include "Rules/DataGuardRuleSetFactory.h"
#include "Rules/DataGuardRuleSet.h"

UDataGuardRuleSetFactory::UDataGuardRuleSetFactory()
{
    SupportedClass = UDataGuardRuleSet::StaticClass();
    bCreateNew = true;
    bEditAfterNew = true;
}

UObject* UDataGuardRuleSetFactory::FactoryCreateNew(
    UClass* Class,
    UObject* InParent,
    FName Name,
    EObjectFlags Flags,
    UObject* Context,
    FFeedbackContext* Warn)
{
    return NewObject<UDataGuardRuleSet>(InParent, Class, Name, Flags);
}

Private/Rules/AssetDefinition_DataGuardRuleSet.h

#pragma once

#include "AssetDefinitionDefault.h"
#include "AssetDefinition_DataGuardRuleSet.generated.h"

UCLASS()
class UAssetDefinition_DataGuardRuleSet final
    : public UAssetDefinitionDefault
{
    GENERATED_BODY()

public:
    virtual FText GetAssetDisplayName() const override;
    virtual FLinearColor GetAssetColor() const override;
    virtual TSoftClassPtr<UObject> GetAssetClass() const override;
    virtual TConstArrayView<FAssetCategoryPath>
        GetAssetCategories() const override;
};

Private/Rules/AssetDefinition_DataGuardRuleSet.cpp

#include "Rules/AssetDefinition_DataGuardRuleSet.h"
#include "Rules/DataGuardRuleSet.h"

#define LOCTEXT_NAMESPACE "AssetDefinitionDataGuardRuleSet"

FText UAssetDefinition_DataGuardRuleSet::GetAssetDisplayName() const
{
    return LOCTEXT("Name", "Data Guard Rule Set");
}

FLinearColor UAssetDefinition_DataGuardRuleSet::GetAssetColor() const
{
    return FLinearColor(0.10f, 0.55f, 0.72f);
}

TSoftClassPtr<UObject>
UAssetDefinition_DataGuardRuleSet::GetAssetClass() const
{
    return UDataGuardRuleSet::StaticClass();
}

TConstArrayView<FAssetCategoryPath>
UAssetDefinition_DataGuardRuleSet::GetAssetCategories() const
{
    static const FAssetCategoryPath Categories[] =
    {
        FAssetCategoryPath(LOCTEXT("Category", "Data Guard"))
    };
    return Categories;
}

#undef LOCTEXT_NAMESPACE

UnrealEd, AssetDefinition, AssetTools 중 실제 필요한 Module 이름은 사용하는 UE5 버전의 헤더 소속을 확인해 DataGuardEditor의 Private Dependency에 추가합니다. API 변경이 있는 경우 컴파일러가 가리킨 첫 누락 타입의 공식 헤더부터 확인합니다.

→5. 코드가 동작하는 이유

Reflection이 Asset 클래스와 Factory를 발견하고 Content Browser가 Factory로 새 UObject를 Package 안에 생성합니다. Asset Definition은 표시 메타데이터만 제공하므로 데이터 구조와 UI 표현이 분리됩니다. 모든 클래스가 Editor Module에 있기 때문에 Runtime 대상에는 포함되지 않습니다.

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

!자주 하는 실수

• Editor Asset을 Runtime Blueprint가 참조: Cook에서 클래스가 없거나 Editor Module 혼입 오류가 납니다. 참조 감사를 수행합니다.
• Factory의 SupportedClass 불일치: 생성 메뉴가 없거나 잘못된 타입이 생성됩니다.
• Asset Definition과 구형 AssetTypeActions를 중복 등록: 엔진 버전에 맞는 한 방식을 선택합니다.
• Rule Asset을 Plugin 소스와 함께 자동 발견된다고 가정: 검색 경로와 기본 Rule Set 선택 정책을 명시합니다.
• 저장하지 않은 Asset로만 검증: Editor 재시작과 소스 관리 동기화 뒤 다시 엽니다.

✎7. 직접 실습

✎직접 실습

DA_DataGuardRules를 생성해 /Game 아래 검사 경로와 BP_ 접두어 규칙을 추가하세요. 저장·재시작 뒤 값이 유지되는지 확인하고, Reference Viewer에서 Runtime Asset이 이 Rule Set을 참조하지 않는지 검증하세요.

?8. 이해 점검 질문 3개

?이해 점검

1. Asset 클래스, Factory, Asset Definition은 각각 어떤 책임을 가지나요?
2. Editor Module의 Rule Set을 Runtime Asset이 참조하면 안 되는 이유는 무엇인가요?
3. 엔진 버전에 따라 Asset API가 다를 때 무엇을 기준으로 구현을 조정해야 하나요?

■9. 핵심 요약

■핵심 요약

Data Guard 규칙을 Editor 전용 Asset으로 분리해 프로젝트별 정책을 소스 수정 없이 편집할 수 있게 했습니다. Runtime 참조를 금지하고 Cook 대상에서 제외하는 것이 핵심입니다. 다음 강의에서는 이 규칙을 Unreal Data Validation 흐름에 연결합니다.