Plugin mesin VkQuality Unity

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

VkKualitas merekomendasikan Vulkan pada kumpulan perangkat yang lebih terbatas daripada Unity pada daftar default mesin telusur. Gunakan VkKualitas untuk mendapatkan manfaat performa Vulkan sekaligus membatasi penggunaan Vulkan ke perangkat yang lebih baru dengan grafis yang lebih baru {i>driver<i}, yang membatasi paparan game Anda terhadap masalah pengemudi. Khusus VkKualitas memberikan rekomendasi berkualitas, bukan jaminan, karena masih mungkin mengalami masalah {i>driver<i} pada perangkat yang direkomendasikan. VkKualitas mendukung daftar kustom, yang memberi Anda kemampuan untuk menambah atau menghapus rekomendasi perangkat untuk game.

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

Mengaktifkan Vulkan di game mesin Unity Anda

VkKualitas mengharuskan game Anda memiliki perender OpenGL ES dan Vulkan diaktifkan di setelan project Unity. Aktifkan perender dengan menggunakan tombol Otomatis Graphics API atau dengan menyetel secara manual API grafis.

Mendapatkan plugin VkKualitas untuk mesin Unity

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

Mengelola daftar rekomendasi Vulkan VkKualitas

VkKualitas menyertakan daftar rekomendasi default dari perangkat yang didukung. Sebagai informasi tentang penggunaan daftar rekomendasi khusus, lihat Menggunakan daftar rekomendasi.

Daftar rekomendasi mencakup tiga kategori:

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

Kecocokan daftar yang diizinkan perangkat

VkKualitas memeriksa terlebih dahulu apakah perangkat aktif termasuk dalam perangkat yang mengizinkan dan apakah menjalankan versi Android minimum dan driver Vulkan yang ditentukan dalam daftar yang diizinkan untuk perangkat tersebut. Jika kriteria-kriteria ini terpenuhi, VkKualitas merekomendasikan Vulkan dengan menampilkan Nilai enum RECOMMENDATION_VULKAN_BECAUSE_DEVICE_MATCH.

Jika perangkat ada dalam daftar yang diizinkan, tetapi menjalankan versi Android atau driver di bawah minimum yang ditentukan untuknya dalam daftar yang diizinkan, VkKualitas merekomendasikan OpenGL ES dengan menampilkan RECOMMENDATION_GLES_BECAUSE_OLD_DRIVER.

Kecocokan rekomendasi GPU

Jika tidak ditemukan kecocokan perangkat di daftar yang diizinkan perangkat, Vkquality akan mengevaluasi Model GPU dan versi driver terhadap rekomendasi GPU mengizinkan dan menolak daftar. Jika model GPU dan versi driver cocok dengan entri di GPU dari daftar rekomendasi yang diizinkan, Vkquality merekomendasikan Vulkan dengan menampilkan Konstanta enum RECOMMENDATION_VULKAN_BECAUSE_PREDICTION_MATCH.

Jika model GPU dan versi driver cocok dengan entri di GPU daftar penolakan rekomendasi, VkKualitas merekomendasikan OpenGL ES dengan menampilkan RECOMMENDATION_GLES_BECAUSE_PREDICTION_MATCH.

Rekomendasi tidak memiliki kecocokan

Jika tidak ditemukan kecocokan, VkKualitas akan merekomendasikan Vulkan jika level API Android perangkat yang berjalan sama dengan atau lebih tinggi dari Future API level di daftar rekomendasi. Daftar rekomendasi default memiliki Future API level sebesar 36, artinya pada perangkat tidak tertandingi yang menjalankan API level 36 atau yang lebih tinggi, VkKualitas menampilkan konstanta enum RECOMMENDATION_VULKAN_BECAUSE_FUTURE_ANDROID.

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

Menambahkan file arsip Vkquality ke project Anda

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

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

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

1. Memilih file plugin VkQuality-1.x.x di hierarki Project Unity untuk memunculkan Import Settings di panel Inspector. Pastikan atribut Platform Android dicentang.

Gambar 2. Setelan impor platform plugin Vkquality.

Menggunakan aktivitas kustom untuk memanggil VkKualitas

Tidak seperti plugin mesin Unity pada umumnya, VkKualitas harus dijalankan untuk mendapatkan rekomendasi API grafis sebelum mesin Unity diinisialisasi. Anda kemudian menggunakan fitur argumen command line pemain Unity untuk menyetel API grafis berdasarkan rekomendasi Vkquality. Di Android, meneruskan argumen command line mengharuskan penggantian perilaku default UnityPlayerActivity dengan membuat instance aktivitas Anda.

Jika game Anda sudah menggunakan aktivitas khusus, lihat Tambahkan VkKualitas ke bagian aktivitas kustom yang ada. Untuk membuat aktivitas khusus baru bagi lihat Menambahkan aktivitas kustom ke project Unity, yang mengikuti berikut ini.

Menambahkan aktivitas kustom ke project mesin Unity Anda

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

1. Salin file VkQualityTestActivity.java ke Direktori Assets/Plugins/Android.
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 (misalnya, MyGameActivity.java).
5. Ubah nama paket dari com.google.android.games.VkQualityTest menjadi cocokkan dengan nilai kolom Package Name di Setelan Project Unity Anda Kategori Player di bagian Other Settings (misalnya, com.mycompany.mygame).
6. Simpan dan tutup file tersebut.

Menambahkan file manifes kustom yang merujuk pada aktivitas kustom Anda, dan memberi tahu Unity untuk menggunakan file manifes kustom:

1. Salin file AndroidManifest.xml dari Assets/Plugins/Android direktori paket plugin ke dalam Asset/Plugins/Android project Anda saat ini.
2. Buka file di editor teks.
3. Ubah nilai setelan activity android:name dari com.google.android.games.VkQualityTest.VkQualityTestActivity ke 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 dan pilih setelan Player. Luaskan bagian Setelan Publikasi, lalu periksa Manifes Utama Kustom .

Gambar 3. Opsi Manifes Utama Kustom di setelan Player Unity.

Proyek Anda sekarang siap untuk menggunakan aktivitas khusus yang memanggil VkKualitas di 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 aktivitas default UnityPlayerActivity, integrasikan rekomendasi VkKualitas dengan menambahkan kode berikut:

Pertama, tambahkan pernyataan impor VkKualitas ke daftar impor di bagian atas file aktivitas khusus:

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

Memanggil fungsi CheckVkQuality dari bagian atas 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 menetapkan API grafis 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 sekarang memanggil VkKualitas saat memulai dan memilih Vulkan atau OpenGL ES berdasarkan rekomendasi Vkquality.

Menggunakan daftar rekomendasi kustom

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

Kotlin

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

Java

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

VkKualitas akan mencari file di penyimpanan internal aplikasi terlebih dahulu saat ini. Jika file tidak ada di penyimpanan internal, VkKualitas akan mencoba memuat dari aset app bundle Anda. Jika file itu tidak ada di salah satu lokasi, VkKualitas menampilkan nilai enum ERROR_MISSING_DATA_FILE.

Untuk membuat file daftar rekomendasi kustom, gunakan Vkquality List Editor yang terletak di repositori GitHub. Dokumentasi untuk file ini terletak di README.

Catatan: Untuk menyertakan file daftar rekomendasi kustom di aset app bundle, mengekspor daftar dari Vkquality List Editor menggunakan library.aar dan menempatkan file .aar yang diekspor di Assets/Android/Plugins saat ini. Unity tidak menyertakan file .vkq jika Anda memasukkannya langsung di Assets/Android/Plugins, dan harus dipaketkan dalam library .aar container. Ekstensi jenis file .vkq masih digunakan saat menentukan untuk StartVkQuality().