نماذج

توضِّح عيّنات "إضافة تطوير الألعاب على Android" كيفية استخدام الميزات الرئيسية للإضافة. يوضّح هذا الموضوع العيّنات والإعدادات اللازمة لتنفيذها.

تتوفّر العيّنات التالية في صفحة "عمليات التنزيل":

• HelloJNI: مشروع تمهيدي
• Endless-Tunnel: مشروع مخصّص لأجهزة Android فقط.
• Teapot: مشروع متوافق مع أنظمة التشغيل Windows وAndroid
• AssemblyCode-Link-Objects: مشروع نموذج يحتوي على رمز مصدر لنص تجميعي

قبل البدء

• ثبِّت إضافة تطوير ألعاب Android والعيّنات. اطّلِع على الدليل المفصّل للبدء للحصول على التفاصيل. يوضّح الموضوع أيضًا كيفية إنشاء وتشغيل عيّنة، ويستخدم إصدار Android من عيّنة Teapot كمثال.

• يوضّح دليل ضبط المشروع كيفية ضبط إعدادات مشروع يستخدم الإضافة، مثل إضافة نظام Android الأساسي وحزمة APK.

HelloJNI

نموذج HelloJNI هو مشروع بسيط يعرض رسالة "مرحبًا من JNI" في نافذة التطبيق. يستخدم المشروع مجموعة مختلفة من رموز المصدر لكل من Windows و Android.

• رمز المصدر لنظام Android ودليل النصوص البرمجية لإنشاء Gradle: HelloJNI\AndroidPackaging
• رمز المصدر لنظام التشغيل Windows ودليل مشروع Visual Studio: HelloJNI

عند إنشاء المشروع، يُرسِل Visual Studio الإعدادات التالية إلى ملف build.gradle على مستوى التطبيق. يمكنك تغيير هذه الإعدادات من خلال تعديل نصوص Gradle البرمجية لإنشاء التطبيق.

• MSBUILD_NDK_VERSION
• MSBUILD_MIN_SDK_VERSION
• MSBUILD_JNI_LIBS_SRC_DIR
• MSBUILD_ANDROID_OUTPUT_APK_NAME
• MSBUILD_ANDROID_GRADLE_BUILD_OUTPUT_DIR

لإعداد العيّنة وتشغيلها:

عرض / إخفاء التعليمات

1. في Visual Studio، افتح نموذج HelloJNI وأنشئ تطبيقًا منه.
2. أضِف نظامًا أساسيًا Android arm64-v8a. لمزيد من المعلومات، يُرجى الاطّلاع على إضافة نظام Android الأساسي.
3. أضِف عنصر حزمة APK لنظام التشغيل Android إلى المنصة الجديدة.
4. اجمع المشروع.
5. أضِف أنظمة Android الأساسية التالية ثم أضِف عنصر APK لنظام Android إلى كل منها: Android-armeabi-v7a، Android-x86، وAndroid-x86_64.
6. أنشئ العيّنة وشغِّلها.

Endless-Tunnel

نموذج Endless-Tunnel هو لعبة Android يجمع فيها اللاعب طوبًا أبيضًا أثناء محاولته الوصول إلى نهاية نفق. تم نقله من ملف برمجي نموذجي لـ OpenGL في مستودع Android NDK على GitHub. لا يقدّم العيّنة إصدارًا من اللعبة متوافقًا مع نظام التشغيل Windows.

تم ضبط إعدادات النموذج وأنظمة التشغيل Android، لذا يمكنك إنشاء المشروع وتشغيله في Visual Studio بدون أي تعديلات. عند فتح الحلّ، يعرض مستكشف الحلول الوحدات التالية:

• endless-tunnel: وحدة التطبيق التي تعرِض منطق اللعبة
• glm: لقطة لمستودع OpenGL Math الذي تم إنشاؤه كمكتبة ثابتة.
• native_app_glue: حزمة تغليف NDK تتواصل مع ملف برمجي NativeActivity.

إبريق شاي

يعرض نموذج Teapot إبريق شاي كلاسيكيًا يتم عرضه باستخدام OpenGL ES ويتم نقله إلى "إضافة تطوير الألعاب" لنظام التشغيل Android لعرض الميزات التالية:

• تطوير المشاريع على جميع الأنظمة الأساسية: يمكنك إنشاء نموذج Teapot لنظامَي التشغيل Windows وAndroid.
• استخدام حِزم Android المخصّصة: تم نقل نصوص Gradle البرمجية لإنشاء الحِزم إلى directory‎ root للنموذج، حيث يقع ملف Teapot.sln.
• إعدادات Android المخصّصة التي توضّح كيفية استخدام أداة فحص العناوين (ASan) و أداة فحص عناوين الأجهزة (HWASan)

ينقسم تنفيذ نموذج Teapot إلى أجزاء متعددة، وهو ما هو معتاد في التطبيقات والألعاب الكبيرة المتوافقة مع جميع المنصات:

• GameApplication الوحدة: تحدِّد إجراءات المستخدم وحالات التطبيق، مثل مستخدم يدير إبريق الشاي أو يعدّل إحصاءات التطبيق.
• وحدة GameEngine: تُنفِّذ وحدة العرض الأساسية.

لإعداد العيّنة وتشغيلها على Android، راجِع البدء السريع. لإعداد العيّنة وتشغيلها على نظام التشغيل Windows:

عرض / إخفاء التعليمات

1. ثبِّت GLEW:
   1. نزِّل حزمة GLEW وألغِ ضغطها.
   2. انسخ الملفات الثنائية من $your-glew-directory\bin\Release\x64 إلى %SystemRoot%\system32.
2. ثبِّت مكتبة freeglut:
   1. نزِّل حزمة freeglut وألغِ ضغطها.
   2. انسخ $your-freeglut-directory\bin\x86\freeglut.dll إلى %SystemRoot%\system32.
3. أضِف تبعيات مشروع freeglut:
   1. افتح Teapot.sln في Visual Studio.
   2. في القائمة، انقر على تصحيح الأخطاء > x64 > محلل أخطاء Windows المحلي.
   3. في مستكشف الحلول، انقر بزر الماوس الأيمن على GameApplication واختَر الخصائص > C/C++ > عام > أدلة تضمين إضافية.
   4. أضِف $your-freeglut-dir\include إلى المسار.
      
   5. انقر على حسنًا.
   6. اختَر الرابط > عام > أدلة المكتبات الإضافية.
   7. أضِف $your-freeglut-dir\lib\x64 إلى المسار.
   8. انقر على حسنًا.
   9. اختَر الرابط > عام > أدلة المكتبة الإضافية.
   10. أضِف freeglut.lib إلى المسار.
   11. انقر على حسنًا.
4. أضِف تبعيات مشروع GLEW:
   1. في لوحة مستكشف الحلول، انقر بزر الماوس الأيمن على GameApplication واختَر الخصائص > C/C++ > عام > أدلة تضمين إضافية.
   2. أضِف $your-glew-dir\include إلى المسار.
   3. انقر على حسنًا.
   4. اختَر الرابط > عام > أدلة المكتبات الإضافية.
   5. أضِف $your-glew-dir\lib\Release\x86 إلى المسار.
   6. انقر على حسنًا.
   7. اختَر الرابط > عام > أدلة المكتبات الإضافية.
   8. أضِف glew32.lib إلى المسار.
   9. انقر على حسنًا.
5. تشغيل العيّنة على نظام التشغيل Windows:
   1. في شريط أدوات Visual Studio، انقر على زر تشغيل محلل أخطاء Windows المحلي.
   2. من المفترض أن يظهر العيّنة على النحو التالي:
      

AssemblyCode-Link-Objects

هذا مشروع نموذج يوضّح كيفية إنشاء مكتبة برمجية أصلية لنظام التشغيل Android من رمز المصدر لرمز التجميع وC/C++. في ما يلي المكونات الرئيسية:

• ‫AssemblyCode-Link-Objects: المكتبة الأساسية لنظام التشغيل Android والتي تم إنشاؤها من رمز مصدر C++ ورمز مصدر التجميع
• StaticLib: مكتبة ثابتة مساعدة تُصدِّر الدالة from_static_lib_assembly_code_as.

يتيح المشروع استخدام تصاميم متعددة. لكل بنية متوافقة ملفاتها المصدر الخاصة بها التي تنفِّذ الدوال التي يتم تصديرها من StaticLib. يجب تضمين ملفات مصدر التجميع للأنظمة الأساسية التي يتم إنشاؤها فقط. يتضمّن هذا المشروع ملفات تجميع في عمليات الإنشاء باستخدام أدوات إنشاء مخصّصة.

لإعداد العيّنة وإنشائها:

عرض / إخفاء التعليمات

1. في Visual Studio، تأكَّد من ضبط أدوات الإنشاء المخصّصة لملفّات الربط:
   1. في مستكشف الحلول، انقر بزر الماوس الأيمن علىملف التجمع ثم انقر على الخصائص. يؤدي ذلك إلى فتح مربع الحوار صفحات الخصائص للملف.
   2. اختَر الإعداد والنظام الأساسي، مثل جميع الإعدادات لملف APK الذي يحمل العلامة Android-arm64-v8a.
   3. تأكَّد من ضبط الإعدادات العامة > الاستبعاد من الإصدار على لا.
   4. تأكَّد من ضبط الإعدادات العامة > نوع العنصر على أداة إنشاء مخصّصة.
   5. انقر على تطبيق إذا كانت هناك تغييرات مطلوب تطبيقها.
   6. تأكَّد من أنّه تم ضبط القيمة التالية في خصائص الإعدادات > أدوات الإنشاء المخصّصة > سطر الأوامر: $(AsToolExe) -o "$(IntDir)%(FileName).o" %(FullPath). يتضمّن NDK أداة تجميع منفصلة لكل بنية وحدة معالجة مركزية، ويقوم $(AsToolExe) بربطها بأداة التجميع الصحيحة. يستخدم هذا المثال سلسلة أدوات NDK لإنشاء مشاريع Android لكل من x86 وx86_64. إذا كنت تريد استخدام yasm لنظام Android الأساسي x86_64، استخدِم $(YasmToolExe) بدلاً من ذلك.
   7. تأكَّد من أنّه تم ضبط القيمة $(IntDir)%(FileName).o في خصائص الإعداد > أدوات الإنشاء المخصّصة > النتائج: يجب تضمين هذه السلسلة في إعداد سطر الأوامر.
   8. تأكَّد من أنّه تم ضبط القيمة التالية في خصائص الضبط > أدوات التصميم المخصّصة > ربط العناصر: Yes.

   على سبيل المثال، يجب أن تبدو إعدادات Android-arm64-v8a مشابهة لقطة الشاشة التالية:

   
2. أنشئ المشروع. يؤدي ذلك إلى إنشاءملف libAssmeblyCodeLinkObjects.so:
   1. افتح ملف AssemblyCode-Link-Objects.sln.
   2. في القائمة، انقر على إنشاء > إنشاء حلّ.
3. للتأكّد من تصدير الدوالّ بشكلٍ صحيح إلى مكتبة Android ، استخدِم أداة nm.exe NDK:
   1. في سطر الأوامر، انتقِل إلى دليل النماذج.
   2. انتقِل إلى موقع مكتبة Android الذي تم إنشاؤه من خلال عملية الإصدار. الموقع التلقائي مشابه لملف $sample_dir\$solution_configuration\$solution_platform\$platform و$sample_dir\Debug\Android-arm64-v8a\arm64-v8a لنظام التشغيل arm64-v8a.
   3. تأكَّد من أنّ قسم الرموز المصدَّرة يحتوي على الدوالّ من خلال تنفيذ الأمر التالي:

        …\ndk\toolschains\llvm\prebuilt\windows-x86_64\aarch64-linux-android\bin\nm.exe --defined-only …\Debug\Android-arm64-v8a\arm64-v8a\libAssmeblyCodeLinkObjects.so

      في الإخراج، من المفترض أن تظهر لك قائمة بالرموز التي تتضمّن التالي:

         T from_shared_object_assembly_code_as
         T from_static_lib_assembly_code_as

PoolAllocator

نموذج PoolAllocator هو تطبيق Android يحتوي على منظِّم ملف ذاكرة يستند إلى حزمة يقدّم وحدات بحجم ثابت بكفاءة عالية.

يخصّص المخصّص الذاكرة بالكامل مسبقًا في وقت الإعداد باستخدام mmap. يتم تتبُّع الوحدات المجانية باستخدام قائمة مرتبطة. بعد ذلك، فإنّ عملية تخصيص الذاكرة هي عملية O(1) سريعة تُعرِض رأس القائمة المرتبطة، وعملية إلغاء التخصيص هي أيضًا عملية O(1) لأنّها تضيف الكتلة إلى الجزء الخلفي من القائمة المرتبطة.

يتضمّن العيّنة إعدادَين لحلّ استخدام HWASan.

• HWASan: يوضّح هذا الإعداد أبسط نهج لاستخدام HWASan مع أدوات تخصيص الذاكرة المخصّصة. تم استبدال التنفيذ الداخلي لموزّع الذاكرة بمكالمات malloc/free التي يتم تتبُّعها تلقائيًا من خلال HWASan. على الرغم من أنّ أداة تخصيص الذاكرة لم تعُد تعمل بصفتها أداة تخصيص مستندة إلى ملف ذاكرة، لا يزال بإمكان أداة HWASan مساعدتك في تحديد أخطاء الذاكرة المهمة، مثل استخدام ذاكرة معيّنة بعد تفريغها.

• HWASan-Advanced: توضِّح هذه الإعدادات كيفية دمج HWASan بالكامل في أداة تخصيص ذاكرة مخصّصة بدون تغيير آلية تخصيص المساحة الأصلية التي تستخدمها أداة التخصيص. ويستخدم طرق وضع العلامات في HWASan لوضع علامات على وحدات الذاكرة في المجموعة المخصّصة مسبقًا، ويُقرب حجم الوحدة إلى الحد الأدنى لحجم الوحدة المطلوب من خلال HWASan، ويعيد ضبط العلامات عند إعادة وحدات الذاكرة إلى المجموعة.

استخدِم الإعداد HWASan لأنّه أبسط ويمكن أن يساعدك في تحديد الأخطاء الشائعة في الذاكرة. استكشِف تنفيذ إعدادات HWASan-Advanced إذا كنت تريد فهم آلية عمل HWASan أو الحفاظ على الدلالات الداخلية لموزّع الذاكرة أثناء استخدام HWASan.