Kompletny tutorial UE5 Steam Workshop: Runtime Asset Swapping i bezpieczeństwo

Każdy deweloper indie zna ten moment, w którym uświadamia sobie, że user-generated content (UGC) jest kluczem do długowieczności jego gry. Danie społeczności narzędzi do swappowania skinów postaci, wymiany modeli broni czy wstrzykiwania własnych filmów może zmienić przelotną premierę w franczyzę na dekadę.

Ale kiedy faktycznie siadasz do implementacji tego w Unreal Engine 5, natychmiast uderzasz w ścianę.

Najczęstszym błędnym przekonaniem — i częstym pytaniem na forach deweloperskich — jest to, jak przesyłać i ładować surowe pliki .FBX przez Steam Workshop. Brutalna rzeczywistość? Nie robisz tego. Unreal Engine jest zaprojektowany tak, aby agresywnie optymalizować, kompresować i „piec” (bake) assety podczas procesu packagingu. Próba parsowania surowych plików .FBX w runtime wymaga albo osadzenia ogromnego (i naruszającego EULA) modułu Unreal Editor w wydanej grze, albo polegania na bibliotekach zewnętrznych, takich jak Assimp, które całkowicie usuwają zaawansowane material graphs i dane skeleton retargeting z UE5.

Aby zbudować profesjonalny pipeline moderski, musisz wykorzystać natywny system plików .pak (package) silnika Unreal Engine.

W tym kompleksowym ue5 steam workshop tutorial, rozbijemy na czynniki pierwsze dokładną architekturę wymaganą do odpytywania Steam Workshop, pobierania niestandardowych assetów, dynamicznego montowania plików .pak w runtime i bezpiecznego swappowania modeli w grze bez naruszania stanu multiplayer.

Architektura modowania w UE5

Zanim napiszesz choćby jedną linię w C++, musisz zrozumieć cykl życia moda w Unreal Engine. Steam Workshop to jedynie sieć dystrybucji plików; nie wie on, czym jest mesh w Unreal Engine.

Workflow wygląda następująco:

1. Modkit: Udostępniasz społeczności okrojoną wersję projektu Unreal Engine, zawierającą bazowy Skeleton i klasy szablonów broni.
2. Bake: Moder importuje swój niestandardowy .FBX do tego Modkitu, konfiguruje materiały UE5 i „gotuje” (cook) asset do pliku .pak.
3. Dystrybucja: Moder używa skryptu SteamCMD (lub dostarczonego przez Ciebie narzędzia w grze), aby przesłać ten .pak do Steam Workshop.
4. Klient: Twoja gra używa Steamworks SDK do odpytywania o subskrybowane przedmioty, pobiera .pak i montuje go w wirtualnym systemie plików.
5. Swap: Logika gry dynamicznie ładuje USkeletalMesh z zamontowanego pliku .pak i aplikuje go do postaci gracza.

Krok 1: Architektura Twojego Modkitu

Jeśli chcesz, aby gracze wymieniali wyświetlany model postaci, potrzebują Twojego skeletonu. Musisz udostępnić publiczną wersję swojego projektu UE5.

Nie możesz jednak po prostu spakować całego kodu źródłowego. Musisz stworzyć sterylne środowisko zawierające tylko niezbędne referencje. Wiąże się to z agresywnym usuwaniem zastrzeżonego kodu, sekretów backendu i płatnych assetów z marketplace, na których redystrybucję nie masz licencji. Jeśli nigdy wcześniej tego nie robiłeś, zdecydowanie zalecamy przeczytanie naszego przewodnika How To Master Unreal Engine Dedicated Server Asset Stripping Step By Step, aby zrozumieć, jak izolować assety bez niszczenia zależności.

W tym Modkicie zapewnisz określoną strukturę folderów (np. /Game/Mods/CustomSkins/). Moder umieści tam swoje assety i użyje Unreal Automation Tool (UAT), aby przygotować plik .pak.

Krok 2: Odpytywanie Steam Workshop w C++

Gdy plik .pak zostanie przesłany na Steam, Twoja gra musi go znaleźć. Upewnij się, że masz włączoną wtyczkę OnlineSubsystemSteam w swoim DefaultEngine.ini.

Podczas gdy Unreal oferuje pewne węzły Blueprint dla Steam, poważna integracja z Workshop wymaga C++ przy użyciu natywnego API Steamworks (ISteamUGC). Oto solidny przykład tego, jak odpytać o przedmioty, które użytkownik aktualnie subskrybuje:

#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);
        }
    }
}

Krok 3: Montowanie plików .pak w runtime

To jest moment, w którym większość deweloperów utyka. Masz ścieżkę do folderu Steam Workshop, ale Unreal Engine nie może natywnie odczytać assetów wewnątrz .pak, dopóki nie zostanie on zamontowany w systemie IPlatformFile.

Aby to zrobić, musisz użyć FPakFile i FCoreDelegates. Upewnij się, że Twój Build.cs zawiera moduł 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;
}

Kluczowa uwaga techniczna: MountPoint zdefiniowany podczas procesu cookingu przez modera MUSI zgadzać się z miejscem, w którym montujesz go w grze, inaczej silnik nie rozwiąże wewnętrznych ścieżek assetów.

Krok 4: Dynamiczne swappowanie assetów

Po zamontowaniu .pak, jego zawartość jest scalana z wirtualnym systemem plików Unreal. Jeśli moder stworzył Skeletal Mesh w /Game/Mods/CustomSkins/SK_CyberNinja, możesz go załadować jak natywny asset.

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!"));
    }
}

Zastępowanie wideo w określonej lokalizacji odbywa się według tej samej logiki. Ładujesz zmodyfikowany asset UMediaPlayer lub UMediaSource z zamontowanego paka i przypisujesz go do instancji materiału ekranu w grze.

Jeśli swappujesz modele broni w środowisku multiplayer, bądź niezwykle ostrożny z component replication. Zmodowane bronie wprowadzające nowe ActorComponents mogą szybko spowodować desynchronizację serwera, jeśli serwer również nie ma zamontowanego moda. Aby dowiedzieć się więcej o tym, jak własność komponentów psuje się w multiplayerze, sprawdź naszą analizę Multiplayer Inventory Nightmares Fixing Swapped Actorcomponent Owners In Unreal Engine.

Dylemat międzyplatformowości i bezpieczeństwa

Implementacja Steam Workshop jest satysfakcjonująca technicznie, ale wprowadza ogromną wadę architektoniczną dla nowoczesnych gier indie: Platform Lock-in.

Steam Workshop działa tylko na Steam. Jeśli Twoja gra odniesie sukces i będziesz chciał ją przenieść na Epic Games Store, Xbox lub PlayStation, nagle stracisz cały ekosystem moderski. Producenci konsol surowo zabraniają używania Steamworks SDK, co oznacza, że gracze konsolowi zostaną odcięci od niestandardowych skinów i broni, które uczyniły Twoją grę popularną na PC.

Co więcej, Steam Workshop nie zapewnia żadnej walidacji w runtime. Złośliwy użytkownik może przygotować plik .pak, który zawiera nadpisujące Blueprinty zaprojektowane do wykonywania dowolnego kodu, spawnowania tysięcy aktorów w celu zawieszenia Twoich dedicated servers lub nadania sobie uprawnień administracyjnych.

Zbudowanie niestandardowego, międzyplatformowego backendu UGC, aby to rozwiązać, wymaga skonfigurowania geograficznie rozproszonego przechowywania plików (CDN), zautomatyzowanych potoków walidacji .pak (instancje UE5 headless skanujące mody pod kątem złośliwych Blueprintów) oraz uwierzytelniania cross-network. Ręczne projektowanie tej infrastruktury wymaga od 4 do 6 miesięcy pracy inżyniera backendu.

Dzięki horizOn te usługi backendowe są wstępnie skonfigurowane. Zamiast być uwięzionym w ekosystemie Steam, możesz wykorzystać Backend-as-a-Service od horizOn, aby hostować ujednolicony, międzyplatformowy portal modów. Gracze na Xbox mogą przeglądać i pobierać dokładnie te same pliki .pak, co gracze na PC, podczas gdy backend horizOn zajmuje się bezpieczną dystrybucją, uwierzytelnianiem graczy i shardingiem bazy danych wymaganym do obsługi tysięcy jednoczesnych pobrań. Pozwala to wydać grę zamiast spędzać pół roku na zarządzaniu własną infrastrukturą AWS.

Najlepsze praktyki integracji modowania w UE5

Jeśli implementujesz niestandardowe swapy assetów, trzymaj się tych sprawdzonych zasad:

1. Nigdy nie ufaj plikom .pak klienta na serwerze: Jeśli Twoja gra jest multiplayer, dedicated server musi dyktować collision bounds i hitbox-y. Jeśli gracz pobierze moda, który czyni jego model 10 razy mniejszym, serwer musi nadal używać oryginalnej kapsuły kolizji. Wizualia są client-side; fizyka jest server-side.
2. Sanityzuj swoje Mount Points: Użyj Asset Registry silnika Unreal, aby przeskanować zawartość .pak natychmiast po zamontowaniu. Jeśli .pak zawiera assety UBlueprint lub UClass (a Twoja gra obsługuje tylko kosmetyczne zmiany meshów), natychmiast go odmontuj. Pozwalaj tylko klasom USkeletalMesh, UTexture2D i UMaterial przejść walidację.
3. Zaimplementuj Async Loading dla swapów: Nigdy nie używaj synchronicznego wywołania LoadObject dla mesha postaci o rozmiarze 50 MB podczas aktywnej rozgrywki. Zamrozi to główny wątek i spowoduje ogromny skok pingu. Zawsze używaj FStreamableManager::RequestAsyncLoad.
4. Standaryzuj konwencje nazewnictwa Skeletonu: Wymuś ścisłą konwencję nazewnictwa w swoim Modkicie. Jeśli moder zmieni hierarchię kości, retargeting Unreala zawiedzie. Dostarcz skrypt walidacyjny w Modkicie.

Podsumowanie

Dodanie funkcjonalności Steam Workshop do Unreal Engine 5 nie polega na parsowaniu surowych plików 3D; chodzi o opanowanie wewnętrznych systemów packagingu i montowania Unreala. Zapewniając czysty Modkit, wykorzystując C++ do komunikacji ze Steamworks i bezpiecznie zarządzając wirtualnym systemem plików, możesz umożliwić swojej społeczności tworzenie niesamowitych treści.

Zawsze jednak planuj przyszłość. Gdy Twoja gra wyjdzie poza Steam, Twoja architektura backendu musi skalować się wraz z nią. Jeśli jesteś gotowy na wdrożenie bezpiecznego, międzyplatformowego systemu UGC bez bólów głowy związanych z infrastrukturą, wypróbuj horizOn za darmo.