نزّل حزمة تطوير Unreal
المتطلّبات
- Unreal Engine من 5.4 إلى 5.8. كل إصدار من 5.5 فما فوق يُبنى وتُشغَّل عليه مجموعة الاختبارات كاملةً قبل كل إصدار؛ أما 5.4 فيُبنى ويُربط في مشروع حقيقي، لكن مجموعة الاختبارات لم تُشغَّل عليه بعد.
- مشروع C++. أما المشاريع القائمة على Blueprint فقط فتحتاج إلى تثبيت سلسلة أدوات C++ لبناء الإضافة.
الإعداد
ثبّت الإضافة
Plugins/ في مشروعك، بحيث يصبح لديك YourProject/Plugins/FlockUnrealSdk/.ثم انقر بالزر الأيمن على ملف .uproject واختر Generate Visual Studio project files، وأعِد
البناء. والإضافة مُفعَّلة افتراضيًا — تحقّق من ذلك في Edit → Plugins → Online Platform →
Flock SDK.اضبط الإعدادات
DefaultGame.ini الخاص بمشروعك.اترك الإصدار يُخبز
استدعاء Flock من C++
"Flock" إلى ملف Build.cs الخاص بوحدة لعبتك. أما المشروع القائم على Blueprint فقط فلا يحتاج إلى شيء هنا.أول استدعاء لك
تهيّئ الحزمة نفسها تلقائيًا مع لعبتك، فليس هناك ما تبدأه. سجّل دخول لاعب، ثم اقرأ شيئًا في المقابل. وأبسط تسجيل دخول هو بالجهاز: بلا شاشة حساب وبلا كلمة مرور. ويحتاج إلى أربعة أشياء:- معرّف الجهاز لهذا التثبيت. اترك معرّف الجهاز فارغًا فتستخدم استدعاءات الجهاز معرّف الحزمة نفسها: GUID
تُنشئه أول مرة يُحتاج إليه وتحفظه في
Saved/Flock/device_id.txt، فيعود اللاعب نفسه في كل تشغيل. واقرأه بـThisDeviceId()على مزوّد المصادقة، أو بـ Flock Get This Device Id في Blueprint. - سجّل الدخول مرة واحدة. يُحفظ تسجيل الدخول بين مرات التشغيل ويُستعاد حين تبدأ الحزمة، فتحقّق أولًا هل سجّل لاعب دخوله من قبل، ولا تسجّل الدخول إلا حين لا يكون أحد قد سجّل دخوله. فتسجيل دخول ثانٍ يُنهي جلسة التحليلات التي بدأها الأول.
- سجّل الجهاز، ثم سجّل الدخول عند الحاجة فقط. فتسجيل الدخول لا يُنشئ حسابًا أبدًا، ولذلك يجب أن يسجّل التشغيل الأول الجهاز. والتسجيل الذي يُنشئ الحساب يسجّل دخول اللاعب أيضًا. وحين يكون للجهاز حساب من قبل، ينجح التسجيل مع ضبط Already Registered ولا يسجّل دخول أحد: فسجّل الدخول حينها. ولا تسجّل الدخول أبدًا بعد تسجيلٍ سجّل دخول اللاعب.
- أحداث تسجيل الدخول. يقول On Authenticated إن لاعبًا سجّل دخوله، أيًّا كانت الطريقة. ويقول On Auth Expired إن تسجيل دخول محفوظًا لم يعد ممكنًا تجديده، فيجب أن يسجّل اللاعب دخوله من جديد.
- سجّل الدخول مرة واحدة. استدعِ حدثًا مخصّصًا مثل Sign In With This Device، يبدأ بـ Branch على Flock Is Authenticated. وقيمة True تعني أن تسجيل دخول محفوظًا قد استُعيد: فلا تفعل شيئًا آخر.
- سجّل الجهاز، ثم سجّل الدخول عند الحاجة فقط. وعند False، شغّل Flock Register With Device تاركًا Device Id فارغًا، فتستخدم معرّف هذا التثبيت. ومن On Success فيها، فكّك النتيجة وتفرّع على Already Registered: فقيمة True تشغّل Flock Login With Device وDevice Id فيها فارغ أيضًا؛ وقيمة False تعني أن التسجيل سجّل دخول اللاعب.
- مرّر كل On Failure عبر To String (Flock Error) إلى Print String: فالنص يقول ما الخطأ وكيف تصلحه.

سجّل الدخول مرة واحدة: حين لا يكون أحد قد سجّل دخوله، سجّل الجهاز؛ وحين يكون له حساب من قبل، سجّل الدخول بالمعرّف نفسه.
UFUNCTION():
Signed in as … ثم Playing …. والإخفاق يسجّل الاستدعاء الذي
أخفق، وسبب الخادم، وسطر Fix:: انظر معالجة الأخطاء.
ومعرّف الجهاز الفارغ يعني معرّف هذا التثبيت في LoginWithDevice وRegisterWithDevice وLinkDevice وعُقدها؛
أما أي معرّف آخر فيُرسَل كما تمرّره تمامًا. وتسجيل الخروج يُبقيه. ويُنشأ معرّف جديد حين يختفي الملف (إعادة
التثبيت على هاتف، أو حذف مجلد Saved أو تنظيفه)، ومع المعرّف الجديد يأتي لاعب جديد بلا شيء من تقدّمه: ولكي تُبقي
اللاعبين عبر إعادة التثبيت أو جهاز جديد، قدّم لهم ربط الحسابات (بريدًا إلكترونيًا
أو حساب منصة). وحين تتعذّر قراءة الملف وكتابته معًا، تسجّل الحزمة تحذيرًا يقول السبب وكيف تصلحه، وتستخدم
معرّفًا لذلك التشغيل وحده. (ولا يصلح FPlatformMisc::GetDeviceId معرّفًا: فهو فارغ على Windows وMac وLinux.)
لا تمرّر معرّفًا من عندك إلا في حالتين:
- لعبتك تسجّل دخول اللاعبين أصلًا بمعرّف من عندها (GUID محفوظ في SaveGame أو في ملف، كما كانت تعرض الإصدارات السابقة من هذه الصفحة): فواصل تمرير ذلك المعرّف نفسه. فتركه فارغًا يسجّل دخول كل لاعب موجود إلى حساب جديد فارغ.
- نسختان من اللعبة تُشغَّلان من مجلد مشروع واحد (Play In Editor بجانب لعبة مستقلة، أو عميلا لعبة على جهاز
واحد) تتشاركان
Saved/، فتتشاركان المعرّف المحفوظ وتكونان لاعبًا واحدًا. فمرّر معرّفًا آخر في إحداهما.
TWeakObjectPtr إلى الحزمة، لا UFlockSubsystem* الخام ولا this أبدًا. فقد يصل الردّ
بعد أن تبدأ اللعبة الإغلاق، فيشير المؤشّر الخام حينها إلى لا شيء.التهيئة
خيار Auto Initialize on Load (في Flock SDK Settings، تحت Initialization) مُفعَّل افتراضيًا، لذا يكونUFlockSubsystem قيد التشغيل قبل BeginPlay. ولتأجيل ذلك إلى ما بعد شاشة البداية أو اتفاقية الترخيص،
عطّله واستدعِ InitializeFromSettings() بنفسك (وفي Blueprint، Initialize From Settings على نظام Flock
الفرعي):
صادِق لاعبًا
البريد الإلكتروني، ومعرّف الجهاز، وGoogle، وApple، وSteam، وFacebook، وDiscord. تستبدل الحزمة بيان الاعتماد الذي أنتجته حزمة تطوير المنصة لديك بجلسة Flock، وتخزّن الرموز مشفَّرة بين مرات التشغيل، وتستعيد الجلسة تلقائيًا عند الإقلاع، وتجدّد رموز الوصول المنتهية بصمت. كل طريقة عقدة غير متزامنة تحت Flock | Auth (Flock Login With Email وFlock Register With Device وغيرهما)، أو استدعاء على مزوّد المصادقة في C++. وتسجيل الدخول والتسجيل استدعاءان منفصلان: فتسجيل الدخول لا يُنشئ حسابًا أبدًا، والتسجيل الذي يُنشئ حسابًا يسجّل دخول اللاعب أيضًا. وكل طريقة تتبع نمط الجهاز في أول استدعاء لك. ومثال ذلك تسجيل الدخول بالبريد الإلكتروني من شاشة تسجيل الدخول الخاصة بك:اعمل مع بيانات لعبتك
نقرة واحدة في القائمة تحوّل قوالب واجهتك الخلفية وإعداداتها ومتاجرها إلى عقد مُحدَّدة الأنواع. Tools → Flock → Sync Schemas — بلا C++، وبلا سلسلة أدوات، وبلا خطوة بناء.
يولّد Tools → Flock → Sync Schemas ملفات مُحدَّدة الأنواع من مخطّطاتك أنت.

تجلب Get Gameplay وتحوّل وتُعيد بنية مُحدَّدة الأنواع — فكّكها للحصول على أطراف حقيقية.
Get ← Set members in struct من المحرّك ← Save:

تُعيد Get معرّف الصف إلى جانب البنية، لأن Save يحتاج إليه.
Get.

التأشير على عضو يُظهر طرفه — والأعضاء غير الملموسين يبقون كما كانوا تمامًا.

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

يحدّد Codegen Target ما تُصدِره المزامنة. وBlueprint هو الافتراضي.
Source/FlockGenerated وتسجّلها في ملف .uproject. ابنِ وأعِد تشغيل المحرّر، ثم أضف
الوحدة إلى ملف Build.cs الخاص بوحدة لعبتك وضمّن ترويستها:
PlayerLevel وعنصر متجر GemPack وعملة Gold؛ أما أسماؤك فتتبع مخطّطاتك
أنت.
BlueprintType، فتظل
الرسوم ترى أنواعك بعد التبديل.
الأمثلة
تأتي الإضافة بمثالين مصنوعين من Blueprint وحده، بلا شيفرة C++ خاصة بهما (مثال المتجر منذ 1.48.0). فعّل Show Plugin Content في إعدادات Content Browser لتراهما تحتContent/Samples في الإضافة. ويحتاج كلاهما
أولًا إلى ملء Project Settings → Plugins → Flock SDK Settings.
- Shop (
Content/Samples/Shop) — افتح المستوىFlockShopSampleوشغّله: سجّل دخول جهاز، وافتح المتجر، واشترِ بالمحفظة أو بمال حقيقي (متجر الهاتف، أو الدفع عبر الويب على Windows وMac وLinux)، واستعمل ما يملكه اللاعب، واستعد المشتريات. ويحتاج إلى متجر في لوحة تحكّم Flock، والوسمcurrencyعلى قالب اللاعب الذي يحمل المحفظة، ومعرّفات منتجات المتجر للعناصر المدفوعة بمال حقيقي. انظر المتاجر والمخزون والشراء داخل التطبيق. - Multiplayer (
Content/Samples/Multiplayer) — اضبط Game Instance Class علىBP_FlockSampleGameInstanceتحت Project Settings → Maps & Modes، ثم شغّل المستوىFlockMultiplayerSampleفي لعبتين مستقلّتين: سجّل الدخول باسم جهاز مختلف في كل منهما (فالاسم الواحد يجعلهما لاعبًا واحدًا)، ثم استضِف وانضمّ برمز، أو ابحث عن مباراة سريعة في طابور موجود للعبتك في لوحة تحكّم Flock. انظر اللعب الجماعي.
استكشف الميزات
تسجيل الدخول
ربط الحسابات
بيانات اللاعب
المتاجر والمخزون
الشراء داخل التطبيق
الدفع عبر الويب
الإعدادات عن بُعد
لوحات الصدارة
الإشعارات
الأصول
التحليلات والأحداث
اللعب الجماعي
اختبار اللعب مع Protokite
الإعدادات المتقدّمة
يضبط Project Settings أيضًا التحليلات، وإعادات محاولة HTTP، وذاكرة وضع عدم الاتصال، ومسارات توليد الشيفرة. والقيم الافتراضية معقولة — فلا تغيّرها إلا عند الحاجة. وتفعيل Enable Debug Logs يتتبّع كل اتصال بالشبكة ضمن الفئةLogFlock، ويذكر كل سطر مصدر
الاستدعاء لتميّز رسم Blueprint من شيفرة C++:
التخزين المؤقّت دون اتصال
تُخزَّن قراءات الإعدادات واللعبة وفهرس المتجر وقوالب اللاعبين مؤقتًا على القرص، ضمن نطاق إصدار لعبتك، وتُقدَّم عند تعذّر الوصول إلى الخادم — إذ يُجرَّب الخادم أولًا دائمًا، ولا توجد مدد صلاحية. وتُحفظ قيم الإعدادات للاعب المسجّل الدخول لكل لاعب على حدة، فتُعطي القراءة دون اتصال آخر قيم ذلك اللاعب، وإلا فقيم اللعبة العامة، ولا تُعطي قيم لاعب آخر أبدًا. أما عمليات الكتابة على بيانات اللاعب فتُصفّ في طابور عند انقطاع الاتصال وتُعاد تلقائيًا عند عودته. أما منح العملات فلا يُصفّ أبدًا: إذ يفشل المنح بدل أن يُصفّ، ولا يُعاد إرساله إطلاقًا بعد إخفاق غامض، فلا يمكن أن يُقيَّد مرتين.معالجة الأخطاء
يردّ كل استدعاء بقيمةTFlockResult<T> بدل أن يرمي استثناءً — فـUnreal تُبنى مع تعطيل الاستثناءات.
تحقّق من bSuccess، ثم اقرأ Value أو Error. وذلك داخل أي دالة إكمال، حيث Result هي قيمة TFlockResult
التي استلمتها:
Error.ToDisplayText() ما الخطأ وكيف تصلحه: الاستدعاء الذي أخفق، وسبب الخادم نفسه، والمعرّف
المُرمَّز، وحالة HTTP، ثم سطر Fix:. ويحمل Output Log النصّ نفسه لكل استدعاء أخفق.
Error.Message ما الخطأ وحده، وError.Hint الإصلاح وحده؛ ولا يكون أيٌّ منهما فارغًا عند الإخفاق.
وفي Blueprint، لكل عقدة غير متزامنة طرف On Failure يحمل Error نفسه. وتحوّله To String (Flock
Error) إلى نص العرض، وتعطي Break Flock Error قيمته Error Code، وهي تعداد (enum) تقارنه دون مطابقة
نصوص.