Complemento del motor VkQuality para Unity

El complemento VkQuality para el motor Unity proporciona recomendaciones de tiempo de lanzamiento de la API de gráficos (OpenGL ES o Vulkan) para usarla en tu juego en conjuntos dispositivos.

VkQuality recomienda Vulkan en un conjunto de dispositivos más restringido que Unity en la lista de entidades permitidas predeterminada de tu motor. Usa VkQuality para obtener los beneficios de rendimiento de Vulkan, al mismo tiempo que limita el uso de Vulkan a dispositivos más nuevos con gráficos más nuevos de usuarios, lo que limita la exposición del juego a problemas de controladores. Solo VkQuality hace recomendaciones de calidad, no garantías, ya que es posible encontrar problemas de controladores en los dispositivos recomendados. VkQuality admite listas personalizadas, que te permite agregar o quitar recomendaciones de dispositivos para tu el juego.

Nota: VkQuality siempre recomienda OpenGL ES en dispositivos más antiguos que ejecutan Android 9.0 (nivel de API 28) o versiones anteriores, o no admite al menos la versión 1.1 de Vulkan en la API de Cloud. VkQuality devuelve el valor enum RECOMMENDATION_GLES_BECAUSE_OLD_DEVICE en estos dispositivos.

Cómo habilitar Vulkan en tu juego de motor de Unity

VkQuality requiere que el juego tenga tanto los procesadores OpenGL ES como Vulkan en la configuración del proyecto de Unity. Habilita los procesadores mediante la opción Auto API de gráficos o mediante la configuración manual de las APIs de gráficos.

Cómo obtener el complemento VkQuality para el motor de Unity

Descarga el complemento VkQuality desde GitHub. El complemento es compatible con Unity 2021 y versiones posteriores. Usa Unity 2021 LTS o una versión posterior para habilitar Vulkan en Android El paquete del complemento contiene un proyecto de muestra básico que usa el complemento para configurar la API de gráficos al inicio y, luego, muestra una cadena configurada en la API de gráficos activos del dispositivo.

Administra la lista de recomendaciones de VkQuality para Vulkan

VkQuality incluye una lista de recomendaciones predeterminadas de dispositivos compatibles. Para Para obtener más información sobre cómo utilizar una lista de recomendaciones personalizadas, consulta el artículo Cómo utilizar una lista de recomendaciones lista de recomendaciones.

La lista de recomendaciones incluye tres categorías:

• Lista de dispositivos permitidos de Vulkan
• Lista de entidades permitidas para recomendaciones de GPU
• Lista de entidades denegadas de recomendaciones de GPU

Coincidencias de la lista de dispositivos permitidos

VkQuality verifica primero si el dispositivo activo está incluido en el dispositivo y si ejecuta la versión mínima de Android y el controlador de Vulkan versión especificada en la lista de entidades permitidas de ese dispositivo. Si se cumplen estos criterios, VkQuality recomienda Vulkan devolviendo el Valor de enumeración RECOMMENDATION_VULKAN_BECAUSE_DEVICE_MATCH.

Si el dispositivo está en la lista de permitidos, pero ejecuta una versión o un controlador de Android inferior al mínimo especificado en la lista de entidades permitidas, VkQuality recomienda OpenGL ES mostrando RECOMMENDATION_GLES_BECAUSE_OLD_DRIVER.

Coincidencias de recomendaciones de GPU

Si no se encuentra una coincidencia de dispositivo en la lista de dispositivos permitidos, VkQuality evalúa el Permitir y rechazar el modelo de GPU y la versión del controlador según la recomendación de GPU listas. Si el modelo de la GPU y la versión del controlador coinciden con una entrada en la GPU lista de recomendaciones permitidas, VkQuality recomienda Vulkan devolviendo el Es la constante enum RECOMMENDATION_VULKAN_BECAUSE_PREDICTION_MATCH.

Si el modelo de la GPU y la versión del controlador coinciden con una entrada en la GPU. en la lista de denegación de recomendaciones, VkQuality recomienda OpenGL ES RECOMMENDATION_GLES_BECAUSE_PREDICTION_MATCH

Recomendaciones sin coincidencias

Si no se encuentran coincidencias, VkQuality recomienda Vulkan si el nivel de API de Android de el dispositivo en ejecución sea igual o superior al nivel de Future API en el lista de recomendaciones. La lista de recomendaciones predeterminadas tiene el nivel Future API de 36, lo que significa que, en dispositivos sin coincidencias con el nivel de API 36 o superior, VkQuality muestra la constante enum RECOMMENDATION_VULKAN_BECAUSE_FUTURE_ANDROID.

Si no se encuentran coincidencias en la lista de dispositivos permitidos o en las listas de recomendaciones de GPU, haz lo siguiente: y el nivel de API del dispositivo es inferior al nivel de API futuro, VkQuality recomienda OpenGL ES mostrando RECOMMENDATION_GLES_BECAUSE_NO_DEVICE_MATCH.

Agrega el archivo VkQuality a tu proyecto.

El complemento VkQuality es el archivo VkQuality-1.x.x.aar ubicado en el Directorio Assets/Android/Plugins del archivo del paquete descargado. El estado el número de versión del archivo .aar coincide con el número de versión del paquete el nombre del archivo. Para instalar el complemento, sigue estos pasos:

1. Copia el archivo .aar en el directorio Assets/Android/Plugins de tu en un proyecto final. (Crea los subdirectorios Android y Plugins necesarios si existen).

Figura 1: Archivo .aar VkQuality en el directorio de proyecto requerido.

1. Selecciona el archivo del complemento VkQuality-1.x.x en la jerarquía del proyecto de Unity. para que aparezca Import Settings en el panel Inspector. Asegúrate de que las La plataforma Android está marcada.

Figura 2: Configuración de importación de la plataforma del complemento VkQuality.

Cómo usar una actividad personalizada para llamar a VkQuality

A diferencia de los complementos típicos del motor de Unity, se debe ejecutar VkQuality para obtener un recomendación de la API de Graphics antes de que se inicialice el motor Unity. Luego, utilizas Usa la función de argumentos de línea de comandos del reproductor de Unity para establecer la API de Graphics según la recomendación VkQuality. En Android, pasar de la línea de comandos requiere anular el comportamiento predeterminado del UnityPlayerActivity mediante la creación de una actividad actividad.

Si tu juego ya usa una actividad personalizada, consulta el artículo Cómo agregar VkQuality a una personalizada existente. Para crear una nueva actividad personalizada para tus consulta Agrega una actividad personalizada a tu proyecto de Unity, que sigue a continuación.

Agrega una actividad personalizada a tu proyecto de motor de Unity

En el complemento, se incluye un ejemplo de actividad personalizada que usa VkQuality. paquete en Assets/Plugins/Android/VkQualityTestActivity.java. Para personalizar el archivo y usarlo en tu juego, sigue estos pasos:

1. Copia el archivo VkQualityTestActivity.java en tu Assets/Plugins/Android.
2. Cámbiale el nombre a uno adecuado para tu juego (por ejemplo, MyGameActivity.java).
3. Abre el archivo en un editor de texto.
4. Cambia el nombre de la clase de VkQualityTestActivity por el nombre que le diste a la clase. (por ejemplo, MyGameActivity.java).
5. Cambia el nombre del paquete de com.google.android.games.VkQualityTest a coincide con el valor del campo Package Name en la configuración del proyecto de Unity Player en Other Settings (por ejemplo, com.mycompany.mygame).
6. Guarda el archivo y ciérralo.

Agrega un archivo de manifiesto personalizado que haga referencia a tu actividad personalizada e indícale a Unity para usar tu archivo de manifiesto personalizado:

1. Copia el archivo AndroidManifest.xml de Assets/Plugins/Android. directorio del paquete de complementos en el Asset/Plugins/Android de tu proyecto. .
2. Abre el archivo en un editor de texto.
3. Cambia el valor del parámetro de configuración activity android:name de com.google.android.games.VkQualityTest.VkQualityTestActivity a la los nombres de paquetes y actividades que usaste en los pasos anteriores (por ejemplo, com.mycompany.mygame.MyGameActivity).
4. Guarda el archivo y ciérralo.
5. Abre la ventana de configuración de Unity y selecciona la configuración de Player. Expandir la sección Publishing Settings y marca el Custom Main Manifest. .

Figura 3: La opción Custom Main Manifest de la configuración de Player de Unity

Tu proyecto ahora está configurado para usar la actividad personalizada que llama a VkQuality en y elige Vulkan u OpenGL ES según la recomendación VkQuality.

Agrega VkQuality a una actividad personalizada existente

Si tu juego ya tiene una actividad personalizada que anula la configuración predeterminada UnityPlayerActivity, integra las recomendaciones de VkQuality agregando el elemento siguiente código:

Primero, agrega la sentencia de importación VkQuality a la lista de importaciones en la parte superior de el archivo de actividad personalizado:

Kotlin

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

Java

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

A continuación, crea algunas constantes en el cuerpo de tu clase Activity para el Opciones de API de gráficos:

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;

Crea una variable para realizar un seguimiento de la selección de la API:

Kotlin

private var apiOverride = OVERRIDE_NONE

Java

private int apiOverride = OVERRIDE_NONE;

Agrega la siguiente función a tu clase 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);
  }
}

Llama a la función CheckVkQuality desde la parte superior de una anulación onCreate(). antes de llamar a la implementación de la clase base:

Kotlin

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

Java

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

Por último, agrega una anulación de la función updateUnityCommandLineArguments() que usa el valor de apiOverride para pasar un argumento de la línea de comandos al Motor de Unity que especifica qué API de gráficos usar:

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

Tu actividad personalizada ahora llama a VkQuality al inicio y elige Vulkan u OpenGL. ES según la recomendación VkQuality.

Usa una lista de recomendaciones personalizadas

Para especificar un archivo de lista de recomendaciones personalizadas, pasa el nombre del archivo que contenga la lista a StartVkQuality() en lugar de pasar una cadena vacía:

Kotlin

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

Java

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

VkQuality primero busca el archivo en el almacenamiento interno de la aplicación . Si el archivo no se encuentra en el almacenamiento interno, VkQuality intentará cargar de los recursos del paquete de aplicación. Si el archivo no se encuentra en ninguna de las dos ubicaciones, VkQuality muestra el valor enum ERROR_MISSING_DATA_FILE.

Para crear un archivo de lista de recomendaciones personalizada, usa el Editor de listas de VkQuality. en el repositorio de GitHub. Documentación para el la herramienta se encuentra en su archivo README.

Nota: Para incluir un archivo de lista de recomendaciones personalizadas en los recursos de tu paquete de aplicación, Exporta la lista desde el Editor de listas de VkQuality con la biblioteca .aar. y coloca el archivo .aar exportado en la Assets/Android/Plugins . Unity no incluye el archivo .vkq si lo colocas directamente en Assets/Android/Plugins, debe incluirse en una biblioteca .aar. contenedor. La extensión de tipo de archivo .vkq se sigue usando cuando se especifica la nombre de archivo de StartVkQuality().