نماذج

توضّح نماذج Android Game Development Extension كيفية استخدام الميزات الرئيسية للإضافة. يوضّح هذا المستند النماذج والإعدادات اللازمة لتشغيلها.

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

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

قبل البدء

  • ثبِّت Android Game Development Extension والنماذج. يمكنك الاطّلاع على دليل البدء السريع لمزيد من التفاصيل. ويوضّح الموضوع أيضًا كيفية إنشاء نموذج وتشغيله، ويستخدم إصدار 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 Game Development Extension لتوضيح الميزات التالية:

  • تطوير المشاريع على أنظمة أساسية متعددة: يمكنك إنشاء نموذج Teapot لنظامَي التشغيل Windows وAndroid.
  • استخدام حزمة Android المخصّصة: تم نقل النصوص البرمجية لإنشاء Gradle إلى الدليل الجذري للنموذج، حيث يوجد ملف Teapot.sln.
  • إعدادات Android المخصّصة التي توضّح كيفية استخدام Address Sanitizer (ASan) وHardware Address Sanitizer (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. في مستكشف الحلول (Solution Explorer)، انقر بزر الماوس الأيمن على GameApplication واختَر الخصائص (Properties) > C/C++ > عام (General) > أدلة تضمين إضافية (Additional Include Directories).
    4. أضِف $your-freeglut-dir\include إلى المسار.
      مربّع حوار صفحة خصائص "أدلة التضمين الإضافية" (Additional Include Directories) في Visual Studio
    5. انقر على حسنًا.
    6. اختَر Linker (الرابط) > General (عام) > Additional Library Directories (أدلة المكتبات الإضافية).
    7. أضِف $your-freeglut-dir\lib\x64 إلى المسار. مربّع حوار صفحة خصائص "أدلة المكتبات الإضافية" في Visual Studio
    8. انقر على حسنًا.
    9. اختَر Linker (الرابط) > General (عام) > Additional Library Directories (أدلة المكتبات الإضافية).
    10. أضِف freeglut.lib إلى المسار.
    11. انقر على حسنًا.
  4. أضِف تبعيات مشروع GLEW:
    1. في لوحة مستكشف الحلول، انقر بزر الماوس الأيمن على GameApplication واختَر الخصائص > C/C++‎ > عام > أدلة تضمين إضافية.
    2. أضِف $your-glew-dir\include إلى المسار.
    3. انقر على حسنًا.
    4. اختَر Linker (الرابط) > General (عام) > Additional Library Directories (أدلة المكتبات الإضافية).
    5. أضِف $your-glew-dir\lib\Release\x86 إلى المسار.
    6. انقر على حسنًا.
    7. اختَر Linker (الرابط) > General (عام) > Additional Library Directories (أدلة المكتبات الإضافية).
    8. أضِف glew32.lib إلى المسار.
    9. انقر على حسنًا.
  5. شغِّل النموذج على نظام التشغيل Windows:
    1. في شريط أدوات Visual Studio، انقر على زر التشغيل Local Windows Debugger.
    2. يجب أن يظهر النموذج على النحو التالي:
      تطبيق Teapot النموذجي قيد التشغيل في نافذة Windows

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

  • ‫AssemblyCode-Link-Objects: مكتبة Android الرئيسية المجمّعة من رموز برمجية أصلية والمصمَّمة من الرمز المصدر للغة C++‎ ولغة التجميع
  • ‫StaticLib: مكتبة ثابتة مساعِدة تصدِّر الدالة from_static_lib_assembly_code_as

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

لإعداد النموذج وإنشائه:

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

    على سبيل المثال، من المفترض أن تظهر إعدادات Android-arm64-v8a على النحو التالي:

    مربّع حوار Visual Studio Property Pages لأدوات الإنشاء المخصّصة
  2. أنشئ المشروع. يؤدي ذلك إلى إنشاء ملف libAssmeblyCodeLinkObjects.so:
    1. افتح ملف AssemblyCode-Link-Objects.sln.
    2. في القائمة، انقر على Build (إنشاء) > Build Solution (إنشاء حلّ).
  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 مساعدتك في تحديد أخطاء الذاكرة المهمة، مثل حالات استخدام ذاكرة معيّنة بعد تفريغها (use-after-free).

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

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