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

مقدمة

في ما يلي دليل لتصحيح أخطاء عملية التجميع والإنشاء لألعاب 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. إضافة حزمة Firebase Unity SDK كـ .unitypackage أو
      2. اطّلِع على أحد البدائل في خيارات تثبيت Unity الإضافية ونفِّذه.
   2. تأكَّد من أنّ كل منتج من Firebase في مشروعك وEDM4U:
      • تستخدم الإصدار نفسه
      • تم تثبيتها إما كملفات .unitypackage حصريًا أو من خلال Unity Package Manager حصريًا.

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

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

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

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

أخطاء أثناء التشغيل في وضع Play

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

يُرجى التأكّد من الموافقة على حِزم Firebase في "الأمان والخصوصية " (Security& Privacy) على نظام التشغيل Mac

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

لإجراء ذلك، انقر على رمز Apple > الإعدادات المفضّلة للنظام > الأمان والخصوصية.

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

انقر على الزر السماح على أي حال (Allow Anyway).

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

ارجع إلى 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 Package Manager

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

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

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

أخطاء في Resolver وإصدار جهاز الاختبار

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

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

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

مشاكل "Single Dex" وإزالة البيانات غير الضرورية (إلزامي في حال استخدام Cloud Firestore)

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

Cannot fit requested classes in a single dex file.

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

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

تفعيل ميزة "إزالة البيانات غير الضرورية"

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

تفعيل ملفات DEX المتعددة

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

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

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

فهم أخطاء وقت التشغيل في جهاز الاختبار وإصلاحها

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

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

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 للتعرّف على خيارات إضافية.