نزّل حزمة تطوير Unity
.unitypackage من صفحة الإصدارات.المتطلّبات
- Unity 2021.3 أو أحدث
com.unity.nuget.newtonsoft-json3.0.2+
الإعداد
استورد الحزمة
.unitypackage (Assets → Import Package → Custom Package). أبقِ كل العناصر محدّدة: تُوضع الحزمة
في Assets/FlockSDK/، وأمثلتها في Assets/FlockSDK/Samples/.أضف اعتمادية JSON
Packages/manifest.json وأضف هذا السطر داخل كتلة "dependencies" فيه، بجانب الأسطر الموجودة
هناك (لا تستبدل الملف):com.unity.nuget.newtonsoft-json.اضبط الإعدادات
Assets/Resources/FlockConfig.asset. ولا بدّ من أمر واحد قبل أن تبدأ الحزمة:- Resolve Game Version — يُبحث عن اسم إصدارك ويُخبز معرّفه داخل الإعداد: أي يُكتب في ملف الإعداد داخل المحرّر، فيحمله كل بناء (الحقل Resolved Version ID للقراءة فقط). وتستخدم التهيئة عند التشغيل ذلك المعرّف المخبوز مباشرةً ولا تتصل بالخادم إطلاقًا، لذا يجب أن يُحلّ قبل أن تلعب أو تبني. وتحلّه النافذة تلقائيًا كلما تغيّرت بيانات اعتمادك، ويعيد زر Resolve Game Version ذلك.

تبويب 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.
أول استدعاء لك
مع تفعيل 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.
- الجهاز
- البريد الإلكتروني
- Google / Apple / Steam / Facebook / Discord
async:FlockEvents.OnAuthenticated وOnAuthExpired لتقود بهما واجهتك:
اعمل مع بيانات لعبتك
افتح تبويب Code Generation في Flock → Settings واضغط Sync Schemas (في بطاقة Actions) لتحويل قوالب اللاعبين والإعدادات والمتاجر الموجودة في لوحة التحكم إلى وسائط وصول C# مُحدَّدة الأنواع داخل Generated Code Path (Assets/Flock/Generated/ افتراضيًا، ويُضبط في بطاقة Output Folder).

تبويب 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.

ملف 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 من الأعلى إلى الأسفل: 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.
اقرأ الأجزاء بنفسك
إن فضّلت صياغة نصّك الخاص، فكل جزء متاح على الاستثناء:FlockShopItemId.Sword لعنصر متجر اسمه Sword (راجع
اعمل مع بيانات لعبتك)؛ واستعمل عنصرك أنت.
Hint مكتوب لك أنت لا للاعبيك — فهو يذكر أسماء دوال الحزمة وخطوات لوحة التحكم. اعرضه في طبقة
التصحيح لديك أو في السجلّات، واكتب نصًّا منفصلًا موجّهًا للاعبين في واجهتك. ويمكنك جلب النصّ نفسه
لأي رمز عبر FlockErrorHints.For(errorCode).StatusCode لم يرفضه الخادم: فإمّا أن الطلب لم يصل إليه قط (مشكلة اتصال على
الجهاز، ويذكرها Hint)، وإمّا أن الحزمة رفضت الاستدعاء بنفسها قبل إرساله (وسيط فارغ، أو لا لاعب مسجَّل
دخوله)، ويذكر Message ما ينبغي تغييره.
