UE5 Steam Workshop 완벽 튜토리얼: 런타임 Asset Swapping 및 보안

모든 인디 개발자는 사용자 생성 콘텐츠(UGC)가 게임의 수명을 결정짓는 핵심이라는 사실을 깨닫는 순간을 맞이합니다. 커뮤니티에 캐릭터 스킨을 교체하거나, 무기 모델을 변경하거나, 커스텀 비디오를 삽입할 수 있는 도구를 제공하면 일시적인 흥행작을 10년 넘게 지속되는 프랜차이즈로 탈바꿈시킬 수 있습니다.

하지만 실제로 Unreal Engine 5에서 이를 구현하려고 하면 즉시 난관에 봉착하게 됩니다.

가장 흔한 오해이자 개발자 포럼에서 자주 올라오는 질문은 Steam Workshop을 통해 원본 .FBX 파일을 업로드하고 로드하는 방법입니다. 냉혹한 현실은? 그렇게 하지 않는다는 것입니다. Unreal Engine은 패키징 과정에서 에셋을 공격적으로 최적화, 압축 및 bake하도록 설계되었습니다. 런타임에 원본 .FBX 파일을 파싱하려고 시도하려면 방대하고(EULA를 위반하는) Unreal Editor 모듈을 출시된 게임에 포함하거나, UE5의 고급 material graphs 및 skeleton retargeting 데이터를 완전히 제거하는 Assimp와 같은 타사 라이브러리에 의존해야 합니다.

전문적인 모딩 파이프라인을 구축하려면 Unreal Engine의 네이티브 .pak(package) 시스템을 활용해야 합니다.

이 종합적인 ue5 steam workshop tutorial에서는 Steam Workshop 쿼리, 커스텀 에셋 다운로드, 런타임 시 동적 .pak 파일 마운트, 그리고 멀티플레이어 상태를 깨뜨리지 않고 안전하게 게임 모델을 교체하는 데 필요한 정확한 아키텍처를 분석합니다.

UE5 모딩 아키텍처

C++ 코드를 한 줄이라도 쓰기 전에 Unreal Engine 모드의 라이프사이클을 이해해야 합니다. Steam Workshop은 단순한 파일 배포 네트워크일 뿐이며, Unreal Engine 메시가 무엇인지 알지 못합니다.

워크플로우는 다음과 같습니다:

1. Modkit: 기본 Skeleton 및 무기 템플릿 클래스가 포함된 경량화된 Unreal Engine 프로젝트를 커뮤니티에 제공합니다.
2. Bake: 모더는 이 Modkit에 커스텀 .FBX를 임포트하고, UE5 materials를 설정한 다음 에셋을 .pak 파일로 "cook"합니다.
3. 배포: 모더는 SteamCMD 스크립트(또는 개발자가 제공하는 인게임 도구)를 사용하여 해당 .pak을 Steam Workshop에 업로드합니다.
4. 클라이언트: 게임은 Steamworks SDK를 사용하여 구독한 항목을 쿼리하고, .pak을 다운로드하여 가상 파일 시스템에 마운트합니다.
5. Swap: 게임 로직은 마운트된 .pak에서 USkeletalMesh를 동적으로 로드하여 플레이어 캐릭터에 적용합니다.

1단계: Modkit 설계

플레이어가 캐릭터 모델을 교체하게 하려면 개발자의 스켈레톤이 필요합니다. UE5 프로젝트의 공개 버전을 배포해야 합니다.

하지만 전체 소스 코드를 그대로 압축해서 제공할 수는 없습니다. 필요한 참조만 포함된 깨끗한 환경을 만들어야 합니다. 여기에는 독점 코드, 백엔드 비밀, 재배포 라이선스가 없는 유료 marketplace asset을 공격적으로 제거하는 작업이 포함됩니다. 이 작업을 처음 해본다면, 종속성을 깨뜨리지 않고 에셋을 격리하는 방법을 이해하기 위해 How To Master Unreal Engine Dedicated Server Asset Stripping Step By Step 가이드를 읽어보는 것을 강력히 추천합니다.

이 Modkit에서는 특정 폴더 구조(예: /Game/Mods/CustomSkins/)를 제공합니다. 모더는 여기에 에셋을 배치하고 Unreal Automation Tool (UAT)을 사용하여 .pak 파일을 cook합니다.

2단계: C++에서 Steam Workshop 쿼리하기

.pak 파일이 Steam에 업로드되면 게임에서 이를 찾아야 합니다. DefaultEngine.ini에서 OnlineSubsystemSteam 플러그인이 활성화되어 있는지 확인하세요.

Unreal은 Steam을 위한 몇 가지 Blueprint 노드를 제공하지만, 본격적인 Workshop 통합을 위해서는 네이티브 Steamworks API(ISteamUGC)를 사용하는 C++가 필요합니다. 다음은 사용자가 현재 구독 중인 항목을 쿼리하는 견고한 예시입니다:

#include "SteamWorkshopManager.h"
#include "ThirdParty/Steamworks/Steamv157/sdk/public/steam/steam_api.h"

void USteamWorkshopManager::QuerySubscribedMods()
{
    if (!SteamAPI_Init())
    {
        UE_LOG(LogTemp, Error, TEXT("Steam API failed to initialize."));
        return;
    }

    // Get the number of subscribed items
    uint32 NumSubscribed = SteamUGC()->GetNumSubscribedItems();
    if (NumSubscribed == 0)
    {
        UE_LOG(LogTemp, Warning, TEXT("User has no subscribed Workshop items."));
        return;
    }

    // Retrieve the PublishedFileIds
    TArray<PublishedFileId_t> SubscribedItems;
    SubscribedItems.SetNum(NumSubscribed);
    SteamUGC()->GetSubscribedItems(SubscribedItems.GetData(), NumSubscribed);

    // Iterate and get install info
    for (PublishedFileId_t FileId : SubscribedItems)
    {
        uint32 ItemState = SteamUGC()->GetItemState(FileId);
        
        // Check if the item is installed and ready
        if (ItemState & k_EItemStateInstalled)
        {
            uint64 SizeOnDisk;
            char FolderPath[1024];
            uint32 Timestamp;

            bool bSuccess = SteamUGC()->GetItemInstallInfo(FileId, &SizeOnDisk, FolderPath, sizeof(FolderPath), &Timestamp);
            
            if (bSuccess)
            {
                FString ModDirectory = UTF8_TO_TCHAR(FolderPath);
                UE_LOG(LogTemp, Log, TEXT("Found Mod at: %s"), *ModDirectory);
                
                // Proceed to locate the .pak file inside this directory and mount it
                FindAndMountPakFile(ModDirectory);
            }
        }
        else
        {
            // Trigger SteamUGC()->DownloadItem() if not installed
            UE_LOG(LogTemp, Log, TEXT("Item %llu is not installed yet."), FileId);
        }
    }
}

3단계: 런타임 시 .pak 파일 마운트하기

이 부분에서 대부분의 개발자가 막힙니다. Steam Workshop 폴더의 파일 경로를 확보했지만, Unreal Engine은 IPlatformFile 시스템에 마운트되기 전까지는 .pak 내부의 에셋을 네이티브로 읽을 수 없습니다.

이를 위해 FPakFile과 FCoreDelegates를 사용해야 합니다. Build.cs에 PakFile 모듈이 포함되어 있는지 확인하세요.

#include "IPlatformFilePak.h"
#include "HAL/PlatformFileManager.h"
#include "Misc/Paths.h"

bool USteamWorkshopManager::MountPakFile(const FString& PakFilePath)
{
    IPlatformFile& InnerPlatformFile = FPlatformFileManager::Get().GetPlatformFile();
    FPakPlatformFile* PakPlatformFile = static_cast<FPakPlatformFile*>(FPlatformFileManager::Get().FindPlatformFile(FPakPlatformFile::GetTypeName()));

    // Initialize the PakPlatformFile if it doesn't exist
    if (!PakPlatformFile)
    {
        PakPlatformFile = new FPakPlatformFile();
        PakPlatformFile->Initialize(&InnerPlatformFile, TEXT(""));
        FPlatformFileManager::Get().SetPlatformFile(*PakPlatformFile);
    }

    // Ensure the file exists
    if (!InnerPlatformFile.FileExists(*PakFilePath))
    {
        UE_LOG(LogTemp, Error, TEXT("Pak file does not exist: %s"), *PakFilePath);
        return false;
    }

    // Standard mount point, usually "../../../"
    FString MountPoint = FPaths::ProjectDir(); 
    
    // Mount the pak
    if (PakPlatformFile->Mount(*PakFilePath, 0, *MountPoint))
    {
        UE_LOG(LogTemp, Log, TEXT("Successfully mounted Pak: %s"), *PakFilePath);
        return true;
    }

    UE_LOG(LogTemp, Error, TEXT("Failed to mount Pak: %s"), *PakFilePath);
    return false;
}

중요 기술 참고: 모더가 cook 과정에서 정의한 MountPoint는 게임에서 마운트하는 위치와 반드시 일치해야 합니다. 그렇지 않으면 엔진이 내부 에셋 경로를 해석하지 못합니다.

4단계: 동적으로 에셋 교체하기

.pak이 마운트되면 그 내용은 Unreal의 가상 파일 시스템으로 병합됩니다. 모더가 /Game/Mods/CustomSkins/SK_CyberNinja에 Skeletal Mesh를 생성했다면, 네이티브 에셋처럼 로드할 수 있습니다.

void AMyPlayerCharacter::ApplyModdedSkin(const FString& AssetPath)
{
    // Example AssetPath: "/Game/Mods/CustomSkins/SK_CyberNinja.SK_CyberNinja"
    USkeletalMesh* ModdedMesh = LoadObject<USkeletalMesh>(nullptr, *AssetPath);
    
    if (ModdedMesh)
    {
        GetMesh()->SetSkeletalMesh(ModdedMesh);
        UE_LOG(LogTemp, Log, TEXT("Successfully swapped character model!"));
    }
}

특정 위치의 비디오를 교체하는 것도 동일한 로직을 따릅니다. 마운트된 pak에서 수정된 UMediaPlayer 또는 UMediaSource 에셋을 로드하여 인게임 화면의 material instance에 할당합니다.

멀티플레이어 환경에서 무기 모델을 교체하는 경우 component replication 처리에 매우 주의해야 합니다. 새로운 ActorComponents를 도입하는 모드 무기는 서버에도 해당 모드가 마운트되어 있지 않으면 급격한 서버 데싱크(desync)를 유발할 수 있습니다. 멀티플레이어에서 컴포넌트 소유권이 어떻게 깨지는지 자세히 알아보려면 Multiplayer Inventory Nightmares Fixing Swapped Actorcomponent Owners In Unreal Engine 분석을 확인하세요.

크로스 플랫폼 및 보안 딜레마

Steam Workshop 구현은 기술적으로 만족스럽지만, 현대 인디 게임에는 거대한 아키텍처적 결함인 Platform Lock-in을 초래합니다.

Steam Workshop은 Steam에서만 작동합니다. 게임이 흥행하여 Epic Games Store, Xbox 또는 PlayStation으로 포팅하려 할 때, 갑자기 모딩 생태계 전체를 잃게 됩니다. 콘솔 제조사는 Steamworks SDK를 엄격히 금지하므로, PC에서 게임을 인기 있게 만든 커스텀 스킨과 무기를 콘솔 플레이어는 이용할 수 없게 됩니다.

또한 Steam Workshop은 런타임 검증을 제공하지 않습니다. 악의적인 사용자가 임의의 코드를 실행하거나, 전용 서버를 다운시키기 위해 수천 개의 액터를 스폰하거나, 자신에게 관리자 권한을 부여하도록 설계된 Blueprint를 포함한 .pak 파일을 cook할 수 있습니다.

이를 해결하기 위해 커스텀 크로스 플랫폼 UGC 백엔드를 구축하려면 지리적으로 분산된 파일 저장소(CDN), 자동화된 .pak 검증 파이프라인(악성 Blueprint를 스캔하는 헤드리스 UE5 인스턴스), 그리고 크로스 네트워크 인증을 설정해야 합니다. 이러한 인프라를 수동으로 구축하려면 최소 4~6개월의 전담 백엔드 엔지니어링이 필요합니다.

horizOn을 사용하면 이러한 백엔드 서비스가 사전 구성되어 제공됩니다. Steam 생태계에 갇히는 대신 horizOn의 Backend-as-a-Service를 활용하여 통합된 크로스 플랫폼 모드 포털을 운영할 수 있습니다. Xbox 플레이어도 PC 플레이어와 동일한 .pak 파일을 탐색하고 다운로드할 수 있으며, horizOn의 백엔드는 수천 건의 동시 다운로드를 처리하는 데 필요한 보안 배포, 플레이어 인증 및 database sharding을 관리합니다. 이를 통해 인프라 관리에 시간을 허비하는 대신 게임 출시에 집중할 수 있습니다.

UE5 모딩 통합 베스트 프랙티스

커스텀 에셋 교체를 구현하는 경우, 커뮤니티 콘텐츠의 무게로 인해 게임이 무너지지 않도록 다음의 검증된 규칙을 준수하세요:

1. 서버에서 클라이언트 .pak 파일을 절대 신뢰하지 마세요: 멀티플레이어 게임의 경우, dedicated server가 collision bounds와 히트박스를 결정해야 합니다. 플레이어가 캐릭터 모델을 10배 작게 만드는 Workshop 모드를 다운로드하더라도 서버는 원래의 모딩되지 않은 콜리전 캡슐을 계속 사용해야 합니다. 비주얼은 클라이언트 측, 피직스는 서버 측입니다.
2. 마운트 포인트 정리(Sanitize): 마운트 직후 Unreal의 Asset Registry를 사용하여 .pak의 내용을 스캔하세요. .pak에 UBlueprint 또는 UClass 에셋이 포함되어 있고 게임이 코스메틱 메시 교체만 지원한다면, 즉시 마운트를 해제하고 해당 파일을 차단하세요. USkeletalMesh, UTexture2D, UMaterial 클래스만 검증을 통과하도록 허용하세요.
3. 교체 시 Async Loading 구현: 게임 플레이 중에 50MB 캐릭터 메시를 로드할 때 동기식 LoadObject 호출을 절대 사용하지 마세요. 메인 스레드가 멈추고 심각한 핑 스파이크가 발생합니다. 캐릭터에 적용하기 전에 항상 FStreamableManager::RequestAsyncLoad를 사용하여 백그라운드에서 에셋을 스트리밍하세요.
4. 스켈레톤 명명 규칙 표준화: Modkit에서 엄격한 명명 규칙을 강제하세요. 모더가 본 계층 구조를 변경하거나 루트 본의 이름을 바꾸면 Unreal의 리타겟팅이 실패하여 기괴하게 왜곡된 메시가 생성됩니다. 스켈레톤이 완벽하게 일치하지 않을 경우 cook 전에 모더에게 경고하는 검증 스크립트를 Modkit에 포함하세요.

결론

Unreal Engine 5에 Steam Workshop 기능을 추가하는 것은 원본 3D 파일을 파싱하는 것이 아니라, Unreal의 내부 패키징 및 마운팅 시스템을 마스터하는 것입니다. 깨끗한 Modkit을 제공하고, C++를 사용하여 Steamworks와 인터페이스하며, 가상 파일 시스템을 안전하게 관리함으로써 커뮤니티가 놀라운 콘텐츠를 제작할 수 있도록 지원할 수 있습니다.

하지만 항상 미래를 계획하세요. 게임이 Steam을 넘어 성장함에 따라 백엔드 아키텍처도 함께 확장되어야 합니다. 인프라 구축의 번거로움 없이 안전한 크로스 플랫폼 UGC 시스템을 구현할 준비가 되었다면, horizOn을 무료로 체험해 보세요.