افزونه موتور VkQuality Unity

افزونه VkQuality برای موتور Unity توصیه‌های زمان راه‌اندازی API گرافیکی - Vulkan یا OpenGL ES - را برای استفاده برای بازی خود در دستگاه‌های خاص ارائه می‌دهد.

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

Vulkan را در بازی موتور Unity خود فعال کنید

VkQuality نیاز دارد که بازی شما هر دو رندر OpenGL ES و Vulkan را در تنظیمات پروژه Unity فعال داشته باشد. با استفاده از گزینه Auto Graphics API یا با تنظیم دستی APIهای گرافیکی، رندرها را فعال کنید.

افزونه VkQuality را برای موتور Unity دریافت کنید

افزونه VkQuality را از GitHub دانلود کنید. این افزونه با Unity 2021 و بالاتر سازگار است. برای فعال کردن Vulkan در اندروید از Unity 2021 LTS یا بالاتر استفاده کنید. بسته پلاگین شامل یک پروژه نمونه اولیه است که از پلاگین برای تنظیم API گرافیکی در هنگام راه‌اندازی استفاده می‌کند و سپس مجموعه رشته‌ای را به API گرافیکی فعال دستگاه نمایش می‌دهد.

لیست توصیه های VkQuality Vulkan را مدیریت کنید

VkQuality شامل یک لیست توصیه پیش فرض از دستگاه های پشتیبانی شده است. برای اطلاعات در مورد استفاده از لیست توصیه های سفارشی، به بخش استفاده از لیست توصیه های سفارشی مراجعه کنید.

لیست توصیه ها شامل سه دسته است:

  • لیست مجاز دستگاه Vulkan
  • لیست مجاز توصیه های GPU
  • لیست رد توصیه GPU

دستگاه مجاز فهرست مطابقت دارد

VkQuality ابتدا بررسی می‌کند که آیا دستگاه فعال در لیست مجاز دستگاه گنجانده شده است و آیا حداقل نسخه Android و نسخه درایور Vulkan مشخص شده در لیست مجاز برای آن دستگاه را اجرا می‌کند یا خیر. اگر این معیارها برآورده شوند، VkQuality Vulkan را با برگرداندن مقدار enum RECOMMENDATION_VULKAN_BECAUSE_DEVICE_MATCH توصیه می کند.

اگر دستگاه در لیست مجاز است، اما نسخه Android یا نسخه درایور آن کمتر از حداقل تعیین شده برای آن در لیست مجاز است، VkQuality با بازگرداندن RECOMMENDATION_GLES_BECAUSE_OLD_DRIVER OpenGL ES را توصیه می‌کند.

پیشنهاد GPU مطابقت دارد

اگر هیچ دستگاه مطابقی در لیست مجاز دستگاه یافت نشد، VkQuality مدل GPU و نسخه درایور را بر اساس توصیه GPU لیست های مجاز و رد می کند. اگر مدل GPU و نسخه درایور با یک ورودی در لیست مجاز توصیه‌های GPU مطابقت داشته باشند، VkQuality Vulkan را با برگرداندن ثابت enum RECOMMENDATION_VULKAN_BECAUSE_PREDICTION_MATCH توصیه می‌کند.

اگر مدل GPU و نسخه درایور با ورودی لیست رد توصیه های GPU مطابقت داشته باشند، VkQuality با بازگرداندن RECOMMENDATION_GLES_BECAUSE_PREDICTION_MATCH OpenGL ES را توصیه می کند.

توصیه های بدون مسابقه

اگر هیچ منطبقی یافت نشد، VkQuality Vulkan را توصیه می‌کند اگر سطح Android API دستگاه در حال اجرا برابر یا بالاتر از سطح Future API در لیست توصیه‌ها باشد. لیست توصیه‌های پیش‌فرض دارای سطح Future API 36 است، به این معنی که در دستگاه‌های بی‌همتا که سطح API 36 یا بالاتر دارند، VkQuality مقدار ثابت RECOMMENDATION_VULKAN_BECAUSE_FUTURE_ANDROID را برمی‌گرداند.

اگر هیچ منطبقی در لیست مجوزهای دستگاه یا لیست‌های توصیه‌های GPU یافت نشد و سطح API دستگاه کمتر از سطح Future API باشد، VkQuality با بازگرداندن RECOMMENDATION_GLES_BECAUSE_NO_DEVICE_MATCH OpenGL ES را توصیه می‌کند.

فایل آرشیو VkQuality را به پروژه خود اضافه کنید

افزونه VkQuality فایل VkQuality-1.xxaar است که در فهرست Assets/Android/Plugins آرشیو بسته دانلود شده قرار دارد. شماره نسخه واقعی فایل .aar با شماره نسخه نام بایگانی بسته مطابقت دارد. برای نصب افزونه مراحل زیر را انجام دهید:

  1. فایل .aar را در فهرست Assets/Android/Plugins پروژه خود کپی کنید. (در صورت عدم وجود زیرشاخه های Android و Plugins مورد نیاز را ایجاد کنید.)
فایل VkQuality .aar در دایرکتوری پروژه مورد نیاز.
شکل 1. فایل VkQuality .aar در دایرکتوری پروژه مورد نیاز.
  1. فایل پلاگین VkQuality-1.xx را در سلسله مراتب پروژه Unity انتخاب کنید تا تنظیمات واردات آن در پنجره Inspector ظاهر شود. مطمئن شوید که پلتفرم اندروید بررسی شده است.
شکل 2. تنظیمات واردات پلت فرم پلاگین VkQuality.
شکل 2. تنظیمات واردات پلت فرم پلاگین VkQuality.

از یک فعالیت سفارشی برای فراخوانی VkQuality استفاده کنید

برخلاف پلاگین‌های معمولی موتور Unity، VkQuality باید برای دریافت یک توصیه API گرافیکی قبل از راه‌اندازی موتور Unity اجرا شود. سپس از ویژگی آرگومان های خط فرمان Unity player برای تنظیم API گرافیکی بر اساس توصیه VkQuality استفاده می کنید. در اندروید، ارسال آرگومان های خط فرمان مستلزم نادیده گرفتن رفتار پیش فرض UnityPlayerActivity با ایجاد یک فعالیت سفارشی است .

اگر بازی شما از قبل از یک فعالیت سفارشی استفاده می‌کند، به بخش افزودن VkQuality به یک فعالیت سفارشی موجود مراجعه کنید. برای ایجاد یک فعالیت سفارشی جدید برای بازی خود، به افزودن یک فعالیت سفارشی به پروژه یونیتی خود مراجعه کنید، که در ادامه آمده است.

یک فعالیت سفارشی به پروژه موتور Unity خود اضافه کنید

یک نمونه فعالیت سفارشی که از VkQuality استفاده می کند در بسته افزونه در Assets/Plugins/Android/VkQualityTestActivity.java گنجانده شده است. برای سفارشی کردن فایل و استفاده از آن در بازی، مراحل زیر را انجام دهید:

  1. فایل VkQualityTestActivity.java را در فهرست Assets/Plugins/Android خود کپی کنید.
  2. نام آن را به چیزی مناسب برای بازی خود تغییر دهید (مثلاً MyGameActivity.java ).
  3. فایل را در یک ویرایشگر متن باز کنید.
  4. نام کلاس را از VkQualityTestActivity به نامی که به فایل دادید (به عنوان مثال MyGameActivity.java ) تغییر دهید.
  5. نام بسته را از com.google.android.games.VkQualityTest تغییر دهید تا با مقدار فیلد Package Name در دسته Unity Project Settings Player خود در بخش تنظیمات دیگر مطابقت داشته باشد (به عنوان مثال com.mycompany.mygame ).
  6. فایل را ذخیره کرده و ببندید.

یک فایل مانیفست سفارشی اضافه کنید که به فعالیت سفارشی شما اشاره می کند و به Unity بگویید از فایل مانیفست سفارشی شما استفاده کند:

  1. فایل AndroidManifest.xml را از فهرست Assets/Plugins/Android بسته افزونه در فهرست Asset/Plugins/Android پروژه خود کپی کنید.
  2. فایل را در یک ویرایشگر متن باز کنید.
  3. مقدار تنظیم activity android:name از com.google.android.games.VkQualityTest.VkQualityTestActivity به نام بسته و فعالیتی که در مراحل قبلی استفاده کردید (به عنوان مثال com.mycompany.mygame.MyGameActivity ) تغییر دهید.
  4. فایل را ذخیره کرده و ببندید.
  5. پنجره تنظیمات Unity را باز کنید و تنظیمات Player را انتخاب کنید. بخش تنظیمات انتشار را باز کنید و کادر مانیفست اصلی سفارشی را علامت بزنید.
شکل 3. گزینه Custom Main Manifest در تنظیمات Unity Player.
شکل 3. گزینه Custom Main Manifest در تنظیمات Unity Player .

پروژه شما اکنون برای استفاده از فعالیت سفارشی تنظیم شده است که VkQuality را هنگام راه اندازی فراخوانی می کند و Vulkan یا OpenGL ES را بر اساس توصیه VkQuality انتخاب می کند.

VkQuality را به یک فعالیت سفارشی موجود اضافه کنید

اگر بازی شما قبلاً یک فعالیت سفارشی دارد که UnityPlayerActivity پیش‌فرض را لغو می‌کند، توصیه‌های VkQuality را با افزودن کد زیر یکپارچه کنید:

ابتدا عبارت واردات VkQuality را به لیست واردات در بالای فایل فعالیت سفارشی اضافه کنید:

کاتلین 

import com.google.android.games.vkquality.VKQuality;

جاوا 

import com.google.android.games.vkquality.VKQuality;

در مرحله بعد، در بدنه کلاس Activity خود برای انتخاب های گرافیکی API ثابت ایجاد کنید:

کاتلین 

companion object {
  private const val OVERRIDE_NONE = 0
  private const val OVERRIDE_GLES = 1
  private const val OVERRIDE_VULKAN = 2

جاوا 

private static final int OVERRIDE_NONE = 0;
private static final int OVERRIDE_GLES = 1;
private static final int OVERRIDE_VULKAN = 2;

یک متغیر برای پیگیری انتخاب API ایجاد کنید:

کاتلین 

private var apiOverride = OVERRIDE_NONE

جاوا 

private int apiOverride = OVERRIDE_NONE;

تابع زیر را به کلاس Activity خود اضافه کنید:

کاتلین 

private fun CheckVkQuality() {
    val vkQuality = VKQuality(this)
    val startResult = vkQuality.StartVkQuality("")
    if (startResult == VKQuality.INIT_SUCCESS) {
        // In the current release, we can assume GetVkQuality is
        // ready as soon as StartVkQuality has returned success.
        val getResult = vkQuality.GetVkQuality()
        LogVkQualityResult(getResult)
        apiOverride =
            when (getResult) {
                VKQuality.RECOMMENDATION_VULKAN_BECAUSE_DEVICE_MATCH,
                VKQuality.RECOMMENDATION_VULKAN_BECAUSE_PREDICTION_MATCH,
                VKQuality.RECOMMENDATION_VULKAN_BECAUSE_FUTURE_ANDROID -> OVERRIDE_VULKAN
                VKQuality.RECOMMENDATION_GLES_BECAUSE_OLD_DEVICE,
                VKQuality.RECOMMENDATION_GLES_BECAUSE_OLD_DRIVER,
                VKQuality.RECOMMENDATION_GLES_BECAUSE_NO_DEVICE_MATCH,
                VKQuality.RECOMMENDATION_GLES_BECAUSE_PREDICTION_MATCH -> OVERRIDE_GLES
                else -> OVERRIDE_GLES
            }
        vkQuality.StopVkQuality()
    } else {
        Log.e("VKQUALITY", "VkQuality start failed with result: $startResult")
    }
}

جاوا 

private void CheckVkQuality() {
  VKQuality vkQuality = new VKQuality(this);
  // An empty string specifies use of the default
  // built-in device list file.
  int startResult = vkQuality.StartVkQuality("");
  if (startResult == VKQuality.INIT_SUCCESS) {
      // In the current release, we can assume GetVkQuality is
      // ready as soon as StartVkQuality has returned success.
      int getResult = vkQuality.GetVkQuality();

      switch (getResult) {
          case VKQuality.RECOMMENDATION_VULKAN_BECAUSE_DEVICE_MATCH:
          case VKQuality.RECOMMENDATION_VULKAN_BECAUSE_PREDICTION_MATCH:
          case VKQuality.RECOMMENDATION_VULKAN_BECAUSE_FUTURE_ANDROID:
              apiOverride = OVERRIDE_VULKAN;
              break;
          case VKQuality.RECOMMENDATION_GLES_BECAUSE_OLD_DEVICE:
          case VKQuality.RECOMMENDATION_GLES_BECAUSE_OLD_DRIVER:
          case VKQuality.RECOMMENDATION_GLES_BECAUSE_NO_DEVICE_MATCH:
          case VKQuality.RECOMMENDATION_GLES_BECAUSE_PREDICTION_MATCH:
          default:
              apiOverride = OVERRIDE_GLES;
              break;
      }
      vkQuality.StopVkQuality();
  } else {
      Log.e("VKQUALITY", "VkQuality start failed with result: " + startResult);
  }
}

قبل از فراخوانی اجرای کلاس پایه، تابع CheckVkQuality را از بالای یک تابع override onCreate() فراخوانی کنید:

کاتلین 

override fun onCreate(savedInstanceState: Bundle?) {
  CheckVkQuality()
  super.onCreate(savedInstanceState)
}

جاوا 

@Override
protected void onCreate(Bundle savedInstanceState) {
    CheckVkQuality();
    super.onCreate(savedInstanceState);
}

در نهایت، یک بازنویسی از تابع updateUnityCommandLineArguments() اضافه کنید که از مقدار apiOverride برای ارسال یک آرگومان خط فرمان به موتور Unity استفاده می کند که مشخص می کند از کدام API گرافیکی استفاده شود:

کاتلین 

override fun updateUnityCommandLineArguments(cmdLine: String): String {
  if (apiOverride == OVERRIDE_VULKAN) {
      Log.i("VKQUALITY", "Passing -force-vulkan")
      return appendCommandLineArgument(cmdLine, "-force-vulkan")
  } else if (apiOverride == OVERRIDE_GLES) {
      Log.i("VKQUALITY", "Passing -force-gles")
      return appendCommandLineArgument(cmdLine, "-force-gles")
  }
  Log.i("VKQUALITY", "No override passed")
  // let Unity pick the Graphics API based on PlayerSettings
  return cmdLine
}

private fun appendCommandLineArgument(cmdLine: String, arg: String?): String {
    return if (arg == null || arg.isEmpty()) cmdLine
    else if (cmdLine == null || cmdLine.isEmpty()) arg else "$cmdLine $arg"
}

جاوا 

@Override protected String updateUnityCommandLineArguments(String cmdLine)
{
    if (apiOverride == OVERRIDE_VULKAN) {
        Log.i("VKQUALITY", "Passing -force-vulkan");
        return appendCommandLineArgument(cmdLine, "-force-vulkan");
    }
    else if (apiOverride == OVERRIDE_GLES) {
        Log.i("VKQUALITY", "Passing -force-gles");
        return appendCommandLineArgument(cmdLine, "-force-gles");
    }
    Log.i("VKQUALITY", "No override passed");
    // let Unity pick the Graphics API based on PlayerSettings
    return cmdLine;
}

private String appendCommandLineArgument(String cmdLine, String arg) {
    if (arg == null || arg.isEmpty())
        return cmdLine;
    else if (cmdLine == null || cmdLine.isEmpty())
        return arg;
    else
        return cmdLine + " " + arg;
}

فعالیت سفارشی شما اکنون در هنگام راه اندازی VkQuality را فراخوانی می کند و Vulkan یا OpenGL ES را بر اساس توصیه VkQuality انتخاب می کند.

از یک لیست توصیه های سفارشی استفاده کنید

یک فایل لیست توصیه سفارشی را با ارسال نام فایل حاوی لیست به StartVkQuality() به جای ارسال یک رشته خالی مشخص کنید:

کاتلین 

val startResult = vkQuality.StartVkQuality("CUSTOM_FILE_NAME.vkq")

جاوا 

int startResult = vkQuality.StartVkQuality("CUSTOM_FILE_NAME.vkq");

VkQuality ابتدا فایل را در دایرکتوری حافظه داخلی برنامه شما جستجو می کند. اگر فایل در حافظه داخلی نیست، VkQuality سعی می کند فایل را از دارایی های بسته برنامه شما بارگیری کند. اگر فایل در هیچ یک از مکان‌ها نباشد، VkQuality مقدار enum ERROR_MISSING_DATA_FILE را برمی‌گرداند.

برای ایجاد یک فایل لیست توصیه سفارشی، از ابزار ویرایشگر فهرست VkQuality واقع در مخزن GitHub استفاده کنید. اسناد این ابزار در README آن قرار دارد.