عیب‌یابی فرایند ساخت، نصب، و اجرای بازی

مقدمه

در زیر راهنمایی برای اشکال‌زدایی فرایند کامپایل و ساخت بازی‌های Unity بااستفاده از کیت توسعه نرم‌افزار Firebase برای Unity ارائه شده است. این راهنما نحوه بررسی و حل بسیاری از مشکلات رایج‌تری را که ممکن است هنگام پیکربندی و ساخت بازی برای پلاتفرمی جدید یا پس‌از به‌روزرسانی با آن‌ها مواجه شوید شرح می‌دهد. این خطاها براساس زمان وقوعشان در فرایند مرتب شده‌اند. به‌ترتیب با آن‌ها مشورت کنید و پس‌از حل هرکدام، به مورد بعدی بروید.

علاوه‌بر این سند، برای اطلاعات بیشتر به پرسشگان Firebase برای Unity مراجعه کنید.

مشکلات گردآوری «حالت بازی»

اولین دسته از مشکلات ساخت می‌تواند هنگام آزمایش در ویرایشگر، قبل‌از تلاش برای شروع ساخت تلفن همراه، رخ دهد. این بخش مربوط به همه خطاهای Firebase است که قبل و درطول «حالت پخش» رخ می‌دهد.

وقتی Unity شروع می‌شود یا تغییراتی را در وابستگی‌ها، کد، یا دارایی‌های دیگر شناسایی می‌کند، سعی می‌کند پروژه را بازسازی کند. اگر پروژه در آن زمان نتواند کامپایل شود، ویرایشگر خطاهای کامپایل را در کنسول ثبت می‌کند و اگر بخواهید وارد «حالت بازی» شوید، یک بالاپر خطا در برگه صحنه 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 به‌عنوان .unitypackages یا
      2. یکی از گزینه‌های جایگزین را در گزینه‌های نصب Unity اضافی بررسی و اجرا کنید.
   2. مطمئن شوید که هر محصول Firebase در پروژه شما و EDM4U:
      • نسخه یکسانی داشته باشند
      • یا منحصراً به‌عنوان .unitypackage یا منحصراً ازطریق Unity Package Manager نصب شده باشند.

3. اگر «کیت توسعه نرم‌افزار Firebase در Unity» را قبل‌از نسخه «10.0.0» به‌عنوان .unitypackage وارد کرده‌اید، بایگانی zip «کیت توسعه نرم‌افزار Firebase در Unity» حاوی بسته‌هایی برای پشتیبانی از NET 3 .x.و NET 4 .x.است. مطمئن شوید که فقط سطح سازگار .NET Framework را در پروژه‌تان گنجانده‌اید:

   1. سازگاری بین نسخه‌های Unity Editor و سطوح چارچوب‌های ‎ .NET در افزودن Firebase به پروژه Unity بحث شده است.
   2. اگر به‌طور تصادفی بسته‌های Firebase خود را در سطح چارچوب .NET اشتباه وارد کرده‌اید یا باید از استفاده از .unitypackages به یکی از گزینه‌های نصب اضافی Unity تغییر دهید، تمیزترین راه این است که هر بسته Firebase را ازطریق روش‌های ذکرشده در این بخش انتقال حذف کنید و سپس همه بسته‌های Firebase را دوباره وارد کنید.

4. بررسی کنید که ویرایشگرتان درحال بازسازی پروژه‌تان باشد و تلاش‌هایتان برای بازی کردن، جدیدترین وضعیت پروژه‌تان را منعکس کند:

   1. به‌طور پیش‌فرض، ویرایشگر Unity به‌گونه‌ای تنظیم شده است که هرگاه تغییراتی در دارایی یا پیکربندی شناسایی شود، بازسازی انجام دهد.
   2. ممکن است این عملکرد غیرفعال شده باشد و Unity Editor روی بازآوری/بازهمگردانی دستی تنظیم شده باشد. این موضوع را بررسی کنید و اگر مشکل همین است، بازآوری دستی را امتحان کنید.

خطاهای زمان اجرای «حالت پخش»

اگر بازی‌تان شروع می‌شود اما هنگام اجرا با Firebase مشکل دارد، موارد زیر را امتحان کنید:

مطمئن شوید که بسته‌های Firebase را در «امنیت و حریم خصوصی» در Mac OS تأیید کرده‌اید

اگر هنگام راه‌اندازی بازی در ویرایشگر در Mac OS، کادر گفتگویی با این پیام دریافت کردید: «FirebaseCppApp-<version>.bundle Cannot be opened because the developer cannot be verified.»، باید آن فایل بسته خاص را در منو «امنیت و حریم خصوصی» Mac تأیید کنید.

برای انجام این کار، روی نماد Apple > اولویت‌های سیستم > امنیت و حریم خصوصی کلیک کنید

در منوِ امنیت، تقریباً در نیمه صفحه، بخشی وجود دارد که می‌گوید «استفاده از FirebaseCppApp-<version>.bundle مسدود شد زیرا از توسعه‌دهنده شناسایی‌شده‌ای نیست».

روی دکمه‌ای که برچسب به‌هرحال مجاز شود دارد کلیک کنید.

احتیاط: فایل‌هایی ازاین‌دست را تأیید نکنید، مگراینکه به منبع اعتماد داشته باشید یا خودتان آن‌ها را نوشته باشید و بدانید چه کاری انجام می‌دهند و چرا سیستم آن‌ها را پرچم‌گذاری کرده است.

به Unity برگردید و دوباره Play (پخش) را فشار دهید.

سپس هشداری مشابه هشدار اول خواهید دید:

باز کردن را فشار دهید تا برنامه‌تان بتواند ادامه دهد؛ دیگر درباره این فایل خاص از شما سؤال نخواهد شد.

مطمئن شوید پروژه‌تان حاوی فایل‌های پیکربندی معتبر باشد و از آن‌ها استفاده کند

1. مطمئن شوید تنظیمات ساخت شما برای هدف موردنظرتان (iOS یا Android) در فایل > تنظیمات ساخت تنظیم شده باشد. برای بحث کامل‌تر، اسناد تنظیمات ساخت Unity را بخوانید.
2. فایل پیکربندی را برای برنامه‌تان (google-services.json برای Android یا GoogleService-Info.plist برای iOS) بارگیری کنید و هدف را از کنسول Firebase در تنظیمات پروژه > برنامه‌های شما بسازید: اگر قبلاً این فایل‌ها را داشته‌اید، آن‌ها را در پروژه‌تان حذف کنید و با جدیدترین نسخه جایگزین کنید، مطمئن شوید که دقیقاً همان‌طور که در بالا نشان داده شده است نوشته شده باشند و «(۱)» یا اعداد دیگری به نام فایل‌ها اضافه نشده باشد.
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 Package Manager را بررسی کنید تا مطمئن شوید کیت‌های توسعه نرم‌افزار Firebase و EDM4U منحصراً ازطریق یکی از این دو روش نصب شده‌اند.
2. برخی‌از افزایه‌های توسعه‌یافته توسط Google، مانند Google Play، و افزایه‌های طرف سوم ممکن است به EDM4U وابسته باشند. این افزونه‌ها ممکن است شامل EDM4U در .unitypackages یا بسته‌های Unity Package Manager (UPM) باشند. مطمئن شوید که فقط یک نسخه از EDM4U در پروژه‌تان وجود دارد. اگر هر بسته UPM به EDM4U وابسته باشد، بهتر است فقط نسخه‌های UPM از EDM4U را نگه دارید که در صفحه بایگانی Google APIs for Unity یافت می‌شود.

مطمئن شوید که همه محصولات Firebase در پروژه شما نسخه یکسانی داشته باشند.

1. اگر کیت‌های توسعه نرم‌افزار Firebase ازطریق .unitypackage نصب شده‌اند، بررسی کنید که آیا همه کتابخانه‌های FirebaseCppApp تحت Assets/Firebase/Plugins/x86_64/ نسخه یکسانی دارند یا نه.
2. اگر کیت‌های توسعه نرم‌افزار Firebase ازطریق Unity Package Manager (UPM) نصب شده‌اند، Windows > Package Manager را باز کنید، «Firebase» را جستجو کنید و مطمئن شوید همه بسته‌های Firebase نسخه یکسانی دارند.
3. اگر پروژه‌تان حاوی نسخه‌های مختلفی از کیت‌های توسعه نرم‌افزار Firebase است، توصیه می‌کنیم قبل‌از نصب مجدد همه کیت‌های توسعه نرم‌افزار Firebase، این بار با نسخه‌های یکسان، همه کیت‌های توسعه نرم‌افزار Firebase را به‌طور کامل بردارید. بهترین روش این است که همه بسته‌های Firebase را ازطریق روش‌های ذکرشده در این بخش انتقال بردارید.

خطاهای ساخت دستگاه هدف و حل‌کننده

اگر بازی‌تان در ویرایشگر کار می‌کند (برای هدف ساخت مناسبی که انتخاب کرده‌اید پیکربندی شده است)، سپس بررسی کنید که مدیر وابستگی خارجی برای Unity (EDM4U) به‌درستی پیکربندی شده باشد و کار کند.

توجه: EDM4U را به‌عنوان بخشی از فرایند راه‌اندازی Unity Firebase اضافه کرده‌اید.

مخزن EDM4U GitHub حاوی راهنمای گام‌به‌گام برای این بخش از فرایند است که باید قبل‌از ادامه دادن آن را مرور و دنبال کنید.

مشکلات «Single Dex» و کوچک‌سازی (اجباری درصورت استفاده از Cloud Firestore)

هنگام ساختن برنامه Android، ممکن است با خطای ساخت مربوط به داشتن یک فایل dex مواجه شوید. پیام خطا شبیه به مورد زیر است (اگر پروژه شما برای استفاده از سیستم ساخت Gradle پیکربندی شده باشد):

Cannot fit requested classes in a single dex file.

فایل‌های .dex برای نگهداری مجموعه‌ای از تعاریف کلاس و داده‌های جانبی مرتبط با آن‌ها برای برنامه‌های Android استفاده می‌شوند. یک فایل dex تکی به ارجاع به ۶۵٬۵۳۶ روش محدود است؛ اگر تعداد کل روش‌ها از همه کتابخانه‌های Android در پروژه شما از این حد فراتر رود، ساخت‌ها ناموفق خواهد بود.

دو مرحله زیر را می‌توان به‌صورت متوالی اعمال کرد؛ فقط درصورتی مولتی‌دکس را فعال کنید که کوچک‌سازی مشکل را برطرف نکند.

فعال کردن Minification

Unity در نسخه ۲۰۱۷.۲، کوچک‌سازی را برای حذف کدهای استفاده‌نشده معرفی کرد که می‌تواند تعداد کل روش‌های ارجاع‌شده را در یک فایل 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 Studio، ابزارهای جستجوی بیشتری دردسترس است که تولید جستجوهای سازنده را ساده‌تر می‌کند.

iOS

درحال بررسی گزارش‌ها

اگر از دستگاه فیزیکی استفاده می‌کنید، آن را به رایانه وصل کنید. lldb را در Xcode بازرسی کنید.

مشکلات Swift

اگر با گزارش‌های خطایی مواجه شدید که به swift اشاره می‌کنند، به بخش مدیر وابستگی خارجی برای Unity مراجعه کنید.

مراحل بعدی

اگر بازی شما همچنان مشکلات کامپایل، ساخت یا اجرا مربوط به Firebase دارد، صفحه مشکلات Firebase SDK برای Unity را بررسی کنید و درنظر داشته باشید که یک مشکل جدید ثبت کنید. علاوه‌براین، برای آشنایی با گزینه‌های بیشتر، به صفحه پشتیبانی Firebase مراجعه کنید.