حزمة تطوير Unreal

تربط حزمة تطوير Flock لـUnreal لعبتك بالواجهة الخلفية لـFlock: مصادقة اللاعبين، وبيانات الحفظ، والاقتصاد، والإعدادات عن بُعد، والتحليلات — كل ذلك يُضبط من Project Settings، مع عقد Blueprint مُحدَّدة الأنواع أو شيفرة C++ تُولَّد من مخطّطاتك أنت. كل ميزة تعمل من Blueprint. فكل استدعاء عقدة غير متزامنة قائمة بذاتها لها طرفا نجاح وفشل، ولا طرف Target توصّله — إذ تستدلّ العقد على الحزمة من الرسم الذي تقع فيه.

نزّل حزمة تطوير Unreal

احصل على أحدث إصدار من الإضافة عبر GitHub.

وصول مبكر. كل ما يلي متاح اليوم. والأصول القابلة للتنزيل هي ميزة Unity الوحيدة التي لم تصل بعد إلى حزمة Unreal — وستصل في إصدار لاحق.

المتطلّبات

Unreal Engine 5.5
مشروع C++. أما المشاريع القائمة على Blueprint فقط فتحتاج إلى تثبيت سلسلة أدوات C++ لبناء الإضافة.

الإعداد

ثبّت الإضافة

نزّل أحدث إصدار وفكّ ضغطه داخل مجلد Plugins/ في مشروعك، بحيث يصبح لديك YourProject/Plugins/FlockUnrealSdk/.ثم انقر بالزر الأيمن على ملف .uproject واختر Generate Visual Studio project files، وأعِد البناء. والإضافة مُفعَّلة افتراضيًا — تحقّق من ذلك في Edit → Plugins → Online Platform → Flock SDK.

اضبط الإعدادات

افتح Project Settings → Plugins → Flock SDK واملأ الحقول الأربعة من صفحة لعبتك على لوحة التحكم:

الحقل	القيمة
API URL	اترك القيمة الافتراضية (`https://api-flock.qwacks.com`) ما لم يُطلب منك غير ذلك
API Key	يُعرّف لعبتك — تعامَل معه كما تتعامل مع كلمة المرور
Game Name	اسم لعبتك كما هو على لوحة التحكم
Game Version	اسم إصدار لعبتك، مثل `1.0.0`

وتُحفظ القيم في ملف DefaultGame.ini الخاص بمشروعك.

اترك الإصدار يُخبز

يُحلّ معرّف إصدار اللعبة ويُخبز من تلقاء نفسه ما إن تصبح تلك الحقول صحيحة، فلا يُجري بدء التشغيل أي اتصال بالشبكة للعثور عليه. ويمكنك فرض ذلك في أي وقت عبر Tools → Flock → Resolve Game Version.

أول استدعاء لك

تهيّئ الحزمة نفسها تلقائيًا مع لعبتك، فليس هناك ما تبدأه. سجّل دخول لاعب، ثم اقرأ شيئًا في المقابل.

رسم Blueprint يمرّر Flock Login With Device إلى Flock Get Game — سجّل الدخول عند BeginPlay، ثم اقرأ سجل اللعبة — بلا طرف Target في أيٍّ من العقدتين.

UFlockSubsystem* Sdk = UFlockSubsystem::Get(this);

Sdk->GetAuthProvider()->LoginWithDevice(DeviceId,
    [Sdk](TFlockResult<FFlockPlayerLoginResponse> Login)
    {
        if (!Login.bSuccess) { return; }

        Sdk->GetGameProvider()->GetGame(
            [](TFlockResult<FFlockGameSchema> Game)
            {
                UE_LOG(LogTemp, Log, TEXT("Playing %s"), *Game.Value.Name);
            });
    });

التهيئة

خيار Auto-Initialize On Load مُفعَّل افتراضيًا، لذا يكون UFlockSubsystem قيد التشغيل قبل BeginPlay. ولتأجيل ذلك إلى ما بعد شاشة البداية أو اتفاقية الترخيص، عطّله واستدعِ InitializeFromSettings() بنفسك. ولأن التهيئة تقرأ معرّف إصدار مخبوزًا، فهي متزامنة ولا تُجري أي اتصال بالشبكة — فتبدأ لعبتك دون اتصال تمامًا كما تبدأ مع الاتصال.

صادِق لاعبًا

البريد الإلكتروني، ومعرّف الجهاز، وGoogle، وApple، وSteam، وFacebook، وDiscord. تستبدل الحزمة بيان الاعتماد الذي أنتجته حزمة تطوير المنصة لديك بجلسة Flock، وتخزّن الرموز مشفَّرة بين مرات التشغيل، وتستعيد الجلسة تلقائيًا عند الإقلاع، وتجدّد رموز الوصول المنتهية بصمت.

عقدتا Flock Login With Email وFlock Register With Device في رسم Blueprint — تسجيل الدخول والتسجيل استدعاءان منفصلان — فالتسجيل لا يسجّل دخول اللاعب.

Sdk->GetAuthProvider()->LoginWithEmail(Email, Password,
    [](TFlockResult<FFlockPlayerLoginResponse> Result)
    {
        if (Result.bSuccess)
        {
            UE_LOG(LogTemp, Log, TEXT("Signed in as %s"), *Result.Value.PlayerId);
        }
    });

لن تمرّر معرّف لاعب إطلاقًا. فالقراءات والأوامر تعمل نيابةً عن اللاعب المسجَّل دخوله؛ أما طرف Player Id فمُخبَّأ في القسم المتقدّم لكل عقدة، للحالة النادرة التي تتصرّف فيها بالنيابة عن لاعب آخر.

اعمل مع بيانات لعبتك

نقرة واحدة في القائمة تحوّل قوالب واجهتك الخلفية وإعداداتها ومتاجرها إلى عقد مُحدَّدة الأنواع. Tools → Flock → Sync Schemas — بلا C++، وبلا سلسلة أدوات، وبلا خطوة بناء.

قائمة Tools تعرض Resolve Game Version وSync Schemas وClean Generated — يولّد Tools → Flock → Sync Schemas ملفات مُحدَّدة الأنواع من مخطّطاتك أنت.

وتصبح قراءة إعدادٍ ما عقدة واحدة تحمل معها عملية الجلب والمعرّف:

عقدة Get Gameplay المُولَّدة تُغذّي عقدة Break — تجلب Get Gameplay وتحوّل وتُعيد بنية مُحدَّدة الأنواع — فكّكها للحصول على أطراف حقيقية.

وتغيير بيانات لاعب يجري هكذا: Get ← Set members in struct من المحرّك ← Save:

عقدة Get Player Level تُغذّي Set members ثم Save Player Level — تُعيد Get معرّف الصف إلى جانب البنية، لأن Save يحتاج إليه.

أشّر على الأعضاء الذين تريد كتابتهم. أما غير المؤشَّر عليهم فيحتفظون بما جلبته Get.

لوحة Details لعقدة Set members in struct — التأشير على عضو يُظهر طرفه — والأعضاء غير الملموسين يبقون كما كانوا تمامًا.

وتأخذ مشتريات المتجر ومنح العملات قائمة منسدلة مُولَّدة بدل معرّف تكتبه بيدك:

عقدة Flock Purchase في رسم Blueprint — اشترِ باختيار العنصر — فالمعرّف مخبوز ولا يمكن أن تخطئ في كتابته.

تفضّل C++؟

بدّل Codegen Target إلى C++ فتُصدِر المزامنة وحدة مُولَّدة بدلًا من ذلك — USTRUCT لكل قالب وإعداد، وUENUM لكل مجموعة معرّفات، وسطح استدعاء مُحدَّد الأنواع.

إعداد Codegen Target في Project Settings — يحدّد Codegen Target ما تُصدِره المزامنة. وBlueprint هو الافتراضي.

FFlockGenerated::GetPlayerLevel(this,
    [this](TFlockResult<FPlayerLevelTemplate> Result, const FString& RowId)
    {
        if (!Result.bSuccess) { return; }

        FPlayerLevelTemplate Progress = Result.Value;
        Progress.Level.Stage = 5;
        FFlockGenerated::SavePlayerLevel(this, RowId, Progress, nullptr);
    });

FFlockGenerated::Purchase(this, EFlockShopItemId::GemPack, OnBought);
FFlockGenerated::AddFunds(this, EFlockCurrencyId::Gold, 100, OnCredited);

ويستخدم المشروع الواحد أحد الهدفين لا كليهما. وبنى C++ المُولَّدة من نوع BlueprintType، فتظل الرسوم ترى أنواعك بعد التبديل.

استكشف الميزات

اللاعبون والمصادقة

بيانات اللاعب

المتاجر والمخزون

الإعدادات عن بُعد

التحليلات والأحداث

الإعدادات المتقدّمة

يضبط Project Settings أيضًا التحليلات، وإعادات محاولة HTTP، وذاكرة وضع عدم الاتصال، ومسارات توليد الشيفرة. والقيم الافتراضية معقولة — فلا تغيّرها إلا عند الحاجة. وتفعيل Enable Debug Logs يتتبّع كل اتصال بالشبكة ضمن الفئة LogFlock، ويذكر كل سطر مصدر الاستدعاء لتميّز رسم Blueprint من شيفرة C++:

[Flock SDK] -> GET .../v1/player_data?player_id=01KY... [Blueprint 'bpTest']
[Flock SDK] <- 200 GET .../v1/player_data?player_id=01KY... (34 ms, 2060 bytes) [Blueprint 'bpTest']

التخزين المؤقّت دون اتصال

تُخزَّن قراءات الإعدادات واللعبة وفهرس المتجر وقوالب اللاعبين مؤقتًا على القرص، ضمن نطاق إصدار لعبتك، وتُقدَّم عند تعذّر الوصول إلى الخادم — إذ يُجرَّب الخادم أولًا دائمًا، ولا توجد مدد صلاحية. أما عمليات الكتابة على بيانات اللاعب فتُصفّ في طابور عند انقطاع الاتصال وتُعاد تلقائيًا عند عودته. أما منح العملات فلا يُصفّ أبدًا: إذ يفشل المنح بدل أن يُصفّ، ولا يُعاد إرساله إطلاقًا بعد إخفاق غامض، فلا يمكن أن يُقيَّد مرتين.

معالجة الأخطاء

يردّ كل استدعاء بقيمة TFlockResult<T> بدل أن يرمي استثناءً — فـUnreal تُبنى مع تعطيل الاستثناءات. تحقّق من bSuccess، ثم اقرأ Value أو Error.

if (!Result.bSuccess && Result.Error.Code == EFlockErrorCode::ShopInsufficientFunds)
{
    // The server declined — not enough funds.
}

وفي Blueprint، لكل عقدة غير متزامنة طرف On Failure يحمل Error نفسه، وتحوّله UFlockErrorLibrary إلى نص للعرض أو إلى تحقّق من خطأ مُرمَّز دون مطابقة نصوص.

تجد المرجع الكامل للواجهة البرمجية، وأدلّة كل ميزة، وتفاصيل توليد الشيفرة في ملف README الخاص بالحزمة.

بدء الاستخدام

المفاهيم

حزم التطوير

الميزات

المرجع

حزمة تطوير Unreal

نزّل حزمة تطوير Unreal

المتطلّبات

الإعداد

أول استدعاء لك

التهيئة

صادِق لاعبًا

اعمل مع بيانات لعبتك

تفضّل C++؟

استكشف الميزات

اللاعبون والمصادقة

بيانات اللاعب

المتاجر والمخزون

الإعدادات عن بُعد

التحليلات والأحداث

الإعدادات المتقدّمة

التخزين المؤقّت دون اتصال

معالجة الأخطاء

نزّل حزمة تطوير Unreal

​المتطلّبات

​الإعداد

​أول استدعاء لك

​التهيئة

​صادِق لاعبًا

​اعمل مع بيانات لعبتك

​تفضّل C++؟

​استكشف الميزات

اللاعبون والمصادقة

بيانات اللاعب

المتاجر والمخزون

الإعدادات عن بُعد

التحليلات والأحداث

​الإعدادات المتقدّمة

​التخزين المؤقّت دون اتصال

​معالجة الأخطاء

المتطلّبات

الإعداد

أول استدعاء لك

التهيئة

صادِق لاعبًا

اعمل مع بيانات لعبتك

تفضّل C++؟

استكشف الميزات

الإعدادات المتقدّمة

التخزين المؤقّت دون اتصال

معالجة الأخطاء