VkQuality Unity-Engine-Plug-in

Das VkQuality-Plug-in für die Unity-Engine gibt Empfehlungen zur Startzeit der Graphics API (Vulkan oder OpenGL ES) für Ihr Spiel auf bestimmten Geräten.

VkQuality empfiehlt Vulkan auf einer Reihe von Geräten, die stärker eingeschränkt sind als die Standard-Zulassungsliste der Unity-Engine. Mit VkQuality profitierst du von den Leistungsvorteilen von Vulkan und kannst Vulkan auf neuere Geräte mit neueren Grafiktreibern beschränken. Dadurch wird die Anfälligkeit deines Spiels für Treiberprobleme eingeschränkt. VkQuality gibt nur Empfehlungen zur Qualität, keine Garantien, da auf empfohlenen Geräten weiterhin Treiberprobleme auftreten können. VkQuality unterstützt benutzerdefinierte Listen, mit denen Sie Geräteempfehlungen für Ihr Spiel hinzufügen oder entfernen können.

Hinweis :VkQuality empfiehlt immer OpenGL ES auf älteren Geräten, auf denen Android 9.0 (API-Level 28) oder niedriger ausgeführt wird oder die nicht mindestens Version 1.1 der Vulkan API unterstützen. VkQuality gibt für diese Geräte den enum-Wert RECOMMENDATION_GLES_BECAUSE_OLD_DEVICE zurück.

Vulkan in deinem Unity-Engine-Spiel aktivieren

Für VkQuality ist für Ihr Spiel sowohl der OpenGL ES- als auch der Vulkan-Renderer in den Unity-Projekteinstellungen aktiviert. Aktivieren Sie die Renderer mithilfe der Option Auto Graphics API oder durch manuelle Festlegung der Grafik-APIs.

VkQuality-Plug-in für Unity-Engine abrufen

Laden Sie das VkQuality-Plug-in von GitHub herunter. Das Plug-in ist mit Unity 2021 und höher kompatibel. Verwenden Sie Unity 2021 LTS oder höher, um Sense unter Android zu aktivieren. Das Plug-in-Paket enthält ein grundlegendes Beispielprojekt, das das Plug-in verwendet, um die Grafik-API beim Start festzulegen, und dann einen String anzeigt, der für die aktive Grafik-API des Geräts festgelegt ist.

Empfehlungsliste für VkQuality Vulkan verwalten

VkQuality enthält eine Standardliste mit Empfehlungen für unterstützte Geräte. Informationen zum Verwenden einer benutzerdefinierten Empfehlungsliste finden Sie im Abschnitt Benutzerdefinierte Empfehlungsliste verwenden.

Die Liste der Empfehlungen umfasst drei Kategorien:

• Zulassungsliste mit Vulkan-Geräten
• Zulassungsliste mit GPU-Empfehlungen
• Sperrliste für GPU-Empfehlungen

Übereinstimmende Geräte in der Zulassungsliste

VkQuality prüft zuerst, ob das aktive Gerät auf der Zulassungsliste für Geräte steht und ob die mindestens erforderliche Android- und Vulkan-Treiberversion ausgeführt wird, die in der Zulassungsliste für dieses Gerät angegeben sind. Wenn diese Kriterien erfüllt sind, empfiehlt VkQuality Vulkan und gibt den enum-Wert RECOMMENDATION_VULKAN_BECAUSE_DEVICE_MATCH zurück.

Wenn das Gerät auf der Zulassungsliste steht, aber eine Android-Version oder Treiberversion ausgeführt wird, die unter dem in der Zulassungsliste angegebenen Minimum liegt, empfiehlt VkQualityem OpenGL ES, indem RECOMMENDATION_GLES_BECAUSE_OLD_DRIVER zurückgegeben wird.

GPU-Empfehlung stimmt überein mit

Wenn auf der Zulassungsliste für Geräte keine Übereinstimmung gefunden wird, wertet VkQuality das GPU-Modell und die Treiberversion anhand der GPU-Empfehlungs- und Zulassungslisten aus. Wenn das GPU-Modell und die Treiberversion mit einem Eintrag in der Zulassungsliste der GPU-Empfehlungen übereinstimmen, empfiehlt VkQuality, Vulkan durch die Rückgabe der enum-Konstante RECOMMENDATION_VULKAN_BECAUSE_PREDICTION_MATCH zu empfehlen.

Wenn das GPU-Modell und die Treiberversion mit einem Eintrag in der Liste zum Ablehnen von GPU-Empfehlungen übereinstimmen, empfiehlt VkQuality die Verwendung von OpenGL ES durch Rückgabe von RECOMMENDATION_GLES_BECAUSE_PREDICTION_MATCH.

Empfehlungen ohne Übereinstimmung

Wenn keine Übereinstimmungen gefunden werden, empfiehlt VkQuality Vulkan, wenn das Android API-Level des laufenden Geräts dem Future API-Level in der Empfehlungsliste entspricht oder höher ist. Die standardmäßige Empfehlungsliste hat das Future API-Level 36. Das bedeutet, dass auf nicht übereinstimmenden Geräten mit API-Level 36 oder höher die enum-Konstante RECOMMENDATION_VULKAN_BECAUSE_FUTURE_ANDROID zurückgegeben wird.

Wenn in der Zulassungsliste für Geräte oder in den GPU-Empfehlungslisten keine Übereinstimmungen gefunden werden und das API-Level des Geräts unter dem Future API-Level liegt, empfiehlt VkQualityem OpenGL ES durch die Rückgabe von RECOMMENDATION_GLES_BECAUSE_NO_DEVICE_MATCH.

Fügen Sie Ihrem Projekt die VkQuality-Archivdatei hinzu

Das VkQuality-Plug-in ist die Datei VkQuality-1.x.x.aar, die sich im Verzeichnis Assets/Android/Plugins des heruntergeladenen Paketarchivs befindet. Die tatsächliche Versionsnummer der AAR-Datei stimmt mit der Versionsnummer des Paketnamens des Pakets überein. Führen Sie die folgenden Schritte aus, um das Plug-in zu installieren:

1. Kopieren Sie die AAR-Datei in das Verzeichnis Assets/Android/Plugins Ihres Projekts. Erstellen Sie die erforderlichen Unterverzeichnisse Android und Plugins, falls sie noch nicht vorhanden sind.

Abbildung 1. Die VkQuality-AAR-Datei im erforderlichen Projektverzeichnis

1. Wählen Sie in der Unity-Projekthierarchie die Plug-in-Datei VkQuality-1.x.x aus, um die zugehörigen Importeinstellungen im Bereich Inspector aufzurufen. Achten Sie darauf, dass die Android-Plattform aktiviert ist.

Abbildung 2. Die Plattformimporteinstellungen für das VkQuality-Plug-in

Benutzerdefinierte Aktivität zum Aufrufen von VkQuality verwenden

Im Gegensatz zu typischen Unity-Engine-Plug-ins muss VkQuality ausgeführt werden, um eine Grafik-API-Empfehlung zu erhalten, bevor die Unity-Engine initialisiert wird. Anschließend verwenden Sie die Funktion Unity-Player-Befehlszeilenargumente, um die Grafik-API basierend auf der VkQuality-Empfehlung festzulegen. Unter Android muss für die Übergabe von Befehlszeilenargumenten das Standardverhalten von UnityPlayerActivity überschrieben werden, indem eine benutzerdefinierte Aktivität erstellt wird.

Wenn Ihr Spiel bereits eine benutzerdefinierte Aktivität verwendet, lesen Sie den Abschnitt VkQuality zu einer vorhandenen benutzerdefinierten Aktivität hinzufügen. Wie Sie eine neue benutzerdefinierte Aktivität für Ihr Spiel erstellen, erfahren Sie im Abschnitt Benutzerdefinierte Aktivität zu Ihrem Unity-Projekt hinzufügen.

Dem Unity-Engine-Projekt eine benutzerdefinierte Aktivität hinzufügen

Das Plug-in-Paket in Assets/Plugins/Android/VkQualityTestActivity.java enthält ein Beispiel für eine benutzerdefinierte Aktivität, die VkQuality verwendet. So passen Sie die Datei an und verwenden sie in Ihrem Spiel:

1. Kopieren Sie die Datei VkQualityTestActivity.java in das Verzeichnis Assets/Plugins/Android.
2. Geben Sie dem Namen einen für Ihr Spiel geeigneten Namen, z. B. MyGameActivity.java.
3. Öffnen Sie die Datei in einem Texteditor.
4. Ändern Sie den Klassennamen von VkQualityTestActivity in den Namen, den Sie der Datei gegeben haben (z. B. MyGameActivity.java).
5. Ändern Sie den Paketnamen von com.google.android.games.VkQualityTest so, dass er mit dem Wert im Feld Paketname in der Kategorie Player der Unity-Projekteinstellungen unter Weitere Einstellungen übereinstimmt, z. B. com.mycompany.mygame.
6. Speichern und schließen Sie die Datei.

Fügen Sie eine benutzerdefinierte Manifestdatei hinzu, die auf Ihre benutzerdefinierte Aktivität verweist, und weisen Sie Unity an, diese zu verwenden:

1. Kopieren Sie die Datei AndroidManifest.xml aus dem Verzeichnis Assets/Plugins/Android des Plug-in-Pakets in das Verzeichnis Asset/Plugins/Android Ihres Projekts.
2. Öffnen Sie die Datei in einem Texteditor.
3. Ändern Sie den Wert der Einstellung activity android:name von com.google.android.games.VkQualityTest.VkQualityTestActivity in die Paket- und Aktivitätsnamen, die Sie in den vorherigen Schritten verwendet haben (z. B. com.mycompany.mygame.MyGameActivity).
4. Speichern und schließen Sie die Datei.
5. Öffnen Sie das Unity-Einstellungsfenster und wählen Sie die Player-Einstellungen aus. Maximieren Sie den Bereich Veröffentlichungseinstellungen und klicken Sie das Kästchen Benutzerdefiniertes Hauptmanifest an.

Abbildung 3. Die Option Custom Main Manifest in den Unity-Player-Einstellungen.

Ihr Projekt ist jetzt so eingerichtet, dass die benutzerdefinierte Aktivität verwendet wird, die beim Start VkQuality aufruft und Vulkan oder OpenGL ES basierend auf der VkQuality-Empfehlung auswählt.

VkQuality zu einer vorhandenen benutzerdefinierten Aktivität hinzufügen

Wenn Ihr Spiel bereits eine benutzerdefinierte Aktivität hat, die den standardmäßigen UnityPlayerActivity überschreibt, integrieren Sie die VkQuality-Empfehlungen, indem Sie den folgenden Code hinzufügen:

Fügen Sie zuerst die VkQuality-Importanweisung zur Liste der Importe oben in der Datei der benutzerdefinierten Aktivität hinzu:

Kotlin

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

Java

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

Erstellen Sie als Nächstes im Textkörper Ihrer Activity-Klasse einige Konstanten für die Auswahl der APIs für die Grafik-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;

Erstellen Sie eine Variable, um die API-Auswahl zu verfolgen:

Kotlin

private var apiOverride = OVERRIDE_NONE

Java

private int apiOverride = OVERRIDE_NONE;

Fügen Sie der Klasse Activity die folgende Funktion hinzu:

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

Rufen Sie die Funktion CheckVkQuality über die Überschreibungsfunktion onCreate() auf, bevor Sie die Basisklassenimplementierung aufrufen:

Kotlin

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

Java

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

Fügen Sie schließlich eine Überschreibung der Funktion updateUnityCommandLineArguments() hinzu, die den Wert von apiOverride verwendet, um ein Befehlszeilenargument an die Uneinheitlichkeit zu übergeben und festzulegen, welche Grafik-API verwendet werden soll:

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

Ihre benutzerdefinierte Aktivität ruft jetzt beim Start VkQuality auf und wählt Vulkan oder OpenGL ES basierend auf der VkQuality-Empfehlung aus.

Benutzerdefinierte Empfehlungsliste verwenden

Geben Sie eine benutzerdefinierte Empfehlungslistendatei an. Übergeben Sie dazu den Namen der Datei, die die Liste enthält, an StartVkQuality(), anstatt einen leeren String zu übergeben:

Kotlin

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

Java

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

VkQuality sucht zuerst im internen Speicherverzeichnis Ihrer Anwendung nach der Datei. Wenn sich die Datei nicht im internen Speicher befindet, versucht VkQuality, die Datei aus den Assets Ihres App Bundles zu laden. Wenn sich die Datei nicht an einem der beiden Speicherorte befindet, gibt VkQuality den enum-Wert ERROR_MISSING_DATA_FILE zurück.

Mit dem Tool VkQuality List Editor im GitHub-Repository können Sie eine benutzerdefinierte Datei mit einer Empfehlungsliste erstellen. Die Dokumentation zum Tool finden Sie in der Readme-Datei.

Hinweis :Wenn Sie Ihren App-Bundle-Assets eine benutzerdefinierte Empfehlungsliste hinzufügen möchten, exportieren Sie die Liste mithilfe der Option .aar library aus dem VkQuality-Listen-Editor und speichern Sie die exportierte .aar-Datei im Verzeichnis Assets/Android/Plugins. Die Datei .vkq ist in Unity nicht enthalten. Wenn Sie sie direkt im Verzeichnis Assets/Android/Plugins ablegen, muss sie in einem .aar-Bibliothekscontainer gebündelt sein. Beim Angeben des Dateinamens für StartVkQuality() wird weiterhin die Dateiendung .vkq verwendet.