المكوّن الإضافي لمحرك Vkquality Unity

يوفّر المكوّن الإضافي VkQuality الخاص بمحرك Unity اقتراحات بشأن وقت بدء تشغيل واجهة برمجة التطبيقات للرسومات، مثل Vulkan أو OpenGL ES، لاستخدامها في لعبتك على أجهزة معيّنة.

توصي Vkالجودة بـ Vulkan على مجموعة أجهزة أكثر تقييدًا من قائمة السماح التلقائية لمحرّك Unity. استخدِم VkQuality للاستفادة من مزايا أداء Vulkan مع قصر استخدام Vulkan على أجهزة أحدث ومزودة ببرامج تشغيل أحدث للرسومات، ما يحدّ من تعرّض لعبتك لمشاكل السائق. تقدّم خدمة VkQuality توصيات الجودة فقط، وليس كضمانات، إذ لا يزال من الممكن مواجهة مشاكل السائق على الأجهزة المقترَحة. تدعم VkQuality القوائم المخصّصة التي تتيح لك إضافة اقتراحات للأجهزة أو إزالتها للعبتك.

تفعيل Vulkan في لعبة Unity Engine

تتطلّب خدمة VkQuality أن يتم تفعيل كل من عارضَي OpenGL ES وVulkan في لعبتك في إعدادات مشروع Unity. يمكنك تفعيل برامج العرض باستخدام الخيار Auto Graphics API أو من خلال إعداد واجهات برمجة تطبيقات الرسومات يدويًا.

الحصول على المكوّن الإضافي VkQuality في محرِّك Unity

نزِّل المكوّن الإضافي VkQuality من GitHub. يتوافق المكوّن الإضافي مع Unity 2021 والإصدارات الأحدث. يمكنك استخدام Unity 2021 LTS أو الإصدارات الأحدث لتفعيل Vulkan على نظام Android. تحتوي حزمة المكونات الإضافية على نموذج مشروع أساسي يستخدم المكون الإضافي لضبط واجهة برمجة تطبيقات الرسومات عند بدء التشغيل ثم تعرض سلسلة مجموعة لواجهة برمجة تطبيقات الرسومات النشطة للجهاز.

إدارة قائمة الاقتراحات في VkQuality Vulkan

تشتمل خدمة VkQuality على قائمة اقتراحات تلقائية بالأجهزة المتوافقة. للحصول على معلومات بشأن استخدام قائمة اقتراحات مخصّصة، راجِع قسم استخدام قائمة اقتراحات مخصّصة.

تشمل قائمة الاقتراحات ثلاث فئات:

  • القائمة المسموح بها لأجهزة Vulkan
  • قائمة السماح باقتراحات وحدة معالجة الرسومات
  • قائمة رفض اقتراحات وحدة معالجة الرسومات

تطابق قائمة الأجهزة المسموح بها

تتحقق Vkquality أولاً مما إذا كان الجهاز النشط مضمّنًا في قائمة الأجهزة المسموح بها، وما إذا كان يعمل بالحد الأدنى من إصدار Android وإصدار برنامج تشغيل Vulkan المحدد في قائمة السماح لهذا الجهاز. في حال استيفاء هذه المعايير، تقترح VkQuality خوارزمية Vulkan من خلال عرض قيمة تعداد RECOMMENDATION_VULKAN_BECAUSE_DEVICE_MATCH.

إذا كان الجهاز مدرجًا في القائمة المسموح بها، ولكنّه يعمل بإصدار نظام التشغيل Android أو إصدار برنامج التشغيل أقل من الحد الأدنى المحدَّد له في قائمة السماح، يوصي VkQuality بـ OpenGL ES من خلال عرض RECOMMENDATION_GLES_BECAUSE_OLD_DRIVER.

مطابقات الاقتراحات بشأن وحدة معالجة الرسومات

إذا لم يتم العثور على أي جهاز مطابق في قائمة السماح للأجهزة، تقيّم VkQuality طراز وحدة معالجة الرسومات وإصدار برنامج التشغيل وفقًا لقوائم السماح والرفض المقترَحة من خلال وحدة معالجة الرسومات. إذا تطابق طراز وحدة معالجة الرسومات وإصدار برنامج التشغيل مع إدخال في قائمة الاقتراحات بشأن وحدة معالجة الرسومات، تقترح VkQuality استخدام Vulkan من خلال عرض ثابت التعداد RECOMMENDATION_VULKAN_BECAUSE_PREDICTION_MATCH.

في حال تطابق طراز وحدة معالجة الرسومات وإصدار برنامج التشغيل مع أحد الإدخالات في قائمة رفض اقتراحات وحدة معالجة الرسومات، تقترح أداة VkQuality استخدام OpenGL ES من خلال عرض الرمز RECOMMENDATION_GLES_BECAUSE_PREDICTION_MATCH.

الاقتراحات التي لا تتطابق مع المحتوى المطابق

في حال عدم العثور على أي نتائج مطابقة، تقترح VkQuality استخدام Vulkan إذا كان مستوى واجهة برمجة تطبيقات Android للجهاز قيد التشغيل مساويًا لمستوى واجهة برمجة التطبيقات المستقبلي في قائمة الاقتراحات أو أعلى منه. تحتوي قائمة الاقتراحات التلقائية على مستوى مستقبلي لواجهة برمجة التطبيقات يبلغ 36، ما يعني أنّه على الأجهزة غير المطابقة التي تعمل بالمستوى 36 أو أعلى من واجهة برمجة التطبيقات، تعرض واجهة برمجة التطبيقات VkQuality ثابت التعداد RECOMMENDATION_VULKAN_BECAUSE_FUTURE_ANDROID.

إذا لم يتم العثور على أي تطابقات في قائمة السماح للأجهزة أو قوائم اقتراحات وحدة معالجة الرسومات، وكان مستوى واجهة برمجة التطبيقات للجهاز أقل من مستوى واجهة برمجة التطبيقات Future API، تقترح أداة VkQuality OpenGL ES من خلال عرض رمز الاستجابة RECOMMENDATION_GLES_BECAUSE_NO_DEVICE_MATCH.

إضافة ملف أرشيف VkQuality إلى مشروعك

المكوّن الإضافي VkQuality هو ملف VkQuality-1.x.x.aar في الدليل Assets/Android/Plugins لأرشيف الحزم الذي تم تنزيله. يتطابق رقم الإصدار الفعلي لملف .aar مع رقم إصدار اسم أرشيف الحزمة. لتثبيت المكوّن الإضافي، قم بتنفيذ الخطوات التالية:

  1. انسخ ملف .aar إلى دليل Assets/Android/Plugins لمشروعك. (أنشئ الدليل الفرعي Android وPlugins المطلوبَين في حال عدم توفّرهما).
ملف Vkquality .aar في دليل المشروع المطلوب.
الشكل 1.ملف VkQuality .aar في دليل المشروع المطلوب.
  1. حدد ملف المكوّن الإضافي VkQuality-1.x.x في التسلسل الهرمي لمشروع Unity لإظهار إعدادات الاستيراد في جزء أداة الفحص. تأكّد من وضع علامة في المربّع نظام Android الأساسي.
الشكل 2. إعدادات استيراد النظام الأساسي للمكوّن الإضافي VkQuality
الشكل 2. إعدادات استيراد النظام الأساسي للمكوّن الإضافي VkQuality

استخدام نشاط مخصّص للاتصال بـ VkQuality

على عكس المكونات الإضافية النموذجية لمحرك Unity، يجب تنفيذ VkQuality للحصول على توصية واجهة برمجة التطبيقات للرسومات قبل إعداد محرك Unity. بعد ذلك، يمكنك استخدام ميزة وسيطات سطر الأوامر في مشغّل Unity لضبط واجهة برمجة التطبيقات للرسومات استنادًا إلى اقتراح VkQuality. على نظام التشغيل Android، يتطلب ضبط وسيطات سطر الأوامر تجاوز السلوك التلقائي UnityPlayerActivity من خلال إنشاء نشاط مخصّص.

إذا كانت لعبتك تستخدم نشاطًا مخصّصًا، اطّلِع على القسم إضافة VkQuality إلى نشاط مخصّص حالي. لإنشاء نشاط مخصص جديد للعبتك، راجع إضافة نشاط مخصص إلى مشروع Unity، والذي يليه.

إضافة نشاط مخصّص إلى مشروع محرّك 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. خيار البيان الرئيسي المخصّص في إعدادات Unity Player
الشكل 3: خيار البيان الرئيسي المخصّص في إعدادات مشغّل Unity.

تم إعداد مشروعك لاستخدام النشاط المخصّص الذي يستدعي VkQuality عند بدء التشغيل ويختار Vulkan أو OpenGL ES بناءً على توصية VkQuality.

إضافة VkQuality إلى نشاط مخصّص حالي

إذا كانت لعبتك تتضمّن نشاطًا مخصَّصًا يتجاوز الإعداد التلقائي UnityPlayerActivity، يمكنك دمج اقتراحات VkQuality من خلال إضافة الرمز التالي:

أولاً، أضف عبارة استيراد VkQuality إلى قائمة عمليات الاستيراد أعلى ملف النشاط المخصص:

Kotlin

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

Java

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

بعد ذلك، أنشِئ بعض الثوابت في نص فئة Activity الخاصة بخيارات واجهة برمجة التطبيقات للرسومات:

Kotlin

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

Java

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

أنشئ متغيّرًا لتتبّع اختيار واجهة برمجة التطبيقات:

Kotlin

private var apiOverride = OVERRIDE_NONE

Java

private int apiOverride = OVERRIDE_NONE;

أضِف الدالة التالية إلى فئة Activity:

Kotlin

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")
    }
}

Java

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 من أعلى دالة التجاوز onCreate() قبل استدعاء تنفيذ الفئة الأساسية:

Kotlin

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

Java

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

وأخيرًا، أضِف قيمة تجاوز الدالة updateUnityCommandLineArguments() التي تستخدم القيمة apiOverride لتمرير وسيطة سطر أوامر إلى Unity Engine لتحديد واجهة برمجة تطبيقات الرسومات المراد استخدامها:

Kotlin

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"
}

Java

@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() بدلاً من تمرير سلسلة فارغة:

Kotlin

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

Java

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

تبحث خدمة Vkquality أولاً عن الملف في دليل وحدة التخزين الداخلية لتطبيقك. إذا لم يكن الملف في وحدة التخزين الداخلية، ستحاول VkQuality تحميل الملف من أصول حزمة التطبيق. إذا لم يكن الملف في أي من الموقعين، فإن VkQuality تعرض قيمة التعداد ERROR_MISSING_DATA_FILE.

لإنشاء ملف قائمة اقتراحات مخصّص، استخدِم أداة Vkquality List Editor الموجودة في مستودع GitHub. توجد وثائق الأداة في README.