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

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

احصل على أحدث ملف .unitypackage من صفحة الإصدارات.

المتطلّبات

  • Unity 2021.3 أو أحدث
  • com.unity.nuget.newtonsoft-json 3.0.2+

الإعداد

1

استورد الحزمة

نزّل أحدث إصدار واستورد ملف .unitypackage (Assets → Import Package → Custom Package). أبقِ كل العناصر محدّدة: تُوضع الحزمة في Assets/FlockSDK/، وأمثلتها في Assets/FlockSDK/Samples/.
2

أضف اعتمادية JSON

افتح Packages/manifest.json وأضف هذا السطر داخل كتلة "dependencies" فيه، بجانب الأسطر الموجودة هناك (لا تستبدل الملف):
أو أضفها من Package Manager: + → Add package by name، ثم com.unity.nuget.newtonsoft-json.
3

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

افتح Flock → Settings. وفي تبويب Configuration املأ بطاقة API Credentials من صفحة لعبتك على لوحة التحكم:وتُحفظ القيم في Assets/Resources/FlockConfig.asset. ولا بدّ من أمر واحد قبل أن تبدأ الحزمة:
  • Resolve Game Version — يُبحث عن اسم إصدارك ويُخبز معرّفه داخل الإعداد: أي يُكتب في ملف الإعداد داخل المحرّر، فيحمله كل بناء (الحقل Resolved Version ID للقراءة فقط). وتستخدم التهيئة عند التشغيل ذلك المعرّف المخبوز مباشرةً ولا تتصل بالخادم إطلاقًا، لذا يجب أن يُحلّ قبل أن تلعب أو تبني. وتحلّه النافذة تلقائيًا كلما تغيّرت بيانات اعتمادك، ويعيد زر Resolve Game Version ذلك.
وفي أعلى التبويب بطاقة Setup فيها زر Verify في صفّ Connection. وهو فحص اختياري يتأكّد أن Api Url وApi Key يصلان إلى Flock؛ وتبدأ الحزمة من دونه.
نافذة Flock Settings، تبويب Configuration، مع بطاقة Setup وبطاقة API Credentials

تبويب Configuration: بطاقة Setup (وصفّ Scene bootstrap فيها يقول "Not needed — Auto-Initialize On Load is on.") وبطاقة API Credentials وقد مُلئت فيها Api Url وApi Key وGame Name وGame Version وResolved Version ID.

يُشحن مفتاح الواجهة البرمجية داخل نسختك المبنية (إذ يُحمَّل من Resources عند التشغيل). استخدم مفتاحًا مخصّصًا للبيئة الصحيحة، وبدّله من لوحة التحكم إن تسرّب.

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

مع تفعيل Auto-Initialize On Load (الوضع الافتراضي) تكون الحزمة قيد التشغيل حين يُحمَّل أول مشهد، وتستعيد في الخلفية تسجيل دخول اللاعب المحفوظ. أضف هذا المكوّن إلى كائن GameObject في أول مشهد لديك: ينتظر انتهاء تلك الاستعادة، ثم يسجّل دخول اللاعب فقط إن لم يكن أحد مسجَّل الدخول، ثم يُجري استدعاءً.
النجاح هو ظهور Signed in as ومعرّف اللاعب في الـ Console. دون تمرير معرّف، تستعمل استدعاءات الجهاز Authentication.ThisDeviceId: معرّفًا تصنعه الحزمة أول مرة يُحتاج إليه وتحفظه في ملفات اللعبة المحفوظة (Flock/device_id.txt تحت Application.persistentDataPath؛ وفي تخزين المتصفّح على WebGL)، وهو من النوع نفسه على كل منصّة. ويبقى بعد تسجيل الخروج. ويُصنع معرّف جديد بعد إعادة تثبيت اللعبة أو مسح بيانات التطبيق أو حذف الملف، وعلى WebGL بعد مسح بيانات الموقع، أو في نافذة خاصة، أو حين تُقدَّم اللعبة من عنوان صفحة آخر؛ وقد تعيد استعادة الهاتف من نسخة احتياطية المعرّف القديم. ومع المعرّف الجديد يأتي لاعب جديد، فاعرض ربط الحسابات (بريدًا إلكترونيًا أو حساب منصّة) على اللاعبين الذين يريدون العودة إلى حسابهم من جهاز آخر. لا تمرّر معرّفًا خاصًا بك إلا في حالتين؛ فهو يُرسَل كما هو. والنص الفارغ ليس كترك المعرّف: فاستدعاءا الدخول والتسجيل يرسلانه ويرفضه الخادم، وLinkDeviceAsync يرفضه قبل الإرسال.
  • لعبتك تسجّل دخول اللاعبين بمعرّف خاص بها من قبل (SystemInfo.deviceUniqueIdentifier، أو معرّف محفوظ في PlayerPrefs): فاستمرّ في تمرير ذلك المعرّف. وتركه يمنح كل لاعب حالي حسابًا جديدًا فارغًا.
  • نسختان من اللعبة على حاسوب واحد (المحرّر وبناء) تتشاركان المعرّف المحفوظ، فهما لاعب واحد: مرّر معرّفًا مختلفًا في إحداهما.

التهيئة

يمكن أن تبدأ الحزمة بثلاث طرق. التلقائية هي الافتراضية وتناسب معظم الألعاب؛ أما الطريقتان الأخريان فتمنحانك، مقابل قليل من الإعداد، تحكّمًا في وقت التهيئة (بعد شاشة البداية، أو اتفاقية الترخيص، وما إلى ذلك).
لا شيء عليك استدعاؤه — إذ تهيّئ الحزمة نفسها من FlockConfig.asset قبل تحميل أول مشهد، وتستعيد الجلسة المحفوظة في الخلفية. وتفاعَل مع أحداث دورة الحياة إن احتجت. ولا يعود للعمل لمعالج أُضيف متأخرًا إلا OnInitialized وOnInitializationFailed: فقد تنتهي الاستعادة قبل أن يشترك سكربتك، لذا اقرأ FlockClient.IsRestoringSession أيضًا.
التهيئة تفشل سريعًا. فالإعداد الخاطئ يرمي استثناءً (ومسار التهيئة التلقائية يسجّل الخطأ بدل أن ينهار)، ويرمي FlockClient.Instance استثناءً حتى تنجح التهيئة. احتَط بـFlockClient.IsInitialized، أو افحص FlockClient.InitializationError، أو تعامَل مع FlockEvents.OnInitializationFailed.

أسطر using وتعريفات التجميع

كل أنواع الحزمة في نطاق أسماء يبدأ بـFlock. أضف أسطر using التي يحتاجها السكربت: السكربت في التجميع الافتراضي للعبتك (بلا تعريف تجميع خاص به) يرى الحزمة كما هي. أما السكربت الواقع تحت تعريف تجميع (.asmdef) خاص بك فيحتاج مرجعًا إلى Flock.Runtime في Assembly Definition References لذلك التعريف. والشيفرة التي يكتبها Sync Schemas تذهب إلى Assets/Flock/Generated/، ولا تعريف تجميع فيه، فهي جزء من التجميع الافتراضي: ولا يستطيع سكربت تحت تعريف تجميع خاص بك استعمال الأسماء المُولَّدة. استدعِها من سكربت خارجه، أو استعمل الاستدعاءات الخام التي تأخذ اسمًا (UnlockAchievementAsync("first_win")).

صادِق لاعبًا

تسجيل الدخول لا يُنشئ حسابًا — فالتسجيل استدعاء منفصل من نوع RegisterWith…Async، والتسجيل الذي يُنشئ الحساب يُدخل اللاعب أيضًا. وتسجيل هوية لها حساب بالفعل ينجح بدل أن يفشل (يُعيد null ولا يُدخل أحدًا)، فيمكنك توجيه اللاعب إلى تسجيل الدخول. ودوال المصادقة ترمي استثناءً عند الإخفاق، لذا غلّفها بـtry/catch.
سجّل الدخول، وسجّل الجهاز عند أول تشغيل، كما يُظهر أول استدعاء لك. ويعمل الرمز داخل دالة async:
وتتجدّد الجلسات تلقائيًا. اشترك في FlockEvents.OnAuthenticated وOnAuthExpired لتقود بهما واجهتك:

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

افتح تبويب Code Generation في Flock → Settings واضغط Sync Schemas (في بطاقة Actions) لتحويل قوالب اللاعبين والإعدادات والمتاجر الموجودة في لوحة التحكم إلى وسائط وصول C# مُحدَّدة الأنواع داخل Generated Code Path (Assets/Flock/Generated/ افتراضيًا، ويُضبط في بطاقة Output Folder).
تبويب Code Generation في نافذة Flock

تبويب Code Generation: بطاقة Status بعد مزامنة، ثم How It Works، وOutput Folder (Generated Code Path)، وActions (Sync Schemas، وDelete Generated Code، وOpen Catalog).

يفترض المثال أدناه وجود قالب لاعب اسمه PlayerProgress (حقوله level وxp وclass)، وإعداد لعبة اسمه Gameplay (max_lives وspawn_rate وwelcome_text)، وعنصر متجر GemPack في لوحة التحكم. وهذه أمثلة: أنشئها في لوحة التحكم أولًا (بيانات اللاعب، والإعدادات عن بُعد، والمتاجر والمخزون)، أو استعمل أسماءك أنت. ويعمل الرمز داخل دالة async.
وسائط الوصول هذه غير موجودة قبل المزامنة. فدالة GetPlayerProgressAsync أعلاه مُولَّدة من قالب PlayerProgress في لوحة التحكم. وإن كتبت الاستدعاء قبل إنشاء القالب — أو قبل أوّل تشغيل لـ Sync Schemas — فسيفشل عند الترجمة لا عند التشغيل. وتفشل أسطر using Flock.Generated… بالطريقة نفسها حتى أوّل مزامنة، لأن المزامنة هي التي تكتب نطاقات الأسماء هذه:
ولهذا الخطأ سببان. إمّا أن السكربت ينقصه سطر using لنطاق الأسماء المُولَّد (using Flock.Generated.Templates; هنا — انظر أسطر using وتعريفات التجميع)، وإمّا أن وسيط الوصول لم يُولَّد قط. والترتيب دائمًا: أنشئ القالب في لوحة التحكم ← شغّل Sync Schemas ← اكتب الاستدعاء. وإضافة قالب أو إعادة تسميته لاحقًا تستلزم مزامنة جديدة.ولا تستطيع رسالة مترجم Unity أن تخبرك بشيء من ذلك، ولهذا تراقب الحزمة عملية الترجمة وتطبع الخطوة الناقصة في الـ Console حين تتعرّف على أحد هذه الأخطاء. كما تعرض بطاقة Status في تبويب Code Generation ما إذا كانت مزامنة قد جرت أصلًا، وأي إصدار للعبة زامنت عليه آخر مرّة.
تكتب كل مزامنة أيضًا ملف FlockContentCatalog للقراءة فقط (Open Catalog في بطاقة Actions) — فيستطيع المصمّمون تصفّح كل متجر وإعداد وقالب من لوحة Inspector دون لمس الشيفرة أو لوحة التحكم.
ملف FlockContentCatalog مفتوحًا في لوحة Inspector

ملف FlockContentCatalog المُولَّد — المتاجر والإعدادات والقوالب بقيمها.

الأمثلة

يحمل ملف .unitypackage ثلاثة أمثلة تحت Assets/FlockSDK/Samples/، كلّ منها سكربت واحد تضيفه إلى كائن GameObject فارغ قبل أن تضغط Play:
  • QuickStart (FlockQuickStartSample) — سجّل الدخول بهذا الجهاز، واعرض اللاعب، وأرسل حدث تحليلات تجريبيًا، واقرأ بيانات اللاعب.
  • Shop (FlockShopSample) — سجّل الدخول، واعرض عناصر المتاجر، واشترِ بالمحفظة أو بمال حقيقي، واستعد المشتريات. انظر المتاجر والمخزون.
  • Multiplayer (FlockPlayWithFriendsSample، FlockQuickMatchSample) — استضِف وانضمّ برمز، أو ابحث عن مباراة في طابور. ولا تُترجم إلا مع تثبيت Netcode for GameObjects؛ انظر اللعب الجماعي.
وفي ملف README.md داخل كل مجلّد خطواته.

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

تسجيل الدخول

ربط الحسابات

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

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

لوحات الصدارة

الإشعارات

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

الأصول

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

اللعب الجماعي

اختبار اللعب مع Protokite

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

يضبط تبويب Advanced Settings سجلّات التصحيح، والتحليلات (مع التقاط الاستثناءات وذاكرة الأحداث)، وذاكرة الأصول، وذاكرة وضع عدم الاتصال (Enable Offline Cache وOffline Cache Directory: نُسخ ممّا أعادته استدعاءات القراءة في الحزمة، تُحفظ على القرص وتُقدَّم حين لا تتوفّر الشبكة)، وإعادات محاولة HTTP، وتحديث المجموعة في اللعب الجماعي، وأدوات المحرّر (بما فيها Auto-Initialize On Load). والقيم الافتراضية معقولة — فلا تغيّرها إلا عند الحاجة.
تبويب Advanced Settings في نافذة Flock

Advanced Settings من الأعلى إلى الأسفل: Optional، وAnalytics (مع Exceptions وCaching)، وAsset Cache، وOffline Cache، وHTTP Retry Policy، وMultiplayer، وTools.

ملاحظات المنصّات

WebGL: لا تستطيع النسخة العاملة في المتصفّح كتابة الملفات بالطريقة التي تكتبها ذاكرات الحزمة. فقبل أن تبني لـWebGL، ألغِ تحديد Enable Asset Cache (بطاقة Asset Cache) وEnable Offline Cache (بطاقة Offline Cache) في تبويب Advanced Settings. فتُنزَّل الأصول حينئذ في كل مرّة تُطلب، وتحتاج القراءات إلى الشبكة.

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

يرفع كل إخفاق في الحزمة استثناء FlockException. وتذكر رسالته Message الاستدعاء الذي أخفق، وسبب الخادم نفسه، والمعرّف المُرمَّز، وحالة HTTP — ثم سطر Fix: يخبرك بما تفعله تاليًا. وتعمل الأمثلة أدناه داخل دالة async.
Console
وقد يعني رمز الخادم الواحد أمورًا مختلفة تبعًا لطريقة دخول اللاعب، ولذلك يكون الحل خاصًّا بنوع بيانات الاعتماد — فالرسالة أعلاه تقول «سجّل هذا الجهاز»، بينما يقول الرمز نفسه عند الدخول بالبريد الإلكتروني إن كلمة المرور خاطئة.

اقرأ الأجزاء بنفسك

إن فضّلت صياغة نصّك الخاص، فكل جزء متاح على الاستثناء:
تفرّع على ErrorCode لا على نصّ الرسالة أبدًا. فالرموز عقد ثابت، أما الصياغة فليست كذلك وستتغيّر بين الإصدارات.
يُولّد Sync Schemas القيمة FlockShopItemId.Sword لعنصر متجر اسمه Sword (راجع اعمل مع بيانات لعبتك)؛ واستعمل عنصرك أنت.
Hint مكتوب لك أنت لا للاعبيك — فهو يذكر أسماء دوال الحزمة وخطوات لوحة التحكم. اعرضه في طبقة التصحيح لديك أو في السجلّات، واكتب نصًّا منفصلًا موجّهًا للاعبين في واجهتك. ويمكنك جلب النصّ نفسه لأي رمز عبر FlockErrorHints.For(errorCode).
والإخفاق الذي لا يحمل StatusCode لم يرفضه الخادم: فإمّا أن الطلب لم يصل إليه قط (مشكلة اتصال على الجهاز، ويذكرها Hint)، وإمّا أن الحزمة رفضت الاستدعاء بنفسها قبل إرساله (وسيط فارغ، أو لا لاعب مسجَّل دخوله)، ويذكر Message ما ينبغي تغييره.
تجد المرجع الكامل للواجهة البرمجية، وتفاصيل توليد الشيفرة، وذاكرة وضع عدم الاتصال، وضبط التحليلات في ملف README الخاص بالحزمة.