حزمة تطوير 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);

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

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

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

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

ربط الحسابات

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

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

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

الإشعارات

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

الأصول

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

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

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

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

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

يرفع كل إخفاق في الحزمة استثناء FlockException يحمل رسالة Message مقروءة، ورمز Code لأخطاء الواجهة الخلفية المُرمَّزة، وStatusCode حيثما ينطبق.

try
{
    await FlockClient.Instance.Authentication.LoginWithEmailAsync(email, password);
}
catch (FlockException ex)
{
    Debug.LogError($"Sign-in failed: {ex.Message}");
}

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

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

المفاهيم

حزم التطوير

الميزات

المرجع

حزمة تطوير Unity

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

المتطلّبات

الإعداد

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

التهيئة

صادِق لاعبًا

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

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

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

ربط الحسابات

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

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

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

الإشعارات

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

الأصول

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

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

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

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

​المتطلّبات

​الإعداد

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

​التهيئة

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

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

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

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

ربط الحسابات

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

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

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

الإشعارات

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

الأصول

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

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

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

المتطلّبات

الإعداد

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

التهيئة

صادِق لاعبًا

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

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

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

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