Plug-in del motore VkQualità Unity

Il plug-in VkQuality per il motore Unity fornisce suggerimenti sul momento del lancio dell'API grafica (Vulkan o OpenGL ES) da utilizzare per il tuo gioco su specifiche dispositivi mobili.

VkQuality consiglia Vulkan su un insieme di dispositivi più limitato rispetto a Unity nella lista consentita predefinita del motore di ricerca. Usa VkQuality per ottenere i vantaggi in termini di prestazioni Vulkan limitando l'uso di Vulkan ai dispositivi più recenti con grafiche più recenti i driver, il che limita l'esposizione del tuo gioco a problemi legati ai conducenti. Solo VkQuality offre consigli di qualità, non una garanzia, in quanto è comunque possibile riscontri problemi con il conducente sui dispositivi consigliati. VkQuality supporta elenchi personalizzati, che ti consente di aggiungere o rimuovere consigli sui dispositivi per il tuo per giocare.

Attivare Vulkan nel gioco del motore Unity

VkQuality richiede che il gioco abbia entrambi i renderer OpenGL ES e Vulkan nelle impostazioni del progetto Unity. Abilita i renderer utilizzando il metodo Automatico Graphics API o impostando manualmente le API grafiche.

Ottieni il plug-in VkQuality per il motore Unity

Scarica il plug-in VkQuality da GitHub. Il plug-in è compatibile con Unity 2021 e versioni successive. Utilizza Unity 2021 LTS o versioni successive per attivare Vulkan su Android. Il pacchetto del plug-in contiene un progetto di esempio di base che utilizza il plug-in per impostare l'API grafica all'avvio, quindi visualizza una stringa impostata su all'API grafica attiva del dispositivo.

Gestire l'elenco di suggerimenti di VkQuality Vulkan

VkQuality include un elenco predefinito di dispositivi supportati. Per informazioni sull'utilizzo di un elenco di consigli personalizzato, consulta la sezione Utilizzare un elenco dei consigli.

L'elenco di consigli include tre categorie:

• Lista consentita dei dispositivi Vulkan
• Lista consentita dei suggerimenti per le GPU
• Elenco valori bloccati per i suggerimenti GPU

Corrispondenze della lista consentita del dispositivo

VkQuality verifica innanzitutto se il dispositivo attivo è incluso nell'autorizzazione del dispositivo e se sul sistema sia installata la versione minima di Android e il driver Vulkan alla versione specificata nell'elenco di autorizzazioni per il dispositivo. Se questi criteri vengono soddisfatti, VkQuality consiglia Vulkan restituendo il valore Valore enum RECOMMENDATION_VULKAN_BECAUSE_DEVICE_MATCH.

Se il dispositivo è nella lista consentita, ma esegue una versione di Android o un driver inferiore al valore minimo specificato nell'elenco di elementi consentiti, VkQuality consiglia OpenGL ES restituendo RECOMMENDATION_GLES_BECAUSE_OLD_DRIVER.

Corrispondenze suggerimenti GPU

Se non viene trovata una corrispondenza tra dispositivi nell'elenco dei dispositivi consentiti, VkQuality valuta la Il modello GPU e la versione del driver, rispetto ai suggerimenti di GPU, consentono e negano elenchi. Se il modello GPU e la versione del driver corrispondono a una voce nella GPU nella lista consentita di suggerimenti, VkQuality consiglia Vulkan restituendo il valore Costante enum di RECOMMENDATION_VULKAN_BECAUSE_PREDICTION_MATCH.

Se il modello GPU e la versione del driver corrispondono a una voce nella GPU suggerimenti, VkQuality consiglia OpenGL ES restituisce RECOMMENDATION_GLES_BECAUSE_PREDICTION_MATCH.

Consigli senza corrispondenze

Se non vengono trovate corrispondenze, VkQuality consiglia Vulkan se il livello API Android di il dispositivo in esecuzione è uguale o superiore al livello API Future nella dall'elenco di consigli. L'elenco di suggerimenti predefinito ha un livello API Future di 36, vale a dire su dispositivi senza pari con livello API 36 o superiore, VkQuality restituisce la costante enum RECOMMENDATION_VULKAN_BECAUSE_FUTURE_ANDROID.

Se non vengono trovate corrispondenze nella lista consentita dei dispositivi o negli elenchi di consigli per le GPU, e il livello API del dispositivo è inferiore al livello API Future, VkQuality consiglia OpenGL ES restituendo RECOMMENDATION_GLES_BECAUSE_NO_DEVICE_MATCH.

Aggiungi il file di archivio VkQuality al tuo progetto

Il plug-in VkQuality è il file VkQuality-1.x.x.aar che si trova nella sezione Directory Assets/Android/Plugins dell'archivio dei pacchetti scaricato. L'effettivo il numero di versione del file .aar corrisponde a quello del pacchetto nome dell'archivio. Per installare il plug-in, procedi nel seguente modo:

1. Copia il file .aar nella directory Assets/Android/Plugins del tuo progetto. (Crea le sottodirectory Android e Plugins necessarie, se non esistono.

1. Seleziona il file del plug-in VkQuality-1.x.x nella gerarchia del progetto Unity per visualizzare le impostazioni di importazione nel riquadro Ispezione. Assicurati che La piattaforma Android sia selezionata.

Utilizzare un'attività personalizzata per chiamare VkQuality

A differenza dei tipici plug-in del motore Unity, VkQuality deve essere eseguito per ottenere un il suggerimento dell'API Graph prima dell'inizializzazione del motore Unity. Quindi utilizzi la funzionalità Argomenti della riga di comando del player Unity per impostare Graphic User Interface in base al suggerimento di VkQuality. Su Android, passare argomenti della riga di comando richiede di eseguire l'override del comportamento predefinito UnityPlayerActivity creando un'attività personalizzata attività.

Se il tuo gioco utilizza già un'attività personalizzata, consulta la sezione Aggiungere VkQuality a un sezione attività personalizzata esistente. Per creare una nuova attività personalizzata per il tuo consulta la sezione Aggiungere un'attività personalizzata al progetto Unity di seguito.

Aggiungere un'attività personalizzata al progetto del motore Unity

Un esempio di attività personalizzata che utilizza VkQuality è incluso nel plug-in pacchetto in Assets/Plugins/Android/VkQualityTestActivity.java. Per personalizzare il file e utilizzarlo nel tuo gioco, svolgi i seguenti passaggi:

1. Copia il file VkQualityTestActivity.java nel tuo Directory Assets/Plugins/Android.
2. Assegna un nome appropriato al tuo gioco (ad esempio, MyGameActivity.java).
3. Apri il file in un editor di testo.
4. Cambia il nome del corso da VkQualityTestActivity con il nome che hai assegnato alla (ad esempio MyGameActivity.java).
5. Cambia il nome del pacchetto da com.google.android.games.VkQualityTest a corrisponda al valore del campo Package Name (Nome pacchetto) nelle impostazioni del progetto Unity Categoria Player in Altre impostazioni (ad esempio, com.mycompany.mygame).
6. Salva e chiudi il file.

Aggiungi un file manifest personalizzato che faccia riferimento alla tua attività personalizzata e comunicalo a Unity per utilizzare il file manifest personalizzato:

1. Copia il file AndroidManifest.xml da Assets/Plugins/Android directory del pacchetto del plug-in nel file Asset/Plugins/Android del tuo progetto .
2. Apri il file in un editor di testo.
3. Modifica il valore dell'impostazione activity android:name da com.google.android.games.VkQualityTest.VkQualityTestActivity al i nomi di pacchetti e attività utilizzati nei passaggi precedenti (ad esempio, com.mycompany.mygame.MyGameActivity).
4. Salva e chiudi il file.
5. Apri la finestra delle impostazioni Unity e seleziona le impostazioni del Player. Espandi la sezione Impostazioni di pubblicazione e controlla il file manifest principale personalizzato casella di controllo.

Il tuo progetto è ora configurato per utilizzare l'attività personalizzata che chiama VkQuality su all'avvio e sceglie Vulkan o OpenGL ES in base al suggerimento di VkQuality.

Aggiungere VkQuality a un'attività personalizzata esistente

Se il tuo gioco ha già un'attività personalizzata che sostituisce l'attività predefinita UnityPlayerActivity, integra i suggerimenti di VkQuality aggiungendo il parametro codice seguente:

Innanzitutto, aggiungi l'istruzione di importazione VkQuality all'elenco delle importazioni nella parte superiore della il file dell'attività personalizzata:

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

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

Poi, crea alcune costanti nel corpo della classe Activity per scelte dell'API grafica:

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;

Crea una variabile per monitorare la selezione dell'API:

private var apiOverride = OVERRIDE_NONE

private int apiOverride = OVERRIDE_NONE;

Aggiungi la seguente funzione alla tua classe 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);
  }
}

Chiama la funzione CheckVkQuality dall'alto di un override onCreate() prima di chiamare l'implementazione della classe base:

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

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

Infine, aggiungi un override della funzione updateUnityCommandLineArguments() che utilizza il valore apiOverride per passare un argomento della riga di comando Motore Unity che specifica l'API grafica da utilizzare:

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

La tua attività personalizzata ora chiama VkQuality all'avvio e sceglie Vulkan o OpenGL ES in base al suggerimento di VkQuality.

Utilizzare un elenco di consigli personalizzato

Specifica un file di elenco di suggerimenti personalizzato passando il nome del file contenente l'elenco a StartVkQuality() anziché passare una stringa vuota:

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

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

VkQuality cerca innanzitutto il file nella memoria interna dell'applicazione . Se il file non è nella memoria interna, VkQuality tenta di caricare il file degli asset dell'app bundle. Se il file non si trova in nessuna delle due posizioni, VkQuality restituisce il valore enum ERROR_MISSING_DATA_FILE.

Per creare un file di elenco di suggerimenti personalizzato, utilizza l'editor dell'elenco VkQuality nel repository GitHub. Documentazione per si trova nel relativo file README.