دليل UE5 Steam Workshop الكامل: الـ Runtime Asset Swapping والأمان

يعرف كل مطور ألعاب مستقل (indie) تلك اللحظة التي يدرك فيها أن المحتوى الذي ينشئه المستخدمون (UGC) هو المفتاح لإطالة عمر لعبته. إن منح مجتمعك الأدوات اللازمة لتبديل الـ character skins، أو استبدال نماذج الأسلحة، أو حقن فيديوهات مخصصة يمكن أن يحول إصداراً عابراً إلى سلسلة ألعاب تستمر لعقد من الزمن.

ولكن عندما تجلس فعلياً لتنفيذ ذلك في Unreal Engine 5، ستصطدم فوراً بجدار.

المفهوم الخاطئ الأكثر شيوعاً — وسؤال متكرر في منتديات المطورين — هو كيفية رفع وتحميل ملفات .FBX الخام عبر Steam Workshop. الحقيقة المرة؟ أنت لا تفعل ذلك. تم تصميم Unreal Engine لتحسين وضغط وعمل "bake" للأصول (assets) بقوة أثناء عملية الـ packaging. محاولة تحليل ملفات .FBX الخام في الـ runtime تتطلب إما تضمين وحدة Unreal Editor الضخمة (والتي تنتهك اتفاقية ترخيص المستخدم النهائي EULA) في لعبتك المشحونة، أو الاعتماد على مكتبات خارجية مثل Assimp، والتي تجرد تماماً الـ material graphs المتقدمة وبيانات الـ skeleton retargeting الخاصة بـ UE5.

لبناء pipeline احترافي للـ modding، تحتاج إلى استخدام نظام ملفات الـ .pak (package) الأصلي في Unreal Engine.

في هذا الـ ue5 steam workshop tutorial الشامل، سنقوم بتفكيك الهندسة المعمارية الدقيقة المطلوبة للاستعلام من Steam Workshop، وتحميل الأصول المخصصة، وعمل mount لملفات الـ .pak ديناميكياً في الـ runtime، وتبديل نماذج لعبتك بأمان دون التأثير على حالة الـ multiplayer.

هندسة الـ Modding في UE5

قبل كتابة سطر واحد من C++، يجب أن تفهم دورة حياة الـ mod في Unreal Engine. إن Steam Workshop مجرد شبكة لتوزيع الملفات؛ فهو لا يعرف ما هو الـ mesh الخاص بـ Unreal Engine.

سير العمل (workflow) يبدو كالتالي:

1. الـ Modkit: توفر لمجتمعك مشروع Unreal Engine مبسطاً يحتوي على الـ Skeleton الأساسي وفئات قوالب الأسلحة.
2. الـ Bake: يقوم الـ modder باستيراد ملف الـ .FBX المخصص الخاص به إلى هذا الـ Modkit، ويقوم بإعداد الـ UE5 materials، ثم يقوم بعمل "cook" للأصل في ملف .pak.
3. التوزيع: يستخدم الـ modder سكربت SteamCMD (أو أداة داخل اللعبة توفرها أنت) لرفع ملف الـ .pak هذا إلى Steam Workshop.
4. العميل (Client): تستخدم لعبتك Steamworks SDK للاستعلام عن العناصر المشترك بها، وتحميل ملف الـ .pak وعمل mount له في نظام الملفات الافتراضي.
5. التبديل (Swap): يقوم منطق اللعبة بتحميل الـ USkeletalMesh ديناميكياً من ملف الـ .pak الذي تم عمل mount له وتطبيقه على شخصية اللاعب.

الخطوة 1: هندسة الـ Modkit الخاص بك

إذا كنت تريد أن يستبدل اللاعبون نموذج الشخصية المعروض، فهم بحاجة إلى الـ skeleton الخاص بك. يجب عليك توزيع نسخة عامة من مشروع UE5 الخاص بك.

ومع ذلك، لا يمكنك ببساطة ضغط الكود المصدري بالكامل. تحتاج إلى إنشاء بيئة نظيفة تحتوي فقط على المراجع الضرورية. يتضمن ذلك إزالة الكود المملوك، وأسرار الـ backend، وأصول الـ marketplace المدفوعة التي لا تملك ترخيصاً لإعادة توزيعها. إذا لم تكن قد فعلت ذلك من قبل، فنحن نوصي بشدة بقراءة دليلنا حول How To Master Unreal Engine Dedicated Server Asset Stripping Step By Step لفهم كيفية عزل الأصول دون كسر التبعيات (dependencies).

في هذا الـ Modkit، ستوفر هيكل مجلدات محدد (مثل /Game/Mods/CustomSkins/). سيضع الـ modder أصوله هنا، ويستخدم Unreal Automation Tool (UAT) لعمل cook لملف .pak.

الخطوة 2: الاستعلام من Steam Workshop في C++

بمجرد رفع ملف الـ .pak إلى Steam، تحتاج لعبتك إلى العثور عليه. تأكد من تفعيل إضافة OnlineSubsystemSteam في ملف DefaultEngine.ini الخاص بك.

بينما يوفر Unreal بعض عقد Blueprint لـ Steam، فإن التكامل الجدي مع Workshop يتطلب C++ باستخدام Steamworks API الأصلي (ISteamUGC). إليك مثال قوي لكيفية الاستعلام عن العناصر التي يشترك فيها المستخدم حالياً:

#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: عمل Mount لملفات .pak في الـ Runtime

هذا هو المكان الذي يتعثر فيه معظم المطورين. لديك مسار الملف لمجلد Steam Workshop، لكن Unreal Engine لا يمكنه قراءة الأصول داخل الـ .pak بشكل أصلي حتى يتم عمل mount له في نظام IPlatformFile.

للقيام بذلك، تحتاج إلى استخدام 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;
}

ملاحظة تقنية هامة: الـ MountPoint الذي تم تحديده أثناء عملية الـ cooking بواسطة الـ modder يجب أن يتطابق مع المكان الذي تقوم بعمل mount فيه في اللعبة، وإلا سيفشل المحرك في الوصول إلى مسارات الأصول الداخلية.

الخطوة 4: تبديل الأصول ديناميكياً

بمجرد عمل mount لملف الـ .pak ، يتم دمج محتوياته في نظام الملفات الافتراضي لـ Unreal. إذا قام الـ modder بإنشاء Skeletal Mesh في /Game/Mods/CustomSkins/SK_CyberNinja ، يمكنك تحميله تماماً مثل أي أصل أصلي.

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

استبدال فيديو في موقع محدد يتبع نفس المنطق تماماً. تقوم بتحميل أصل UMediaPlayer أو UMediaSource المعدل من الـ pak الذي تم عمل mount له وتعيينه لـ material instance الخاص بشاشتك داخل اللعبة.

إذا كنت تقوم بتبديل نماذج الأسلحة في بيئة multiplayer، فكن حذراً للغاية في كيفية التعامل مع الـ component replication. الأسلحة المعدلة التي تقدم ActorComponents جديدة يمكن أن تسبب بسرعة حالات desync للسيرفر إذا لم يكن السيرفر قد قام أيضاً بعمل mount للـ mod. للتعمق في كيفية تعطل ملكية المكونات في الـ multiplayer، راجع تحليلنا حول Multiplayer Inventory Nightmares Fixing Swapped Actorcomponent Owners In Unreal Engine.

معضلة تعدد المنصات والأمان

يعد تنفيذ Steam Workshop مرضياً من الناحية التقنية، ولكنه يقدم عيباً معمارياً هائلاً لألعاب الـ indie الحديثة: الارتباط بالمنصة (Platform Lock-in).

يعمل Steam Workshop فقط على Steam. إذا حققت لعبتك نجاحاً كبيراً وأردت نقلها إلى Epic Games Store أو Xbox أو PlayStation، فستفقد فجأة نظام الـ modding البيئي بالكامل. تمنع الشركات المصنعة لأجهزة الكونسول استخدام Steamworks SDK بشكل صارم، مما يعني أن لاعبي الكونسول سيُحرمون من الـ skins والأسلحة المخصصة التي جعلت لعبتك شائعة على الكمبيوتر.

علاوة على ذلك، لا يوفر Steam Workshop أي تحقق (validation) في الـ runtime. يمكن لمستخدم ضار عمل cook لملف .pak يحتوي على Blueprints مصممة لتنفيذ كود عشوائي، أو إنشاء آلاف الـ actors لإيقاف الـ dedicated servers الخاصة بك، أو منح أنفسهم صلاحيات إدارية.

يتطلب بناء backend مخصص لـ UGC يدعم تعدد المنصات لحل هذه المشكلة إعداد تخزين ملفات موزع جغرافياً (CDN)، و pipelines آلية للتحقق من ملفات الـ .pak (نسخ UE5 headless تقوم بفحص الـ mods المرفوعة بحثاً عن Blueprints ضارة)، ومصادقة عبر الشبكات. هندسة هذه البنية التحتية يدوياً تتطلب بسهولة من 4 إلى 6 أشهر من هندسة الـ backend المتخصصة.

مع horizOn، تأتي خدمات الـ backend هذه معدة مسبقاً. بدلاً من أن تكون مقيداً بنظام Steam البيئي، يمكنك استخدام Backend-as-a-Service من horizOn لاستضافة بوابة mods موحدة ومتعددة المنصات. يمكن للاعبين على Xbox تصفح وتحميل نفس ملفات الـ .pak تماماً مثل لاعبي الكمبيوتر، بينما يتولى backend horizOn التوزيع الآمن، ومصادقة اللاعبين، والـ database sharding المطلوب لخدمة آلاف التحميلات المتزامنة. يتيح لك هذا شحن لعبتك بدلاً من قضاء نصف عام في إدارة البنية التحتية الخاصة بك على AWS.

أفضل الممارسات لتكامل الـ Modding في UE5

إذا كنت تقوم بتنفيذ تبديل الأصول المخصصة، فالتزم بهذه القواعد المجربة لمنع لعبتك من الانهيار تحت وطأة محتوى المجتمع:

1. لا تثق أبداً بملفات الـ .pak الخاصة بالعميل على السيرفر: إذا كانت لعبتك multiplayer، يجب أن يحدد الـ dedicated server حدود التصادم (collision bounds) والـ hitboxes. إذا قام لاعب بتحميل mod من Workshop يجعل نموذج شخصيته أصغر بـ 10 مرات، يجب على السيرفر الاستمرار في استخدام كبسولة التصادم الأصلية غير المعدلة. المرئيات تكون client-side؛ والفيزياء تكون server-side.
2. قم بتطهير (Sanitize) نقاط الـ Mount الخاصة بك: استخدم Asset Registry الخاص بـ Unreal لفحص محتويات ملف الـ .pak فوراً بعد عمل mount. إذا كان ملف الـ .pak يحتوي على أصول UBlueprint أو UClass (ولعبتك تدعم فقط تبديل الـ mesh التجميلي)، فقم فوراً بإلغاء الـ mount ووضع علامة على الملف. اسمح فقط لفئات USkeletalMesh و UTexture2D و UMaterial باجتياز التحقق.
3. نفذ الـ Async Loading للتبديلات: لا تستخدم أبداً استدعاء LoadObject متزامن لـ mesh شخصية بحجم 50 ميجابايت أثناء اللعب الفعلي. سيؤدي ذلك إلى تجميد الـ main thread والتسبب في ارتفاع كبير في الـ ping. استخدم دائماً FStreamableManager::RequestAsyncLoad لتحميل الأصل في الخلفية قبل تطبيقه على الشخصية.
4. توحيد اتفاقيات تسمية الـ Skeleton: فرض اتفاقية تسمية صارمة في الـ Modkit الخاص بك. إذا قام الـ modder بتغيير تسلسل العظام أو إعادة تسمية العظمة الجذرية (root bone)، فسيفشل الـ retargeting في Unreal، مما يؤدي إلى mesh مشوه بشكل مروع. وفر سكربت تحقق في الـ Modkit الخاص بك يحذر الـ modders قبل عمل cook إذا كان الـ skeleton الخاص بهم لا يتطابق تماماً مع الخاص بك.

المضي قدماً

إضافة وظائف Steam Workshop إلى Unreal Engine 5 لا تتعلق بتحليل ملفات ثلاثية الأبعاد خام؛ بل تتعلق بإتقان أنظمة الـ packaging والـ mounting الداخلية في Unreal. من خلال توفير Modkit نظيف، واستخدام C++ للتفاعل مع Steamworks، وإدارة نظام الملفات الافتراضي الخاص بك بأمان، يمكنك تمكين مجتمعك من بناء محتوى مذهل.

ومع ذلك، خطط دائماً للمستقبل. مع نمو لعبتك خارج Steam، تحتاج بنية الـ backend الخاصة بك إلى التوسع معها. إذا كنت مستعداً لتنفيذ نظام UGC آمن ومتعدد المنصات دون صداع البنية التحتية، فجرب horizOn مجاناً.