تصحيح أخطاء عملية إنشاء اللعبة وتثبيتها وتشغيلها

مقدمة

في ما يلي دليل لتصحيح أخطاء عملية الترجمة والإنشاء لألعاب Unity باستخدام حزمة تطوير البرامج (SDK) لمنصّة Firebase في Unity. ويوضّح كيفية التحقيق في العديد من المشاكل الأكثر شيوعًا التي قد تواجهها وحلّها أثناء ضبط لعبتك وإنشاءها لمنصة جديدة أو بعد تحديثها. يتم ترتيبها بترتيب وقت حدوث هذه الأخطاء في العملية. راجِع هذه الحلول بالترتيب واتّبِع الخطوات اللازمة بعد حلّ كل مشكلة.

بالإضافة إلى هذا المستند، يمكنك الرجوع إلى الأسئلة الشائعة حول Firebase لـ Unity للحصول على مزيد من المعلومات.

مشاكل التجميع في "وضع التشغيل"

يمكن أن تحدث الفئة الأولى من مشاكل الإصدار أثناء الاختبار في المحرِّر قبل محاولة بدء إصدار متوافق مع الأجهزة الجوّالة. يتناول هذا القسم جميع أخطاء Firebase التي تحدث قبل "وضع التشغيل" وأثناءه.

عندما تبدأ Unity أو تكتشف تغييرات في التبعيات أو التعليمات البرمجية أو الأصول الأخرى، ستحاول إعادة بناء المشروع. إذا تعذّر تجميع المشروع في ذلك الوقت، سيسجّل المحرِّر أخطاء التجميع في وحدة التحكّم، وإذا حاولت الدخول إلى "وضع التشغيل"، ستظهر لك نافذة منبثقة تعرض رسالة خطأ في علامة التبويب Scene في Unity نصّها All compiler errors have to be fixed before you can enter playmode!.

تصحيح الأخطاء المرتبطة بالتجميع المرتبط بمنصة Firebase

عدم توفّر الأنواع والفئات والطرق والأعضاء

تحدث العديد من مشاكل Firebase بسبب عدم تمكّن المحرِّر والمجمِّع من العثور على الأنواع والفئات والطُرق والعناصر اللازمة. تشمل الأعراض الشائعة لهذا الاضطراب أنواعًا من الأعراض التالية:

The type or namespace name ‘<CLASS OR NAMESPACE NAME>' could not be found. Are you missing a using directive or an assembly reference?

The type or namespace name <TYPE OR NAMESPACE NAME> does not exist in the namespace ‘Firebase<.OPTIONAL NESTED NAMESPACE NAME PATH>' (are you missing an assembly reference?)

‘<CLASS NAME>' does not contain a definition for ‘<MEMBER VARIABLE OR METHOD NAME>'

خطوات الحلّ:

1. في حال استخدام فئات أو طُرق Firebase في الرموز البرمجية، تأكَّد من إتاحتها من خلال توفير توجيهات using الصحيحة لمنتجات Firebase المحدّدة التي تحتاج إليها.

   1. أمثلة من MechaHamster: Level Up With Firebase Edition:
      1. using Firebase.RemoteConfig;
      2. using Firebase.Crashlytics;

2. تأكَّد من استيراد حِزم Firebase المناسبة:

   1. لاستيراد الحِزم المناسبة، يمكنك اتّباع أيّ من الخطوتَين التاليتَين:
      1. أضِف حزمة تطوير البرامج (SDK) لمنصّة Firebase Unity ك.unitypackage أو
      2. راجِع أحد البدائل في خيارات تثبيت Unity الإضافية ونفِّذه.
   2. تأكَّد من أنّ كل منتج من منتجات Firebase في مشروعك وEDM4U:
      • استخدام الإصدار نفسه
      • تم التثبيت إما كـ .unitypackage حصريًا أو من خلال Unity Package Manager.

3. إذا استوردت حزمة Firebase Unity SDK قبل الإصدار "10.0.0" كـ .unitypackage، سيتضمّن أرشيف حزمة Firebase Unity SDK المضغوط حِزمًا متوافقة مع كلّ من ‎.NET 3.x و‎.NET 4.x. تأكَّد من تضمين مستوى ‎.NET Framework المتوافق فقط في مشروعك:

   1. يمكنك الاطّلاع على التوافق بين إصدارات "محرر Unity" ومستويات إطار عمل ‎.NET في مقالة إضافة Firebase إلى مشروع Unity.
   2. إذا استوردت حِزم Firebase عن طريق الخطأ في مستوى خاطئ من إطار عمل .NET أو كنت بحاجة إلى التبديل من استخدام .unitypackage إلى أحد خيارات تثبيت Unity الإضافية، فإنّ الطريقة الأكثر ملاءمةً هي إزالة كل حزمة Firebase من خلال الطرق المذكورة في قسم نقل البيانات هذا ثم إعادة استيراد كل حِزم Firebase مرة أخرى.

4. تأكَّد من أنّ المحرِّر يعيد إنشاء مشروعك وأنّ محاولاتك لتشغيله تعكس أحدث حالة لمشروعك:

   1. يتم ضبط محرِّر Unity تلقائيًا على إعادة الإنشاء عند رصد تغييرات في مواد العرض أو الإعدادات.
   2. من المحتمل أنّه تم إيقاف هذه الوظيفة وأنّه تم ضبط "أداة إنشاء ألعاب Unity" على إعادة التحديث/إعادة الترجمة يدويًا. يُرجى التحقيق في هذه المشكلة ومحاولة إعادة تحميل الصفحة يدويًا إذا كان هذا هو الحال.

أخطاء وقت التشغيل في "وضع اللعب"

إذا بدأت اللعبة ولكنها تواجه مشاكل مع Firebase أثناء تشغيلها، جرِّب ما يلي:

التأكّد من الموافقة على حِزم Firebase في "الأمان والخصوصية" على نظام التشغيل Mac

إذا ظهرت لك رسالة خطأ عند تشغيل لعبتك في المحرِّر على نظام التشغيل Mac OS مفادها "تعذّر فتح FirebaseCppApp-<version>.bundle لأنّه لا يمكن إثبات ملكية المطوّر"، عليك الموافقة على ملف الحِزمة هذا في قائمة "الأمان والخصوصية" على نظام التشغيل Mac.

لإجراء ذلك، انقر على رمز Apple > System Preferences (الإعدادات المفضَّلة للنظام) > Security & Privacy (الأمان والخصوصية).

في قائمة الأمان، في منتصف الصفحة تقريبًا، يظهر قسم يشير إلى أنّه "تم حظر استخدام FirebaseCppApp-<version>.bundle لأنّه ليس من مطوّر محدّد".

انقر على الزر السماح على أي حال.

تحذير: لا توافق على ملفات مماثلة إلا إذا كنت تثق في المصدر أو كتبتها بنفسك وكنت على دراية بوظائفها وسبب وضع النظام علامة عليها.

ارجِع إلى Unity واضغط على تشغيل مرة أخرى.

سيظهر لك بعد ذلك تحذير مشابه للتحذير الأول:

اضغط على فتح وسيتمكن برنامجك من المتابعة، ولن يُطلب منك هذا الملف المحدّد مرة أخرى.

التأكّد من أنّ مشروعك يحتوي على ملفات إعداد صالحة ويستخدمها

1. تأكَّد من ضبط إعدادات الإنشاء على الجهاز المستهدَف الذي تريده (iOS أو Android) في ملف > إعدادات الإنشاء. للحصول على مناقشة أكثر اكتمالاً، يُرجى الاطّلاع على مستندات إعدادات الإنشاء في Unity.
2. نزِّل ملف الإعدادات لتطبيقك (google-services.json لنظام التشغيل Android أو GoogleService-Info.plist لنظام التشغيل iOS) واستهدِف عملية الإنشاء من وحدة تحكّم Firebase في إعدادات المشروع > تطبيقاتك: إذا كانت لديك هذه الملفات، احذفها من مشروعك واستبدِلها بأحدث إصدار، مع التأكّد من أنّها مكتوبة بالشكل نفسه المعروض أعلاه بدون "(1)" أو أرقام أخرى مرفقة بأسماء الملفات.
3. إذا كانت وحدة التحكّم تحتوي على رسالة بشأن الملفات في Assets/StreamingAssets/، تأكَّد من عدم توفّر أي رسائل في وحدة التحكّم تفيد بأنّه تعذّر على Unity تعديل الملفات هناك.
4. تأكَّد من إنشاء Assets/StreamingAssets/google-services-desktop.json ومطابقته لملف الإعداد الذي تم تنزيله.
   • إذا لم يتم إنشاؤه تلقائيًا ولم يكن StreamingAssets/ متوفّرًا، يمكنك إنشاء الدليل يدويًا في الدليل Assets.
   • تحقَّق مما إذا كان Unity قد أنشأ الآن google-services-desktop.json.

تأكَّد من أنّه تم تثبيت كل منتجات Firebase وEDM4U حصريًا من خلال .unitypackage أو "مدير حِزم Unity".

1. تحقَّق من مجلد Assets/ ومدير حِزم Unity للتأكّد من تثبيت حِزم SDK لمنصّة Firebase وبرنامج EDM4U من خلال طريقة واحدة فقط.
2. قد تعتمد بعض المكوّنات الإضافية التي طوّرتها Google، مثل Google Play، والمكوّنات الإضافية التابعة لجهات خارجية على EDM4U. قد تتضمّن هذه المكونات الإضافية EDM4U في حِزم .unitypackage أو حِزم Unity Package Manager (UPM). التأكّد من توفّر نسخة واحدة فقط من EDM4U في مشروعك إذا كانت أي حِزم UPM تعتمد على EDM4U، من الأفضل الاحتفاظ بإصدارات UPM فقط من EDM4U، والتي يمكن العثور عليها على صفحة Google APIs for Unity المؤرشفة.

تأكّد من أنّ كل منتج Firebase في مشروعك يستخدم الإصدار نفسه.

1. إذا تم تثبيت حِزم Firebase SDK من خلال .unitypackage، تحقّق مما إذا كانت جميع مكتبات FirebaseCppApp ضمن Assets/Firebase/Plugins/x86_64/ تستخدم الإصدار نفسه.
2. إذا تم تثبيت حِزم تطوير البرامج (SDK) لمنصّة Firebase من خلال أداة Unity Package Manager (UPM)، افتح Windows > مدير الحزم، وابحث عن "Firebase" وتأكَّد من أنّ كل حِزم Firebase تعمل في الإصدار نفسه.
3. إذا كان مشروعك يحتوي على إصدارات مختلفة من حِزم تطوير البرامج (SDK) لـ Firebase، ننصحك بإزالة جميع حِزم تطوير البرامج (SDK) لـ Firebase بالكامل قبل تثبيت جميع حِزم تطوير البرامج (SDK) لـ Firebase مرة أخرى، وهذه المرة بالإصدارات نفسها. إنّ الطريقة الأكثر ملاءمةً هي إزالة كل حزمة Firebase من خلال الطرق المذكورة في قسم نقل البيانات هذا.

أداة حل المشاكل وأخطاء إصدار الجهاز المستهدف

إذا كانت لعبتك تعمل في المحرِّر (تم ضبطها لاستهداف عملية الإنشاء المناسبة التي تختارها)، عليك بعد ذلك التأكّد من أنّ أداة إدارة التبعيات الخارجية في Unity (EDM4U) تم ضبطها وتعمل بشكل صحيح.

ملاحظة: ستضيف EDM4U كجزء من عملية إعداد Unity Firebase.

يحتوي مستودع GitHub الخاص ببرنامج EDM4U على دليل خطوة بخطوة لهذا الجزء من العملية يجب مراجعته واتّباعه قبل المتابعة.

مشاكل "Dex واحد" والتصغير (إجراء إلزامي في حال استخدام Cloud Firestore)

أثناء إنشاء تطبيق Android، قد يتعذّر عليك إنشاء إصدار مرتبط بامتلاك ملف واحد لـ dex. تبدو رسالة الخطأ مشابهة لما يلي (إذا تم ضبط مشروعك على استخدام نظام إصدار Gradle):

Cannot fit requested classes in a single dex file.

تُستخدَم ملفات .dex لتخزين مجموعة من تعريفات الفئات والبيانات الملحقة المرتبطة بها لتطبيقات Android. يقتصر ملف dex واحد على الإشارة إلى 65,536 طريقة، ولن تنجح عمليات الإنشاء إذا تجاوز إجمالي عدد الطرق من جميع مكتبات Android في مشروعك هذا الحدّ.

يمكن تطبيق الخطوتَين التاليتَين بشكل تسلسلي، ولا تفعِّل ميزة multidex إلا إذا لم يؤدّي تصغير حجم التطبيق إلى حلّ المشكلة.

تفعيل التصغير

طرحت Unity ميزة التصغير في الإصدار 2017.2 لإزالة الرموز البرمجية غير المستخدَمة، ما يمكن أن يؤدي إلى تقليل إجمالي عدد الطرق المُشار إليها في ملف dex واحد. * يمكن العثور على الخيار في إعدادات المشغّل > Android > إعدادات النشر > تصغير حجم الملفات. * قد تختلف الخيارات في إصدارات Unity المختلفة، لذا يُرجى الرجوع إلى مستندات Unity الرسمية.

تفعيل Multidex

إذا استمر عدد الطرق المُشار إليها في تجاوز الحدّ الأقصى بعد تفعيل التصغير، يمكنك تفعيل multidex كخيار آخر. هناك عدة طرق لتحقيق ذلك في Unity:

• إذا تم تفعيل نموذج Gradle المخصّص ضمن إعدادات المشغّل، عدِّل mainTemplate.gradle.
• إذا كنت تستخدم "استوديو Android" لإنشاء المشروع الذي تم تصديره، عدِّل ملف build.gradle على مستوى الوحدة.

يمكنك الاطّلاع على مزيد من التفاصيل في دليل مستخدم MultiDex.

فهم أخطاء وقت التشغيل على الجهاز المستهدَف وإصلاحها

إذا كانت لعبتك تعمل في المحرِّر ويمكن إنشاؤها وتثبيتها على جهازك المستهدَف، ولكنك تواجه أخطاء وقت التشغيل، عليك فحص السجلّات التي تم إنشاؤها على الجهاز وفحصها.

يوضّح هذا القسم بالتفصيل كيفية فحص السجلّات بحثًا عن الأخطاء المحتمَلة وأحد هذه الأخطاء الذي لا يحدث إلا أثناء التشغيل على الجهاز أو المحاكي.

Android

مُحاكي

• راجِع السجلات المعروضة في وحدة تحكّم المحاكي أو اطّلِع على نافذة Logcat.

الجهاز

تعرَّف على أداة adb وadb logcat وكيفية استخدامهما.

• على الرغم من أنّه يمكنك استخدام الأدوات المختلفة في بيئة سطر الأوامر لفلترة النتائج، يمكنك بدلاً من ذلك النظر في خيارات Logcat.

• في ما يلي طريقة بسيطة لبدء جلسة ADB من جديد:

  adb logcat -c && adb logcat <OPTIONS>

  حيث تكون OPTIONS هي العلامات التي ترسلها إلى سطر الأوامر لفلترة الإخراج.

استخدام Logcat من خلال "استوديو Android"

عند استخدام Logcat من خلال "استوديو Android"، تتوفّر أدوات بحث إضافية تسهّل عملية إنشاء عمليات بحث مثمرة.

iOS

فحص السجلات

إذا كنت تستخدم جهازًا فعليًا، اربطه بالكمبيوتر. راجِع lldb في Xcode.

مشاكل Swift

إذا صادفت سجلات أخطاء تشير إلى Swift، يمكنك الرجوع إلى قسم مدير التبعيات الخارجي في Unity لمعرفة كيفية التعامل معها.

خطوات إضافية

إذا كانت لعبتك لا تزال تواجه مشاكل في الترجمة أو التصميم أو التشغيل مرتبطة بمنصّة Firebase، يمكنك الاطّلاع على صفحة مشاكل حزمة تطوير البرامج (SDK) لمنصّة Firebase في Unity والتفكير في إرسال مشكلة جديدة. بالإضافة إلى ذلك، يمكنك الرجوع إلى صفحة دعم Firebase للتعرّف على الخيارات الإضافية.