> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwacks.com/llms.txt
> Use this file to discover all available pages before exploring further.
# حزمة تطوير Unity
> أضف Flock إلى لعبتك في Unity عبر حزمة التطوير الرسمية بلغة C#.
تربط حزمة تطوير Flock لـUnity لعبتك بالواجهة الخلفية لـFlock: مصادقة اللاعبين، وبيانات الحفظ،
والاقتصاد، والإعدادات عن بُعد، والأصول القابلة للتنزيل، والتحليلات — كل ذلك يُضبط من نافذة واحدة
داخل المحرّر، مع شيفرة C# مُحدَّدة الأنواع تُولَّد من مخطّطاتك أنت.
احصل على أحدث ملف `.unitypackage` من صفحة الإصدارات.
المتطلّبات
* Unity **2020.3** أو أحدث
* `com.unity.nuget.newtonsoft-json` **3.0.2+**
الإعداد
نزّل أحدث [إصدار](https://github.com/QwackStack/FlockUnitySdk/releases) واستورد ملف
`.unitypackage` (**Assets → Import Package → Custom Package**).
أضف Newtonsoft JSON إلى `Packages/manifest.json`:
```json theme={null}
{ "dependencies": { "com.unity.nuget.newtonsoft-json": "3.0.2" } }
```
افتح **Flock → Settings** واملأ الحقول الأربعة من صفحة لعبتك على
[لوحة التحكم](https://flock-saas.qwacks.com):
| الحقل | القيمة |
| ---------------- | ------------------------------------------------------------------------------- |
| **API URL** | اترك القيمة الافتراضية (`https://api-flock.qwacks.com`) ما لم يُطلب منك غير ذلك |
| **API Key** | يُعرّف لعبتك — تعامَل معه كما تتعامل مع كلمة المرور |
| **Game ID** | المعرّف الفريد للعبتك |
| **Game Version** | اسم إصدار موجود على لوحة التحكم (مثل `v1.0.0`) |
وتُحفظ القيم في `Assets/Resources/FlockConfig.asset`. وأثناء إدخالك لها، تُجهّز النافذة الأمرين
اللذين تحتاجهما الحزمة قبل أن تبدأ:
* **Resolve Game Version** — يُبحث عن اسم إصدارك و**يُخبز معرّفه داخل الإعداد**. وتستخدم التهيئة
عند التشغيل ذلك المعرّف المخبوز مباشرةً ولا تتصل بالخادم إطلاقًا، لذا يجب أن يُحلّ قبل أن تلعب
أو تبني. وتحلّه النافذة تلقائيًا كلما تغيّرت بيانات اعتمادك (أو اضغط **Resolve Game Version**).
* **Verify** — يؤكّد زر **Verify** في قائمة **Setup** أن بيانات اعتمادك تصل فعلًا إلى Flock.
وظهور علامات خضراء عبر قائمة **Setup** يعني أنك جاهز للتهيئة.
يُشحن مفتاح الواجهة البرمجية داخل نسختك المبنية (إذ يُحمَّل من `Resources` عند التشغيل). استخدم
مفتاحًا مخصّصًا للبيئة الصحيحة، وبدّله من لوحة التحكم إن تسرّب.
أول استدعاء لك
مع تفعيل التهيئة التلقائية تكون الحزمة قيد التشغيل بالفعل — ما عليك إلا استخدام
`FlockClient.Instance`.
```csharp theme={null}
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` قبل تحميل أول مشهد، وتستعيد
الجلسة المحفوظة في الخلفية. وتفاعَل مع أحداث دورة الحياة إن احتجت:
```csharp theme={null}
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**.
عطّل **Auto-Initialize On Load** وأنشئ العميل بنفسك — بعد شاشة البداية أو اتفاقية الترخيص مثلًا.
و`Create` متزامن ولا يُجري أي اتصال بالشبكة.
```csharp theme={null}
var config = Resources.Load("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`.
```csharp theme={null}
await FlockClient.Instance.Authentication.LoginWithDeviceAsync("device-uuid");
```
```csharp theme={null}
await FlockClient.Instance.Authentication.LoginWithEmailAsync(email, password);
```
مرّر الرمز أو التذكرة الصادرة عن المنصة إلى دالة `LoginWith…Async` المقابلة.
وتتجدّد الجلسات تلقائيًا. اشترك في `FlockEvents.OnAuthenticated` و`OnAuthExpired` لتقود بهما واجهتك.
اعمل مع بيانات لعبتك
شغّل **Code Generation → Sync Schemas** في نافذة Flock لتحويل قوالب اللاعبين والإعدادات والمتاجر
الموجودة في لوحة التحكم إلى وسائط وصول C# مُحدَّدة الأنواع داخل `Assets/Flock/Generated/`.
```csharp theme={null}
// 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 دون لمس الشيفرة أو لوحة التحكم.
استكشف الميزات
الإعدادات المتقدّمة
يضبط تبويب **Advanced Settings** التحليلات، وإعادات محاولة HTTP، وذاكرتَي الأصول ووضع عدم الاتصال،
وأدوات المحرّر (بما فيها **Auto-Initialize On Load**). والقيم الافتراضية معقولة — فلا تغيّرها إلا
عند الحاجة.
معالجة الأخطاء
يرفع كل إخفاق في الحزمة استثناء `FlockException` يحمل رسالة `Message` مقروءة، ورمز `Code` لأخطاء
الواجهة الخلفية المُرمَّزة، و`StatusCode` حيثما ينطبق.
```csharp theme={null}
try
{
await FlockClient.Instance.Authentication.LoginWithEmailAsync(email, password);
}
catch (FlockException ex)
{
Debug.LogError($"Sign-in failed: {ex.Message}");
}
```
تجد المرجع الكامل للواجهة البرمجية، وتفاصيل توليد الشيفرة، وذاكرة وضع عدم الاتصال، وضبط
التحليلات في [ملف README الخاص بالحزمة](https://github.com/QwackStack/FlockUnitySdk#readme).