Plugin mesin VkQuality Unity

Plugin VkQuality untuk mesin Unity memberikan rekomendasi waktu peluncuran API grafis—Vulkan atau OpenGL ES—untuk digunakan bagi game Anda di perangkat tertentu.

VkQuality merekomendasikan Vulkan di kumpulan perangkat yang lebih terbatas daripada daftar yang diizinkan default mesin Unity. Gunakan VkQuality untuk mendapatkan manfaat performa Vulkan sekaligus membatasi penggunaan Vulkan ke perangkat yang lebih baru dengan driver grafis yang lebih baru, yang membatasi eksposur game Anda terhadap masalah driver. VkQuality hanya memberikan rekomendasi kualitas, bukan jaminan, karena masih mungkin menemukan masalah driver pada perangkat yang direkomendasikan. VkQuality mendukung daftar kustom, yang memberi Anda kemampuan untuk menambahkan atau menghapus rekomendasi perangkat untuk game.

Catatan: VkQuality selalu merekomendasikan OpenGL ES pada perangkat lama yang menjalankan Android 9.0 (API level 28) atau yang lebih rendah atau tidak mendukung setidaknya versi 1.1 Vulkan API. VkQuality menampilkan nilai enum RECOMMENDATION_GLES_BECAUSE_OLD_DEVICE di perangkat ini.

Mengaktifkan Vulkan di game mesin Unity Anda

VkQuality mengharuskan game Anda mengaktifkan perender OpenGL ES dan Vulkan di setelan project Unity. Aktifkan perender dengan menggunakan opsi Auto Graphics API atau dengan menyetel API grafis secara manual.

Mendapatkan plugin VkQuality untuk mesin Unity

Download plugin VkQuality dari GitHub. Plugin ini kompatibel dengan Unity 2021 dan yang lebih baru. Gunakan LTS 2021 Unity atau yang lebih baru untuk mengaktifkan Vulkan di Android. Paket plugin berisi project contoh dasar yang menggunakan plugin untuk menyetel API grafis saat memulai, lalu menampilkan string yang disetel ke API grafis aktif perangkat.

Mengelola daftar rekomendasi VkQuality Vulkan

VkQuality menyertakan daftar rekomendasi default dari perangkat yang didukung. Untuk mengetahui informasi tentang penggunaan daftar rekomendasi kustom, lihat bagian Menggunakan daftar rekomendasi kustom.

Daftar rekomendasi mencakup tiga kategori:

• Daftar yang diizinkan perangkat Vulkan
• Daftar yang diizinkan untuk rekomendasi GPU
• Daftar tolak rekomendasi GPU

Kecocokan daftar yang diizinkan perangkat

VkQuality terlebih dahulu akan memeriksa apakah perangkat aktif disertakan dalam daftar yang diizinkan perangkat, dan apakah menjalankan versi Android minimum dan versi driver Vulkan yang ditentukan dalam daftar yang diizinkan untuk perangkat tersebut. Jika kriteria ini terpenuhi, VkQuality akan merekomendasikan Vulkan dengan menampilkan nilai enum RECOMMENDATION_VULKAN_BECAUSE_DEVICE_MATCH.

Jika perangkat berada dalam daftar yang diizinkan, tetapi menjalankan versi Android atau versi driver di bawah batas minimum yang ditentukan dalam daftar yang diizinkan, VkQuality akan merekomendasikan OpenGL ES dengan menampilkan RECOMMENDATION_GLES_BECAUSE_OLD_DRIVER.

Rekomendasi GPU cocok

Jika tidak ada kecocokan perangkat yang ditemukan dalam daftar yang diizinkan perangkat, VkQuality akan mengevaluasi model GPU dan versi driver terhadap daftar izin dan tolak rekomendasi GPU. Jika model GPU dan versi driver cocok dengan entri dalam daftar yang diizinkan rekomendasi GPU, VkQuality akan merekomendasikan Vulkan dengan menampilkan konstanta enum RECOMMENDATION_VULKAN_BECAUSE_PREDICTION_MATCH.

Jika model GPU dan versi driver cocok dengan entri dalam daftar tolak rekomendasi GPU, VkQuality akan merekomendasikan OpenGL ES dengan menampilkan RECOMMENDATION_GLES_BECAUSE_PREDICTION_MATCH.

Rekomendasi tanpa kecocokan

Jika tidak ada kecocokan yang ditemukan, VkQuality akan merekomendasikan Vulkan jika level API Android dari perangkat yang berjalan sama dengan atau lebih tinggi dari Future API level dalam daftar rekomendasi. Daftar rekomendasi default memiliki Future API level 36, yang berarti pada perangkat tidak cocok yang menjalankan API level 36 atau yang lebih tinggi, VkQuality akan menampilkan konstanta enum RECOMMENDATION_VULKAN_BECAUSE_FUTURE_ANDROID.

Jika tidak ada kecocokan yang ditemukan di daftar yang diizinkan perangkat atau daftar rekomendasi GPU, dan level API perangkat di bawah Future API level, VkQuality akan merekomendasikan OpenGL ES dengan menampilkan RECOMMENDATION_GLES_BECAUSE_NO_DEVICE_MATCH.

Menambahkan file arsip VkQuality ke project Anda

Plugin VkQuality adalah file VkQuality-1.x.x.aar yang berada di direktori Assets/Android/Plugins dari arsip paket yang didownload. Nomor versi file .aar sebenarnya cocok dengan nomor versi nama arsip paket. Untuk menginstal plugin, lakukan langkah-langkah berikut:

1. Salin file .aar ke direktori Assets/Android/Plugins project Anda. (Buat subdirektori Android dan Plugins yang diperlukan jika tidak ada.)

Gambar 1.File .aar VkQuality di direktori project yang diperlukan.

1. Pilih file plugin VkQuality-1.x.x dalam hierarki Project Unity untuk memunculkan Import Settings di panel Inspector. Pastikan platform Android dicentang.

Gambar 2. Setelan impor platform plugin VkQuality.

Menggunakan aktivitas kustom untuk memanggil VkQuality

Tidak seperti plugin mesin Unity standar, VkQuality harus dieksekusi untuk mendapatkan rekomendasi API grafis sebelum mesin Unity diinisialisasi. Anda kemudian menggunakan fitur argumen command line pemain Unity untuk menetapkan API grafis berdasarkan rekomendasi VkQuality. Di Android, meneruskan argumen command line mengharuskan penggantian perilaku default UnityPlayerActivity dengan membuat aktivitas kustom.

Jika game Anda sudah menggunakan aktivitas kustom, lihat bagian Menambahkan VkQuality ke aktivitas kustom yang ada. Untuk membuat aktivitas kustom baru untuk game Anda, lihat Menambahkan aktivitas kustom ke project Unity Anda, yang akan ditampilkan nanti.

Menambahkan aktivitas kustom ke project mesin Unity Anda

Contoh aktivitas kustom yang menggunakan VkQuality disertakan dalam paket plugin di Assets/Plugins/Android/VkQualityTestActivity.java. Untuk menyesuaikan file dan menggunakannya di game Anda, lakukan langkah-langkah berikut:

1. Salin file VkQualityTestActivity.java ke direktori Assets/Plugins/Android Anda.
2. Ganti namanya dengan nama yang sesuai untuk game Anda (misalnya, MyGameActivity.java).
3. Buka file di editor teks.
4. Ubah nama class dari VkQualityTestActivity menjadi nama yang Anda berikan pada file (misalnya, MyGameActivity.java).
5. Ubah nama paket dari com.google.android.games.VkQualityTest agar cocok dengan nilai kolom Package Name di kategori Player Unity Project Settings di bagian Other Settings (misalnya, com.mycompany.mygame).
6. Simpan dan tutup file tersebut.

Tambahkan file manifes kustom yang mereferensikan aktivitas kustom Anda, dan beri tahu Unity untuk menggunakan file manifes kustom Anda:

1. Salin file AndroidManifest.xml dari direktori Assets/Plugins/Android paket plugin ke direktori Asset/Plugins/Android project Anda.
2. Buka file di editor teks.
3. Ubah nilai setelan activity android:name dari com.google.android.games.VkQualityTest.VkQualityTestActivity menjadi nama paket dan aktivitas yang Anda gunakan di langkah sebelumnya (misalnya, com.mycompany.mygame.MyGameActivity).
4. Simpan dan tutup file tersebut.
5. Buka jendela setelan Unity, lalu pilih setelan Player. Luaskan bagian Publishing Settings, dan centang kotak Custom Main Manifest.

Gambar 3. Opsi Custom Main Manifest di setelan Player Unity.

Project Anda kini disiapkan untuk menggunakan aktivitas kustom yang memanggil VkQuality saat memulai dan memilih Vulkan atau OpenGL ES berdasarkan rekomendasi VkQuality.

Menambahkan VkQuality ke aktivitas kustom yang ada

Jika game Anda sudah memiliki aktivitas kustom yang menggantikan UnityPlayerActivity default, integrasikan rekomendasi VkQuality dengan menambahkan kode berikut:

Pertama, tambahkan pernyataan impor VkQuality ke daftar impor di bagian atas file aktivitas kustom:

Kotlin

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

Java

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

Selanjutnya, buat beberapa konstanta dalam isi class Activity untuk pilihan API grafis:

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;

Buat variabel untuk melacak pilihan API:

Kotlin

private var apiOverride = OVERRIDE_NONE

Java

private int apiOverride = OVERRIDE_NONE;

Tambahkan fungsi berikut ke class Activity Anda:

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

Panggil fungsi CheckVkQuality dari bagian atas fungsi penggantian onCreate() sebelum memanggil implementasi class dasar:

Kotlin

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

Java

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

Terakhir, tambahkan penggantian fungsi updateUnityCommandLineArguments() yang menggunakan nilai apiOverride untuk meneruskan argumen command line ke mesin Unity yang menentukan API grafis mana yang akan digunakan:

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

Aktivitas kustom Anda kini memanggil VkQuality saat startup dan memilih Vulkan atau OpenGL ES berdasarkan rekomendasi VkQuality.

Menggunakan daftar rekomendasi kustom

Tentukan file daftar rekomendasi kustom dengan meneruskan nama file yang berisi daftar tersebut ke StartVkQuality(), bukan meneruskan string kosong:

Kotlin

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

Java

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

VkQuality terlebih dahulu akan mencari file di direktori penyimpanan internal aplikasi Anda. Jika file tidak ada di penyimpanan internal, VkQuality akan mencoba memuat file dari aset app bundle Anda. Jika file tidak ada di kedua lokasi tersebut, VkQuality akan menampilkan nilai enum ERROR_MISSING_DATA_FILE.

Untuk membuat file daftar rekomendasi kustom, gunakan alat VkQuality List Editor yang ada di repositori GitHub. Dokumentasi untuk alat ini terdapat di README.

Catatan: Untuk menyertakan file daftar rekomendasi kustom dalam aset app bundle, ekspor daftar dari Editor Daftar VkQuality menggunakan opsi .aar library dan tempatkan file .aar yang diekspor di direktori Assets/Android/Plugins. Jika Anda menempatkannya langsung di dalam direktori Assets/Android/Plugins, Unity tidak menyertakan file .vkq. File tersebut harus dipaketkan dalam penampung library .aar. Ekstensi jenis file .vkq masih digunakan saat menentukan nama file untuk StartVkQuality().