Плагин VkQuality для движка Unity

Плагин VkQuality для движка Unity предоставляет рекомендации по выбору графического API (Vulkan или OpenGL ES) для запуска игры на определенных устройствах.

VkQuality рекомендует Vulkan для меньшего количества устройств, чем белый список по умолчанию в движке Unity. Используйте VkQuality, чтобы повысить производительность за счет Vulkan, но ограничить его применение новыми устройствами с новыми графическими драйверами. Это позволит снизить вероятность возникновения проблем с драйверами в вашей игре. VkQuality только рекомендует настройки качества, но не гарантирует их, поскольку на рекомендованных устройствах все равно могут возникать проблемы с драйверами. VkQuality поддерживает пользовательские списки, что позволяет добавлять и удалять рекомендации устройств для игры.

Примечание. VkQuality всегда рекомендует OpenGL ES на старых устройствах с Android 9.0 (уровень API 28) или более ранней версией, а также на устройствах, которые не поддерживают Vulkan API версии 1.1 или более поздней. На таких устройствах VkQuality возвращает значение перечисления RECOMMENDATION_GLES_BECAUSE_OLD_DEVICE.

Как включить Vulkan в игре на движке Unity

Для работы VkQuality в настройках проекта Unity должны быть включены рендереры OpenGL ES и Vulkan. Включите средства визуализации, выбрав параметр Auto Graphics API (Автоматический выбор графического API) или вручную настроив графические API.

Как получить плагин VkQuality для движка Unity

Скачайте плагин VkQuality с сайта GitHub. Плагин совместим с Unity 2021 и более поздними версиями. Чтобы включить Vulkan на Android, используйте Unity 2021 LTS или более поздней версии. Пакет плагина содержит базовый пример проекта, в котором плагин используется для настройки графического API при запуске, а затем отображает строку, заданную для активного графического API устройства.

Как управлять списком рекомендаций 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, если уровень API Android на устройстве равен или выше уровня API Future в списке рекомендаций. В списке рекомендаций по умолчанию указан уровень API 36. Это значит, что на устройствах, не соответствующих требованиям, с уровнем API 36 или выше VkQuality возвращает константу перечисления RECOMMENDATION_VULKAN_BECAUSE_FUTURE_ANDROID.

Если совпадений в белом списке устройств или списках рекомендаций по графическим процессорам не найдено, а уровень API устройства ниже уровня 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 нет, создайте их.

Рисунок 1. Файл .aar VkQuality в нужном каталоге проекта.

1. Выберите файл плагина VkQuality-1.x.x в иерархии Project (Проект) в Unity, чтобы открыть его Import Settings (Настройки импорта) на панели Inspector (Инспектор). Убедитесь, что выбрана платформа Android.

Рисунок 2. Настройки импорта платформы плагина VkQuality.

Как вызвать VkQuality с помощью специального действия

В отличие от обычных плагинов движка Unity, VkQuality должен быть запущен для получения рекомендации по графическому API до инициализации движка Unity. Затем вы используете функцию аргументов командной строки проигрывателя Unity, чтобы настроить графический API на основе рекомендации VkQuality. Чтобы передавать аргументы командной строки на устройствах Android, необходимо переопределить режим работы по умолчанию для UnityPlayerActivity, создав специальное действие.

Если в вашей игре уже используется пользовательское действие, ознакомьтесь с разделом Как добавить VkQuality в существующее пользовательское действие. Чтобы создать новый объект activity для игры, следуйте инструкциям в разделе Как добавить объект activity в проект 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 (категория Player (Проигрыватель), раздел Other Settings (Другие настройки), например 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. Разверните раздел Publishing Settings (Настройки публикации) и установите флажок Custom Main Manifest (Собственный основной манифест).

Рисунок 3. Параметр Custom Main Manifest (Пользовательский основной манифест) в настройках Player (Проигрыватель) в 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 несколько констант для выбора графического API:

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;

Создайте переменную для отслеживания выбора API:

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, указывающий, какой графический API использовать:

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 пытается загрузить его из объектов набора App Bundle. Если файла нет ни в одном из этих мест, VkQuality возвращает значение перечисления ERROR_MISSING_DATA_FILE.

Чтобы создать собственный список рекомендаций, используйте инструмент VkQuality List Editor, который находится в репозитории GitHub. Документация по инструменту находится в файле README.

Примечание. Чтобы добавить файл со списком рекомендаций в ресурсы набора App Bundle, экспортируйте список из VkQuality List Editor с помощью параметра .aar library и поместите экспортированный файл .aar в каталог Assets/Android/Plugins. Unity не включает файл .vkq, если вы помещаете его непосредственно в каталог Assets/Android/Plugins. Он должен быть упакован в контейнер библиотеки .aar. Расширение .vkq по-прежнему используется при указании названия файла для StartVkQuality().