4-2. 에셋 자동화 | UE5 Editor Tools Deep Dive

01

EditorAssetLibrary 핵심 API

에셋 검색, 로드, 수정의 기본 메서드

                    Python - 에셋 검색 및 로드
                    import unreal

# 특정 폴더의 모든 에셋 나열
assets = unreal.EditorAssetLibrary.list_assets(
    "/Game/Meshes",
    recursive=True,
    include_folder=False)

unreal.log(f"Found {len(assets)} assets")

# 에셋 존재 확인
if unreal.EditorAssetLibrary.does_asset_exist(
        "/Game/Meshes/SM_Chair"):
    unreal.log("SM_Chair exists!")

# 에셋 로드 (UObject 반환)
mesh = unreal.EditorAssetLibrary.load_asset(
    "/Game/Meshes/SM_Chair")

# Asset Registry를 통한 고급 검색
asset_registry = unreal.AssetRegistryHelpers.get_asset_registry()

# 특정 클래스의 모든 에셋 검색
filter = unreal.ARFilter(
    class_names=["StaticMesh"],
    package_paths=["/Game/Meshes"],
    recursive_paths=True)
asset_data_list = asset_registry.get_assets(filter)

for ad in asset_data_list:
    unreal.log(f"  {ad.asset_name} - {ad.asset_class_path}")
                

02

배치 임포트/익스포트

외부 파일 일괄 임포트와 에셋 익스포트 자동화

                    Python - FBX 배치 임포트
                    import unreal
import os

def batch_import_fbx(source_dir, dest_path):
    """FBX 파일 일괄 임포트"""
    tasks = []

    for filename in os.listdir(source_dir):
        if not filename.lower().endswith(".fbx"):
            continue

        task = unreal.AssetImportTask()
        task.set_editor_property("automated", True)
        task.set_editor_property("destination_path", dest_path)
        task.set_editor_property("filename",
            os.path.join(source_dir, filename))
        task.set_editor_property("replace_existing", True)
        task.set_editor_property("save", True)

        # FBX 임포트 옵션
        options = unreal.FbxImportUI()
        options.set_editor_property("import_mesh", True)
        options.set_editor_property("import_textures", False)
        options.set_editor_property("import_materials", False)
        options.set_editor_property("import_as_skeletal", False)

        # Static Mesh 옵션
        sm_options = options.static_mesh_import_data
        sm_options.set_editor_property(
            "combine_meshes", True)
        sm_options.set_editor_property(
            "auto_generate_collision", True)

        task.set_editor_property("options", options)
        tasks.append(task)

    # 일괄 임포트 실행
    unreal.AssetToolsHelpers.get_asset_tools().import_asset_tasks(tasks)

    # 결과 확인
    for task in tasks:
        for path in task.get_editor_property("imported_object_paths"):
            unreal.log(f"Imported: {path}")

# 사용 예
batch_import_fbx(
    "D:/Assets/FBX",
    "/Game/Imported/Meshes")
                

                    Python - 텍스처 배치 임포트
                    def batch_import_textures(source_dir, dest_path):
    """PNG/TGA 텍스처 일괄 임포트 + 자동 설정"""
    extensions = (".png", ".tga", ".jpg", ".exr")
    tasks = []

    for filename in os.listdir(source_dir):
        if not filename.lower().endswith(extensions):
            continue

        task = unreal.AssetImportTask()
        task.set_editor_property("automated", True)
        task.set_editor_property("destination_path", dest_path)
        task.set_editor_property("filename",
            os.path.join(source_dir, filename))
        task.set_editor_property("replace_existing", True)
        task.set_editor_property("save", True)
        tasks.append(task)

    unreal.AssetToolsHelpers.get_asset_tools().import_asset_tasks(tasks)

    # 임포트 후 텍스처 설정 자동 적용
    for task in tasks:
        for path in task.get_editor_property("imported_object_paths"):
            tex = unreal.EditorAssetLibrary.load_asset(path)
            if not tex:
                continue

            name = tex.get_name().lower()
            # 노멀맵 자동 감지
            if "_n" in name or "_normal" in name:
                tex.set_editor_property("compression_settings",
                    unreal.TextureCompressionSettings.TC_NORMALMAP)
                tex.set_editor_property("srgb", False)
            # 마스크맵 자동 감지
            elif "_mask" in name or "_orm" in name:
                tex.set_editor_property("compression_settings",
                    unreal.TextureCompressionSettings.TC_MASKS)
                tex.set_editor_property("srgb", False)

            unreal.EditorAssetLibrary.save_loaded_asset(tex)
                

03

에셋 감사 및 정리

프로젝트 에셋 규칙 검증 자동화

                    Python - 에셋 감사 스크립트
                    import unreal

def run_audit():
    """프로젝트 에셋 네이밍 및 설정 감사"""
    issues = []

    # 네이밍 컨벤션 규칙
    naming_rules = {
        "StaticMesh": "SM_",
        "SkeletalMesh": "SK_",
        "Material": "M_",
        "MaterialInstanceConstant": "MI_",
        "Texture2D": "T_",
        "Blueprint": "BP_",
        "ParticleSystem": "PS_",
        "SoundWave": "S_",
    }

    registry = unreal.AssetRegistryHelpers.get_asset_registry()
    all_assets = unreal.EditorAssetLibrary.list_assets(
        "/Game", recursive=True)

    with unreal.ScopedSlowTask(
            len(all_assets), "Auditing assets...") as task:
        task.make_dialog(True)

        for asset_path in all_assets:
            if task.should_cancel():
                break
            task.enter_progress_frame(1, asset_path)

            ad = registry.get_asset_by_object_path(asset_path)
            if not ad:
                continue

            class_name = str(ad.asset_class_path.asset_name)
            asset_name = str(ad.asset_name)

            # 네이밍 검사
            if class_name in naming_rules:
                prefix = naming_rules[class_name]
                if not asset_name.startswith(prefix):
                    issues.append({
                        "type": "NAMING",
                        "path": asset_path,
                        "msg": f"Missing prefix '{prefix}'"
                    })

    # 결과 출력
    unreal.log(f"=== Audit Complete: {len(issues)} issues ===")
    for issue in issues:
        unreal.log_warning(
            f"[{issue['type']}] {issue['path']}: {issue['msg']}")

    return issues
                

ScopedSlowTask

unreal.ScopedSlowTask로 진행 바 다이얼로그를 표시하고, should_cancel()로 사용자 취소를 지원합니다. 배치 작업에서 반드시 사용하세요.

04

에셋 수정 및 저장

에셋 프로퍼티 변경, 이름 변경, 복제, 삭제

                    Python - 에셋 조작
                    import unreal

# 에셋 이름 변경
unreal.EditorAssetLibrary.rename_asset(
    "/Game/Meshes/Chair",
    "/Game/Meshes/SM_Chair")

# 에셋 복제
unreal.EditorAssetLibrary.duplicate_asset(
    "/Game/Meshes/SM_Chair",
    "/Game/Meshes/SM_Chair_Copy")

# 에셋 삭제
unreal.EditorAssetLibrary.delete_asset(
    "/Game/Meshes/OldMesh")

# 에셋 저장
asset = unreal.EditorAssetLibrary.load_asset(
    "/Game/Meshes/SM_Chair")
unreal.EditorAssetLibrary.save_loaded_asset(asset)

# 디렉터리의 모든 에셋 저장
unreal.EditorAssetLibrary.save_directory(
    "/Game/Meshes")

# 에셋 메타데이터 태그 설정
unreal.EditorAssetLibrary.set_metadata_tag(
    "/Game/Meshes/SM_Chair",
    "AuditStatus",
    "Approved")

# 메타데이터 읽기
status = unreal.EditorAssetLibrary.get_metadata_tag(
    "/Game/Meshes/SM_Chair",
    "AuditStatus")

# 참조 찾기
refs = unreal.EditorAssetLibrary.find_package_referencers_for_asset(
    "/Game/Meshes/SM_Chair")
for ref in refs:
    unreal.log(f"Referenced by: {ref}")
                

SUMMARY

핵심 요약

EditorAssetLibrary로 에셋 검색, 로드, 이름 변경, 복제, 삭제 등 CRUD 작업을 자동화합니다
AssetImportTask와 FbxImportUI로 FBX, 텍스처 등 외부 파일의 일괄 임포트를 자동화합니다
ScopedSlowTask로 배치 작업에 진행 바를 표시하고 사용자 취소를 지원합니다
Asset Registry를 통한 고급 검색으로 클래스, 경로 기반 에셋 필터링이 가능합니다
에셋 감사 스크립트로 네이밍 컨벤션, 설정 규칙 등 프로젝트 표준을 자동 검증합니다

PRACTICE

도전 과제

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

실습 1: Python으로 에셋 일괄 임포트

unreal.AssetImportTask를 사용하여 지정된 폴더의 모든 FBX/PNG 파일을 UE5 프로젝트에 일괄 임포트하는 Python 스크립트를 작성하세요. 임포트 설정(스케일, 텍스처 압축 등)을 자동으로 적용하세요.

실습 2: 에셋 일괄 이름 변경 스크립트

unreal.EditorAssetLibrary.rename_asset()을 사용하여 특정 폴더의 에셋 이름에 접두사를 일괄 추가하는 스크립트를 작성하세요. StaticMesh에는 SM_, Texture에는 T_, Material에는 M_ 접두사를 자동으로 붙이세요.

심화 과제: 에셋 파이프라인 자동화 도구

외부 DCC 도구에서 내보낸 에셋을 자동으로 임포트, 이름 변경, LOD 생성, 머티리얼 할당, 지정된 폴더로 이동하는 전체 에셋 파이프라인을 Python으로 구현하세요. 파일 시스템 감시(watchdog)를 활용한 자동 감지 기능도 추가하세요.