Wtyczka silnika VkQuality Unity

Wtyczka VkQuality do silnika Unity udostępnia zalecenia dotyczące czasu uruchomienia interfejsu graficznego API (Vulkan lub OpenGL ES), którego można używać w grze na konkretnych urządzeniach.

VkQuality zaleca interfejs Vulkan w bardziej ograniczonym zestawie urządzeń niż domyślna lista dozwolonych silnika Unity. Użyj Vk Quality, by wykorzystać zalety interfejsu Vulkan i ograniczyć korzystanie z Vulkana do nowszych urządzeń z nowszymi sterownikami graficznymi. To ograniczenie zmniejsza ryzyko problemów ze sterownikami w grze. Vkquality generuje tylko rekomendacje dotyczące jakości, a nie gwarantuje, ponieważ nadal mogą występować problemy ze sterownikami na zalecanych urządzeniach. Vkquality obsługuje listy niestandardowe, dzięki którym możesz dodawać i usuwać rekomendacje dotyczące urządzeń dla Twojej gry.

Włącz interfejs Vulkan w grze silnikowej na Unity

VkQuality wymaga, aby gra miała w ustawieniach projektu Unity włączone mechanizmy renderowania OpenGL ES i Vulkan. Włącz mechanizmy renderowania za pomocą opcji Auto Graphics API lub ręcznie ustawiając interfejsy graficzne API.

Pobierz wtyczkę VkQuality dla silnika Unity

Pobierz wtyczkę VkQuality z GitHuba. Wtyczka jest zgodna z Unity w wersji 2021 i nowszych. Aby włączyć interfejs Vulkan na Androidzie, użyj platformy Unity 2021 LTS lub nowszej. Pakiet wtyczek zawiera przykładowy projekt podstawowy, który za pomocą wtyczki ustawia interfejs Graphic API podczas uruchamiania, a potem wyświetla ciąg znaków odpowiadający aktywnemu interfejsowi graficznemu na urządzeniu.

Zarządzanie listą rekomendacji VkQuality Vulkan

VkQuality zawiera domyślną listę rekomendacji obsługiwanych urządzeń. Informacje o korzystaniu z niestandardowej listy rekomendacji znajdziesz w sekcji Używanie niestandardowej listy rekomendacji.

Lista rekomendacji zawiera 3 kategorie:

• Lista dozwolonych urządzeń Vulkan
• Lista dozwolonych rekomendacji GPU
• Lista odrzuconych rekomendacji GPU

Dopasowania do list dozwolonych urządzeń

Vkquality najpierw sprawdza, czy aktywne urządzenie znajduje się na liście dozwolonych urządzeń i czy działa na nim minimalna wersja Androida i wersja sterownika Vulkan określone na liście dozwolonych urządzeń. Jeśli te kryteria są spełnione, VkQuality zaleca interfejs Vulkan, zwracając wartość wyliczeniową RECOMMENDATION_VULKAN_BECAUSE_DEVICE_MATCH.

Jeśli urządzenie znajduje się na liście dozwolonych, ale ma wersję Androida lub sterownika poniżej minimalnej wartości określonej na liście dozwolonych, VkQuality zaleca standard OpenGL ES, zwracając wartość RECOMMENDATION_GLES_BECAUSE_OLD_DRIVER.

Dopasowania rekomendacji GPU

Jeśli na liście dozwolonych urządzeń nie zostanie znalezione żadne pasujące urządzenie, VkQuality ocenia model GPU i wersję sterownika pod kątem list dozwolonych i odrzuconych GPU. Jeśli model GPU i wersja sterownika pasują do wpisu na liście dozwolonych rekomendacji GPU, VkQuality zaleca interfejs Vulkan, zwracając stałą wyliczenie RECOMMENDATION_VULKAN_BECAUSE_PREDICTION_MATCH.

Jeśli model GPU i wersja sterownika są zgodne z wpisem na liście odrzuconych rekomendacji GPU, VkQuality zaleca tryb OpenGL ES, zwracając wartość RECOMMENDATION_GLES_BECAUSE_PREDICTION_MATCH.

Rekomendacje bez pasujących wyników

W przypadku braku dopasowań VkQuality zaleca interfejs Vulkan, jeśli poziom interfejsu Android API działającego urządzenia jest równy lub wyższy niż poziom interfejsu Future API na liście rekomendacji. Domyślna lista rekomendacji ma w przyszłości poziom interfejsu API wynoszący 36, co oznacza, że na niedopasowanych urządzeniach z interfejsem API na poziomie 36 lub wyższym VkQuality zwraca stałą wyliczenie RECOMMENDATION_VULKAN_BECAUSE_FUTURE_ANDROID.

Jeśli nie znaleziono dopasowań na liście dozwolonych urządzeń lub listach rekomendacji dotyczących GPU, a poziom interfejsu API urządzenia jest poniżej poziomu interfejsu Future API, VkQuality zaleca działanie OpenGL ES, zwracając wartość RECOMMENDATION_GLES_BECAUSE_NO_DEVICE_MATCH.

Dodaj do projektu plik archiwum VkQuality

Wtyczka VkQuality to plik VkQuality-1.x.x.aar znajdujący się w katalogu Assets/Android/Plugins w pobranym archiwum pakietów. Rzeczywista numer wersji pliku .aar odpowiada numerowi wersji nazwy archiwum pakietów. Aby zainstalować wtyczkę, wykonaj następujące czynności:

1. Skopiuj plik .aar do katalogu Assets/Android/Plugins swojego projektu. (Jeśli nie istnieją, utwórz potrzebne podkatalogi Android i Plugins).

1. Wybierz plik wtyczki VkQuality-1.x.x w hierarchii Projektu Unity, aby wyświetlić jego Ustawienia importowania w panelu Inspektor. Upewnij się, że platforma Android jest zaznaczona.

Używanie niestandardowej aktywności do wywoływania VkQuality

W przeciwieństwie do typowych wtyczek silnika Unity przed zainicjowaniem silnika Unity musi zostać wykonany kod VkQuality, by uzyskać rekomendację interfejsu API grafiki. Następnie za pomocą funkcji argumentów wiersza poleceń odtwarzacza Unity skonfiguruj interfejs API graficznego zgodnie z rekomendacją VkQuality. Na Androidzie przekazywanie argumentów wiersza poleceń wymaga zastąpienia domyślnego działania obiektu UnityPlayerActivity przez utworzenie aktywności niestandardowej.

Jeśli Twoja gra korzysta już z niestandardowej aktywności, zapoznaj się z sekcją Dodawanie funkcji VkQuality do istniejącej aktywności niestandardowej. Aby utworzyć nową niestandardową aktywność w grze, przeczytaj sekcję Dodawanie niestandardowej aktywności do projektu w Unity (patrz poniżej).

Dodawanie niestandardowego działania do projektu Unity

Przykład niestandardowej aktywności, która korzysta z parametru VkQuality, znajduje się w pakiecie wtyczki w komponencie Assets/Plugins/Android/VkQualityTestActivity.java. Aby dostosować plik i użyć go w grze, wykonaj te czynności:

1. Skopiuj plik VkQualityTestActivity.java do katalogu Assets/Plugins/Android.
2. Zmień nazwę na odpowiednią dla gry (np. MyGameActivity.java).
3. Otwórz plik w edytorze tekstu.
4. Zmień nazwę zajęć z VkQualityTestActivity na nazwę nadaną plikowi (np. MyGameActivity.java).
5. Zmień nazwę pakietu z com.google.android.games.VkQualityTest, by była zgodna z wartością w polu Nazwa pakietu w ustawieniach projektu w kategorii Odtwarzacz w sekcji Inne ustawienia (np. com.mycompany.mygame).
6. Zapisz i zamknij plik.

Dodaj niestandardowy plik manifestu, który odwołuje się do Twojej niestandardowej aktywności, i poproś Unity o użycie Twojego niestandardowego pliku manifestu:

1. Skopiuj plik AndroidManifest.xml z katalogu Assets/Plugins/Android pakietu wtyczki do katalogu Asset/Plugins/Android projektu.
2. Otwórz plik w edytorze tekstu.
3. Zmień wartość ustawienia activity android:name z com.google.android.games.VkQualityTest.VkQualityTestActivity na nazwy pakietu i aktywności użyte w poprzednich krokach (np. com.mycompany.mygame.MyGameActivity).
4. Zapisz i zamknij plik.
5. Otwórz okno ustawień Unity i wybierz ustawienia Odtwarzacza. Rozwiń sekcję Ustawienia publikowania i zaznacz pole wyboru Niestandardowy główny plik manifestu.

Twój projekt jest teraz skonfigurowany do używania niestandardowej aktywności, która podczas uruchamiania wywołuje funkcję VkQuality i wybiera Vulkan lub OpenGL ES na podstawie rekomendacji VkQuality.

Dodawanie wartości VkQuality do dotychczasowej aktywności niestandardowej

Jeśli Twoja gra ma już niestandardową aktywność, która zastępuje domyślną wartość UnityPlayerActivity, zintegruj rekomendacje VkQuality, dodając ten kod:

Najpierw dodaj instrukcję importu VkQuality do listy importów na górze pliku niestandardowej aktywności:

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

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

Następnie utwórz w treści klasy Activity kilka stałych opcji interfejsu graficznego:

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;

Utwórz zmienną do śledzenia wyboru interfejsu API:

private var apiOverride = OVERRIDE_NONE

private int apiOverride = OVERRIDE_NONE;

Dodaj do klasy Activity tę funkcję:

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

Wywołaj funkcję CheckVkQuality od góry funkcji zastępowania onCreate() przed wywołaniem implementacji klasy podstawowej:

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

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

Na koniec dodaj zastąpienie funkcji updateUnityCommandLineArguments(), która korzysta z wartości apiOverride, aby przekazać argument wiersza poleceń do silnika Unity, określając, którego interfejsu graficznego ma używać:

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

Twoja niestandardowa aktywność wywołuje teraz przy uruchamianiu VkQuality i wybiera Vulkan lub OpenGL ES na podstawie rekomendacji VkQuality.

Użyj niestandardowej listy rekomendacji

Aby określić niestandardowy plik z listą rekomendacji, zamiast pustego ciągu znaków przekaż do StartVkQuality() nazwę pliku zawierającego tę listę:

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

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

VkQuality najpierw szuka pliku w katalogu pamięci wewnętrznej Twojej aplikacji. Jeśli pliku nie ma w pamięci wewnętrznej, VkQuality spróbuje wczytać go z zasobów pakietu aplikacji. Jeśli pliku nie ma w żadnej z tych lokalizacji, VkQuality zwraca wartość wyliczenia ERROR_MISSING_DATA_FILE.

Aby utworzyć niestandardowy plik listy rekomendacji, użyj narzędzia VkQuality List Editor w repozytorium GitHub. Dokumentacja narzędzia znajduje się w pliku README.