حزمة تطوير Unity

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

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

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

المتطلّبات

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

الإعداد

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

نزّل أحدث إصدار واستورد ملف .unitypackage (Assets → Import Package → Custom Package).

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

أضف Newtonsoft JSON إلى Packages/manifest.json:

{ "dependencies": { "com.unity.nuget.newtonsoft-json": "3.0.2" } }

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

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

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

بطاقة بيانات اعتماد الواجهة البرمجية في نافذة Flock — أدخِل بيانات اعتمادك في نافذة Flock → Settings.

وتُحفظ القيم في Assets/Resources/FlockConfig.asset. وأثناء إدخالك لها، تُجهّز النافذة الأمرين اللذين تحتاجهما الحزمة قبل أن تبدأ:

Resolve Game Version — يُبحث عن اسم إصدارك ويُخبز معرّفه داخل الإعداد. وتستخدم التهيئة عند التشغيل ذلك المعرّف المخبوز مباشرةً ولا تتصل بالخادم إطلاقًا، لذا يجب أن يُحلّ قبل أن تلعب أو تبني. وتحلّه النافذة تلقائيًا كلما تغيّرت بيانات اعتمادك (أو اضغط Resolve Game Version).
Verify — يؤكّد زر Verify في قائمة Setup أن بيانات اعتمادك تصل فعلًا إلى Flock.

وظهور علامات خضراء عبر قائمة Setup يعني أنك جاهز للتهيئة.

قائمة Setup تُظهر اتصالًا مُتحقَّقًا منه وإصدار لعبة مُحلًّا — تمّ التحقّق من الاتصال وحُلّ إصدار اللعبة — وكلاهما مطلوب قبل التهيئة.

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

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

مع تفعيل التهيئة التلقائية تكون الحزمة قيد التشغيل بالفعل — ما عليك إلا استخدام FlockClient.Instance.

using Flock;

// 1. Sign a player in. Auth methods throw on failure.
await FlockClient.Instance.Authentication.LoginWithDeviceAsync("device-uuid");

// 2. Call any service through the singleton.
var game = await FlockClient.Instance.Game.GetGameAsync();
Debug.Log($"Signed in as {FlockClient.Instance.CurrentPlayerId}, playing {game.Name}");

التهيئة

يمكن أن تبدأ الحزمة بثلاث طرق. التلقائية هي الافتراضية وتناسب معظم الألعاب؛ أما الطريقتان الأخريان فتمنحانك، مقابل قليل من الإعداد، تحكّمًا في وقت التهيئة (بعد شاشة البداية، أو اتفاقية الترخيص، وما إلى ذلك).

تلقائيًا (الوضع الافتراضي)
مكوّن داخل المشهد
يدويًا

لا شيء عليك استدعاؤه — إذ تهيّئ الحزمة نفسها من FlockConfig.asset قبل تحميل أول مشهد، وتستعيد الجلسة المحفوظة في الخلفية. وتفاعَل مع أحداث دورة الحياة إن احتجت:

FlockEvents.OnInitialized     += ()       => Debug.Log("Flock ready");
FlockEvents.OnSessionRestored += signedIn => Debug.Log(signedIn ? "Resumed" : "Show login");

عطّل Auto-Initialize On Load، ثم اضغط Add to Scene في نافذة Flock (أو أضف مكوّن FlockBootstrap بنفسك). يقرأ المكوّن ملف إعدادك ويهيّئ الحزمة في Awake. ضعه في مشهد إقلاع مع تفعيل Don’t Destroy On Load.

مكوّن FlockBootstrap في لوحة Inspector — مكوّن FlockBootstrap موجَّهًا إلى ملف إعداد FlockConfig لديك.

عطّل Auto-Initialize On Load وأنشئ العميل بنفسك — بعد شاشة البداية أو اتفاقية الترخيص مثلًا. وCreate متزامن ولا يُجري أي اتصال بالشبكة.

var config = Resources.Load<FlockConfigAsset>("FlockConfig");
FlockClient.Create(config.ToInitConfig());

// Manual init does NOT resume a saved session — do it yourself if you persist sessions:
bool signedIn = await FlockClient.Instance.Authentication.TryRestoreSessionAsync();

التهيئة تفشل سريعًا. فالإعداد الخاطئ يرمي استثناءً (ومسار التهيئة التلقائية يسجّل الخطأ بدل أن ينهار)، ويرمي FlockClient.Instance استثناءً حتى تنجح التهيئة. احتَط بـFlockClient.IsInitialized، أو افحص FlockClient.InitializationError، أو تعامَل مع FlockEvents.OnInitializationFailed.

صادِق لاعبًا

تسجيل الدخول لا يُنشئ حسابًا — فالتسجيل استدعاء منفصل من نوع RegisterWith…Async. وتسجيل هوية لها حساب بالفعل ينجح بدل أن يفشل، فيمكنك توجيه اللاعب إلى تسجيل الدخول. ودوال المصادقة ترمي استثناءً عند الإخفاق، لذا غلّفها بـtry/catch.

الجهاز
البريد الإلكتروني
Google / Apple / Steam / Facebook / Discord

await FlockClient.Instance.Authentication.LoginWithDeviceAsync("device-uuid");

await FlockClient.Instance.Authentication.LoginWithEmailAsync(email, password);

مرّر الرمز أو التذكرة الصادرة عن المنصة إلى دالة LoginWith…Async المقابلة.

وتتجدّد الجلسات تلقائيًا. اشترك في FlockEvents.OnAuthenticated وOnAuthExpired لتقود بهما واجهتك.

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

شغّل Code Generation → Sync Schemas في نافذة Flock لتحويل قوالب اللاعبين والإعدادات والمتاجر الموجودة في لوحة التحكم إلى وسائط وصول C# مُحدَّدة الأنواع داخل Assets/Flock/Generated/.

تبويب Code Generation في نافذة Flock — تبويب Code Generation — شغّل Sync Schemas، ثم تصفّح فهرس المحتوى المُولَّد.

// Player data — typed accessor generated from your "PlayerProgress" template.
var progress = await FlockClient.Instance.Player.GetPlayerProgressAsync();
progress.Level = 5;
await progress.UpdateAsync();

// Remote config — change values on the dashboard without rebuilding.
var gameplay = await FlockClient.Instance.Config.GetGameplayAsync();
float speed = gameplay.BaseMoveSpeed;

// Shop — enum-keyed purchase; the SDK resolves ids for you.
await FlockClient.Instance.Shop.PurchaseAsync(FlockShopItemId.GemPack);

وسائط الوصول هذه غير موجودة قبل المزامنة. فدالة GetPlayerProgressAsync أعلاه مُولَّدة من قالب PlayerProgress في لوحة التحكم. وإن كتبت الاستدعاء قبل إنشاء القالب — أو قبل أوّل تشغيل لـ Sync Schemas — فسيفشل عند الترجمة لا عند التشغيل:

'PlayerProvider' does not contain a definition for 'GetPlayerProgressAsync'

والترتيب دائمًا: أنشئ القالب في لوحة التحكم ← شغّل Sync Schemas ← اكتب الاستدعاء. وإضافة قالب أو إعادة تسميته لاحقًا تستلزم مزامنة جديدة.ولا تستطيع رسالة مترجم Unity أن تخبرك بشيء من ذلك، ولهذا تراقب الحزمة عملية الترجمة وتطبع الخطوة الناقصة في الـ Console حين تتعرّف على أحد هذه الأخطاء. كما يعرض تبويب Code Generation ما إذا كانت مزامنة قد جرت أصلًا، وأي إصدار للعبة زامنت عليه آخر مرّة.

تكتب كل مزامنة أيضًا ملف FlockContentCatalog للقراءة فقط — فيستطيع المصمّمون تصفّح كل متجر وإعداد وقالب من لوحة Inspector دون لمس الشيفرة أو لوحة التحكم.

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

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

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

ربط الحسابات

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

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

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

الإشعارات

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

الأصول

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

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

يضبط تبويب Advanced Settings التحليلات، وإعادات محاولة HTTP، وذاكرتَي الأصول ووضع عدم الاتصال، وأدوات المحرّر (بما فيها Auto-Initialize On Load). والقيم الافتراضية معقولة — فلا تغيّرها إلا عند الحاجة.

تبويب Advanced Settings في نافذة Flock — Advanced Settings — التحليلات، وإعادات المحاولة، والتخزين المؤقّت، وأدوات المحرّر.

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

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

try
{
    await FlockClient.Instance.Authentication.LoginWithDeviceAsync(deviceId);
}
catch (FlockException ex)
{
    Debug.LogError(ex.Message);
}

Console

Device login failed: Invalid login credentials [player.invalid_login_credentials, HTTP 400]
Fix: This device is not registered yet. Call Authentication.RegisterWithDeviceAsync(deviceId) once to create the account, then Authentication.LoginWithDeviceAsync(deviceId) on later launches.

وقد يعني رمز الخادم الواحد أمورًا مختلفة تبعًا لطريقة دخول اللاعب، ولذلك يكون الحل خاصًّا بنوع بيانات الاعتماد — فالرسالة أعلاه تقول «سجّل هذا الجهاز»، بينما يقول الرمز نفسه عند الدخول بالبريد الإلكتروني إن كلمة المرور خاطئة.

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

إن فضّلت صياغة نصّك الخاص، فكل جزء متاح على الاستثناء:

الخاصية	ما تحمله
`Message`	كل ما يلي مجموعًا في السطر المعروض أعلاه.
`ServerMessage`	سبب الخادم وحده (`"Invalid login credentials"`)، أو `null`.
`Hint`	نصّ `Fix:` وحده، أو `null` حين لا تملك الحزمة ما تضيفه.
`Operation`	الاستدعاء الذي أخفق (`"Device login"`).
`Code`	المعرّف المُرمَّز كنصّ (`"player.invalid_login_credentials"`).
`ErrorCode`	الرمز نفسه كقيمة `FlockErrorCode`، لاستعماله في `switch`.
`StatusCode`	حالة HTTP، أو `null` إن لم يصل الطلب إلى الخادم أصلًا.
`Body`	جسم الاستجابة الخام، للسجلّات.

تفرّع على ErrorCode لا على نصّ الرسالة أبدًا. فالرموز عقد ثابت، أما الصياغة فليست كذلك وستتغيّر بين الإصدارات.

catch (FlockException ex) when (ex.ErrorCode == FlockErrorCode.ShopInsufficientFunds)
{
    ShowNotEnoughCoinsDialog();
}

Hint مكتوب لك أنت لا للاعبيك — فهو يذكر أسماء دوال الحزمة وخطوات لوحة التحكم. اعرضه في طبقة التصحيح لديك أو في السجلّات، واكتب نصًّا منفصلًا موجّهًا للاعبين في واجهتك. ويمكنك جلب النصّ نفسه لأي رمز عبر FlockErrorHints.For(errorCode).

والإخفاق الذي لا يحمل StatusCode لم يصل إلى الخادم قط — وتلك مشكلة اتصال على الجهاز، لا رفضٌ من الواجهة الخلفية.

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

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

المفاهيم

حزم التطوير

الميزات

المرجع

حزمة تطوير Unity

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

المتطلّبات

الإعداد

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

التهيئة

صادِق لاعبًا

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

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

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

ربط الحسابات

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

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

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

الإشعارات

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

الأصول

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

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

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

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

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

​المتطلّبات

​الإعداد

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

​التهيئة

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

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

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

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

ربط الحسابات

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

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

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

الإشعارات

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

الأصول

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

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

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

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

المتطلّبات

الإعداد

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

التهيئة

صادِق لاعبًا

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

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

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

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

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