نمونه

نمونه‌های «افزونه توسعه بازی 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 به دایرکتوری ریشه نمونه منتقل شدند، جایی که فایل 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. در منو، روی Debug > x64 > Local Windows Debugger کلیک کنید.
    3. در Solution Explorer، روی GameApplication کلیک راست کنید و Properties > C/C++ > General > Additional Include Directories را انتخاب کنید.
    4. ‫$your-freeglut-dir\include را به مسیر اضافه کنید.
      کادر گفتگوی صفحه ویژگی Visual Studio Additional Include Directories.
    5. روی Ok (تأیید) کلیک کنید.
    6. Linker > General > Additional Library Directories را انتخاب کنید.
    7. ‫$your-freeglut-dir\lib\x64 را به مسیر اضافه کنید. کادر گفتگوی صفحه ویژگی Visual Studio Additional Library Directories.
    8. روی Ok (تأیید) کلیک کنید.
    9. Linker > General > Additional Library Directories را انتخاب کنید.
    10. ‫freeglut.lib را به مسیر اضافه کنید.
    11. روی Ok (تأیید) کلیک کنید.
  4. افزودن وابستگی‌های پروژه GLEW:
    1. در پانل Solution Explorer، روی GameApplication کلیک راست کنید و Properties > C/C++ > General > Additional Include Directories را انتخاب کنید.
    2. ‫$your-glew-dir\include را به مسیر اضافه کنید.
    3. روی Ok (تأیید) کلیک کنید.
    4. Linker > General > Additional Library Directories را انتخاب کنید.
    5. ‫$your-glew-dir\lib\Release\x86 را به مسیر اضافه کنید.
    6. روی Ok (تأیید) کلیک کنید.
    7. Linker > General > Additional Library Directories را انتخاب کنید.
    8. ‫glew32.lib را به مسیر اضافه کنید.
    9. روی Ok (تأیید) کلیک کنید.
  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 کلیک کنید. با این کار، کادر گفتگوی صفحه‌های ویژگی‌ها برای فایل باز می‌شود.
    2. پیکربندی و پلاتفرم را انتخاب کنید، مثلاً همه پیکربندی‌ها برای Android-arm64-v8a.
    3. مطمئن شوید General (عمومی) > Exclude from Build (مستثنی کردن از ساخت) روی No (نه) تنظیم شده باشد.
    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. مطمئن شوید که Configuration Properties > Custom Build Tools > Outputs: روی $(IntDir)%(FileName).o تنظیم شده باشد. این رشته باید در تنظیم خط فرمان گنجانده شود.
    8. مطمئن شوید که Configuration Properties > Custom Build Tools > Link Objects: روی Yes تنظیم شده باشد.

    برای مثال، تنظیمات Android-arm64-v8a باید شبیه به نماگرفت زیر باشد:

    کادر گفتگوی Visual Studio Property Pages برای Custom Build Tools.
  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 آشنا شوید یا می‌خواهید معناشناسی داخلی تخصیص‌دهنده حافظه را هنگام استفاده از HWASan حفظ کنید، پیاده‌سازی پیکربندی HWASan-Advanced را کاوش کنید.